Skip to content

AlexsLemonade/refinebio-js

BranchesTags

Repository files navigation

contributor: 2 formatter: prettier license: BSD-3-Clause

refine.bio JS

This is a Javascript API client for refine.bio.

What is refine.bio?

image

refine.bio is a multi-organism collection of genome-wide transcriptome or gene expression data that has been obtained from publicly available repositories and uniformly processed and normalized. refine.bio allows biologists, clinicians, and machine learning researchers to search for experiments from different source repositories all in one place and build custom data sets for their questions of interest.

Links

Here are the addtional resources for refine.bio API:

Table of contents

(back to top)

Getting Started

Built With

We use the npm package isomorphic-unfetch which supports an API request for both Node.js and a browser.

Add refine.bio API

To add refine.bio API, go to the root directory of your project and run the following command:

yarn add refinebio

(back to top)

Usage

Import Refinebio module into your Javascript file and instantiate it.

import Refinebio from 'refinebio'

const api = Refinebio()

To override refine.bio API default config settings upon instantiation:

const api = Refinebio({ verbose: true })

This newly created instance api returns the following properties:

key value
updateConfig A method for accessing or updating the config object
resourceName Methods for each resource

To use updateConfig method:

import Refinebio from 'refinebio'

const api = Refinebio()

// access the config
const config = api.updateConfig()

// update the config
const updateConfiog = api.updateConfig({ verbose: true })

To use one of the resouces:

import Refinebio from 'refinebio'

const api = Refinebio()

const tokenRequest = await api.token.create({ is_activated: true })

if (tokenRequest.isOkay) {
  console.log('TokenRequest resolved')
}

Config

The following properties can be overridden:

key value Description
path urlString refine.bio API Url consists of host and API version number.
verbose boolean By setting this option to true, it logs endpoints for each resrouce in terminal when an HTTP request is made. The default value is false.

(back to top)

REST API

Available Actions

Our API supports the following actions:

Action Description
create sends a POST request and returns a new instance
get sends a GET request and returns a single object
filter sends a GET resuest with a query string and returns a list of objects(maybe paginated)
update sends a PUT request and returns a single object
  • create takes an object as an argument
  • get takes an identifier and an optional query parameter object
  • filter takes a filter object and coverts it to a query parameter
  • update takes an object as an argument

How filters work

Our filter action automatically converts a filter object into a query parameter.

Example:

// get advanced filtered search results
const getSearchResults = await api.search.filter({
  downloadable_organism: 'HOMO_SAPIENS',
  technology: ['microarray', 'rna-seq']
})

// 'search?filter_order=downloadable_organism%2Ctechnology%2Ctechnology&downloadable_organism=HOMO_SAPIENS&technology=microarray&technology=rna-seq'

Resources

List of resources

compendia

This resource can be used to get the compendia result. This may return a specific compendia result by its corresponding identifier or a list of all compendia results with filtering.

Please view the API documentation for more details.

Action Type ReDoc SwaggerUI
compendia.get compendia_read view view
compendia.filter compendia_list view view
Example 
// get a specific compendia result
const getCompendia = Refinebio().compendia.get(id)

// get a list of all compendia results
const getCompendiaList = await Refinebio().compendia.filter(query)

computationalResults

This resource can be used to get the computational result. This may return a specific computational result by its corresponding identifier or a list of all computational results with filtering.

Each one contains meta-information about the output of a computer process. This can also return valid S3 urls if a valid token is sent in the header HTTP_API_KEY.

Please view the API documentation for more details.

Action Type ReDoc SwaggerUI
computationalResults.get computational_results_read view view
computationalResults.filter computational_result_list view view
Example 
// get a specific computational result
const getComputationalResult = await Refinebio().computationalResults.get(id)

// get a list of all computational results
const getComputationalResults = await Refinebio().computationalResults.filter(
  query
)

dataset

This resource can be used to create, get, or update a single dataset.

Please view the API documentation for more details.

Action ReDoc SwaggerUI
dataset.create view view
dataset.get view view
dataset.update view view
Example 
// create a dataset
const createDataset = async() => await Refinebio().dataset.create({})

// get a dataset
const getDataset = async() => await Refinebio().dataset.get(id)

// update a dataset
const updateDataset = async() Refinebio().dataset.update(tokenID, {})

experiments

This resource can be used to get the experiment. This may return a specific experiment by its corresponding accession code or a paginated list of all experiments with advanced filtering.

Please view the API documentation for more details.

Action Type ReDoc SwaggerUI
experiments.get experiments_read view view
experiments.filter experiments_list view view
Example 
// get a specific experiment
const getExperiment = await Refinebio().experiments.get(accessionCode)

// get a list of all experiments
const getExpriments = await Refinebio().experiments.filter(query)

institutions

This resource can be used to get an unpaginated list of all the available "institution" information.

Please view the API documentation for more details.

Action ReDoc SwaggerUI
institutions.filter view view
Example 
const getInstitutions = async () => await Refinebio().institutions.filter(query)

jobs

This resource can be used to get the downloader, processor, or survery job. This may return a specific job by its corresponding identifier or a list of jobs by its job type with filtering.

Please view the API documentation for more details.

Action Type ReDoc SwaggerUI
jobs.downloader.get jobs_downloader_read view view
jobs.downloader.filter jobs_downloader_list view view
jobs.processor.get jobs_processor_read view view
jobs.processor.filter jobs_processor_list view view
jobs.survey.get jobs_survey_read view view
jobs.survey.filter jobs_survey_list view view
Example 
// get a specific downloader job
const getDownloaderJob = await Refinebio().jobs.downloader.get(id)

// get a list of downloader jobs
getDownloaderJobs = await Refinebio().jobs.downloader.filter(query)

// get a specific processor job
const getProcessorJob = await Refinebio().jobs.processor.get(id)

// get a list of processor jobs
getProcessorJobs = await Refinebio().jobs.processor.filter(query)

// get a specific servey job
const getSurveyJob = await Refinebio().jobs.survey.get(id)

// get a list of survey jobs
getSurveyJobs = await Refinebio().jobs.survey.filter(query)

organisms

This resource can be used to get the organism. This may return an organism by its name or a paginated list of all available organisms with filtering.

Please view the API documentation for more details.

Action Type ReDoc SwaggerUI
organisms.get organisms_read view view
organisms.filter organisms_list view view
Example 
// get a specific organism
const getOrganism = await Refinebio().organisms.get(name)

// get a list of all available organisms
const getOrganisms = await Refinebio().organisms.filter(query)

originalFiles

This resource can be used to get the original files. This may return a specific original file by its corresponding identifier or a list of all original files that are associated with samples with filtering.

These are the files we proccess.

Please view the API documentation for more details.

Action Type ReDoc SwaggerUI
originalFiles.get original_files_read view view
originalFiles.filter original_files_list view view
Example 
// get a specific original file
const getOriginalFile = await Refinebio().originalFiles.get(id)

// get a list of all original files
const getOriginalFiles = await Refinebio().originalFiles.filter(query)

platforms

This resource can be used to get an unpaginated list of all available "platform" information.

Please view the API documentation for more details.

Action ReDoc SwaggerUI
platforms.filter view view
Example 
const getPlatforms = await Refinebio().platforms.filter(query)

processors

This resource can be used to get the processor. This may return a specific processor by its corresponding identifier or a list of all processors with filtering.

Please view the API documentation for more details.

Action Type ReDoc SwaggerUI
processors.get processors_read view view
processors.filter processors_list view view
Example 
// get a specific processor
const getProcessor = await Refinebio().processors.get(id)

// get a list of all processors
const getProcessors = await Refinebio().processors.filter(query)

qnTargets

This resource can be used to get the organisms which have available QN Targets. This may return a detailed view of the Quantile Normalization file for an organism by its name or a list of all organisms with filtering.

Please view the API documentation for more details.

Action Type ReDoc SwaggerUI
qnTargets.get qn_targets_read view view
qnTargets.filter qn_targets_list view view
Example 
// get a Quantile Normalization file for an organism
const getQnTarget = await Refinebio().qnTargets.get(name)

// get a list of all organisms with available QN Targets
const getOrganismsWithQnTargets = await Refinebio().qnTargets.filter(query)

samples

This resource can be used to get the detailed information about the sample. This may return a specific sample information by its corresponding accession code or a list of all sample details with filtering.

Please view the API documentation for more details.

Action Type ReDoc SwaggerUI
samples.get samples_read view view
samples.filter samples_list view view
Example 
// get a specific sample
const getQnTarget = await Refinebio().samples.get(accessionCode)
// get a list of all samples
const getOrganismsWithQnTargets = await Refinebio().samples.filter(query)

search

This resource can be used to search among the experiments with advanced filtering.

This is powered by ElasticSearch, information regarding advanced usages of the filters can be found in the Django-ES-DSL-DRF docs.

There's an additional field in the response named facets that contain stats on the number of results per filter type.

Please view the API documentation for more details.

Action ReDoc SwaggerUI
search.filter view view
Example 
const getSearchResults = await Refinebio().search.filter(query)

statsAbout

This resource can be used to get the general statistics for the site used in the about page.

Please view the API documentation for more details.

Action ReDoc SwaggerUI
statsAbout.get view view
Example 
const getStatsAbout = await Refinebio()api.statsAbout.get()

stats

This resource can be used to get the statistics about the health of the system.

Please view the API documentation for more details.

Action Type ReDoc SwaggerUI
stats.get stats_list view view
stats.failures.downloader.filter stats_failures_downloader_list view view
stats.failures.processor.filter sstats_failures_processor_list view view
Example 
// get stats on the health of the system.
const getStatsOnHealth = await Refinebio().stats.get()

// get stats on a failures downloader list
const getFailureDownloader = await Refinebio().stats.failures.downloader.filter()

// get stats on a failures processor list
const getFailureProcessor = await Refinebio().stats.failures.processor.filter()

token

This resource can be used to create, get, or update a token. The token can be used in requests that provide urls to download computed files. Setting is_activated to true indicates agreement with refine.bio's Terms of Use and Privacy Policy.

Please view the API documentation for more details.

Action ReDoc SwaggerUI
token.create view view
token.get view view
token.update view view
Example 
// create a new token
const createToken = async() => await Refinebio().token.create({ is_activated: true })

// get a specific token
const getToken = async() => await Refinebio().token.get(tokenID)

// update a specific token's active state
const updateToken = async() Refinebio().token.update(tokenID, { is_activated: true })

transcriptomeIndices

This resource can be used to get the detailed information about a sample. This may return a S3 url associated with the organism and length, along with other metadata about the transcriptome index we have stored, or a list of all Transcriptome Indice with filtering.

Please view the API documentation for more details.

Action Type ReDoc SwaggerUI
transcriptomeIndices.get transcriptome_indices_read view view
transcriptomeIndices.filter transcriptome_indices_list view view
Example 
// get a S3 url associated with the transcriptome index
const getS3Url = await Refinebio().transcriptomeIndices.get(id)

// get a list of all transcriptome Indices
const getTranScruptomeIndices = await Refinebio().transcriptomeIndices.filter(
  query
)

(back to top)

Contributing

Let's collaborate with us! Any contributions would be greatly appreciated. Please share your idea by making a pull request.

Prerequisites

This project requires NodeJS (version 17 or later) and Yarn.
To make sure you have them available on your machine, run the following command:

$ yarn -v && node -v
1.22.18
v17.8.0

Installation

BEFORE INSTALLING: please read the prerequisites

  1. Clone this repository on your local machine
$ https://github.com/AlexsLemonade/refinebio-js.git
$ cd refinebio-js
  1. Install dependencies
$ yarn install
  1. Create a new feature branch
$git checkout -b feature/your-branch-name
  1. Commit your changes
$git commit -m 'add describe your feature'
  1. Push to the branch on remote
$git push origin feature/your-branch-name
  1. Open a new pull request via Github

Development

Recompile on changes

$ yarn dev

Run the tests

$ yarn test

Lint the code

$ yarn lint

Build a distribution version

This script will generate a distribution version of the project in your local dist/ folder.

$ yarn build

(back to top)

License

The 3-Clause BSD License

(back to top)

About

Javascript client for refine.bio

Resources

Readme

License

BSD-3-Clause license
Activity
Custom properties

Stars

0 stars

Watchers

5 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 3

  •  
  •  
  •  

Languages