Merge branch 'release/0.1.0'

README.md

@@ -1,2 +1,158 @@
-# gdc-viewer
-A plugin for JBrowse for viewing GDC data
+# GDC JBrowse Plugin - Faceted Search and New Store Classes
+A plugin for [JBrowse](https://jbrowse.org/) for viewing [GDC](https://gdc.cancer.gov/) data. For any bugs, issues, or feature recommendations please create an issue through GitHub.
+
+# Installation and Setup
+## 1. Install JBrowse
+Quick setup of JBrowse - https://github.com/GMOD/jbrowse/#install-jbrowse-from-github-for-developers
+
+## 2. Install Plugin
+See [JBrowse - Installing Plugins](https://jbrowse.org/docs/plugins.html) for a general approach to installing plugins.
+
+For installing gdc-viewer plugin:
+1) Copy the gdc-viewer folder into the JBrowse `plugins` directory.
+2) Add 'gdc-viewer' to the array of plugins in the `jbrowse_conf.json`.
+
+## 3. Install Reference Sequence Data
+Now setup the reference sequence used. GDC requires the GRCh38 Human reference files, which can be found at http://ftp.ensembl.org/pub/release-94/fasta/homo_sapiens/dna/. You'll want to download the files of the form `Homo_sapiens.GRCh38.dna.chromosome.1.fa.gz`.
+
+Then you can use the `bin/prepare-refeqs.pl` command to generate the RefSeq information.
+
+Below is an example of these two steps for Chr1.
+
+Ex. Chromosome 1
+1. Download Homo_sapiens.GRCh38.dna.chromosome.1.fa.gz from the above site.
+```
+wget http://ftp.ensembl.org/pub/release-94/fasta/homo_sapiens/dna/Homo_sapiens.GRCh38.dna.chromosome.1.fa.gz
+```
+2. Setup refeq with the following command
+```
+bin/prepare-refseqs.pl --fasta Homo_sapiens.GRCh38.dna.chromosome.1.fa.gz
+```
+Note that you can specify multiple fast in one command by doing `--fasta fasta1.fa.gz --fasta fasta2.fa.gz ...`
+
+## 4. Adding new tracks
+We have some basic example tracks in `data/tracks.conf`. You can also add new tracks by using the GDC dialog accessible within JBrowse. These are present in the menu under `GDC`.
+
+### A. Explore GDC
+This dialog is similar to the Exploration section of the GDC data portal. As you apply facets on the left-hand side, updated results will be shown on the right side. You can create donor specific SSM, Gene, and CNV tracks, along with GDC-wide SSM, Gene and CNV tracks.
+
+### B. View GDC Projects
+This dialog shows the projects present on the GDC Data Portal. You can add SSM, Gene, and CNV tracks for each project.
+
+### C. View GDC Primary Sites
+This dialog shows the primary sites present on the GDC Data Portal. You can add SSM, Gene, and CNV tracks for each primary site.
+
+## 5. Run JBrowse
+You'll have to run the following commands:
+
+```
+./setup.sh
+utils/jb_run.js -p 3000
+```
+
+JBrowse should now be running with the GDC Plugin working!
+
+# JBrowse configuration
+## Faceted Track Selector
+Add the following to your jbrowse.conf to use the faceted track selector.
+```
+[trackSelector]
+type = Faceted
+displayColumns =
+  + label
+  + key
+  + datatype
+  + case
+  + project
+  + primarySite
+```
+
+Note that this will only show preloaded tracks as well as tracks you have added using the various dialogs. It does not dynamically create tracks based on what is available from the GDC.
+
+# Available Store SeqFeature
+## A note on filters
+All SeqFeatures support filters as they are defined in the [GDC API Documentation](https://docs.gdc.cancer.gov/API/Users_Guide/Search_and_Retrieval/#filters-specifying-the-query).
+Note that filters should have the filter type prepended to the front. Ex. Case filters use `cases.`, SSM filters use `ssms.`, and Gene filters use `genes.`. GraphQL is used to retrieve results, so if the filters work there, they work with these Store classes.
+
+The following shows a filter for cases by ethnicity:
+{
+  "op":"in",
+  "content":{
+    "field":"cases.demographic.ethnicity",
+    "value":[
+      "hispanic or latino"
+    ]
+  }
+}
+
+## Genes
+A simple view of all of the genes seen across all cases.
+
+Example Track:
+```
+[tracks.GDC_Genes]
+storeClass=gdc-viewer/Store/SeqFeature/Genes
+type=JBrowse/View/Track/CanvasVariants
+key=GDC Genes
+metadata.datatype=Gene
+unsafePopup=true
+fmtDetailValue_projects=function(value) { return "<div id='projects-gdc-" + value +  "'>Loading...</div>";}
+```
+
+You can apply filters to the track too, in the same format as GDC. The below example only shows Genes whose biotype is not 'protein_coding'.
+
+```
+filters={"op":"!=","content":{"field":"cases.biotype","value":"protein_coding"}}
+```
+
+You can set the max number of genes to return with the `size` field. It defaults to 100.
+You can view case specific genes by setting the `case` field.
+
+## SSMs
+A simple view of all of the simple somatic mutations seen across all cases.
+
+Example Track:
+```
+[tracks.GDC_SSM]
+storeClass=gdc-viewer/Store/SeqFeature/SimpleSomaticMutations
+type=JBrowse/View/Track/CanvasVariants
+key=GDC SSM
+metadata.datatype=SSM
+unsafePopup=true
+fmtDetailValue_projects=function(value) { return "<div id='projects-gdc-" + value +  "'>Loading...</div>";}
+```
+
+You can apply filters to the track too, in the same format as GDC. The below example only shows SSMs whose reference allele is 'G'.
+
+```
+filters={"op":"=","content":{"field":"ssms.reference_allele","value":"G"}}
+```
+
+You can set the max number of SSMs to return with the `size` field. It defaults to 100.
+You can view case specific SSMs by setting the `case` field.
+
+## CNVs
+A simple view of all of the CNVs seen across all cases.
+
+Example Track:
+```
+[tracks.GDC_CNV]
+storeClass=gdc-viewer/Store/SeqFeature/CNVs
+type=JBrowse/View/Track/Wiggle/XYPlot
+key=GDC CNV
+metadata.datatype=CNV
+autoscale=local
+bicolor_pivot=0
+unsafePopup=true
+```
+
+You can apply filters to the track too, in the same format as GDC. The below example only shows CNVs that are 'Gains'.
+
+```
+filters={"op":"=","content":{"field":"cnv_change","value":["Gain"]}}
+```
+
+You can set the max number of CNVs to return with the `size` field. It defaults to 500.
+You can view case specific CNVs by setting the `case` field.
+
+Note: You can also use a density plot for the copy number data. Simply change the type from `JBrowse/View/Track/Wiggle/XYPlot` to `JBrowse/View/Track/Wiggle/Density.`

data/jbrowse.conf

@@ -0,0 +1,96 @@
+#### JBrowse main configuration file
+
+## uncomment the section below to customize this browser's title and description
+[aboutThisBrowser]
+title = JBrowse GDC
+description = View GDC Data Portal SSMs, Genes, and CNVs
+
+## uncomment and edit the example below to configure a faceted track selector
+[trackSelector]
+type = Faceted
+displayColumns =
+  + label
+  + key
+  + datatype
+  + case
+  + project
+  + primarySite
+## optionally sort the faceted track selector by column (use the names from displayColumns)
+# initialSortColumn=label
+## optionally give different names to some of the data facets using renameFacets
+# [trackSelector.renameFacets]
+# submission = Submission ID
+# developmental-stage = Conditions
+# cell-line = Cell Line
+# key = Dataset
+# label = Track
+
+## uncomment this section to get hierarchical trackselector options
+# [trackSelector]
+## optionally turn off sorting for the hierarchical track selector
+# sortHierarchical = false
+## set collapsed categories for the hierarchical track selector
+# collapsedCategories = Reference sequence,Quantitative / XY Plot
+## set category ordering in the hierarchical track selector
+# categoryOrder = BAM, Transcripts, Quantitative/Density, VCF
+
+## configure where to get metadata about tracks.  always indexes the
+## `metadata` part of each track config, but this can be used to load
+## additional metadata from CSV or JSON urls
+# [trackMetadata]
+# sources = data/trackMetadata.csv
+
+
+[GENERAL]
+
+
+## add a document.domain to set the same-origin policy
+# documentDomain=foobar.com
+
+## use classic jbrowse menu with file instead of track and genome
+#classicMenu = true
+
+## hide open genome option
+#hideGenomeOptions = true
+
+## enable or disable high resolution rendering for canvas features. set to auto, disabled, or numerical scaling factor. default: 2
+# highResolutionMode=auto
+
+## uncomment to change the default sort order of the reference
+## sequence dropdown
+# refSeqOrder = length descending
+
+
+## to set a default data directory other than 'data', uncomment and
+## edit the line below
+# dataRoot = data
+
+## optionally add more include statements to load and merge in more
+## configuration files
+include  = {dataRoot}/trackList.json
+include += {dataRoot}/tracks.conf
+# include += ../url/of/my/other/config.json
+# include += another_config.conf
+
+## uncomment and edit the example below to enable one or more
+## JBrowse plugins
+[ plugins.gdc-viewer ]
+location = plugins/gdc-viewer
+
+# [ plugins.AnotherPlugin ]
+# location = ../plugin/dir/someplace/else
+
+## edit the datasets list below to add datasets to the jbrowse dataset
+## selector
+
+# [datasets.volvox]
+# url  = ?data=sample_data/json/volvox
+# name = Volvox Example
+
+# [datasets.modencode]
+# url  = ?data=sample_data/json/modencode
+# name = MODEncode Example
+
+# [datasets.yeast]
+# url  = ?data=sample_data/json/yeast
+# name = Yeast Example

data/tracks.conf

@@ -0,0 +1,23 @@
+[tracks.GDC_SSM]
+storeClass=gdc-viewer/Store/SeqFeature/SimpleSomaticMutations
+type=JBrowse/View/Track/CanvasVariants
+key=GDC SSM
+metadata.datatype=SSM
+unsafePopup=true
+fmtDetailValue_projects=function(value) { return "<div id='projects-gdc-" + value +  "'>Loading...</div>";}
+
+[tracks.GDC_Genes]
+storeClass=gdc-viewer/Store/SeqFeature/Genes
+type=JBrowse/View/Track/CanvasVariants
+key=GDC Genes
+metadata.datatype=Gene
+unsafePopup=true
+fmtDetailValue_projects=function(value) { return "<div id='projects-gdc-" + value +  "'>Loading...</div>";}
+
+[tracks.GDC_CNV]
+storeClass=gdc-viewer/Store/SeqFeature/CNVs
+type=JBrowse/View/Track/Wiggle/XYPlot
+key=GDC CNV
+metadata.datatype=CNV
+autoscale=local
+bicolor_pivot=0

gdc-viewer/css/main.css

@@ -0,0 +1,94 @@
+table.results-table {
+    width: 100%;
+    border: 1px solid #e6e6e6;
+    border-collapse: collapse;
+    border-spacing: 0;
+}
+
+table.results-table td {
+    border: 1px solid #e6e6e6;
+    padding: .2rem .4rem;
+}
+
+table.results-table tr:nth-child(odd) {
+    background-color: #f2f2f2;
+}
+
+.filterNameGDC {
+    background: #3d3d3d;
+    border-radius: 4px;
+    padding: 6px 12px;
+    margin: 2px;
+    color: white;
+}
+
+.filterValueGDC {
+    background: #255425;
+    border-radius: 4px;
+    padding: 6px 12px;
+    margin: 2px;
+    color: white;
+}
+
+.joinWordGDC {
+    background: #005083;
+    border-radius: 4px;
+    padding: 6px 12px;
+    margin: 2px;
+    color: white;
+}
+
+.flexHolder {
+    display: flex;
+    flex-direction: row;
+    flex-wrap: wrap;
+    align-items: stretch;
+}
+
+.flex-column {
+    display: flex;
+    flex-direction:column;
+}
+
+.flex-row {
+    display: flex;
+    flex-direction:row;
+}
+
+.loading-gdc {
+    display: flex;
+    justify-content: center;
+}
+
+.loading-gdc > div {
+    border: 8px solid #f3f3f3;
+    border-radius: 50%;
+    border-top: 8px solid #166aa2;
+    width: 60px;
+    height: 60px;
+    -webkit-animation: spin 2s linear infinite;
+    animation: spin 2s linear infinite;
+  }
+
+  @-webkit-keyframes spin {
+    0% { -webkit-transform: rotate(0deg); }
+    100% { -webkit-transform: rotate(360deg); }
+  }
+
+  @keyframes spin {
+    0% { transform: rotate(0deg); }
+    100% { transform: rotate(360deg); }
+  }
+
+.nowrapTabStrip {
+    width: 100% !important;
+}
+
+.accordionContainer {
+    height: 500px;
+    overflow: scroll;
+}
+
+.dijitContentPane.dijitAccordionContainer-child.dijitAccordionContainer-dijitContentPane {
+    width: 100% !important;
+}