diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 5f0acd0..ec685d7 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -28,7 +28,7 @@ body: For information on how to contribute, please refer to our [contributing guidelines](https://www.nipreps.org/community/CONTRIBUTING/). options: - "Yes" - - Yes, but I would need guidance + - "Yes, but I would need guidance" - "No" validations: required: true diff --git a/.github/config.yml b/.github/config.yml new file mode 100644 index 0000000..a88e7e3 --- /dev/null +++ b/.github/config.yml @@ -0,0 +1,25 @@ +# Configuration for new-pr-welcome - https://github.com/behaviorbot/new-pr-welcome + +# Comment to be posted to on PRs from first time contributors in your repository +newPRWelcomeComment: > + Welcome, new contributor! + + We ask you to read through the Contributing Guide: + https://github.com/nipreps/fmripost-template/blob/main/CONTRIBUTING.md + + 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. + + To boil it down, here are some highlights: + + 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 a descriptive title for your pull request. + Please remember to set your pull request as a "draft" if it is not ready for review. + 3) Any code you submit will be licensed under the same terms (Apache License 2.0) as the rest of fMRIPost-template. + 4) We invite every contributor to add themselves to the `.zenodo.json` file + (https://github.com/nipreps/fmripost-template/blob/main/.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. + + 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. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 1f527a6..45d7c41 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,15 +1,11 @@ - +Closes . ## Changes proposed in this pull request - - - - diff --git a/.mailmap b/.mailmap index f07018a..b06a280 100644 --- a/.mailmap +++ b/.mailmap @@ -1,3 +1,6 @@ Christopher J. Markiewicz Christopher J. Markiewicz Christopher J. Markiewicz +Taylor Salo +Taylor Salo +Taylor Salo diff --git a/.zenodo.json b/.zenodo.json index 73678f8..fcc06d6 100644 --- a/.zenodo.json +++ b/.zenodo.json @@ -6,18 +6,6 @@ "affiliation": "Lausanne University Hospital and University of Lausanne, Lausanne, Switzerland", "name": "Esteban, Oscar", "orcid": "0000-0001-8435-6191" - }, - { - "name": "Ferrer, Vicente" - }, - { - "name": "Uruñuela, Eneko" - }, - { - "name": "Pedregosa, Fabian" - }, - { - "name": "Caballero Gaudes, Cesar" } ], "creators": [ @@ -36,7 +24,7 @@ "neuroimaging", "workflow", "pipeline", - "preprocessing", + "postprocessing", "fMRI", "BIDS" ], diff --git a/Dockerfile b/Dockerfile index a4f53e1..cd44fe9 100644 --- a/Dockerfile +++ b/Dockerfile @@ -2,7 +2,7 @@ # # MIT License # -# Copyright (c) The NiPreps Developers +# Copyright (c) 2024 The NiPreps Developers # # Permission is hereby granted, free of charge, to any person obtaining a copy # of this software and associated documentation files (the "Software"), to deal diff --git a/NOTICE b/NOTICE index 594f60c..746743b 120000 --- a/NOTICE +++ b/NOTICE @@ -1 +1 @@ -src/fmripost_aroma/data/NOTICE \ No newline at end of file +src/fmripost_template/data/NOTICE \ No newline at end of file diff --git a/README.md b/README.md deleted file mode 100644 index 721069e..0000000 --- a/README.md +++ /dev/null @@ -1,2 +0,0 @@ -# fmripost-template -A generic fMRIPost workflow diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..e0313cf --- /dev/null +++ b/README.rst @@ -0,0 +1,42 @@ +################# +fMRIPost-template +################# + +A generic fMRIPost workflow. + +******** +Overview +******** + +fMRIPost-template is a template repository that can be used to create new fMRIPost workflows. + +The workflows and functions in this repository are designed to implement the majority of +general-purpose steps in an fMRIPost pipeline. +Here are a few of the key features: + +1. Configuration files to define expected BIDS derivatives from the preprocessing pipeline. +2. Functions to collect and organize data from the BIDS derivatives. +3. The ability to work with the following preprocessing configurations: + + - fMRIPrep with ``--level full`` and the required output space for the fMRIPost workflow. + For example, fMRIPost-AROMA requires outputs in ``MNI152NLin6Asym`` space with + 2x2x2 mm voxels. + - fMRIPrep with ``--level full`` and boldref-space outputs, + along with transforms to the required output space for the fMRIPost workflow. + - fMRIPrep with ``--level full`` and boldref-space outputs, + along with transforms to spaces that can be combined with existing transforms to + required spaces. + For example, users may apply fMRIPost-AROMA to boldref derivatives with transforms to + MNI152NLin2009cAsym space. + In this case, the fMRIPost-AROMA workflow will pull a transform from MNI152NLin2009cAsym + to MNI152NLin6Asym from TemplateFlow and apply it, + along with the boldref-to-MNI152NLin2009cAsym transform, to the boldref-space derivatives. + + .. warning:: + + Currently, minimal- and resampling-level fMRIPrep derivatives are not supported, + as fMRIPost workflows typically require confounds that are only generated with + ``--level full``. + +4. General NiPreps infrastructure for running a BIDS App, such as a config file, + a command-line interface, and tools to generate HTML reports. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/theme_overrides.css b/docs/_static/theme_overrides.css new file mode 100644 index 0000000..fad2f17 --- /dev/null +++ b/docs/_static/theme_overrides.css @@ -0,0 +1,21 @@ +/* override table width restrictions */ +@media screen and (min-width: 767px) { + + .wy-table-responsive table td { + /* !important prevents the common CSS stylesheets from overriding + this as on RTD they are loaded after this stylesheet */ + white-space: normal !important; + } + + .wy-table-responsive { + overflow: visible !important; + } +} + + +/* Fix parameter type style */ +.function .classifier { + margin: 0 0 0 5px; + padding: 3px; + background: rgba(0, 0, 0, .1); +} diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..e28e126 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,39 @@ +.. include:: links.rst + +================ +Developers - API +================ + +The *NiPreps* community and contributing guidelines +--------------------------------------------------- + +*fMRIPost-template* is a *NiPreps* application, and abides by the +`NiPreps Community guidelines `__. +Please, make sure you have read and understood all the documentation +provided in the `NiPreps portal `__ before +you get started. + +Setting up your development environment +--------------------------------------- + +We believe that *fMRIPost-template* must be free to use, inspect, and critique. +Correspondingly, you should be free to modify our software to improve it +or adapt it to new use cases and we especially welcome contributions to +improve it or its documentation. + +We actively direct efforts into making the scrutiny and improvement processes +as easy as possible. +As part of such efforts, we maintain some +`tips and guidelines for developers `__ +to help minimize your burden if you want to modify the software. + +Internal configuration system +----------------------------- + +.. automodule:: fmripost_template.config + :members: from_dict, load, get, dumps, to_filename, init_spaces + +Workflows +--------- + +.. automodule:: fmripost_template.workflows.base diff --git a/docs/changes.rst b/docs/changes.rst new file mode 100644 index 0000000..ac10c4f --- /dev/null +++ b/docs/changes.rst @@ -0,0 +1,7 @@ +.. include:: links.rst + +---------- +What's new +---------- + +.. include:: ../CHANGES.rst diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..465bec9 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,363 @@ +# fmripost_template documentation build configuration file, created by +# sphinx-quickstart on Mon May 9 09:04:25 2016. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# Notes on fMRIPost-template-specific style: +# 1. For rst headings, we use the following convention, based on +# https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections: +# # with overline, for parts +# * with overline, for chapters +# = for sections +# - for subsections +# ^ for subsubsections +# " for paragraphs + +import os +import sys + +# Avoid distutils.LooseVersion which is deprecated +from packaging import version as pver +from sphinx import __version__ as sphinxversion + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.append(os.path.abspath('sphinxext')) + +from github_link import make_linkcode_resolve # noqa: E402 + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +needs_sphinx = '1.5.3' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named "sphinx.ext.*") or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', + 'sphinx.ext.coverage', + 'sphinx.ext.mathjax', + 'sphinx.ext.linkcode', + 'sphinx.ext.napoleon', + 'sphinxarg.ext', # argparse extension + 'nipype.sphinxext.plot_workflow', +] + +# Mock modules in autodoc: +autodoc_mock_imports = [ + 'numpy', + 'nitime', + 'matplotlib', +] + +if pver.parse(sphinxversion) >= pver.parse('1.7.0'): + autodoc_mock_imports += [ + 'pandas', + 'nilearn', + 'seaborn', + ] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# Accept custom section names to be parsed for numpy-style docstrings +# of parameters. +# Requires pinning sphinxcontrib-napoleon to a specific commit while +# https://github.com/sphinx-contrib/napoleon/pull/10 is merged. +napoleon_use_param = False +napoleon_custom_sections = [ + ('Inputs', 'Parameters'), + ('Outputs', 'Parameters'), +] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# source_suffix = [".rst", ".md"] +source_suffix = '.rst' + +# The encoding of source files. +# source_encoding = "utf-8-sig" + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'fMRIPost-template' +author = 'The fMRIPost-template developers' +copyright = f'2024, {author}' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = 'version' +# The full version, including alpha/beta/rc tags. +release = 'version' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = 'en' + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +# today = '' +# Else, today_fmt is used as the format for a strftime call. +# today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +# default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +# add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +# add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +# show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +# modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +# keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +# html_theme_path = [] + +# The name for this set of Sphinx documents. +# " v documentation" by default. +# html_title = u'fmripost_template vversion' + +# A shorter title for the navigation bar. Default is the same as html_title. +# html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +# html_logo = None + +# The name of an image file (relative to this directory) to use as a favicon of +# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +# html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +# html_extra_path = [] + +# If not None, a 'Last updated on:' timestamp is inserted at every page +# bottom, using the given strftime format. +# The empty string is equivalent to '%b %d, %Y'. +# html_last_updated_fmt = None + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +# html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +# html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +# html_additional_pages = {} + +# If false, no module index is generated. +# html_domain_indices = True + +# If false, no index is generated. +# html_use_index = True + +# If true, the index is split into individual pages for each letter. +# html_split_index = False + +# If true, links to the reST sources are added to the pages. +# html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +# html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +# html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +# html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g., ".xhtml"). +# html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh' +# html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# 'ja' uses this config value. +# 'zh' user can custom change `jieba` dictionary path. +# html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +# html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'fmripost_template_doc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # 'papersize': 'letterpaper', + # The font size ('10pt', '11pt' or '12pt'). + # 'pointsize': '10pt', + # Additional stuff for the LaTeX preamble. + # 'preamble': '', + # Latex figure (float) alignment + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'fmripost_template.tex', 'fMRIPost-template Documentation', author, 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +# latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +# latex_use_parts = False + +# If true, show page references after internal links. +# latex_show_pagerefs = False + +# If true, show URL addresses after external links. +# latex_show_urls = False + +# Documents to append as an appendix to all manuals. +# latex_appendices = [] + +# If false, no module index is generated. +# latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [(master_doc, 'fmripost-template', 'fMRIPost-template Documentation', [author], 1)] + +# If true, show URL addresses after external links. +# man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ( + master_doc, + 'fMRIPost-template', + 'fMRIPost-template Documentation', + author, + 'fMRIPost-template', + 'One line description of project.', + 'Miscellaneous', + ), +] + +# Documents to append as an appendix to all manuals. +# texinfo_appendices = [] + +# If false, no module index is generated. +# texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +# texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +# texinfo_no_detailmenu = False + +# The following is used by sphinx.ext.linkcode to provide links to github +linkcode_resolve = make_linkcode_resolve( + 'fmripost_template', + 'https://github.com/nipreps/fMRIPost-template/blob/{revision}/{package}/{path}#L{lineno}', +) + +# Links to external libraries' API documentation for intersphinx linking. +intersphinx_mapping = { + 'python': ('https://docs.python.org/3/', None), + 'numpy': ('https://numpy.org/doc/stable/', None), + 'scipy': ('https://docs.scipy.org/doc/scipy/', None), + 'matplotlib': ('https://matplotlib.org/stable/', None), + 'bids': ('https://bids-standard.github.io/pybids/', None), + 'nibabel': ('https://nipy.org/nibabel/', None), + 'nipype': ('https://nipype.readthedocs.io/en/latest/', None), + 'niworkflows': ('https://www.nipreps.org/niworkflows/', None), + 'fmriprep': ('https://fmriprep.org/en/stable/', None), + 'sdcflows': ('https://www.nipreps.org/sdcflows/', None), + 'smriprep': ('https://www.nipreps.org/smriprep/', None), + 'templateflow': ('https://www.templateflow.org/python-client', None), +} + +suppress_warnings = ['image.nonlocal_uri'] + + +def setup(app): + app.add_css_file('theme_overrides.css') + # We need this for the boilerplate script + app.add_js_file('https://cdn.rawgit.com/chrisfilo/zenodo.js/v0.1/zenodo.js') diff --git a/docs/faq.rst b/docs/faq.rst new file mode 100644 index 0000000..5e08994 --- /dev/null +++ b/docs/faq.rst @@ -0,0 +1,21 @@ +.. include:: links.rst + +================================ +FAQ - Frequently Asked Questions +================================ + +.. contents:: + :local: + :depth: 1 + +What is fMRIPost? +----------------- + +fMRIPost workflows are BIDS Apps that ingress fMRI preprocessing derivative datasets. +They fall under the broader umbrella of NiPost workflows, +which are pipelines that perform post-processing on BIDS-Derivative datasets. + +These workflows are primarily tested against the outputs of the `fMRIPrep`_ pipeline, +but we plan to ensure that they can work with derivatives from any pipeline that produces BIDS-Derivative compliant datasets. + +.. _fMRIPrep: https://fmriprep.org diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..7608ae0 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,22 @@ +.. fmripost_template documentation master file, created by + sphinx-quickstart on Mon May 9 09:04:25 2016. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +.. include:: links.rst +.. include:: ../README.rst + +Contents +-------- + +.. toctree:: + :maxdepth: 3 + + installation + usage + workflows + outputs + spaces + faq + api + changes diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..2b115b8 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,49 @@ +.. include:: links.rst + +------------ +Installation +------------ +*fMRIPost-template* should be installed using container technologies. + +.. code-block:: bash + docker pull nipreps/fmripost-template:main + + +Containerized execution (Docker and Singularity) +================================================ +*fMRIPost-template* is a *NiPreps* application, and therefore follows some overarching principles +of containerized execution drawn from the BIDS-Apps protocols. +For detailed information of containerized execution of *NiPreps*, please visit the corresponding +`Docker `__ +or `Singularity `__ subsections. + +External Dependencies +--------------------- +*fMRIPost-template* is written using Python 3.8 (or above), and is based on +nipype_. + +*fMRIPost-template* requires some other neuroimaging software tools that are +not handled by the Python's packaging system (Pypi): + +- FSL_ (version 6.0.7.7) +- ANTs_ (version 2.5.1) +- AFNI_ (version 24.0.05) +- `C3D `_ (version 1.4.0) +- FreeSurfer_ (version 7.3.2) +- `bids-validator `_ (version 1.14.0) +- `connectome-workbench `_ (version 1.5.0) + +Not running on a local machine? - Data transfer +=============================================== +If you intend to run *fMRIPost-template* on a remote system, you will need to +make your data available within that system first. + +For instance, here at the Poldrack Lab we use Stanford's +:abbr:`HPC (high-performance computing)` system, called Sherlock. +Sherlock enables `the following data transfer options +`_. + +Alternatively, more comprehensive solutions such as `Datalad +`_ will handle data transfers with the appropriate +settings and commands. +Datalad also performs version control over your data. diff --git a/docs/license.rst b/docs/license.rst new file mode 100644 index 0000000..a126362 --- /dev/null +++ b/docs/license.rst @@ -0,0 +1,25 @@ +About the *NiPreps* framework licensing +--------------------------------------- +Please check https://www.nipreps.org/community/licensing/ for detailed +information on the criteria we use to license *fMRIPost-template* and other +projects of the framework. + +License information +------------------- +Copyright (c) the *NiPreps* Developers. + +*fMRIPost-template* is licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +Copyright (c), the *fMRIPost-template* developers and the CRN. +All rights reserved. + +All trademarks referenced herein are property of their respective holders. diff --git a/docs/links.rst b/docs/links.rst new file mode 100644 index 0000000..98f4db4 --- /dev/null +++ b/docs/links.rst @@ -0,0 +1,25 @@ +.. _Nipype: https://nipype.readthedocs.io/en/latest/ +.. _BIDS: https://bids.neuroimaging.io/ +.. _`BIDS Derivatives`: https://bids-specification.readthedocs.io/en/stable/05-derivatives/01-introduction.html +.. _`BEP 011`: https://bids-specification.readthedocs.io/en/bep011/05-derivatives/04-structural-derivatives.html +.. _`BEP 012`: https://bids-specification.readthedocs.io/en/bep012/05-derivatives/05-functional-derivatives.html +.. _Installation: installation.html +.. _workflows: workflows.html +.. _FSL: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/ +.. _ANTs: https://stnava.github.io/ANTs/ +.. _FreeSurfer: https://surfer.nmr.mgh.harvard.edu/ +.. _`submillimeter reconstruction`: https://surfer.nmr.mgh.harvard.edu/fswiki/SubmillimeterRecon +.. _`mri_robust_template`: https://surfer.nmr.mgh.harvard.edu/fswiki/mri_robust_template +.. _AFNI: https://afni.nimh.nih.gov/ +.. _GIFTI: https://www.nitrc.org/projects/gifti/ +.. _`Connectome Workbench`: https://www.humanconnectome.org/software/connectome-workbench.html +.. _`HCP Pipelines`: https://humanconnectome.org/software/hcp-mr-pipelines/ +.. _`Docker Engine`: https://www.docker.com/products/container-runtime +.. _`Docker installation`: https://docs.docker.com/install/ +.. _`Docker Hub`: https://hub.docker.com/r/nipreps/fmripost_template/tags +.. _Singularity: https://github.com/singularityware/singularity +.. _SPM: https://www.fil.ion.ucl.ac.uk/spm/software/spm12/ +.. _TACC: https://www.tacc.utexas.edu/ +.. _tedana: https://github.com/me-ica/tedana +.. _`T2* workflow`: https://tedana.readthedocs.io/en/latest/generated/tedana.workflows.t2smap_workflow.html#tedana.workflows.t2smap_workflow # noqa +.. _`citation boilerplate`: https://www.nipreps.org/intro/transparency/#citation-boilerplates diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/outputs.rst b/docs/outputs.rst new file mode 100644 index 0000000..ac253e6 --- /dev/null +++ b/docs/outputs.rst @@ -0,0 +1,114 @@ +.. include:: links.rst + +.. _outputs: + +------------------------------ +Outputs of *fMRIPost-template* +------------------------------ + +*fMRIPost-template* outputs conform to the :abbr:`BIDS (brain imaging data structure)` +Derivatives specification (see `BIDS Derivatives`_, along with the +upcoming `BEP 011`_ and `BEP 012`_). +*fMRIPost-template* generates three broad classes of outcomes: + +1. **Visual QA (quality assessment) reports**: + One :abbr:`HTML (hypertext markup language)` per subject, + that allows the user a thorough visual assessment of the quality + of processing and ensures the transparency of *fMRIPost-template* operation. + +2. **Derivatives**: + Output fMRI data in the requested output spaces and resolutions. + +3. **Confounds**: + Confound time series. + + +Layout +------ + +Assuming fMRIPost-template is invoked with:: + + fmripost_template / / participant [OPTIONS] + +The outputs will be a `BIDS Derivatives`_ dataset of the form:: + + / + logs/ + sub-