more on datahub

.vscode/settings.json

@@ -1,3 +1,3 @@
 {
-    "restructuredtext.confPath": "c:\\Users\\D\\web\\eg-docs\\docs"
+    "restructuredtext.confPath": "/Users/dli/eg-docs/docs"
 }

docs/.gitignore

@@ -1 +1,2 @@
 /_build
+.DS_Store

docs/conf.py

@@ -20,8 +20,8 @@
 # -- Project information -----------------------------------------------------
 
 project = 'WashU Epigenome Browser'
-copyright = '2018, Daofeng Li, Renee Sears and Ting Wang'
-author = 'Daofeng Li, Renee Sears and Ting Wang'
+copyright = '2018, Daofeng Li, Silas Hsu, Renee Sears and Ting Wang'
+author = 'Daofeng Li, Silas Hsu, Renee Sears and Ting Wang'
 
 # The short X.Y version
 version = ''
@@ -134,7 +134,7 @@
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
     (master_doc, 'WashUEpigenomeBrowser.tex', 'WashU Epigenome Browser Documentation',
-     'Daofeng Li, Renee Sears and Ting Wang', 'manual'),
+     'Daofeng Li, Silas Hsu, Renee Sears and Ting Wang', 'manual'),
 ]
 
 

docs/datahub.rst

@@ -12,23 +12,55 @@ which are also defined in JSON syntax:
         "name": "track_name1",
         "url": "track_url1",
         "options": {
-            "color": "red",
-            "other option": "other value"
+            "color": "red"
             }
         },
         {
         "type": "track_type2",
         "name": "track_name2",
         "url": "track_url2",
         "options": {
-            "color": "red",
-            "other option": "other value"
+            "color": "blue"
             }
         }
     ]
 
 .. _JSON: http://json.org/
 
+Example data hub
+----------------
+
+Pasted below is an example data hub for mouse mm10:
+
+.. code-block:: json
+
+    [
+        {
+        "type": "bigwig",
+        "url": "https://wangftp.wustl.edu/~dli/test/TW463_20-5-bonemarrow_MeDIP.bigWig",
+        "name": "MeDIP",
+        "options": {
+            "color": "red"
+            },
+        "metadata": {
+            "sample": "bone",
+            "assay": "MeDIP"
+            }
+        },
+        {
+        "type": "bigwig",
+        "url": "https://wangftp.wustl.edu/~dli/test/TW551_20-5-bonemarrow_MRE.CpG.bigWig",
+        "name": "MRE",
+        "options": {
+            "color": "blue"
+            },
+        "metadata": {
+            "sample": "bone",
+            "assay": "MRE"
+            }
+        }
+    ]
+
 
 Example bigWig track
 --------------------
@@ -40,26 +72,193 @@ Example bigWig track
         "name": "example bigwig",
         "url": "https://vizhub.wustl.edu/hubSample/hg19/GSM429321.bigWig",
         "options": {
-            "color": "blue",
+            "color": "blue"
         }
     }
 
 Supported options: color_, color2_, yScale_, yMax_, yMin_
 
+Track properties
+----------------
+
+type
+~~~~
+
+*Requried*. ``type`` specifies the track type, currently supported track types:
+
+* bigWig
+* bedGraph
+* methylC
+* categorical
+* hic
+* bed
+* bigbed
+* repeatmasker
+* geneAnnotation
+* genomealign
+
+.. note:: ``type`` is case insensitive.
+
+name
+~~~~
+
+*Requried*. ``name`` specifies the track name used internally by the browser. It's aso used for
+display as track legend if no label_ speficied. Value can be any string.
+
+label
+~~~~~
+
+*Optional*. ``label`` specifies the track legend displayed in the browser. It overrites the name_ arrtibute.
+Value can be any string.
+
+url
+~~~
+
+*Requried*. ``url`` contains the URL to the track file, need to be HTTP or HTTPS location string.
+
+.. important:: ``url`` is requried for all the tracks in binary format. While for gene annotaion tracks
+               like ``refGene``, it's not requried, since the data are stored in Mongo database. Another
+               case is ``ruler`` track, ``url`` is also not needed.
+
+
+metadata
+~~~~~~~~
+
+*Optional*. An object speficies the metadata of the track. Examples like::
+
+    "metadata": {
+        "sample": "bone",
+        "assay": "MRE"
+    }
+
+the value of each metadata term can be a **string** or a **list of string** with *hirarchical structure*, for
+example, the public Roamap hub have metadata definition like::
+
+    {
+        "url": "https://egg.wustl.edu/d/hg19/GSM997242_1.bigWig", 
+        "metadata": {
+            "Sample": [
+                "Adult Cells/Tissues", 
+                "Blood", 
+                "Other blood cells", 
+                "CD4+_CD25-_Th_Primary_Cells"
+            ],    
+            "Donor": [
+                "Donor Identifier", 
+                "Donor_332"
+            ],    
+            "Assay": [
+                "Epigenetic Mark", 
+                "Histone Mark", 
+                "H3", 
+                "H3K9", 
+                "H3K9me3"
+            ],    
+            "Institution": [
+                "Broad Institute"
+            ]     
+        },    
+        "type": "bigwig", 
+        "options": {
+            "color": "rgb(159,0,72)"
+        },    
+        "name": "H3K9me3 of CD4+_CD25-_Th_Primary_Cells"
+    }
+
+The list of metadata has order from more generic to more specific, and 
+this helps build the facet table hierarchy, make **search** and **filter** in track table easier.
+
+details
+~~~~~~~
+
+*Optional*. If you want to more information to be shown on right click the track, you can put
+them in ``details`` attribute, contents put here will be displayed when right click the track,
+and toggle the **More Information** dropdown menu::
+
+    "details": {
+        "data source": "Roadmap Project",
+        "date collected": "May 7 2016"
+    }
+
 options
--------
+~~~~~~~
+
+*Optional*. All track render options are placed in an object called ``options``.
+this object can have the following properties:
 
 color
-~~~~~
+^^^^^
+
+``color`` is used to define the color for the track, color name, RGB values can be used.
+For more about color name or RGB, please check https://www.w3schools.com/css/css_colors.asp.
 
 color2
-~~~~~~
+^^^^^^
+
+``color2`` is used to define the color for negative values from the track data. Default is
+the same as color_.
+
+backgroundColor
+
+``backgroundColor`` defines the background color of the track.
+
+height
+^^^^^^
+
+``height`` controls the height of the track, speficied in number, unit is *pixel*.
 
 yScale
-~~~~~~
+^^^^^^
+
+``yScale`` allows you to configure the track's y-scale, you can use *auto* or *fixed*
+here. *auto* means the y-scale will be calculated from the values in view region, from 0
+to maximal of values in view region. *fixed* means you can specify the *minimal* and *maximal* value.
 
 yMax
-~~~~
+^^^^
+
+``yMax`` used to define the *maximal* value of track y-axis. Value is number.
 
 yMin
-~~~~
+^^^^
+
+``yMin`` used to define the *minimal* value of track y-axis. Value is number.
+
+.. important:: If you need the track to be in *fixed* scale, you need to specify ``yScale`` to *fixed*
+               besides of set ``yMax`` and ``yMin``.
+
+colorAboveMax
+^^^^^^^^^^^^^
+
+``colorAboveMax`` defines the color when yScale_ set to *fixed*, and the value exceeds the value
+yMax_ defined.
+
+color2BelowMin
+^^^^^^^^^^^^^^
+
+``color2BelowMin`` defines the color when yScale_ set to *fixed*, and the value below the value
+yMin_ defined.
+
+displayMode
+^^^^^^^^^^^
+
+``displayMode`` specifies display mode for tracks, different tracks have different display mode
+supported. 
+
+
+.. list-table::
+   :widths: 25 50
+   :header-rows: 1
+
+   * - type
+     - display mode
+   * - bigWig
+     - *auto*, *bar*, *heatmap*
+   * - bedGraph
+     - *auto*, *bar*, *heatmap*
+   * - geneAnnotation
+     - *full*, *density*
+   * - HiC
+     - *arc*, *heatmap*
+   * - genomealign
+     - *rough*, *fine*

docs/installation.rst

@@ -1,29 +1,37 @@
 Installation
 ============
 
-Server-side
------------
+Setup
+-----
+* install NodeJS from https://nodejs.org/en/
+* install MongoDB from https://www.mongodb.com/
 
-Enter the ``backend`` directory.  ``npm install``\ , and then ``npm run setup``.  MongoDB must be running.
+.. note:: Feel free to use any package manager tool on your system to install them. Like ``brew`` etc.
 
-Running
-~~~~~~~
+Then enter the ``backend`` directory. Type
+``npm install``\ , and then ``npm run setup``.  This step will load the gene annotation data
+to MongoDB database. (Make sure MongoDB server is running). Go to the ``frontend`` directory,
+type ``npm install`` to install dependent packages.
 
-#. Make sure MongoDB is running.
-#. Enter the ``backend`` directory.
-#. ``npm start``.
-#. Enter the ``frontend`` directory.
-#. ``npm start``.
+Start the browser
+-----------------
 
-Client-side
------------
+#. Make sure MongoDB is running
+#. Enter the ``backend`` directory
+#. type ``npm start``
+#. Enter the ``frontend`` directory
+#. type ``npm start``
+
+The browser is now accessible from http://localhost:3000/browser.
+
+Frontend code architeture
+-------------------------
 
 Quick tour
 ~~~~~~~~~~
 
 The client code is in the ``frontend`` folder.  Here is a quick tour of ``frontend/src``\ :
 
-
 * ``components``\ : All React components.
 
   * ``genomeNavigator``\ : the navigation bar at the top that allows users to navigate
@@ -40,7 +48,6 @@ Suggested order of reading
 
 If you plan to understand the app as a whole, here's a suggested order of code to read:
 
-
 #. ``Feature``\ : a feature or annotation in the genome
 #. ``NavigationContext``\ : a list of ``Feature`` that represents everywhere a user can navigate.  If the ``Feature``\ s are
    actually entire chromosomes, then the user can effectively navigate the whole genome.
@@ -57,7 +64,6 @@ Make a new TrackConfig
 Make a new class that extends ``TrackConfig``\ , or one of its subclasses.  This class packages many essential track
 characteristics:
 
-
 * ``getComponent()`` - gets the component that renders the main visualizer and legend of the track.
 * ``getMenuComponents()`` - specifies context menu items in an array of components.  You can choose existing ones
   in the ``contextMenu`` directory, or make new ones.
@@ -70,14 +76,12 @@ Just work on making the browser render *some* temporary placeholder at first.
 Specify when to use the TrackConfig
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-
 #. Import your new TrackConfig into ``trackConfig/getTrackConfig.js``.
 #. Add an appropriate entry to ``TYPE_NAME_TO_SUBTYPE``\ , which maps track type name to track renderer.
 
 Write a new track visualizer component (implement ``getComponent()``\ )
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-
 #. Make a new component expecting to receive a bunch of props from ``TrackContainer``.  ``Track.js`` documents the props
    to expect.
 #. If you need data, assume it will come through the ``data`` prop.  We will add data fetch in the next step.
@@ -110,7 +114,6 @@ components.  After you use this function, a component will automatically receive
 Specify context menu items with an array of components.  You can choose existing ones in the ``contextMenu`` directory, or
 make new ones.
 
-
 * Make sure the method returns Component *classes*\ , not component instances.
 
 3.  Specify default options
@@ -133,7 +136,6 @@ second or more of computation -- very noticable to the user!
 React (and other) gotchas
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-
 * On Macs, control + click is the same as a right click, which fires a ``contextmenu`` event.  Note that ``click`` events
   do not fire on ``contextmenu`` events.  The ``mousedown`` and ``mouseup`` events will still fire, though.
 * When using native DOM events, they take priority over React events.  This is because React waits for events to bubble
@@ -148,7 +150,6 @@ React (and other) gotchas
 Lessons trying to refactor into WebWorkers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-
 #. Data fetch and track display options are intimately related.  For example, what if someone wants HiC data and
    selects the 5KB resolution option?
 #. Thus, for each track type, we have one object that gets the track component, default rendering options, and data