.. _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 <http://bids.neuroimaging.io/>`_,
   `see BIDS paper <http://dx.doi.org/10.1038/sdata.2016.44>`_).
#. Validate your data (http://incf.github.io/bids-validator/). You can
   safely use the BIDS-validator since no data is uploaded to the server,
   works locally in your browser.

.. warning ::

    `2GB is the default memory setting
    <https://docs.docker.com/docker-for-mac/>`_
    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
    <https://docs.docker.com/docker-for-windows/#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 <bids_dir>:/data:ro -v <output_dir>:/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 ``<output_dir>``)
   subjects:

  ::


      docker run -it --rm -v <bids_dir>:/data:ro -v <output_dir>:/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 `<bids_dir>` and `<output_dir>` must be absolute.  In particular, specifying relative paths for
    `<output_dir>` 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 <bids_dir>:/data:ro` - instructs docker to mount the local
  directory with your input dataset `<bids_dir>`into :code:`/data` inside
  the container in a read only mode.
+ :code:`-v <output_dir>:/out`- instructs docker to mount the local
  directory `<output_dir>`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.