Merge branch 'master' of github.com:Maayanlab/clustergrammer-docs

docs/_build_html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 68ebe9801c3761bbeaf2d725f3f93568
+config: 51e44d81d55c6c120717c7044a43b723
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_build_html/_sources/app_integration.rst.txt

@@ -6,7 +6,7 @@ Clustergrammer can be integrated into web applications to dynamically produce in
 
 Enrichr
 =======
-The enrichment analysis tool, `Enrichr`_, uses Clustergrammer to produce dynamic heatmaps of enriched terms as columns and user input genes as rows. This helps users to understand the relationships between their input genes and the returned enriched terms.
+The enrichment analysis tool, `Enrichr`_, uses Clustergrammer to produce dynamic heatmaps of enriched terms as columns and user input genes as rows, which helps users understand the relationships between their input genes and enriched terms.
 
 .. figure:: _static/enrichr_screenshot_logo.png
   :width: 550px
@@ -38,7 +38,7 @@ L1000CDS2
   :alt: L1000CDS2 Clustergram
   :target: http://amp.pharm.mssm.edu/clustergrammer/l1000cds2/55e0b68a5bf3665f1a726bfa
 
-  `L1000CDS2`_ uses Clustergrammer to produce interactive visualizations of input gene signatures and perturbation signatures that mimick or reverse the user's user-input signature. A users's input signature is shown as rows with gene-expression levels shown as row-bars (red/blue for up/down expression) and perturbations found to mimic/reverse their signature are shown as columns in the heatmap.
+  `L1000CDS2`_ uses Clustergrammer to produce interactive visualizations of input gene signatures and perturbation signatures that mimick or reverse the user's user-input signature. A users's input signature is shown as rows with gene expression levels shown as row-bars (red/blue for up/down expression) and perturbations found to mimic/reverse their signature are shown as columns in the heatmap.
 
 Harmonizome
 ===========

docs/_build_html/_sources/biology_specific_features.rst.txt

@@ -2,13 +2,13 @@
 
 Biology-Specific Features
 -------------------------
-Clustergrammer was developed to visualize high-dimensional biological data (e.g. genome-wide expression data), but it can also generally be applied to any high-dimensional data (e.g. a matrix). Clustergrammer has several biology-specific features that facilitate the analysis of gene-level biological data, such as: gene-expression data, proteomics-data, etc. To take advantage of these features, row names must be genes. See the `CCLE Explorer`_ for examples of gene-expression data. These optional biology-specific features are available in the :ref:`clustergrammer_web` as well as the :ref:`clustergrammer_widget` and will automatically activate if the row-names are genes.
+Clustergrammer was developed to visualize high-dimensional biological data (e.g. genome-wide expression data), but it can also generally be applied to any high-dimensional data. Clustergrammer has several biology-specific features that facilitate the analysis of gene-level biological data, such as: gene expression data, proteomics-data, etc. To take advantage of these features, row names must be official gene names. See the `CCLE Explorer`_ for examples of visualizing gene expression data. These optional biology-specific features are available in the :ref:`clustergrammer_web` as well as the :ref:`clustergrammer_widget` and will automatically activate if the row-names are genes.
 
 .. _hzome_gene_info:
 
 Mouseover Gene Name and Description
 ===================================
-The human genome consists of over 20,000 genes and modern high-throughput measurements are capable of making measurements across the entire genome (e.g. genome-wide expression studies). Human genes have official gene symbols (e.g. *EGFR*) that are frequently used to label genes in these datasets. Since no biologist can be knowledgeable about every gene in the genome a common and repetitive task for biologists is looking up the names and descriptions of genes in a dataset or visualization. To streamline this activity, Clustergrammer automatically displays the full name and description of a gene (provided by data aggregated through the `Harmonizome`_) as a tooltip when a user mouses over a gene label (see screenshot below). This simple feature speeds up analysis of large gene-level datasets.
+The human genome consists of over 20,000 genes and modern high-throughput measurements are capable of making measurements across the entire genome (e.g. genome-wide expression studies). Human genes have official gene symbols (e.g. *EGFR*) that are frequently used to label genes in these datasets. Since no biologist can be knowledgeable about every gene in the genome a common and repetitive task is looking up the names and descriptions of genes in a dataset or visualization. To streamline this activity, Clustergrammer automatically displays the full name and description of a gene (provided by data aggregated through the `Harmonizome`_) as a tooltip when a user mouses over a gene label (see screenshot below). This simple feature speeds up analysis of large gene-level datasets.
 
 .. figure:: _static/gene_info.png
   :width: 700px
@@ -22,11 +22,11 @@ The JavaScript file `hzome_functions.js`_ provides this functionality by utilizi
 
 Enrichment Analysis
 ===================
-The field of biology has amassed an enormous amount of information about the genes in living organisms such as: function, disease-association, up-stream regulators, protein-level binding partners, etc. Integration of this information can help biologists understand patterns in their data. For instance, enrichment analysis a popular method to identify biological information specific to a list of genes -- e.g. a biologist may use enrichment analysis to identify up-stream regulatory transcription factors that specifically target their measured set of up-regulated genes and thereby form hypotheses about potential up-stream regulators in their system.
+The field of biology has amassed an enormous amount of information about the genes in living organisms such as: function, disease-association, up-stream regulators, protein-level binding partners, etc. Integration of this information can help biologists understand patterns in their data. For instance, enrichment analysis is a popular method to identify biological information specific to a list of genes -- e.g. a biologist can use enrichment analysis to identify up-stream regulatory transcription factors that specifically target their a set of up-regulated genes and thereby form hypotheses about potential up-stream regulators.
 
 **Export to Enrichr**
 
-When a user visualizes a matrix with genes as rows, Clustergrammer automatically enables integration with the enrichment analysis tool `Enrichr`_. Users can export a set of clustered genes to `Enrichr`_ using the interactive dendrogram (see screenshot) or import enriched terms into the visualization using :ref:`Enrichrgram <enrichrgram>`.
+When a user visualizes a matrix with genes as rows, Clustergrammer automatically enables integration with the enrichment analysis tool `Enrichr`_. Users can export a set of clustered genes to `Enrichr`_ using the interactive dendrogram (see screenshot) or import enriched terms into the visualization using the :ref:`Enrichrgram <enrichrgram>` functionality.
 
 .. figure:: _static/send_to_Enrichr_modal.png
   :width: 600px
@@ -39,8 +39,11 @@ When a user visualizes a matrix with genes as rows, Clustergrammer automatically
 
 **Enrichrgram**
 
-Users can also import biological information about their genes directly into the visualization (see screenshot below). Simply click the Enrichr-logo at the top-left of the heatmap to bring up a list of libraries from Enrichr, then click on a library to obtain enriched terms for your genes of interest. For instance, clicking on 'ChEA 2016' will enrich for up-stream transcription factors. The enriched terms are shown as row categories, which enables users to see which genes are associated with each term. The row-category titles give the enriched term name, and the red-bars represent the significance of the enrichment (see `Enrichr combined score`_). Users can run enrichment analysis on specific clusters of genes by filtering the matrix to only show only their genes of interest: e.g. use the dendrogram Crop buttons or Brush-Crop buttons to select a subset of genes for analysis.
+Enrichrgram enables users to find biological information specific to their genes of interest (using `Enrichr`_) and import this information directly into the visualization as row categories (see screenshot below). Enrichrgram can be run on the front or back end (using the :ref:`clustergrammer_py_api` to pre-calculate results). This feature enables enrichment analysis to be performed within the visualization itself by both the original author of the visualization and subsequent viewers.
 
+**Enrichrgram Front End**
+
+Enrichrgram on the front end is available to anyone viewing the visualization and can be used by simply clicking the red DNA-like Enrichr logo on the top left of the heatmap, which brings up a list of Enrichr libraries to choose from. To perform enrichment analysis, choose a library and Enrichrgram will return enriched terms from this library that are specifically associated with your list of genes (P-value bars indicate the degree of specificity). For instance, clicking on *ChEA 2016* will calculate enrichment for up-stream transcription factors. The enriched terms are shown as row categoris, which enables users to see which genes are associated with each term. Row-category titles show the enriched term and the red-bars represent the significance of the enrichment (see `Enrichr combined score`_). Users can run enrichment analysis on a specific cluster of genes by filtering the matrix to only show only their genes of interest. This filtering can be done using the Dendrogram Crop buttons (see :ref:`interactive_dendrogram`) or Brush-Crop button (see :ref:`crop`) to select a subset of genes for analysis.
 
 .. figure:: _static/enrichrgram_results.png
   :width: 900px
@@ -49,8 +52,16 @@ Users can also import biological information about their genes directly into the
 
   Users can perform enrichment analysis to find biological information specific to their genes (e.g. a cluster of genes). Users can select from several enrichment libraries, and the top 10 enriched terms will be shown as rows categories. The combined scores for the enriched terms will be shown as red bars behind the row category titles.
 
-`Enrichrgram.js`_ provides this functionality and works with the :ref:`clustergrammer_js` API to depict enriched terms and their associated genes as row categories. The update-row-category functionality can be extended by developers for other domain-specific problems.
+Note that Enrichrgram results run on the front end are not permanent and will be lost after refreshing the page, but the matrix with enrichment results can be downloaded using the :ref:`download` button. Enrichment results can be permanently added to the visualization from the back end using the ``enrichgram`` method described below.
+
+
+**Enrichrgram Back End**
+
+To permanently add pre-calculated enrichment results to a visualization run the ``enrichrgram`` method described in the :ref:`clustergrammer_py_api` before clustering. The Jupyter notebook `Clustergrammer_CCLE_Notebook.ipynb`_ demonstrates how to use the ``enrichrgram`` method to pre-calculate enrichment analysis results for a visualization.
+
+The `Enrichrgram.js`_ library provides this functionality on the front end and works with the :ref:`clustergrammer_js` API to depict enriched terms and their associated genes as row categories. The update-row-category functionality can be extended by developers for other domain-specific problems.
 
+.. _`Clustergrammer_CCLE_Notebook.ipynb`: http://nbviewer.jupyter.org/github/MaayanLab/CCLE_Clustergrammer/blob/master/notebooks/Clustergrammer_CCLE_Notebook.ipynb
 .. _`Enrichrgram.js`: https://github.com/MaayanLab/clustergrammer/blob/master/js/Enrichrgram.js
 .. _`hzome_functions.js`: https://github.com/MaayanLab/clustergrammer/blob/master/js/hzome_functions.js
 .. _`load_clustergram.js`: https://github.com/MaayanLab/clustergrammer/blob/master/js/load_clustergram.js

docs/_build_html/_sources/building_webpage.rst.txt

@@ -17,24 +17,23 @@ Users can obtain a permanent link to their visualization by manually uploading t
 
 Adding Clustergrammer to a Page
 ===============================
-The :ref:`clustergrammer_js` library can be used to generate an interactive visualization in your webpage. Simply include the :ref:`clustergrammer_js` script in your page and load the pre-calculated :ref:`visualization-JSON <visualization_json>` to generate a visualization. Alternatively, :ref:`clustergrammer_js` can also be included as a node module (see `Clustergrammer-Widget source code`_ for an example with Webpack), or can be used with `RequireJS`_ (see `Clustergrammer RequireJS example`_).
+In addition to embedding a visualization hosted by the :ref:`clustergrammer_web` application developers add a Clustergrammer to directly their own page using the core libraries:
 
+**Clustergrammer-JS**: The front-end :ref:`clustergrammer_js` JavaScript library generates the interactive visualization and can be installed via npm: ``npm install Clustergrammer``. See the :ref:`example_pages` for templates to build a site with your visualization
 
-Clustergrammer can be used to generate interactive visualizations for your own web application by: using the :ref:`clustergrammer_js` library on your site, or embedding a visualization provided by the :ref:`clustergrammer_web`.
+**Clustergrammer-PY**: The back-end :ref:`clustergrammer_py` Python library clusters a matrix of data and makes the JSON for the front end and can be installed using pip: ``pip install --upgrade clustergrammer``. See the :ref:`clustergrammer_py_workflow` for examples of how cluster your matrix and generate the :ref:`visualization_json`
 
+To make a page, simply include the :ref:`clustergrammer_js` script in your page and load the pre-calculated :ref:`visualization-JSON <visualization_json>` to generate a visualization (use :ref:`clustergrammer_py` to generate this JSON).
 
-The easiest way to generate a visualization of your own data on a webpage is to:
+:ref:`clustergrammer_js` can also be included as a node module (see `Clustergrammer-Widget source code`_ for an example with Webpack), or can be used with `RequireJS`_ (see `Clustergrammer RequireJS example`_).
 
-#. Follow the :ref:`clustergrammer_py_workflow` to cluster your matrix and generate the :ref:`visualization_json`
-#. Then use the :ref:`example_pages` as templates to build a site with your visualization
 
-These examples require Clustergrammer's JavaScript and Python libraries:
+Jupyter Notebook Webpages
+=========================
 
-#. the front-end :ref:`clustergrammer_js` JavaScript library generates the interactive visualization
-#. the back-end :ref:`clustergrammer_py` Python library clusters a matrix of data and makes the JSON for the front end
-
-The following libraries can be installed using: npm (``npm install Clustergrammer``) and pip (``pip install --upgrade clustergrammer``), respectively.
+The :ref:`clustergrammer_widget` can also be used in combination with `nbviewer`_ to share static Jupyter notebook webpages with embedded interactive Clustergrammer visualizations. This is one of the easiest ways to generate a webpage with Clustergrammer visualizations and several of the :ref:`case_studies` are Jupyter notebooks.
 
+.. _`nbviewer`: http://nbviewer.jupyter.org/
 .. _`homepage`: http://amp.pharm.mssm.edu/clustergrammer
 .. _`Clustergrammer-Widget source code`: https://github.com/MaayanLab/clustergrammer-widget
 .. _`RequireJS`: http://requirejs.org/