.. _command-line-interface:

Command-line usage
==================

*MRtrix3* generally follows a relatively standard Unix syntax, namely:

.. code-block:: console

    $ command [options] argument1 argument2 ...

If you need to become familiar with using the command-line, there are
plenty of tutorials online to get you started. There are however a few notable 
features specific to *MRtrix3*, which are outlined below.


Ordering of options on the command-line
---------------------------------------

Options can typically occur anywhere on the command-line, in any order -
they do not usually need to precede the arguments.

For instance, all three of the lines below will have the same result:

.. code-block:: console

    $ command -option1 -option2 argument1 argument2
    $ command argument1 argument2 -option1 -option2
    $ command -option2 argument1 argument2 -option1

Care must however be taken in cases where a command-line option *itself
has an associated compulsory argument*. For instance, consider a command-line
option ``-number``, which allows the user to manually provide a numerical
value in order to control some behaviour. The user's desired value
*must* be provided *immediately after* '``-number``' appears on the
command-line in order to be correctly associated with that particular option.

For instance, the following would be interpreted correctly:

.. code-block:: console

    $ command -number 10 argument1 argument2

But the following would *not*:

.. code-block:: console

    $ command -number argument1 10 argument2

The following cases would also *not* be interpreted correctly by *MRtrix3*,
even though some other softwares may interpret their command-line options in
such ways:

.. code-block:: console

    $ command -number10 argument1 argument2
    $ command --number=10 argument1 argument2

There are a few cases in *MRtrix3* where the order of options on the
command-line *does* matter, and hence the above demonstration does not apply:

-  :ref:`mrcalc`: ``mrcalc`` is a stack-based calculator, and as such, the
   order of inputs and operations on the command-line determine how the
   mathematical expression is formed.

-  :ref:`mrview`: ``mrview`` includes a number of command-line options for
   automatically configuring the viewing window, and importing data into
   its various tools. Here the order of such options does matter: the
   command line contents are read from left to right, and any command-line
   options that alter the display of a particular image or data open within
   a tool is applied to the *most recent* data (image or otherwise) opened
   by the tool associated with that option.

-  *Scripts*: A subset of the Python scripts provided with *MRtrix3*
   require the selection of an *algorithm*, which defines the approach that
   the script will use to arrive at its end result based on the data
   provided. The name of this algorithm *must* be the *first* argument on
   the command-line; any command-line options provided *prior* to this
   algorithm name will be **silently ignored**.


.. _number_sequences:

Number sequences
----------------

Some options expect arguments in the form of *number sequences* or
*floating-point lists of numbers*. The former consists or a series of
integers separated by commas or colons (no spaces), with colons
indicating a range, optionally with an increment (if different from 1).
For example:

-  ``1,4,8`` becomes ``[ 1 4 8 ]``
-  ``3,6:12,2`` becomes ``[ 3 6 7 8 9 10 11 12 2 ]``
-  ``1:3:10,8:2:0`` becomes ``[ 1 4 7 10 8 6 4 2 0 ]``

Note that the sign of the increment does not matter, it will always run
in the direction required.

Certain commands (e.g. ``mrconvert``) also accept the special ``end``
keyword, which will take on the largest possible value along the corresponding
axis. For example, the following command can be used to extract every other
volume from an input 4D image:

.. code-block:: console

    $ mrconvert input.mif -coord 3 0:2:end output.mif



Floating-point lists
--------------------

Likewise, floating-point lists consist of a comma-separated list of
numbers, for example:

-  ``2.47,-8.2223,1.45e-3``

As in the integer case, it is also possible to supply a range of values using
the colon syntax, although in this case the increment is mandatory. For
example:

- ``3.1:2.2:10`` expands to ``[ 3.1 5.3 7.5 9.7 ]``

The ``nan`` keyword can also be provided to insert a Not-a-Number.


Using shortened option names
----------------------------

Options do not need to be provided in full, as long as the initial part
of the option provided is sufficient to unambiguously identify it.

For example:

.. code-block:: console

    $ mrconvert -debug in.mif out.nii.gz

is the same as:

.. code-block:: console

    $ mrconvert -de in.mif out.nii.gz

but will conflict with the ``-datatype`` option if shortened any
further:

.. code-block:: console

    $ mrconvert -d in.mif out.nii.gz
    mrconvert: [ERROR] several matches possible for option "-d": "-datatype, "-debug"


.. _unix_pipelines:

Unix Pipelines
--------------

The output of one program can be fed straight through to the input of
another program via `Unix
pipes <http://en.wikipedia.org/wiki/Pipeline_%28Unix%29>`__ in a single
command. The appropriate syntax is illustrated in this example:

.. code-block:: console

    $ dwi2tensor /data/DICOM_folder/ - | tensor2metric - -vector ev.mif
    dwi2tensor: [done] scanning DICOM folder "/data/DICOM_folder/"
    dwi2tensor: [100%] reading DICOM series "ep2d_diff"...
    dwi2tensor: [100%] reformatting DICOM mosaic images...
    dwi2tensor: [100%] loading data for image "ACME (hm) [MR] ep2d_diff"...
    dwi2tensor: [100%] estimating tensor components...
    tensor2metric: [100%] computing tensor metrics...

This command will execute the following actions:

1. ``dwi2tensor`` will load the input diffusion-weighted data in DICOM
   format from the folder ``/data/DICOM_folder/`` and compute the
   corresponding tensor components. The resulting data set is then fed
   into the pipe.

2. ``tensor2metric`` will access the data set from the pipe, generate an
   eigenvector map and store the resulting data set as ``ev.mif``.

The two stages of the pipeline are separated by the ``|`` symbol, which
indicates to the system that the output of the first command is to be
used as input for the next command. The image that is to be fed to or
from the pipeline is specified for each program using a single dash
``-`` where the image would normally be specified as an argument.

.. WARNING::

   If you use the ``-`` symbol *without* piping through to the next command,
   the temporary file created will *not* be deleted.

   For example, with a command like this:

   .. code-block:: console

       $ mrconvert image.mif -

   ``mrconvert`` has no way to tell that the image it produced hasn't been passed
   onto another command. This means the temporary file it creates will remain
   on the filesystem (default: ``/tmp/`` on Unix, '.' on Windows, see
   :ref:`mrtrix_config`), needlessly taking up storage space. Eventually this can
   fill up the entire filesystem, causing subsequent commands to fail and creating
   problems for the system as a whole. If this happens, the script
   :ref:`mrtrix_cleanup` can be used to remove temporary files from a specific location.


For this to work properly, it is important to know which arguments each
program will interpret as input images, and which as output images. For
example, this command will fail:

.. code-block:: console

    dwi2tensor - /data/DICOM_folder/ | tensor2metric - ev.mif

In this example, ``dwi2tensor`` will hang waiting for input data (its
first argument should be the input DWI data set). This will also cause
``tensor2metric`` to hang while it waits for ``dwi2tensor`` to provide some
input.

Advanced pipeline usage
'''''''''''''''''''''''

Such pipelines are not limited to two programs. Complex operations can
be performed in one line using this technique. Here is a longer example:

.. code-block:: console

    $ dwi2tensor /data/DICOM_folder/ - | tensor2metric - -vector - | mrcalc -
    mask.nii -mult - | mrview -
    dwi2tensor: [done] scanning DICOM folder "/data/DICOM_folder/"
    dwi2tensor: [100%] reading DICOM series "ep2d_diff"...
    dwi2tensor: [100%] reformatting DICOM mosaic images...
    dwi2tensor: [100%] loading data for image "ACME (hm) [MR] ep2d_diff"...
    dwi2tensor: [100%] estimating tensor components...
    tensor2metric: [100%] computing tensor metrics...
    mrcalc: [100%] computing: (/tmp/mrtrix-tmp-VihKrg.mif * mask.nii) ...

This command will execute the following actions:

1. ``dwi2tensor`` will load the input diffusion-weighted data in DICOM
   format from the folder /data/DICOM\_folder/ and compute the
   corresponding tensor components. The resulting data set is then fed
   into the pipe.

2. ``tensor2metric`` will access the tensor data set from the pipe,
   generate an eigenvector map and feed the resulting data into the next
   stage of the pipeline.

3. ``mrcalc`` will access the eigenvector data set from the pipe,
   multiply it by the image mask.nii, and feed the resulting data into
   the next stage of the pipeline.

4. ``mrview`` will access the masked eigenvector data set from the pipe
   and display the resulting image.

How is it implemented?
''''''''''''''''''''''

The procedure used in *MRtrix3* to feed data sets down a pipeline is somewhat
different from the more traditional use of pipes. Given the large amounts of
data typically contained in a data set, the 'standard' practice of feeding the
entire data set through the pipe would be prohibitively inefficient. *MRtrix3*
applications access the data via memory-mapping (when this is possible), and do
not need to explicitly copy the data into their own memory space. When using
pipes, *MRtrix3* applications will simply generate a temporary file and feed
its filename through to the next stage once their processing is done. The next
program in the pipeline will then simply read this filename and access the
corresponding file. The latter program is then responsible for deleting the
temporary file once its processing is done.

This implies that any errors during processing may result in undeleted
temporary files. By default, these will be created within the ``/tmp`` folder
(on Unix, or the current folder on Windows) with a filename of the form
``mrtrix-tmp-XXXXXX.xyz`` (note this can be changed by specifying a custom
``TmpFileDir`` and ``TmpFilePrefix`` in the :ref:`mrtrix_config`).  If a piped
command has failed, and no other *MRtrix* programs are currently running, these
can be safely deleted.

*Really* advanced pipeline usage
''''''''''''''''''''''''''''''''

As implemented, *MRtrix3* commands treat image file names that start with
the ``TmpFilePrefix`` (default is ``mrtrix-tmp-``) as temporary. When
reading the image name from the previous stage in the pipeline, the
image file name will trivially match this. But this also means that it
is possible to provide such a file as a normal *argument*, and it will
be treated as a temporary *piped* image. For example:

.. code-block:: console

    $ mrconvert /data/DICOM/ -datatype float32 -
    mrconvert: [done] scanning DICOM folder "/data/DICOM/"
    mrconvert: [100%] reading DICOM series "ep2d_diff"...
    mrconvert: [100%] reformatting DICOM mosaic images...
    mrconvert: [100%] copying from "ACME (hm) [MR] ep2d_diff" to "/tmp/mrtrix-tmp-zcD1nr.mif"...
    /tmp/mrtrix-tmp-zcD1nr.mif

Notice that the name of the temporary file is now printed on the
terminal, since the command's stdout has not be piped into another
command, and we specified ``-`` as the second argument. You'll also see
this file is now present in the ``/tmp`` folder. You can use this file
by copy/pasting it as an *argument* to another *MRtrix* command (be
careful though, it will be deleted once this command exits):

.. code-block:: console

    $ mrstats /tmp/mrtrix-tmp-zcD1nr.mif
            channel         mean       median    std. dev.          min          max       count
             [ 0 ]       1053.47           96      1324.71            0         3827       506880
             [ 1 ]       173.526           84      140.645            0          549       506880
    ...

This allows for a non-linear arrangement of pipelines, whereby multiple
pipelines can feed into a single command. This is achieved by using the
shell's output capture feature to insert the temporary file name of one
pipeline as an argument into a second pipeline. In BASH, output capture
is achieved using the ``$(commands)`` syntax, or equivalently using
backticks: ```commands```. For example:

.. code-block:: console

    $ dwi2tensor /data/DICOM/ - | tensor2metric - -mask $(dwi2mask /data/DICOM/ - | maskfilter - erode -npass 3 - ) -vec ev.mif -fa - | mrthreshold - -top 300 highFA.mif
    dwi2mask: [done] scanning DICOM folder "/data/DICOM/"
    dwi2tensor: [done] scanning DICOM folder "/data/DICOM/"
    dwi2mask: [100%] reading DICOM series "ep2d_diff"...
    dwi2tensor: [100%] reading DICOM series "ep2d_diff"...
    dwi2mask: [100%] reformatting DICOM mosaic images...
    dwi2tensor: [100%] reformatting DICOM mosaic images...
    dwi2mask: [100%] loading data for image "ACME (hm) [MR] ep2d_diff"...
    dwi2tensor: [100%] loading data for image "ACME (hm) [MR] ep2d_diff"...
    dwi2mask: [100%] finding min/max of "mean b=0 image"...
    dwi2mask: [done] optimising threshold...
    dwi2mask: [100%] thresholding...
    dwi2tensor: [100%] estimating tensor components...
    dwi2mask: [100%] finding min/max of "mean b=1000 image"...
    dwi2mask: [done] optimising threshold...
    dwi2mask: [100%] thresholding...
    dwi2mask: [done] computing dwi brain mask... 
    maskfilter: [100%] applying erode filter to image -... 
    tensor2metric: [100%] computing tensor metrics...
    mrthreshold: [100%] thresholding "/tmp/mrtrix-tmp-UHvhc2.mif" at 300th top voxel...

In this one command, we asked the system to perform this non-linear
pipeline::

                  dwi2tensor \  
                              |--> tensor2metric  ---> mrthreshold
    dwi2mask ---> maskfilter /

More specifically:

1. ``dwi2tensor`` will load the input diffusion-weighted data in DICOM
   format from the folder /data/DICOM/ and compute the corresponding
   tensor components. The resulting data set is then fed into the pipe.

   1. meanwhile, ``dwi2mask`` will generate a brain mask from the DWI
      data, and feed the result into a second pipeline.

   2. ``maskfilter`` will access the mask from this second pipeline,
      erode the mask by 3 voxels, and output the name of the temporary
      file for use as an *argument* by the next stage.

2. ``tensor2metric`` will access the tensor data set from the first
   pipe, generate eigenvector and FA maps within the mask provided as an
   *argument* by the second pipeline, store the eigenvector map in
   ``ev.mif`` and feed the FA map into the next stage of the pipeline.

3. ``mrthreshold`` will access the FA image from the pipe, identify the
   300 highest-valued voxels, and produce a mask of these voxels, stored
   in ``highFA.mif``.