[ENH] Initial visual reports (nilearn#2019)

* Add externals directory for tempita

* Add html report template

* wip: initial commit of NiftiMasker report

* Embed images in browser

* Minor CSS updates

* Add parameters table, non-responsive

* Add tooltip for docstring

* ENH: Avoid the use of iframes in the notebook

(nicer layout)

* MISC: cleaner inheritance

* Remove ReportMixin class

* Patch merge conflict

* Create reporting module

* Move computation to reporting method of masker

* Call local style sheets

* New nose-exclude dependency

* Correct handling of 3D images

* Revert nose-excludes, unpackage externals

* Re-introduce ReportMixin

* Re-package externals, add nose plugin to ignore

* temporarily remove non-functioning nose plugin

* Define __test__ attr to skip nosetest

* Fix doc error, ignore linting in tempita

* Remove externals from coverage

* Unpackage pure style sheets

* Remove externals from coverage reporting

* Add pure attribution, license

* Ask codecov directly (nicely)

* Initial tests for reporting

* Explicitly cast pathlib to str

* Add overlay on hover

* patch handling of single display images

* Try to be careful about closing things...

* fix: patch CI failure, add new text if hover

* Address @jeromedockes review

* Update images files to svg

* omit externals from coverage

* Move HTMLDocument to reporting

* Add warning re missing MPL import, fix check_html calls

* Move rm_file.py into reporting module

* Fix check_html again

* Move HTMLDocument to its own module

* Adding additional tests

* Retrigger Travis

* Fix flake8 errors... the joys of switching text editors

* Update examples to reference generate_report method

* Change language from HTML to report, add comment on use

* Update plot_nifti_simple example

* Add code comment to plot_nifti_simple

* Add in screenshots to showcase reporting

* Adjust scaling

* embed html reports

* Address review comments

* Fix iframe fenching

* Update path to static HTML

* Set height auto

* Testing raw html directive

* Break plot_mixed_gambles death spiral

* Initial commit of MNE report scraper

* Patch _ReportScraper

* Use iframe rather than html page

* define image_scrapers in sphinx conf

* Update nilearn/reporting/sphinx_report.py

Co-Authored-By: Eric Larson <[email protected]>

* Use get_iframe method

* Re-introduce whitespace in _SCRAPER_TEXT

* Re-trigger CI

* fix report in sphinx

* Fix sphinx_report

Indentation is also necessary

* STY: fix CSS

* Better example

* FIX: avoid displaying reports twice

* STY: more compact view

Without this, the font is too big compared to the font of the examples

* ENH: sphinx-gallery capture with repr_html

Also works for interactive plots such as view_img

* Update nilearn/reporting/sphinx_report.py

Co-Authored-By: Elizabeth DuPre <[email protected]>

* fix: correct dataset fetching

* Add niftimasker report screenshots for rst

* tst: initial tests for sphinx HTMLDocument embedding

* fix: patch location of overlay

* fix tst: do not rely on pytest fixture

* tst: ensure tmpdir is closed after testing

* fix: plot_nifti_simple fetcher

* STY: fix whitespace in embedeed reports

The CSS specified by the unclosing page (the nilearn website) was
getting in the way.

* STY: more styling to isolate from encompasing CSS

* STY: enclose reports with a border

* STY: tweak to limit scrollbars

* CSS to get a better box

This design makes the report really look like a box with a title.

* STY: change colormap on masker report

* STY: smaller reports in docs

* STY: deal gracefully with details overflow

* FIX: remove duplicate CSS rule

* STY: fix scrolling in jupyter

* Address @jeromedockes review

* STY: make reports work in vscode

Two problems arose:

- Default theme is dark
- The width was set wrong

* Add example with resampling to plot_mask_computation

* sty: update private attr in reporting

* Differentiate warns for not fit, no reporting

* fix: patch text in plot_mask_computation

* sty: linting changes

* fix: remove scaling to avoid jumping in page

* sty: make contour thicker for contrast

* Revert "fix: remove scaling to avoid jumping in page"

This reverts commit 250e995.

* fix: typo in sphinx_report

* fix: remove overlay for saving svg images

* Update nilearn/reporting/sphinx_report.py

Co-Authored-By: Gael Varoquaux <[email protected]>

* fix: update and extend test_html_report

* fix: remove leftover nosetests attribute

* Address @jeromedockes review

* Re-introduce mask_img_ in examples

* Generalize warnings in reporting

* Add whats_new entry for generate_report

* fix: patch whats_new entry

* sty: Update display of plot_roi figs for NiftiMasker docs

.coveragerc

@@ -1,4 +1,5 @@
 [run]
 branch = True
 parallel = True
-
+omit =
+    */nilearn/externals/*

Makefile

@@ -63,4 +63,3 @@ doc:
 .PHONY : pdf
 pdf:
 	make -C doc pdf
-

codecov.yml

@@ -0,0 +1,2 @@
+ignore:
+  - "*externals/.*"  # ignore folders and all its contents

doc/conf.py

@@ -281,6 +281,11 @@
 
 _python_doc_base = 'http://docs.python.org/3.6'
 
+# Scraper, copied from https://github.com/mne-tools/mne-python/
+from nilearn.reporting import _ReportScraper
+report_scraper = _ReportScraper()
+scrapers = ('matplotlib', report_scraper)
+
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
     'python': (_python_doc_base, None),
@@ -302,6 +307,7 @@
     'backreferences_dir': os.path.join('modules', 'generated'),
     'reference_url': {'nilearn': None},
     'junit': '../test-results/sphinx-gallery/junit.xml',
+    'image_scrapers': scrapers,
     }
 
 # Get rid of spurious warnings due to some interaction between
@@ -310,7 +316,6 @@
 # details
 numpydoc_show_class_members = False
 
-
 def touch_example_backreferences(app, what, name, obj, options, lines):
     # generate empty examples files, so that we don't get
     # inclusion errors if there are no examples for a class / module
@@ -327,3 +332,4 @@ def touch_example_backreferences(app, what, name, obj, options, lines):
 def setup(app):
     app.add_javascript('copybutton.js')
     app.connect('autodoc-process-docstring', touch_example_backreferences)
+    report_scraper.app = app

doc/manipulating_images/masker_objects.rst

@@ -136,12 +136,25 @@ mask computation parameters.
 The mask can be retrieved and visualized from the `mask_img_` attribute
 of the masker:
 
+.. literalinclude:: ../../examples/04_manipulating_images/plot_mask_computation.py
+    :start-after: # A NiftiMasker with the default strategy
+    :end-before: # Plot the generated mask using the .generate_report method
+
+.. figure:: ../auto_examples/04_manipulating_images/images/sphx_glr_plot_mask_computation_002.png
+    :target: ../auto_examples/04_manipulating_images/plot_mask_computation.html
+    :align: center
+    :scale: 40
+
+Alternatively, the mask can be visualized using the `generate_report`
+method of the masker. The generated report can be viewed in a Jupyter notebook,
+opened in a new browser tab using `report.open_in_browser()`,
+or saved as a portable HTML file `report.save_as_html(output_filepath)`.
+
 .. literalinclude:: ../../examples/04_manipulating_images/plot_mask_computation.py
     :start-after: # We need to specify an 'epi' mask_strategy, as this is raw EPI data
     :end-before: # Generate mask with strong opening
 
-
-.. figure:: ../auto_examples/04_manipulating_images/images/sphx_glr_plot_mask_computation_004.png
+.. figure:: /images/niftimasker_report.png
     :target: ../auto_examples/04_manipulating_images/plot_mask_computation.html
     :scale: 50%
 
@@ -163,7 +176,7 @@ Controling these arguments set the fine aspects of the mask. See the
 functions documentation, or :doc:`the NiftiMasker example
 <../auto_examples/04_manipulating_images/plot_mask_computation>`.
 
-.. figure:: ../auto_examples/04_manipulating_images/images/sphx_glr_plot_mask_computation_005.png
+.. figure:: /images/niftimasker_report_params.png
     :target: ../auto_examples/04_manipulating_images/plot_mask_computation.html
     :scale: 50%
 
@@ -180,9 +193,10 @@ preparation::
    >>> masker # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
    NiftiMasker(detrend=False, dtype=None, high_pass=None, low_pass=None,
          mask_args=None, mask_img=None, mask_strategy='background',
-         memory=Memory(...), memory_level=1, sample_mask=None,
-         sessions=None, smoothing_fwhm=None, standardize=False, t_r=None,
-         target_affine=None, target_shape=None, verbose=0)
+         memory=Memory(...), memory_level=1, reports=True,
+         sample_mask=None, sessions=None, smoothing_fwhm=None,
+         standardize=False, t_r=None, target_affine=None, target_shape=None,
+         verbose=0)
 
 .. note::
 
@@ -234,15 +248,15 @@ Temporal Filtering and confound removal
 properties, before conversion to voxel signals.
 
 - **Standardization**. Parameter ``standardize``: Signals can be
-  standardized (scaled to unit variance). 
+  standardized (scaled to unit variance).
 
 - **Frequency filtering**. Low-pass and high-pass filters can be used to
   remove artifacts. Parameters: ``high_pass`` and ``low_pass``, specified
   in Hz (note that you must specific the sampling rate in seconds with
   the ``t_r`` parameter: ``loss_pass=.5, t_r=2.1``).
 
 - **Confound removal**. Two ways of removing confounds are provided: simple
-  detrending or using prespecified confounds, such as behavioral or movement 
+  detrending or using prespecified confounds, such as behavioral or movement
   information.
 
   * Linear trends can be removed by activating the `detrend` parameter.
@@ -251,7 +265,7 @@ properties, before conversion to voxel signals.
     signal of interest (e.g., the neural correlates of cognitive tasks).
     It is not activated by default in :class:`NiftiMasker` but is recommended
     in almost all scenarios.
-    
+
   * More complex confounds, measured during the acquision, can be removed
     by passing them to :meth:`NiftiMasker.transform`. If the dataset
     provides a confounds file, just pass its path to the masker.

doc/themes/nilearn/static/nature.css_t

@@ -1689,3 +1689,22 @@ ul#tab li div.contents p{
 p.sphx-glr-horizontal {
     margin-top: 2em;
 }
+
+
+/* Sphinx-gallery Report embedding */
+div.sg-report {
+    padding: 0pt;
+    transform: scale(.95);
+}
+
+div.sg-report iframe {
+    display: block;
+    border-style: none;
+    transform: scale(.85);
+    height: 470px;
+    margin-left: -12%; /* Negative because of .8 scaling */
+    margin-top: -4%;
+    padding: 0pt;
+    margin-bottom: 0pt;
+    width: 126%; /* More than 100% because of .8 scaling */
+}