Merge pull request #1024 from oesteban/enh/dynamic-boilerplate

[ENH] Dynamic citation boilerplate

Author: oesteban

.circleci/ds005_outputs.txt

@@ -1,5 +1,8 @@
 fmriprep
 fmriprep/logs
+fmriprep/logs/CITATION.html
+fmriprep/logs/CITATION.md
+fmriprep/logs/CITATION.tex
 fmriprep/sub-01
 fmriprep/sub-01/anat
 fmriprep/sub-01/anat/sub-01_T1w_brainmask.nii.gz

.circleci/ds005_partial_outputs.txt

@@ -1,5 +1,8 @@
 fmriprep
 fmriprep/logs
+fmriprep/logs/CITATION.html
+fmriprep/logs/CITATION.md
+fmriprep/logs/CITATION.tex
 fmriprep/sub-01
 fmriprep/sub-01/anat
 fmriprep/sub-01/anat/sub-01_T1w_brainmask.nii.gz

.circleci/ds054_outputs.txt

@@ -1,5 +1,8 @@
 fmriprep
 fmriprep/logs
+fmriprep/logs/CITATION.html
+fmriprep/logs/CITATION.md
+fmriprep/logs/CITATION.tex
 fmriprep/sub-100185
 fmriprep/sub-100185/anat
 fmriprep/sub-100185/anat/sub-100185_T1w_brainmask.nii.gz

.circleci/ds210_outputs.txt

@@ -1,5 +1,8 @@
 fmriprep
 fmriprep/logs
+fmriprep/logs/CITATION.html
+fmriprep/logs/CITATION.md
+fmriprep/logs/CITATION.tex
 fmriprep/sub-02
 fmriprep/sub-02/anat
 fmriprep/sub-02/anat/sub-02_T1w_brainmask.nii.gz

Dockerfile

@@ -113,7 +113,7 @@ RUN conda install -y mkl=2018.0.3 mkl-service;  sync &&\
                      matplotlib=2.2.0 \
                      pandas=0.23.0 \
                      libxml2=2.9.4 \
-                     libxslt=1.1.29\
+                     libxslt=1.1.29 \
                      traits=4.6.0; sync &&  \
     chmod -R a+rX /usr/local/miniconda; sync && \
     chmod +x /usr/local/miniconda/bin/*; sync && \
@@ -131,6 +131,11 @@ RUN apt-get update && \
                     graphviz=2.38.0-12ubuntu2 && \
     apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
 
+# Install latest pandoc
+RUN curl -o pandoc-2.2.2.1-1-amd64.deb -sSL "https://github.com/jgm/pandoc/releases/download/2.2.2.1/pandoc-2.2.2.1-1-amd64.deb" && \
+    dpkg -i pandoc-2.2.2.1-1-amd64.deb && \
+    rm pandoc-2.2.2.1-1-amd64.deb
+
 # Unless otherwise specified each process should only use one thread - nipype
 # will handle parallelization
 ENV MKL_NUM_THREADS=1 \

docs/contributors.rst

@@ -121,3 +121,39 @@ This image may be accessed by the `fmriprep-docker`_ wrapper via the
 ``-i`` flag, e.g. ::
 
     $ fmriprep-docker -i fmriprep --shell
+
+
+Adding new features to the citation boilerplate
+===============================================
+
+The citation boilerplate is built by adding two dunder attributes
+of workflow objects: ``__desc__`` and ``__postdesc__``.
+Once the full *fMRIPrep* workflow is built, starting from the
+outer workflow and visiting all sub-workflows in topological
+order, all defined ``__desc__`` are appended to the citation
+boilerplate before descending into sub-workflows.
+Once all the sub-workflows of a given workflow have
+been visited, then the ``__postdesc__`` attribute is appended
+and the execution pops out to higher level workflows.
+The dunder attributes are written in Markdown language, and may contain
+references.
+To add a reference, just add a new Bibtex entry to the references
+database (``/fmriprep/data/boilerplate.bib``).
+You can then use the Bibtex handle within the Markdown text.
+For example, if the Bibtex handle is ``myreference``, a citation
+will be generated in Markdown language with ``@myreference``.
+To generate citations with parenthesis and/or additional content,
+brackets should be used: e.g. ``[see @myreference]`` will produce
+a citation like *(see Doe J. et al 2018)*.
+
+
+An example of how this works is shown here: ::
+
+    workflow = Workflow(name=name)
+    workflow.__desc__ = """\
+    Head-motion parameters with respect to the BOLD reference
+    (transformation matrices, and six corresponding rotation and translation
+    parameters) are estimated before any spatiotemporal filtering using
+    `mcflirt` [FSL {fsl_ver}, @mcflirt].
+    """.format(fsl_ver=fsl.Info().version() or '<ver>')
+

fmriprep/cli/run.py

@@ -8,6 +8,7 @@
 
 import os
 import os.path as op
+from pathlib import Path
 import logging
 import sys
 import gc
@@ -93,6 +94,8 @@ def get_parser():
                          help='nipype plugin configuration file')
     g_perfm.add_argument('--anat-only', action='store_true',
                          help='run anatomical workflows only')
+    g_perfm.add_argument('--boilerplate', action='store_true',
+                         help='generate boilerplate only')
     g_perfm.add_argument('--ignore-aroma-denoising-errors', action='store_true',
                          default=False,
                          help='ignores the errors ICA_AROMA returns when there '
@@ -249,7 +252,7 @@ def main():
     opts = get_parser().parse_args()
 
     # FreeSurfer license
-    default_license = op.join(os.getenv('FREESURFER_HOME', ''), 'license.txt')
+    default_license = str(Path(os.getenv('FREESURFER_HOME')) / 'license.txt')
     # Precedence: --fs-license-file, $FS_LICENSE, default_license
     license_file = opts.fs_license_file or os.getenv('FS_LICENSE', default_license)
     if not os.path.exists(license_file):
@@ -299,6 +302,9 @@ def main():
     if opts.reports_only:
         sys.exit(int(retcode > 0))
 
+    if opts.boilerplate:
+        sys.exit(int(retcode > 0))
+
     # Sentry tracking
     if not opts.notrack:
         try:
@@ -354,6 +360,9 @@ def build_workflow(opts, retval):
     a hard-limited memory-scope.
 
     """
+    from subprocess import check_call, CalledProcessError, TimeoutExpired
+    from pkg_resources import resource_filename as pkgrf
+
     from nipype import logging, config as ncfg
     from ..info import __version__
     from ..workflows.base import init_fmriprep_wf
@@ -397,7 +406,7 @@ def build_workflow(opts, retval):
     run_uuid = '%s_%s' % (strftime('%Y%m%d-%H%M%S'), uuid.uuid4())
 
     # First check that bids_dir looks like a BIDS folder
-    bids_dir = op.abspath(opts.bids_dir)
+    bids_dir = os.path.abspath(opts.bids_dir)
     subject_list = collect_participants(
         bids_dir, participant_label=opts.participant_label)
 
@@ -529,6 +538,35 @@ def build_workflow(opts, retval):
         ignore_aroma_err=opts.ignore_aroma_denoising_errors,
     )
     retval['return_code'] = 0
+
+    logs_path = Path(output_dir) / 'fmriprep' / 'logs'
+    boilerplate = retval['workflow'].visit_desc()
+    (logs_path / 'CITATION.md').write_text(boilerplate)
+    logger.log(25, 'Works derived from this fMRIPrep execution should '
+               'include the following boilerplate:\n\n%s', boilerplate)
+
+    # Generate HTML file resolving citations
+    cmd = ['pandoc', '-s', '--bibliography',
+           pkgrf('fmriprep', 'data/boilerplate.bib'),
+           '--filter', 'pandoc-citeproc',
+           str(logs_path / 'CITATION.md'),
+           '-o', str(logs_path / 'CITATION.html')]
+    try:
+        check_call(cmd, timeout=10)
+    except (FileNotFoundError, CalledProcessError, TimeoutExpired):
+        logger.warning('Could not generate CITATION.html file:\n%s',
+                       ' '.join(cmd))
+
+    # Generate LaTex file resolving citations
+    cmd = ['pandoc', '-s', '--bibliography',
+           pkgrf('fmriprep', 'data/boilerplate.bib'),
+           '--natbib', str(logs_path / 'CITATION.md'),
+           '-o', str(logs_path / 'CITATION.tex')]
+    try:
+        check_call(cmd, timeout=10)
+    except (FileNotFoundError, CalledProcessError, TimeoutExpired):
+        logger.warning('Could not generate CITATION.tex file:\n%s',
+                       ' '.join(cmd))
     return retval