Merge remote-tracking branch 'upstream/master' into enh/dataset_description

Author: effigies

.circleci/config.yml

@@ -48,6 +48,7 @@ jobs:
             fi
             sed -i -E "s/(__version__ = )'[A-Za-z0-9.-]+'/\1'${CIRCLE_TAG:-$THISVERSION}'/" wrapper/fmriprep_docker.py
             sed -i -E "s/(var version = )'[A-Za-z0-9.-]+'/\1'${CIRCLE_TAG:-$THISVERSION}'/" docs/citing.rst
+            sed -i "s/title = {FMRIPrep}/title = {FMRIPrep ${CIRCLE_TAG:-$THISVERSION}}/" fmriprep/data/boilerplate.bib
             # Build docker image
             e=1 && for i in {1..5}; do
               docker build \
@@ -230,6 +231,12 @@ jobs:
           keys:
             - regression-v0-{{ epoch }}
             - regression-v0-
+      - run:
+          name: Check PyPi preconditions
+          command: |
+            pip install "setuptools>=27.0" cython numpy twine future docutils
+            python setup.py check -r -s
+            python setup.py sdist
       - run:
           name: Load Docker image layer cache
           no_output_timeout: 30m
@@ -689,8 +696,9 @@ jobs:
       - run:
           name: Deploy to PyPi
           command: |
-            pip install "setuptools>=27.0" cython numpy twine future
+            pip install "setuptools>=27.0" cython numpy twine future docutils
             echo "${CIRCLE_TAG}" > fmriprep/VERSION
+            python setup.py check -r -s
             python setup.py sdist
             twine upload dist/*
             cd wrapper && python setup.py sdist

.github/stale.yml

@@ -0,0 +1,20 @@
+# Number of days of inactivity before an issue becomes stale
+daysUntilStale: 300
+# Number of days of inactivity before a stale issue is closed
+daysUntilClose: 20
+# Issues with these labels will never be considered stale
+exemptLabels:
+  - pinned
+  - security
+  - feature
+  - help wanted
+  - low priority
+# Label to use when marking an issue as stale
+staleLabel: stale
+# Comment to post when marking an issue as stale. Set to `false` to disable
+markComment: >
+  This issue has been automatically marked as stale because it has not had
+  recent activity. It will be closed if no further activity occurs. Thank you
+  for your contributions.
+# Comment to post when closing a stale issue. Set to `false` to disable
+closeComment: false

CONTRIBUTING.md

@@ -54,6 +54,21 @@ It can also be helpful to test your changes locally, using an [FMRIPREP developm
 
 A member of the development team will review your changes to confirm that they can be merged into the main codebase.
 
+Pull requests titles should begin with a descriptive prefix:
+
+* ``ENH``: enhancements or new features
+* ``FIX``: bug fixes
+* ``TST``: new or updated tests
+* ``DOC``: new or updated documentation
+* ``STY``: style changes
+* ``REF``: refactoring existing code
+* ``CI``: updates to continous integration infrastructure
+* ``MAINT``: general maintenance
+
+For example: `[ENH] Support for SB-reference in multi-band datasets`
+
+For works-in-progress, add the ``WIP`` tag in addition to the descriptive prefix.
+Pull-requests tagged with ``[WIP]`` will not be merged until the tag is removed.
 
 ## FMRIPREP coding style guide
 
@@ -105,6 +120,11 @@ We welcome and recognize all contributions from documentation to testing to code
 You can see a list of current contributors in our [zenodo file][link_zenodo].
 If you are new to the project, don't forget to add your name and affiliation there!
 
+## Licensing
+
+fMRIPrep is licensed under the BSD 3-clause license. Any contributions will be licensed under
+the same terms.
+
 ## Thank you!
 
 You're awesome. :wave::smiley:

docs/installation.rst

@@ -6,7 +6,7 @@ Installation
 
 There are four ways to use fmriprep: on the free cloud service OpenNeuro.org,
 in a `Docker Container`_, in a `Singularity Container`_, or in a `Manually
-Prepared Environment`_.
+Prepared Environment (Python 3.5+)`_.
 Using OpenNeuro or a local container method is highly recommended.
 Once you are ready to run fmriprep, see Usage_ for details.
 
@@ -159,8 +159,8 @@ If the data to be preprocessed is also on the HPC, you are ready to run fmriprep
         --participant-label 387 --nthreads 16 \
         --omp-nthreads 16
 
-Manually Prepared Environment
-=============================
+Manually Prepared Environment (Python 3.5+)
+===========================================
 
 .. warning::
 
@@ -170,15 +170,36 @@ Manually Prepared Environment
 Make sure all of fmriprep's `External Dependencies`_ are installed.
 These tools must be installed and their binaries available in the
 system's ``$PATH``.
-In particular, FreeSurfer requires a license file (see :ref:`fs_license`).
+A relatively interpretable description of how your environment can be set-up
+is found in the `Dockerfile <https://github.com/poldracklab/fmriprep/blob/master/Dockerfile>`_.
+As an additional installation setting, FreeSurfer requires a license file (see :ref:`fs_license`).
 
-If you have pip installed, install fmriprep ::
+On a functional Python 3.5 (or above) environment with ``pip`` installed,
+fMRIPrep can be installed using the habitual command ::
 
     $ pip install fmriprep
 
-If you have your data on hand, you are ready to run fmriprep: ::
+Check your installation with the ``--version`` argument ::
 
-    $ fmriprep data/dir output/dir participant --participant-label label
+    $ fmriprep --version
+
+
+External Dependencies
+---------------------
+
+FMRIPrep is written using Python 3.5 (or above), and is based on
+nipype_.
+
+FMRIPrep requires some other neuroimaging software tools that are
+not handled by the Python's packaging system (Pypi) used to deploy
+the ``fmriprep`` package:
+
+- FSL_ (version 5.0.9)
+- ANTs_ (version 2.2.0 - NeuroDocker build)
+- AFNI_ (version Debian-16.2.07)
+- `C3D <https://sourceforge.net/projects/c3d/>`_ (version 1.0.0)
+- FreeSurfer_ (version 6.0.1)
+- `ICA-AROMA <https://github.com/rhr-pruim/ICA-AROMA/>`_ (version 0.4.1-beta)
 
 
 .. _fs_license:
@@ -232,17 +253,3 @@ would be equivalent to the latest example: ::
         -v /path/to_output/dir:/out poldracklab/fmriprep:1.0.0 \
         /data /out participant
     ...
-
-
-External Dependencies
-=====================
-
-FMRIPrep is implemented using nipype_, but it requires some other neuroimaging
-software tools:
-
-- FSL_ (version 5.0.9)
-- ANTs_ (version 2.2.0 - NeuroDocker build)
-- AFNI_ (version Debian-16.2.07)
-- `C3D <https://sourceforge.net/projects/c3d/>`_ (version 1.0.0)
-- FreeSurfer_ (version 6.0.1)
-- `ICA-AROMA <https://github.com/rhr-pruim/ICA-AROMA/>`_ (version 0.4.1-beta)

docs/pull_request_template.md

@@ -1,3 +1,9 @@
+<!--
+Text in these brackets are comments, and won't be visible when you submit your pull request.
+If this is your first contribution, please take the time to read these, in particular the comment
+beginning "Welcome, new contributors!".
+-->
+
 ## Changes proposed in this pull request
 
 <!--
@@ -15,53 +21,29 @@ of ongoing development efforts and possible overlaps between contributions).
 Please summarize here the main changes to the documentation that the reviewers should be aware of.
 -->
 
-## Pull-request guidelines:
+
+
 <!--
-Please make sure you have read the PR guidelines below, and checked 
-all boxes that apply at the bottom.
--->
-1. We invite you to list yourself as a *fMRIPrep* contributor, so if your name 
-   is not already mentioned, please modify the 
-   [``.zenodo.json``](https://github.com/poldracklab/fmriprep/blob/master/.zenodo.json)
-   file with your data right above Russ' entry. Example:
-   ```
-   {
-      "name": "Contributor, New FMRIPrep",
-      "affiliation": "Department of fMRI prep'ing, Open Science Made-Up University",
-      "orcid": "<your id>"
-   },
-   {
-      "name": "Poldrack, Russell A.",
-      "affiliation": "Department of Psychology, Stanford University",
-      "orcid": "0000-0001-6755-0259"
-   },
-   ```
-   
-2. By submitting this request you acknowledge that your contributions are available under the BSD 3-Clause license.
+Welcome, new contributors!
 
-3. Use a descriptive prefix, between brackets for your PR: ``ENH`` (enhancement), ``FIX``, ``TST``, ``DOC``, ``STY``,
-   ``REF`` (refactor), ``CI`` (continous integration), ``MAINT`` (maintenance). Example:
-   ```
-   [ENH] Support for SB-reference in multi-band datasets
-   ```
-   For works-in-progress, add the ``WIP`` tag in addition to the descriptive prefix. 
-   Pull-requests tagged with ``[WIP]`` will not merged in until the tag is removed.
+We ask you to read through the Contributing Guide:
+https://github.com/poldracklab/fmriprep/blob/master/CONTRIBUTING.md
 
-4. Your PR will be reviewed according to the following
-   [template](https://github.com/poldracklab/fmriprep/wiki/Reviewing-a-Pull-Request).
+These are guidelines intended to make communication easier by describing a consistent process, but
+don't worry if you don't get it everything exactly "right" on the first try.
 
-5. Documentation is a fundamental aspect to the *glass-box* philosophy that *fMRIPrep* abides by.
-   Please understand that the *fMRIPrep* team may (are likely to) request you to improve the documentation
-   provided with this PR, within the PR or in future PRs.
-   
+To boil it down, here are some highlights:
 
-**Please review and check the following**:
-<!-- replace the empty checkboxes [ ] below with checked ones [x] accordingly -->
+1) Consider starting a conversation in the issues list before submitting a pull request. The discussion might save you a
+   lot of time coding.
+2) Please use descriptive prefixes in your pull request title, such as "ENH:" for an enhancement or "FIX:" for a bug fix.
+   (See the Contributing guide for the full set.) And consider adding a "WIP" tag for works-in-progress.
+3) Any code you submit will be licensed under the same terms (BSD 3-Clause) as the rest of fMRIPrep.
+4) We invite every contributor to add themselves to the `.zenodo.json` file
+   (https://github.com/poldracklab/fmriprep/blob/master/.zenodo.json), which will result in your being listed as an author
+   at the next release. Please add yourself as the next-to-last entry, just above Russ.
 
-  - [ ] I have read the [guidelines for contributions](https://github.com/poldracklab/fmriprep/blob/master/CONTRIBUTING.md).
-  - [ ] I understand that my contributions will not be merged unless the work is
-        finished (i.e. no ``[WIP]`` tag remains in the title of my PR) and tests pass.
-  - [ ] The proposed code follows the
-        [coding style](https://github.com/poldracklab/fmriprep/blob/master/CONTRIBUTING.md#fmriprep-coding-style-guide),
-        to the extent I understood them (and I will address any comments raised by the PR's reviewers in this regard).
-  - [ ] \(Optional\) I opt-out from being listed in the `.zenodo.json` file.
+A pull request is a conversation. We may ask you to make some changes before accepting your PR,
+and likewise, you should feel free to ask us any questions you have.
+
+-->

fmriprep/__about__.py

@@ -0,0 +1,148 @@
+# -*- coding: utf-8 -*-
+# emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-
+# vi: set ft=python sts=4 ts=4 sw=4 et:
+"""
+Base module variables
+"""
+
+from ._version import get_versions
+__version__ = get_versions()['version']
+del get_versions
+
+__author__ = 'The CRN developers'
+__copyright__ = 'Copyright 2018, Center for Reproducible Neuroscience, Stanford University'
+__credits__ = ['Craig Moodie', 'Ross Blair', 'Oscar Esteban', 'Chris Gorgolewski',
+               'Shoshana Berleant', 'Christopher J. Markiewicz', 'Russell A. Poldrack']
+__license__ = '3-clause BSD'
+__maintainer__ = 'Ross Blair'
+__email__ = '[email protected]'
+__status__ = 'Prototype'
+__url__ = 'https://github.com/poldracklab/fmriprep'
+__packagename__ = 'fmriprep'
+__description__ = ("FMRIprep is a functional magnetic resonance image pre-processing pipeline "
+                   "that is designed to provide an easily accessible, state-of-the-art interface "
+                   "that is robust to differences in scan acquisition protocols and that requires "
+                   "minimal user input, while providing easily interpretable and comprehensive "
+                   "error and output reporting.")
+__longdesc__ = """\
+Preprocessing of functional MRI (fMRI) involves numerous steps to clean and standardize
+data before statistical analysis.
+Generally, researchers create ad hoc preprocessing workflows for each new dataset,
+building upon a large inventory of tools available for each step.
+The complexity of these workflows has snowballed with rapid advances in MR data
+acquisition and image processing techniques.
+FMRIPrep is an analysis-agnostic tool that addresses the challenge of robust and
+reproducible preprocessing for task-based and resting fMRI data.
+FMRIPrep automatically adapts a best-in-breed workflow to the idiosyncrasies of
+virtually any dataset, ensuring high-quality preprocessing with no manual intervention,
+while providing easily interpretable and comprehensive error and output reporting.
+It performs basic preprocessing steps (coregistration, normalization, unwarping, noise
+component extraction, segmentation, skullstripping etc.) providing outputs that can be
+easily submitted to a variety of group level analyses, including task-based or resting-state
+fMRI, graph theory measures, surface or volume-based statistics, etc.
+
+The workflow is based on `Nipype <https://nipype.readthedocs.io>`_ and encompases a large
+set of tools from well-known neuroimaging packages, including
+`FSL <https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/>`_,
+`ANTs <https://stnava.github.io/ANTs/>`_,
+`FreeSurfer <https://surfer.nmr.mgh.harvard.edu/>`_,
+`AFNI <https://afni.nimh.nih.gov/>`_,
+and `Nilearn <https://nilearn.github.io/>`_.
+This pipeline was designed to provide the best software implementation for each state of
+preprocessing, and will be updated as newer and better neuroimaging software becomes
+available.
+
+This tool allows you to easily do the following:
+
+  * Take fMRI data from *unprocessed* (only reconstructed) to ready for analysis.
+  * Implement tools from different software packages.
+  * Achieve optimal data processing quality by using the best tools available.
+  * Generate preprocessing-assessment reports, with which the user can easily identify problems.
+  * Receive verbose output concerning the stage of preprocessing for each subject, including
+    meaningful errors.
+  * Automate and parallelize processing steps, which provides a significant speed-up from
+    typical linear, manual processing.
+
+FMRIPrep has the potential to transform fMRI research by equipping
+neuroscientists with a high-quality, robust, easy-to-use and transparent preprocessing workflow
+which can help ensure the validity of inference and the interpretability of their results.
+
+[Pre-print doi:`10.1101/306951 <https://doi.org/10.1101/306951>`_]
+[Documentation `fmriprep.org <https://fmriprep.readthedocs.io>`_]
+[Software doi:`10.5281/zenodo.852659 <https://doi.org/10.5281/zenodo.852659>`_]
+[Support `neurostars.org <https://neurostars.org/tags/fmriprep>`_]
+"""
+
+DOWNLOAD_URL = (
+    'https://github.com/poldracklab/{name}/archive/{ver}.tar.gz'.format(
+        name=__packagename__, ver=__version__))
+
+
+SETUP_REQUIRES = [
+    'setuptools>=18.0',
+    'numpy',
+    'cython',
+]
+
+REQUIRES = [
+    'numpy',
+    'lockfile',
+    'future',
+    'scikit-learn',
+    'matplotlib>=2.2.0',
+    'nilearn',
+    'sklearn',
+    'nibabel>=2.2.1',
+    'pandas',
+    'grabbit',
+    'pybids>=0.6.3',
+    'nitime',
+    'nipype>=1.1.1',
+    'niworkflows>=0.4.2',
+    'statsmodels',
+    'seaborn',
+    'indexed_gzip>=0.8.2',
+    'scikit-image',
+    'versioneer',
+]
+
+LINKS_REQUIRES = [
+]
+
+TESTS_REQUIRES = [
+    "mock",
+    "codecov",
+    "pytest",
+]
+
+EXTRA_REQUIRES = {
+    'doc': [
+        'sphinx>=1.5.3',
+        'sphinx_rtd_theme',
+        'sphinx-argparse',
+        'pydotplus',
+        'pydot>=1.2.3',
+        'packaging',
+        'nbsphinx',
+    ],
+    'tests': TESTS_REQUIRES,
+    'duecredit': ['duecredit'],
+    'datalad': ['datalad'],
+    'resmon': ['psutil>=5.4.0'],
+    'sentry': ['raven'],
+}
+EXTRA_REQUIRES['docs'] = EXTRA_REQUIRES['doc']
+
+# Enable a handle to install all extra dependencies at once
+EXTRA_REQUIRES['all'] = list(set([
+    v for deps in EXTRA_REQUIRES.values() for v in deps]))
+
+CLASSIFIERS = [
+    'Development Status :: 3 - Alpha',
+    'Intended Audience :: Science/Research',
+    'Topic :: Scientific/Engineering :: Image Recognition',
+    'License :: OSI Approved :: BSD License',
+    'Programming Language :: Python :: 3.5',
+    'Programming Language :: Python :: 3.6',
+    'Programming Language :: Python :: 3.7',
+]