cBio Portal API Client

cBio Portal API client. Parses tab separated responses into JSON format. Works in node and in the browser via a module loader such as Webpack.

This library can be used programatically or via the command line.

Under active development: This library is currently under active development. The module API is not finalized and is likely to change before v1.

Installation

$ npm install cbioportal-api-client --save

Programmatic Usage

API Reference

import CbioPortal from 'cbioportal-api-client';

const cbioPortal = CbioPortal();

cbioPortal.getCancerStudies()
  .then(response => {
    console.log(response); // Prints array of cancer studies returned from API
  });

cbioPortal.getGeneticProfiles({ cancer_study_id: 'gbm_tcga' })
  .then(response => {
    console.log(response); // Prints array of genetic profiles returned from the 'gbm_tcga' study
  });

Command Line Usage

Note: Requires node.

# global install to use anywhere
$ npm install -g cbioportal-api-client

# print usage info using --help
$ cbioportal-api-client --help

  Usage: cbioportal-api-client [options] [command]


  Commands:

    getCancerStudies                 get cancer study meta-data
    getTypesOfCancer                 get clinical cancer types
    getGeneticProfiles [options]     get genetic profile data for a cancer study.
    getCaseLists [options]           get case lists stored for a specific cancer study.
    getProfileData [options]         get genomic profile data for one or more genes.
    getAlterationSummary [options]   summarize alterations for the profile data.

  You can get usage info for specific commands using [command] --help

  Options:

    -h, --help             output usage information
    -V, --version          output the version number
    -f, --format <format>  response format

# example API call, sends JSON formatted response to stdout
$ cbioportal-api-client getProfileData -s gbm_tcga_cnaseq -p gbm_tcga_mutations -g TP53
# .... cut long JSON response

# summarizing alterations
$ cbioportal-api-client getAlterationSummary -s gbm_tcga_cnaseq -p gbm_tcga_mutations,gbm_tcga_gistic -g TP53,MDM2,MDM4
{"summary":{"genes":{"mdm2":{"mutated":1,"cna":9,"combined":10},"mdm4":{"mutated":0,"cna":10,"combined":10},"tp53":{"mutated":29,"cna":2,"combined":30}},"overall":47}}

API Reference

Modules

cbioportal-api-client

• cbioportal-api-client
  • exports
    • ⏏ exports.default(config) ⇒ cbioPortal
  • inner
    • ~cbioPortal : Object
      • .getTypesOfCancer() ⇒ Promise
      • .getCancerStudies() ⇒ Promise
      • .getGeneticProfiles(query) ⇒ Promise
      • .getCaseLists(query) ⇒ Promise
      • .getProfileData(query) ⇒ Promise
      • .getAlterationSummary(query) ⇒ Promise

cbioportal-api-client ⏏ exports.default(config) ⇒ cbioPortal

Creates a new cBio Portal API client

Kind: exports method of cbioportal-api-client
Returns: cbioPortal

| Param | Type | Description | | --- | --- | --- | | config | Object | Configuration options object. | | config.requestOpts | Object | Override the request congfiguration object. |

Example
Basic usage:

import CbioPortal from 'cbioportal-api-client';

const cbioPortal = CbioPortal();

cbioPortal.getCancerStudies()
  .then(response => {
    console.log(response); // Prints array of cancer studies returned from API
  });

cbioportal-api-client~cbioPortal : Object

cbioPortal API Object Prototype. Used as the object prototype when creating an API client object via the module factory method.

Kind: inner constant of cbioportal-api-client

See: Use CbioPortal() for object creation.

• ~cbioPortal : Object
  • .getTypesOfCancer() ⇒ Promise
  • .getCancerStudies() ⇒ Promise
  • .getGeneticProfiles(query) ⇒ Promise
  • .getCaseLists(query) ⇒ Promise
  • .getProfileData(query) ⇒ Promise
  • .getAlterationSummary(query) ⇒ Promise

cbioPortal.getTypesOfCancer() ⇒ Promise

Retrieves a list of all the clinical types of cancer stored on the server.

Kind: instance method of cbioPortal
Returns: Promise
Fulfills: Array response data converted from TSV to JSON

cbioPortal.getCancerStudies() ⇒ Promise

Retrieves meta-data regarding cancer studies stored on the server.

Kind: instance method of cbioPortal
Returns: Promise
Fulfills: Array response data converted from TSV to JSON

cbioPortal.getGeneticProfiles(query) ⇒ Promise

Retrieves meta-data regarding all genetic profiles, e.g. mutation or copy number profiles, stored about a specific cancer study.

Kind: instance method of cbioPortal
Returns: Promise
Fulfills: Array response data converted from TSV to JSON

| Param | Type | Description | | --- | --- | --- | | query | Object | | | query.cancer_study_id | string | Cancer study ID |

cbioPortal.getCaseLists(query) ⇒ Promise

Retrieves meta-data regarding all case lists stored about a specific cancer study.

For example, a within a particular study, only some cases may have sequence data, and another subset of cases may have been sequenced and treated with a specific therapeutic protocol.

Multiple case lists may be associated with each cancer study, and this method enables you to retrieve meta-data regarding all of these case lists.

Kind: instance method of cbioPortal
Returns: Promise
Fulfill: response data converted from TSV to JSON

| Param | Type | Description | | --- | --- | --- | | query | Object | | | query.cancer_study_id | string | Cancer study ID |

cbioPortal.getProfileData(query) ⇒ Promise

Retrieves genomic profile data for one or more genes.

Note: If you pass in multiple genetic profile IDs and multiple genes, the library will make multiple requests as the API does not support this type of query.

Kind: instance method of cbioPortal
Returns: Promise
Fulfill: response data converted from TSV to JSON

| Param | Type | Description | | --- | --- | --- | | query | Object | | | query.case_set_id | string | A unique ID used to identify the case list ID in subsequent interface calls. This is a human readable ID. For example, "gbm_all" identifies all cases profiles in the TCGA GBM study. | | query.genetic_profile_id | Array.<string> | string | One or more genetic profile IDs | | query.gene_list | Array.<string> | string | One or more genes, specified as HUGO Gene Symbols or Entrez Gene IDs |

cbioPortal.getAlterationSummary(query) ⇒ Promise

Summarize gene alterations

Kind: instance method of cbioPortal
Returns: Promise

| Param | Type | Description | | --- | --- | --- | | query | Object | | | query.case_set_id | string | A unique ID used to identify the case list ID in subsequent interface calls. This is a human readable ID. For example, "gbm_all" identifies all cases profiles in the TCGA GBM study. | | query.genetic_profile_id | Array.<string> | string | One or more genetic profile IDs | | query.gene_list | Array.<string> | string | One or more genes, specified as HUGO Gene Symbols or Entrez Gene IDs |

cbioportal-api-client/utils/convertResponse ⇒ Promise

Converts tab delimited responses to JSON format

Returns: Promise - Resolves with the response JSON

| Param | Type | Description | | --- | --- | --- | | response | string | TSV string |

cbioportal-api-client/utils/summarizeAlterations ⇒ Promise

Summarizes alterations for results

Returns: Promise - Resolves with the summary
Fulfills: Object Object with results, see example

| Param | Type | Description | | --- | --- | --- | | dataSets | Object | Array | Converted response dataset(s) |

Example
Basic Usage:

import CbioPortal from 'cbioportal-api-client';
import { summarizeAlterations } from 'cbioportal-api-client/dist/utils';

const cbioPortal = CbioPortal();

cbioPortal.getProfileData({
  case_set_id: 'gbm_tcga_cnaseq',
  genetic_profile_id: ['gbm_tcga_mutations', 'gbm_tcga_gistic'],
  gene_list: ['tp53', 'mdm2', 'mdm4']
})
.then(response => summarizeAlterations(response))
.then(result => console.log(result));

// console.log output

{
  summary: {
    genes: {
      tp53: {
        mutated: 29,
        cna: 2,
        combined: 30
      },
      mdm2: {
        mutated: 1,
        cna: 9,
        combined: 10
      },
      mdm4: {
        mutated: 0,
        cna: 10,
        combined: 10
      }
    },
    overall: 47
  }
}