<commit_before>.. _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::

    $ 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*
   (currently :ref:`5ttgen` and :ref:`dwi2response`) 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 and floating-point lists
-----------------------------------------

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.

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

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


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::

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

is the same as:

.. code::

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

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

.. code::

    $ 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:<commit_msg>docs: update description of number sequences<commit_after>.. _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.

-  :ref:`Scripts <list-of-mrtrix3-scripts>`: A subset of the Python scripts provided with *MRtrix3*
   (currently :ref:`5ttgen` and :ref:`dwi2response`) 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:
{'fraction_non_alphanumeric': 0.10311301400410311, 'fraction_numerical': 0.022923914013022923, 'mean_word_length': 3.4812150279776177, 'pattern_counts': {'":': 2, '<': 6, '<?xml version=': 0, '>': 6, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '113650', 'n_tokens_mistral': 3249, 'n_tokens_neox': 3049, 'n_words': 1485}