From b85b5e3099cf8ae0fdabb45daaea79915723fcac Mon Sep 17 00:00:00 2001 From: Oscar Esteban Date: Sun, 5 Jan 2025 12:41:32 +0100 Subject: [PATCH 1/3] enh: reorganize documentation and redirect to nipreps docs --- docs/source/docker.rst | 106 ------------------------- docs/source/index.rst | 3 +- docs/source/install.rst | 32 +++----- docs/source/{running.rst => usage.rst} | 42 ++++++---- 4 files changed, 39 insertions(+), 144 deletions(-) delete mode 100644 docs/source/docker.rst rename docs/source/{running.rst => usage.rst} (76%) diff --git a/docs/source/docker.rst b/docs/source/docker.rst deleted file mode 100644 index c2064bd52..000000000 --- a/docs/source/docker.rst +++ /dev/null @@ -1,106 +0,0 @@ - -.. _docker: - -Run mriqc with docker -********************* -Preliminaries -------------- -#. Get the Docker Engine (https://docs.docker.com/engine/installation/) -#. Have your data organized in BIDS - (`get BIDS specification `_, - `see BIDS paper `_). -#. Validate your data (https://bids-standard.github.io/bids-validator/). - You can safely use the BIDS-validator since no data is uploaded to the - server, it works locally in your browser. - -.. warning :: - - `2GB is the default memory setting - `_ - on a fresh installation of Docker for Mac. - We recommend increasing the available memory for Docker containers - - When using docker with big datasets (+10GB) docker might fail. - Changing the maximum size of the container will solve it: :: - - $ service docker stop - $ dockerd --storage-opt dm.basesize=30G - - -.. warning :: - - On Windows installations, before using the ``-v`` switch to mount volumes into - the container, it is necessary to `enable shared drives - `_. - - - -.. _docker_run_mriqc: - -Running mriqc -------------- -1. Test that the mriqc container works correctly. A successful run will show - the current mriqc version in the last line of the output: - - :: - - - docker run -it nipreps/mriqc:latest --version - - -2. Run the :code:`participant` level in subjects 001 002 003: - - :: - - - docker run -it --rm -v :/data:ro -v :/out nipreps/mriqc:latest /data /out participant --participant_label 001 002 003 - - -3. Run the group level and report generation on previously processed (use the same ````) - subjects: - - :: - - - docker run -it --rm -v :/data:ro -v :/out nipreps/mriqc:latest /data /out group - - -.. note:: - - If the argument :code:`--participant_label` is not provided, then all - subjects will be processed and the group level analysis will - automatically be executed without need of running the command in item 3. - - -.. warning:: - - Paths `` and `` must be absolute. In particular, specifying relative paths for - `` will generate no error and mriqc will run to completion without error but produce no output. - -.. warning:: - - For security reasons, we recommend to run the docker command with the options - ``--read-only --tmpfs /run --tmpfs /tmp``. This will run the docker image in - read-only mode, and map the temporary folders ``/run`` and ``/tmp`` to the temporal - folder of the host. - -Explaining the mriqc-docker command line ----------------------------------------- -Let's dissect this command line: - -+ :code:`docker run`- instructs the docker engine to get and run a certain - image (which is the last of docker-related arguments: - :code:`nipreps/mriqc:latest`) -+ :code:`-v :/data:ro` - instructs docker to mount the local - directory with your input dataset ``into :code:`/data` inside - the container in a read only mode. -+ :code:`-v :/out`- instructs docker to mount the local - directory ``into :code:`/out` inside the container. This is - where the results of the QC analysis (reports, tables) will be stored. -+ :code:`nipreps/mriqc:latest` - this tells docker to run MRIQC. ``latest`` - corresponds to the version of MRIQC. You - should replace ``latest`` with a version of MRIQC you want to use. Remember - not to switch versions while analysing one dataset! -+ :code:`/data /scratch/out participant` - are the standard - arguments of mriqc. - diff --git a/docs/source/index.rst b/docs/source/index.rst index 2f11c9469..cbae42c18 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -14,8 +14,7 @@ Contents about install - running - docker + usage measures reports workflows diff --git a/docs/source/install.rst b/docs/source/install.rst index c11e4a8e2..df83d4a0b 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -1,28 +1,22 @@ -Installation -************ -Containerized versions ----------------------- -If you have Docker installed, the quickest way to get ``mriqc`` to work -is following :ref:`the running with docker guide `. - -We recommend trying containerized versions first to avoid installation -issues. -MRIQC uses bleeding-edge (oftentimes unreleased) versions of -``nipype`` and ``niworkflows`` and "bare-metal" installations can -be hard. -Nonetheless, we offer support on our `github repository -`_. - +Installing *MRIQC* +****************** +*MRIQC* is a *NiPreps* (`www.nipreps.org `__) +*BIDS App* [BIDSApps]_. +As such, *MRIQC* can be installed manually (*Bare-metal installation*, +see below) or containerized. +For containerized execution with *Docker* or *Singularity*, please +follow the documentation on the *NiPreps* site +(`introduction `__). "Bare-metal" installation ------------------------- -If, for some reason, you really need a bare-metal installation, -MRIQC can be installed as follows. +If, for some reason, you really need a custom installation, +*MRIQC* can be installed as follows. First, please make sure you have the execution system dependencies installed (see below). Second, the latest development version of MRIQC can be installed from -github using ``pip`` on a Python 3 environment: :: +github using ``pip`` on a Python 3 environment: python -m pip install -U mriqc @@ -55,8 +49,6 @@ github using ``pip`` on a Python 3 environment: :: $ sed -i 's/\(backend *: \).*$/\1Agg/g' $( python -c "import matplotlib; print(matplotlib.matplotlib_fname())" ) - - Execution system dependencies ............................. If you are using a a `Neurodebian `_ Linux distribution, diff --git a/docs/source/running.rst b/docs/source/usage.rst similarity index 76% rename from docs/source/running.rst rename to docs/source/usage.rst index 3360d2bdb..202150a61 100644 --- a/docs/source/running.rst +++ b/docs/source/usage.rst @@ -3,18 +3,34 @@ Running *MRIQC* *************** -.. tip:: - Try MRIQC online on `OpenNeuro `_ - without - installation! - -MRIQC is a `BIDS-App `_ [BIDSApps]_, +*MRIQC* is a `BIDS-App `_ [BIDSApps]_, and therefore it inherently understands the :abbr:`BIDS (brain -imaging data structure)` standard [BIDS]_ and follows the -BIDS-Apps standard command line interface:: +imaging data structure)` standard [BIDS]_. +Before moving forward, please make sure to have read and understood +*NiPreps*'s +`introductory documentation `__). + +Containerized execution with *Docker* and *Singularity* +------------------------------------------------------- +For containerized execution with *Docker* or *Singularity*, please +follow the documentation on the *NiPreps* site, which contains +tip and troubleshooting guidelines for both +`Docker `__, and +`Singularity or Apptainer `__. +In addition to container-specific guidelines, the documentation +also includes specific +`help for processing DataLad-managed datasets `__ + +The rest of this documentation page applies to both *bare-metal* +and containerized execution modes. + +A *BIDS Apps* command line interface +------------------------------------ +*MRIQC* follows the *BIDS Apps* standard command line interface:: mriqc bids-root/ output-folder/ participant -That simple command runs MRIQC on all the *T1w* and *BOLD* images found +That simple command runs *MRIQC* on all the *T1w* and *BOLD* images found under the BIDS-compliant folder ``bids-root/``. The last ``participant`` keyword indicates that the first level analysis is run. (i.e. extracting the :abbr:`IQMs (image quality metrics)` from the @@ -80,14 +96,10 @@ Command line interface Running mriqc on HPC clusters ----------------------------- -Singularity containers -...................... -Requesting resources -.................... We have profiled cores and memory usages with the *resource profiler* -tool of nipype. +tool of *Nipype*. -An MRIQC run of one subject (from the ABIDE) dataset, containing only one +An *MRIQC* run of one subject (from the ABIDE) dataset, containing only one run, one BOLD task (resting-state) yielded the following report: .. raw:: html @@ -117,5 +129,3 @@ on ds030 of OpenfMRI: .. [BIDS] `Brain Imaging Data Structure `_ .. [BIDSApps] `BIDS-Apps: portable neuroimaging pipelines that understand BIDS datasets `_ - -.. include:: license.rst From b9008a5aa9fe80e87e91bee92299695c68eeb775 Mon Sep 17 00:00:00 2001 From: Oscar Esteban Date: Mon, 6 Jan 2025 09:52:17 +0100 Subject: [PATCH 2/3] enh: complete suggestions from @yarikoptic Related-to: https://github.com/nipreps/nipreps.github.io/pull/47#discussion_r1903316087 Co-authored-by: Yaroslav Halchenko --- docs/source/usage.rst | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 202150a61..5a78a8162 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -19,7 +19,7 @@ tip and troubleshooting guidelines for both `Singularity or Apptainer `__. In addition to container-specific guidelines, the documentation also includes specific -`help for processing DataLad-managed datasets `__ +`help for processing DataLad-managed datasets `__. The rest of this documentation page applies to both *bare-metal* and containerized execution modes. @@ -86,6 +86,22 @@ in :ref:`The MRIQC Reports `. In the ``group`` level, the :abbr:`IQMs (image quality metrics)` extracted in first place are combined in a table and the group reports are generated. +*MRIQC* can fetch data in *DataLad* datasets +-------------------------------------------- +As of *MRIQC* 22.0.3, the application bundles *DataLad*, enabling automatic +data fetching in *DataLad* datasets. +Employing this feature in containerized environments may lead to +somewhat obscure errors (see, for example, +`nipreps/mriqc#1307 `__). +If you intend to use *DataLad* datasets, please read carefully +*NiPreps*' `help for processing DataLad-managed datasets `__. + +Alternatively, this feature can be disabled by adding +``--no-datalad-get`` to the command line. +This will separate *DataLad* management from *MRIQC*'s operation, +which can be an effective way of debugging issues and averting +fault conditions. + Command line interface ---------------------- .. argparse:: From 825df7f3dba76eb674672a3575de5aa71286fb68 Mon Sep 17 00:00:00 2001 From: Oscar Esteban Date: Mon, 6 Jan 2025 20:28:29 +0100 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Ariel Rokem --- docs/source/usage.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 5a78a8162..dc83b4920 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -10,9 +10,9 @@ Before moving forward, please make sure to have read and understood *NiPreps*'s `introductory documentation `__). -Containerized execution with *Docker* and *Singularity* +Containerized execution with *Docker* and *Singularity*/*Apptainer* ------------------------------------------------------- -For containerized execution with *Docker* or *Singularity*, please +For containerized execution with *Docker* or *Singularity*/*Apptainer*, please follow the documentation on the *NiPreps* site, which contains tip and troubleshooting guidelines for both `Docker `__, and @@ -88,7 +88,7 @@ in :ref:`The MRIQC Reports `. *MRIQC* can fetch data in *DataLad* datasets -------------------------------------------- -As of *MRIQC* 22.0.3, the application bundles *DataLad*, enabling automatic +As of version 22.0.3, *MRIQC* bundles *DataLad*, enabling automatic data fetching in *DataLad* datasets. Employing this feature in containerized environments may lead to somewhat obscure errors (see, for example, @@ -100,7 +100,7 @@ Alternatively, this feature can be disabled by adding ``--no-datalad-get`` to the command line. This will separate *DataLad* management from *MRIQC*'s operation, which can be an effective way of debugging issues and averting -fault conditions. +erroneous conditions. Command line interface ----------------------