refine.bio JS

This is a Javascript API client for refine.bio.

What is refine.bio?

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:

refine.bio API (v1) ReDoc
refine.bio API (v1) Swagger UI
refine.bio Documentation

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
computationalResults
dataset
experiments
institutions
jobs
organisms
originalFiles
platforms
processors
qnTargets
samples
search
statsAbout
stats
token
transcriptomeIndices

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

Clone this repository on your local machine

$ https://github.com/AlexsLemonade/refinebio-js.git
$ cd refinebio-js

Install dependencies

$ yarn install

Create a new feature branch

$git checkout -b feature/your-branch-name

Commit your changes

$git commit -m 'add describe your feature'

Push to the branch on remote

$git push origin feature/your-branch-name

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)

Files

README.md

Latest commit

History

README.md

File metadata and controls

refine.bio JS

What is refine.bio?

Links

Table of contents

Getting Started

Built With

Add refine.bio API

Usage

Config

REST API

Available Actions

How filters work

Resources

compendia

computationalResults

dataset

experiments

institutions

jobs

organisms

originalFiles

platforms

processors

qnTargets

samples

search

statsAbout

stats

token

transcriptomeIndices

Contributing

Prerequisites

Installation

Development

Recompile on changes

Run the tests

Lint the code

Build a distribution version

License

`Config`