Continuing work to improve tutorial pages, for Viz and Enrich tabs.

Author: travis-m-blimkie

docs/enrich.md

@@ -4,31 +4,46 @@ layout: default
 nav_order: 4
 ---
 
-SeptiSearch includes the ability to upload a list of your own genes (e.g. those
+# Perform Pathway Enrichment
+
+## Overview
+SeptiSearch includes the ability to upload any list of genes (e.g. those
 identified as differentially expressed in an RNA-Seq experiment) and test them
-for enriched Reactome pathways using
-[ReactomePA](https://bioconductor.org/packages/ReactomePA), as well as MSigDB's
-Hallmark gene sets and GO terms via
-[enrichR](https://cran.r-project.org/package=enrichR). This functionality is
-designed to complement the use of GSVA (the next tab), which tests your data for
-the dysregulation of the curated sepsis gene sets.
-
-- You have a few options for submitting data here:
-    - Use the "Load example data" button to load a preselected list of genes
-    - You can paste your own list of genes as a single column, with one gene per
-      line. Submitted genes IDs can be Ensembl, Entrez, or HGNC names.
-    - From the Explore the Database (ADD LINK) tab, select a
-      single gene set in the top table, then use the "Test this gene set for
-      enriched pathways" button to send the genes to the Enrichment tab
-- Next, the "1. Perform gene ID mapping" button will be enabled, which will
+for enriched Reactome pathways using [ReactomePA](https://bioconductor.org/packages/ReactomePA),
+as well as MSigDB's Hallmark gene sets and GO terms via [enrichR](https://cran.r-project.org/package=enrichR).
+This functionality is designed to complement the use of GSVA (the next tab), 
+which tests your data for the dysregulation of the curated sepsis gene sets.
+
+## Supported input types
+You have a few options for submitting data to SeptiSearch for pathway enrichment:
+
+1. Use the "Load example data" button to load a preselected list of genes
+2. Paste your own list of genes into the input field as a single column, with
+one gene per line
+  - Submitted genes IDs can be Ensembl, Entrez, or HGNC names; the ID type is
+  automatically detected, and mapping is performed as needed
+3. From the [Explore the Database](explore) tab, select a single gene set in the
+top table, then use the "Test this gene set for enriched pathways" button to
+send the genes to the Enrichment tab
+
+## Running pathway enrichment
+Once you've added genes via one of the above methods, you can proceed with the
+next steps to test your genes:
+
+- The "1. Perform gene ID mapping" button will now be enabled, which will
   complete any necessary mapping steps prior to enrichment testing
-- Once the ID mapping is completed, you can hit the "2. Submit genes for pathway
-  enrichment" button to run the tests.
-- Your results will be displayed in two tables; one containing Reactome pathways
-  identified by ReactomePA, and the second containing GO terms and MSigDB
-  Hallmark gene sets found by enrichR; use the buttons to switch between the
-  two. Hover your cursor over the column names to see a description of each.
-  Both tables can be downloaded using the buttons at the bottom of the
-  sidebar.
-
-![Table of enrichment results, from ReactomePA.](../assets/images/t6.png)  
+- A confirmation message will appear to confirm your genes have been mapped; 
+  click "OK" or anywhere outside the popup to dismiss it
+- When the ID mapping is completed, you can then press the "2. Submit genes for
+  pathway enrichment" button to run the enrichment tests
+- Depending on the number of genes uploaded, this may take up to 30 seconds to
+  complete - please be patient!
+
+Your results will be displayed in two tables; one containing Reactome pathways
+identified by ReactomePA, and the second containing GO terms and MSigDB
+Hallmark gene sets found by enrichR. You can use the buttons to switch between
+the two tables. If you're unsure what any of the columns mean, hover your
+cursor over the column names to see a brief description. Both tables can be
+then downloaded using the buttons at the bottom of the sidebar.
+
+![Table of enrichment results, from ReactomePA.](../assets/images/t6.png)

docs/explore.md

@@ -4,6 +4,8 @@ layout: default
 nav_order: 2
 ---
 
+# Explore the Database
+
 ## Overview
 This tab allows you to easily browse and search the SeptiSearch database.
 Entries are organized by Gene Set Name, which is a unique identifier given to a

docs/visualize.md

@@ -4,21 +4,45 @@ layout: default
 nav_order: 3
 ---
 
-The second tab provides a more visual way of search the curated gene sets, with
-a greater focus on the molecules frequently occuring within SeptiSearch.
+# Visualize the Database
 
-The plot shows the most common molecules in the database, coloured by COVID
-status, with the sidebar on the left providing a number of ways to filter the
-data. The "Reset this page" button at the bottom of the sidebar will reset all
-inputs, returning the plot to its original state.
+## Overview
+This tab provides a way to visualize SeptiSearch's curated gene sets, with
+a greater focus on which molecules frequently occur within the database.
+
+## Interacting with the plot
+The plot that appears shows the most common molecules in the database, coloured
+by COVID status, with the sidebar on the left providing a number of ways to
+filter the data. This plot, made with [plotly](https://plotly.com/r/), is 
+interactive in a number of ways:
+
+- Hovering over any bar with your cursor will display the molecule's name and 
+  both its total number of occurences, and occurrences by COVID status
+- Click-and-drag from side-to-side to zoom in on a region of the x-axis
+- At the top right of the plot there are a number of additional controls you can
+  use
 
 ![Hover over a column in the plot to see the details for that molecule.](../assets/images/t4.png)
 
-You can click one of the bars in the plot to show all entries for that molecule
-in SeptiSearch, and download this table using the button at the bottom of the
-sidebar.
+- Additionally, you can click on a bar in the plot to bring up a table below
+which lists all entries for that molecule in SeptiSearch.
+
+![Click a bar in the plot to list all its entries in SeptiSearch.](../assets/images/t5.png)
+
+## Filtering the data
+The sidebar contains a number of input fields you can use to refine what data is
+included in the visualization.
+
+- The first lets you include only COVID or non-COVID related studies, and will
+  show only the corresponding molecules based on their gene set
+- The next three fields will filter the data based on the assigned Age Group,
+  Tissue Class, and Timepoint
+  - These three options can be combined in any way you like
+  - More than one option can be chosen for each field, e.g. you can see what the
+  	top molecules are for Adults, in any type of Blooc Cell using the Age Group
+  	and Tissue Class input
+  - Check SeptiSearch's About page (the last tab listed at the top of the page)
+    for more details on these labels and how they're defined
 
-Additionally, as this plot is rendered by Plotly, there are a number of other 
-ways in which you can interact with it, such as click-and-drag to zoom in on a 
-specific part of the plot. The controls at the top right of the plot also 
-provide a number of additional options.
+{: .note }
+You can use the "Reset this page" button at the bottom of the sidebar to restore the plot and all filters to their original state.