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

Table of contents

• What is refine.bio?
• Links
• Getting Started
  • Built With
  • Add refine.bio API
• Usage
• REST API
  • Available Actions
  • Resources
• Contributing
  • Prerequisites
  • Installation
  • Development
• License

(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:

sh yarn add refinebio

(back to top)

Usage

Import Refinebio module into your Javascript file and instantiate it.

```js import Refinebio from 'refinebio'

const api = Refinebio() ```

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

js 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:

```js 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:

```js 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:

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

// 'search?filterorder=downloadableorganism%2Ctechnology%2Ctechnology&downloadableorganism=HOMOSAPIENS&technology=microarray&technology=rna-seq' ```

Resources

List of resources

* [**compendia**](#compendia) * [**computationalResults**](#computationalresults) * [**dataset**](#dataset) * [**experiments**](#experiments) * [**institutions**](#institutions) * [**jobs**](#jobs) * [**organisms**](#organisms) * [**originalFiles**](#originalfiles) * [**platforms**](#platforms) * [**processors**](#processors) * [**qnTargets**](#qntargets) * [**samples**](#samples) * [**search**](#search) * [**statsAbout**](#statsabout) * [**stats**](#stats) * [**token**](#token) * [**transcriptomeIndices**](#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

```js // 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

```js // 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

```js // 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

```js // 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

```js 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

```js // 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

```js // 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

```js // 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

```js 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

```js // 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

```js // 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

```js // 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

```js 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

```js 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

```js // 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

```js // 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

```js // 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:

sh $ 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

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

1. Install dependencies

sh $ yarn install

1. Create a new feature branch

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

1. Commit your changes

sh $git commit -m 'add describe your feature'

1. Push to the branch on remote

sh $git push origin feature/your-branch-name

1. Open a new pull request via Github

Development

Recompile on changes

sh $ yarn dev

Run the tests

sh $ yarn test

Lint the code

sh $ yarn lint

Build a distribution version

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

sh $ yarn build

(back to top)

License

The 3-Clause BSD License

(back to top)