Added alteration summary shortcut command to CLI

README.md

@@ -49,11 +49,12 @@ $ cbioportal-api-client --help
 
   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.
+    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
 
@@ -65,11 +66,16 @@ $ cbioportal-api-client --help
 
 # 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
+# API Reference
 
 ## Modules
 
@@ -80,19 +86,8 @@ $ cbioportal-api-client getProfileData -s gbm_tcga_cnaseq -p gbm_tcga_mutations
 <dt><a href="#module_cbioportal-api-client/utils/convertResponse">cbioportal-api-client/utils/convertResponse</a> ⇒ <code>Promise</code></dt>
 <dd><p>Converts tab delimited responses to JSON format</p>
 </dd>
-<dt><a href="#module_cbioportal-api-client/utils/summarizeAlterations">cbioportal-api-client/utils/summarizeAlterations</a></dt>
-<dd><p>Exports utility functions for summarizing gene alterations</p>
-</dd>
-</dl>
-
-## Functions
-
-<dl>
-<dt><a href="#parseResponseMeta">parseResponseMeta(response, cmd)</a> ⇒ <code>Object</code></dt>
-<dd><p>Prepare response meta for the converted JSON</p>
-</dd>
-<dt><a href="#maybeTransformArray">maybeTransformArray(n)</a> ⇒ <code>string</code></dt>
-<dd><p>Transform an array to CSV</p>
+<dt><a href="#module_cbioportal-api-client/utils/summarizeAlterations">cbioportal-api-client/utils/summarizeAlterations</a> ⇒ <code>Promise</code></dt>
+<dd><p>Summarizes alterations for results</p>
 </dd>
 </dl>
 
@@ -239,17 +234,9 @@ Converts tab delimited responses to JSON format
 -----
 
 <a name="module_cbioportal-api-client/utils/summarizeAlterations"></a>
-## cbioportal-api-client/utils/summarizeAlterations
-Exports utility functions for summarizing gene alterations
-
-
------
-
-<a name="exp_module_cbioportal-api-client/utils/summarizeAlterations--module.exports"></a>
-### module.exports(dataSets) ⇒ <code>Promise</code> ⏏
+## cbioportal-api-client/utils/summarizeAlterations ⇒ <code>Promise</code>
 Summarizes alterations for results
 
-**Kind**: Exported function  
 **Returns**: <code>Promise</code> - Resolves with the summary  
 **Fulfills**: <code>Object</code> Object with results, see example  
 
@@ -272,37 +259,7 @@ Example response object:
     }
   }
 }
-
-
 ```
 
 -----
 
-<a name="parseResponseMeta"></a>
-## parseResponseMeta(response, cmd) ⇒ <code>Object</code>
-Prepare response meta for the converted JSON
-
-**Kind**: global function  
-**Returns**: <code>Object</code> - Object with response meta and row meta  
-
-| Param | Type | Description |
-| --- | --- | --- |
-| response | <code>string</code> | Raw response from the server |
-| cmd | <code>string</code> | API command |
-
-
------
-
-<a name="maybeTransformArray"></a>
-## maybeTransformArray(n) ⇒ <code>string</code>
-Transform an array to CSV
-
-**Kind**: global function  
-
-| Param | Type |
-| --- | --- |
-| n | <code>mixed</code> | 
-
-
------
-

docs/README.md.hbs

@@ -49,11 +49,12 @@ $ cbioportal-api-client --help
 
   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.
+    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
 
@@ -65,10 +66,15 @@ $ cbioportal-api-client --help
 
 # 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
+# API Reference
 
 {{>main}}

lib/cli.js

@@ -17,7 +17,7 @@ function apiRequest (cmd, query) {
 
   return cbioPortal[cmd](query)
     .then(response => {
-      process.stdout.write(JSON.stringify(response));
+      process.stdout.write(JSON.stringify(response) + '\n');
       process.exit(0);
     });
 }
@@ -65,4 +65,18 @@ Program
     gene_list: options.geneList
   }));
 
+Program
+  .command('getAlterationSummary')
+  .option('-s, --case-set <case_set_id>', 'specify the case list ID (required)')
+  .option('-p, --genetic-profile <genetic_profile_id>', 'One or more genetic profile IDs (required, separated by comma if more than one)')
+  .option('-g, --gene-list <gene_list>', 'One or more genes, specified as HUGO Gene Symbols or Entrez Gene IDs (required)')
+  .description('summarize alterations for the profile data.')
+  .action(options => apiRequest('getAlterationSummary', {
+    case_set_id: options.caseSet,
+    genetic_profile_id: options.geneticProfile,
+    gene_list: options.geneList
+  }));
+
 Program.parse(process.argv);
+
+if (!Program.args.length) Program.help();

lib/index.js

@@ -10,7 +10,8 @@ import _reduce from 'lodash/reduce';
 import _defaults from 'lodash/defaults';
 import {
   convertResponse,
-  formatQuery
+  formatQuery,
+  summarizeAlterations
 } from './utils';
 
 /**
@@ -138,6 +139,11 @@ const cbioPortal = {
     }
 
     return this.get('ProfileData', { case_set_id, genetic_profile_id, gene_list });
+  },
+
+  getAlterationSummary ({ case_set_id, genetic_profile_id, gene_list }) {
+    return this.getProfileData({ case_set_id, genetic_profile_id, gene_list })
+      .then(results => summarizeAlterations(results));
   }
 
 };

lib/utils/convertResponse.js

@@ -21,6 +21,7 @@ function isPatient (string) {
 /**
  * Prepare response meta for the converted JSON
  *
+ * @private
  * @param  {string} response Raw response from the server
  * @param  {string} cmd      API command
  * @return {Object}          Object with response meta and row meta

lib/utils/formatQuery.js

@@ -3,6 +3,7 @@ import _transform from 'lodash/transform';
 /**
  * Transform an array to CSV
  *
+ * @private
  * @param  {mixed} n
  * @return {string}
  */
@@ -16,6 +17,7 @@ function maybeTransformArray (n) {
 
 /**
  * Formats query params
+ * @private
  */
 export default function convertResponse (query) {
 

lib/utils/summarizeAlterations.js

@@ -8,12 +8,6 @@ import _flatten from 'lodash/flatten';
 import _transform from 'lodash/transform';
 import _flattenDeep from 'lodash/flattenDeep';
 
-/**
- * Exports utility functions for summarizing gene alterations
- *
- * @module cbioportal-api-client/utils/summarizeAlterations
- */
-
 /**
  * Reduce case ID iterator
  *
@@ -113,9 +107,9 @@ function summarizeCopyNumberAlterations (cases = []) {
  *     }
  *   }
  * }
- *
- *
  * ```
+ *
+ * @module cbioportal-api-client/utils/summarizeAlterations
  * @param  {...Object|Array} dataSets Converted response dataset(s)
  * @return {Promise}  Resolves with the summary
  * @fulfills {Object} Object with results, see example

test/lib.js

@@ -224,3 +224,64 @@ Test('getProfileData() - multiple genes AND multiple profiles', t => {
       t.deepEquals(types.sort(), ['mutation_extended', 'copy_number_alteration'].sort());
     });
 });
+
+Test('getAlterationSummary()', t => {
+
+  Nock('http://www.cbioportal.org')
+    .get('/webservice.do')
+    .query({
+      cmd: 'getProfileData',
+      case_set_id: 'gbm_tcga_cnaseq',
+      genetic_profile_id: 'gbm_tcga_mutations',
+      gene_list: 'tp53,mdm2,mdm4'
+    })
+    .replyWithFile(
+      200,
+      __dirname + '/data/gbm_tcga_mutations-tp53-mdm2-mdm4.tsv'
+    );
+
+  Nock('http://www.cbioportal.org')
+    .get('/webservice.do')
+    .query({
+      cmd: 'getProfileData',
+      case_set_id: 'gbm_tcga_cnaseq',
+      genetic_profile_id: 'gbm_tcga_gistic',
+      gene_list: 'tp53,mdm2,mdm4'
+    })
+    .replyWithFile(
+      200,
+      __dirname + '/data/gbm_tcga_gistic-tp53-mdm2-mdm4.tsv'
+    );
+
+  return cbioPortal.getAlterationSummary({
+      case_set_id: 'gbm_tcga_cnaseq',
+      genetic_profile_id: ['gbm_tcga_mutations', 'gbm_tcga_gistic'],
+      gene_list: ['tp53', 'mdm2', 'mdm4']
+    })
+    .then(result => {
+      t.deepEquals(result, {
+        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
+        }
+      });
+
+      return true;
+    });
+});