[DOC] Reporting documentation (#465)

* Added html template for report * doc: initial commit of reporting template * doc: save out html for testing * fix: add missing bokeh js script * fix: unescape HTML ugly way * fix: add missing cdn's * enh: switch to generate_report structure * sty: switch back to pure CSS from bootstrap * fix: differently update template for content * sty: add jupyter notebooks to git ignore * enh:initial commit of dynamic plots * fix: patch unpaired bracket * enh:modularized dynamic kappa/rho plots * enh:docstrings added to KappaRho_DynPlot.py * Force figures default, fold viz into reporting module * enh:TS and Spectrum are now dynamic plots * sty: initial refactor of dynamic figures * fix: re-introduce func to load comp_table * sty: finalize rough refactor * fix: patch linting errors * Initial commit of documentation page for reports * subsections added * doc:plot descriptions completed. new figures. * doc: continue refactor * doc:additional info and pics of icons * doc: finalized first draft of report docs * Advanced on dynamic_figures * Made the refactored code work * fix: new year, new approach * tmp: non-functioning reporting code * Fixes bug * Fixes bug * Added new function to generate html report and removed tempita calls * Added FFT and time series plots * Made template subsitute work and updated necessary bokeh version * Changes html title * remove time series, fft plots * fix: remove unescapes * fix: patch incorrect imports * fix: add missing bokeh import * fix: spelling mistake 🤦 * fix: reflect reorg in get_coeffs call * fix: correct expected test outputs * fix: don't designate file path when saving report * fix: combine generate, html report functions * fix: ignore missing columns in df.drop, to better handle multiple params * Dynamic figures are now two rows, static figure is on the right. Removed the cute dog link and made adding report.txt text to bottom of report automatic * Added new line after References in report.txt * Removes BeautifulSoup dependency in favor of an object tag and changes some CSS styles * enh: switch to grid layout, style About section, add links to navbar * doc: update no-png to no-reports * Addresses PR comments * modifiation of setup.py to properly install all reporting directories * Use relative path for static figures on report * Add version check for bokeh figures * Fix typo Co-authored-by: Taylor Salo <[email protected]> * Removed visual reports and added new reports page to sidebar * Update docs/reporting.rst Co-authored-by: Joshua Teves <[email protected]> * Update docs/reporting.rst Co-authored-by: Joshua Teves <[email protected]> * Update docs/reporting.rst Co-authored-by: Elizabeth DuPre <[email protected]> * Update docs/reporting.rst Co-authored-by: Elizabeth DuPre <[email protected]> * Update docs/reporting.rst Co-authored-by: Elizabeth DuPre <[email protected]> * Update docs/reporting.rst Co-authored-by: Elizabeth DuPre <[email protected]> * Update reporting page figures and text * Update beta map text * Update docs/reporting.rst Co-authored-by: Joshua Teves <[email protected]> * Update docs/reporting.rst Co-authored-by: Joshua Teves <[email protected]> * Update docs/reporting.rst Co-authored-by: Joshua Teves <[email protected]> * Move note higher up the page Co-authored-by: smoia <[email protected]> Co-authored-by: Elizabeth DuPre <[email protected]> Co-authored-by: eurunuela <[email protected]> Co-authored-by: Eneko Uruñuela <[email protected]> Co-authored-by: Taylor Salo <[email protected]> Co-authored-by: Joshua Teves <[email protected]>
ME-ICA · Oct 19, 2020 · 0eaa3ba · 0eaa3ba
1 parent 65dda07
commit 0eaa3ba
Show file tree

Hide file tree

Showing 20 changed files with 170 additions and 78 deletions.
diff --git a/docs/_static/rep01_betaMap.png b/docs/_static/rep01_betaMap.png
diff --git a/docs/_static/rep01_fftPlot.png b/docs/_static/rep01_fftPlot.png
diff --git a/docs/_static/rep01_kappaScree.png b/docs/_static/rep01_kappaScree.png
diff --git a/docs/_static/rep01_kapparhoScatter.png b/docs/_static/rep01_kapparhoScatter.png
diff --git a/docs/_static/rep01_overallview.png b/docs/_static/rep01_overallview.png
diff --git a/docs/_static/rep01_rhoScree.png b/docs/_static/rep01_rhoScree.png
diff --git a/docs/_static/rep01_tool_areazoom.png b/docs/_static/rep01_tool_areazoom.png
diff --git a/docs/_static/rep01_tool_crosshair.png b/docs/_static/rep01_tool_crosshair.png
diff --git a/docs/_static/rep01_tool_hover.png b/docs/_static/rep01_tool_hover.png
diff --git a/docs/_static/rep01_tool_pan.png b/docs/_static/rep01_tool_pan.png
diff --git a/docs/_static/rep01_tool_reset.png b/docs/_static/rep01_tool_reset.png
diff --git a/docs/_static/rep01_tool_save.png b/docs/_static/rep01_tool_save.png
diff --git a/docs/_static/rep01_tool_select.png b/docs/_static/rep01_tool_select.png
diff --git a/docs/_static/rep01_tool_wheelzoom.png b/docs/_static/rep01_tool_wheelzoom.png
diff --git a/docs/_static/rep01_tools.png b/docs/_static/rep01_tools.png
diff --git a/docs/_static/rep01_tsPlot.png b/docs/_static/rep01_tsPlot.png
diff --git a/docs/_static/rep01_varexpPie.png b/docs/_static/rep01_varexpPie.png
diff --git a/docs/index.rst b/docs/index.rst
@@ -157,6 +157,7 @@ tedana is licensed under GNU Lesser General Public License version 2.1.
    usage
    approach
    outputs
+   reporting
    faq
    support
    contributing

diff --git a/docs/outputs.rst b/docs/outputs.rst
@@ -198,81 +198,3 @@ An example report
   Sørensen, T. J. (1948). A method of establishing groups of equal amplitude in plant sociology based on similarity of species content and its application to analyses of the vegetation on Danish commons. I kommission hos E. Munksgaard.
 
   Van Der Walt, S., Colbert, S. C., & Varoquaux, G. (2011). The NumPy array: a structure for efficient numerical computation. Computing in Science & Engineering, 13(2), 22.
-
-Visual reports
---------------
-Static visual reports can be generated by using the ``--png`` flag when calling
-tedana from the command line.
-Images are created and placed within the output directory, in a folder labeled
-``figures``.
-
-These reports consist of three main types of images.
-
-Component Images
-````````````````
-.. image:: /_static/example_good_component.png
-  :align: center
-
-For each component identified by tedana, a single image will be created.
-Above is an example of an accepted component.
-These are designed for an up-close inspection of both the spatial and temporal
-aspects of the component, as well as ancillary information.
-
-The title of the plot provides information about variance, kappa and rho values
-as well as the reasons for rejection, if any (see above for codes).
-
-Below this is the component timeseries, color coded on the basis of its
-classification.
-Green for accepted, Red for rejected, Black for ignored or unclassified.
-
-Slices are then selected from sagittal, axial and coronal planes, to highlight
-the component pattern.
-By default these images used the red-blue colormap and are scaled to 10% of the
-max beta value.
-
-.. note::
-  You can select your own colormap to use by specifying its name when calling
-  tedana with ``--png-cmap``.
-  For example, to use the bone colormap, you would add ``--png-cmap bone``.
-
-Finally, the bottom of the image shows the Fast Fourier Transform of the
-component timeseries.
-
-.. tip::
-  Look for your fundamental task frequencies here!
-
-.. image:: /_static/example_bad_component.png
-  :align: center
-
-Above, you can review a component that was rejected.
-In this case, the subject moved each time the task was performed - which
-affected single slices of the fMRI volume.
-This scan used multiband imaging (collecting multiple slices at once), so
-the motion artifact occurs in more than once slice.
-
-
-Kappa vs Rho Scatter Plot
-`````````````````````````
-.. image:: /_static/example_Kappa_vs_Rho_Scatter.png
-  :align: center
-
-This diagnostic plot shows the relationship between kappa and rho values for
-each component.
-
-This can be useful for getting a big picture view of your data or for comparing
-denoising performance with various fMRI sequences.
-
-Double Pie Chart
-````````````````
-.. image:: /_static/example_Component_Overview.png
-  :align: center
-
-This diagnostic plot shows the relative variance explained by each
-classification type in the outer ring, with individual components on the inner
-ring.
-If a low amount of variance is explained, this will be shown as a gap in the
-ring.
-
-.. tip::
-  Sometimes large variance is due to singular components, which can be
-  easily seen here.
diff --git a/docs/reporting.rst b/docs/reporting.rst
@@ -0,0 +1,169 @@
+#####################
+ICA Components Report
+#####################
+
+The reporting page for the tedana decomposition presents a series
+of interactive plots designed to help you evaluate the quality of your
+analyses. This page describes the plots forming the reports and well as
+information on how to take advantage of the interactive functionalities.
+You can also play around with `our demo`_.
+
+.. _our demo: https://me-ica.github.io/tedana-ohbm-2020/
+
+Report Structure
+================
+
+The image below shows a representative report, which has two sections: a) the summary view,
+and b) the individual component view.
+
+.. image:: /_static/rep01_overallview.png
+  :align: center
+
+.. note::
+  When a report is initially loaded, as no component is selected on the
+  summary view, the individual component view appears empty.
+
+Summary View
+------------
+This view provides an overview of the decomposition and component
+selection results. It includes four different plots.
+
+* **Kappa/Rho Scatter:** This is a scatter plot of `Kappa` vs. `Rho` features for all components.
+  In the plot, each dot represents a different component. The x-axis represents the kappa feature, and the
+  y-axis represents the rho feature. These are two of the most
+  informative features describing the likelihood of the component
+  being BOLD or non-BOLD. Additional information is provided via color
+  and size. In particular, color informs about its classification
+  status (e.g., accepted, rejected); while size relates to
+  the amount of variance explained by the component (larger dot,
+  larger variance).
+.. image:: /_static/rep01_kapparhoScatter.png
+  :align: center
+  :height: 400px
+
+* **Kappa Scree Plot:** This scree plot provides a view of the components ranked by `Kappa`.
+  As in the previous plot, each dot represents a component. The color of the dot informs us
+  about classification status. In this plot, size is not related to variance explained.
+.. image:: /_static/rep01_kappaScree.png
+  :align: center
+  :height: 400px
+
+* **Rho Scree Plot:** This scree plot provides a view of the components ranked by `Rho`.
+  As in the previous plot, each dot represents a component. The color of the dot informs us
+  about classification status. In this plot, size is not related to variance explained.
+.. image:: /_static/rep01_rhoScree.png
+  :align: center
+  :height: 400px
+
+* **Variance Explained Plot:** This pie plot provides a summary of how much variance is explained
+  by each individual component, as well as the total variance explained by each of the three
+  classification categories (i.e., accepted, rejected, ignored). In this plot, each component is
+  represented as a wedge, whose size is directly related to the amount of variance explained. The
+  color of the wedge inform us about the classification status of the component. For this view,
+  components are sorted by classification first, and inside each classification group by variance
+  explained.
+.. image:: /_static/rep01_varexpPie.png
+  :align: center
+  :height: 400px
+
+Individual Component View 
+-------------------------
+This view provides detailed information about an individual 
+component (selected in the summary view, see below). It includes three different plots.
+
+* **Time series:** This plot shows the time series associated with a given component
+  (selected in the summary view). The x-axis represents time (in units of TR), and the
+  y-axis represents signal levels (in arbitrary units). Finally, the color of the trace
+  informs us about the component classification status.
+
+.. image:: /_static/rep01_tsPlot.png
+  :align: center
+  :height: 150px
+
+* **Component beta map:** This plot shows the map of the beta coefficients associated with
+  a given component (selected in the summary view). The colorbar represents the amplitude
+  of the beta coefficients.
+
+.. image:: /_static/rep01_betaMap.png
+  :align: center
+  :height: 400px
+
+* **Spectrum:** This plot shows the spectrogram associated with a given component
+  (selected in the summary view). The x-axis represents frequency (in Hz), and the
+  y-axis represents spectral amplitude.
+
+.. image:: /_static/rep01_fftPlot.png
+  :align: center
+  :height: 150px
+
+Reports User Interactions
+=========================
+
+As previously mentioned, all summary plots in the report allow user interactions. While the 
+Kappa/Rho Scatter plot allows full user interaction (see the toolbar that accompanies the plot
+and the example below), the other three plots allow the user to select components and update the
+figures.
+
+.. image:: /_static/rep01_tools.png
+  :align: center
+  :height: 25px
+
+The table below includes information about all available interactions
+
+.. |Reset| image:: /_static/rep01_tool_reset.png
+  :height: 25px
+
+.. |WZoom| image:: /_static/rep01_tool_wheelzoom.png
+  :height: 25px
+
+.. |BZoom| image:: /_static/rep01_tool_areazoom.png
+  :height: 25px
+
+.. |CHair| image:: /_static/rep01_tool_crosshair.png
+  :height: 25px
+
+.. |Pan| image:: /_static/rep01_tool_pan.png
+  :height: 25px
+
+.. |Hover| image:: /_static/rep01_tool_hover.png
+  :height: 25px
+
+.. |Sel| image:: /_static/rep01_tool_select.png
+  :height: 25px
+
+.. |Save| image:: /_static/rep01_tool_save.png
+  :height: 25px
+
+============  =======  =======================================================
+Interaction   Icon     Description                                            
+============  =======  =======================================================
+Reset         |Reset|  Resets the data bounds of the plot to their values when
+                       the plot was initially created.
+
+Wheel Zoom    |WZoom|  Zoom the plot in and out, centered on the current      
+                       mouse location.
+
+Box Zoom      |BZoom|  Define a rectangular region of a plot to zoom to by     
+                       dragging the mouse over the plot region.
+
+Crosshair     |CHair|  Draws a crosshair annotation over the plot, centered on
+                       the current mouse position                    
+
+Pan           |Pan|    Allows the user to pan a plot by left-dragging a mouse
+                       across the plot region.
+
+Hover         |Hover|  If active, the plot displays informational tooltips 
+                       whenever the cursor is directly over a plot element.
+
+Selection     |Sel|    Allows user to select components by tapping on the dot
+                       or wedge that represents them. Once a component is
+                       selected, the plots forming the individual component
+                       view update to show component specific information. 
+
+Save          |Save|   Saves an image reproduction of the plot in PNG format.
+============  =======  =======================================================
+
+.. note:: 
+  Specific user interactions can be switched on/off by clicking on their associated icon within
+  the toolbar of a given plot. Active interactions show an horizontal blue line underneath their
+  icon, while inactive ones lack the line.
-Original file line number
+Diff line change
@@ Expand Up @@
        usage
        approach
        outputs
+       reporting
        faq
        support
        contributing
@@ Expand Down @@