## Basic usage

Commands are generally issued by typing the command name, followed by a series of arguments and options separated by white spaces. MRtrix applications will typically require at least one argument (usually an image specifier), and may need to be tuned in some way using command line options (described here).

Consider the `mrconvert` command:

    > mrconvert image.img -vox 1,1,2.5 out.mif
    mrconvert: copying data... 100%

In this example, `mrconvert` is the command name, `image.img` is the first argument, `out.mif` is the second argument, `-vox` is an option, and `1,1,2.5` is an additional argument required by the `-vox` option. This command converts the Analyse format image `image.img` into the MRtrix format image `out.mif`, overriding the original voxel size to 1 × 1 × 2.5 mm.

In order to find out how to use a particular program, you can use the `-help` option to display that program's help page (see Standard options).

Note that since arguments are assumed to be separated by white space, filenames containing a space need to be treated with special care to avoid them being interpreted as two arguments instead of one. There are several ways to avoid this problem: the filename can be enclosed in inverted commas, or each white space can be escaped with a preceeding backslash (`'\'`). For example, if there is a file named `'an example filename.img'`, then the following commands are all valid and equivalent:

    > mrinfo 'an example filename.img'
    > mrinfo "an example filename.img"
    > mrinfo an\ example\ filename.img

Unix only: note also that commands and filenames are case-sensitive. If a command you issued fails, check its spelling and case.

top

## Command line options

Command line options may be supplied to modify the behaviour of a program, or to supply additional information. A command-line option consists of one or more minus signs immediately followed by the option name. Options will often require additional arguments to operate correctly, in which case these must be specified immediately after the option itself.

The following example illustrates an option modifying the behaviour of a program:

    > mrconvert -info /data/DICOM_folder/ out.img
    mrconvert [INFO]: opening image "/data/DICOM_folder/"...
    mrconvert [INFO]: initialising DICOM dictionary
    mrconvert: scanning DICOM folder /data/DICOM_folder/"  - ok
    mrconvert: reading DICOM series "t1_mpr_0.9 iso hres"... 100%
    mrconvert [INFO]: loading image "VOLUNTEER(000366) [MR] t1_mpr_0.9 iso hres"...
    mrconvert [INFO]: creating image "poo.mif"...
    mrconvert: copying data... 100%
    mrconvert [INFO]: closing image "VOLUNTEER(000366) [MR] t1_mpr_0.9 iso hres"...
    mrconvert [INFO]: closing image "./poo.mif"...

In this example, the `-info` option tells the program to display additional information while processing.

The following example illustrates the case of an option requiring an additional argument to specify additional information:

    > threshold image.img -percent 20 -invert mask.img
    threshold: finding min/max... 100%
    threshold: thresholding at intensity 266.8... 100%

In this example, the `-percent` option tells the `threshold` program to threshold at the 20% level, and the `-invert` option causes it to invert the results. This will produce the binary mask image `mask.img`, where pixels are set to one if the original intensities were less than 20% of the maximum pixel intensity in `image.img`, and set to zero otherwise.

MRtrix programs will accept shortened option names as long as there are no ambiguities. For example, the following command is equivalent to that above:

    > threshold image.img --p 20 -inv mask.img
    threshold: finding min/max... 100%
    threshold: thresholding at intensity 266.8... 100%

However, the following command will fail:

    > threshold image.img -p 20 -i mask.img
    threshold: several matches possible for option "i": "invert", "info"

since `threshold` accepts two different options that both start with 'i'.

top

## Standard options

All MRtrix programs understand the following options:

Option | Action
--- | ---
`-info` | display information messages.
`-quiet` | do not display information messages or progress status.
`-debug` | display debugging messages.
`-help` | display the program's information page and exit.
`-version` | display version information and exit.

To find out how to use a program, including the required number of arguments and all valid options, type the program name followed by the `-help` option. This will display that program's help page.

top

## Number sequences

Many MRtrix applications understand sequences of numbers and can operate according to the sequence specified. For example, you may only need a few series from a data set. In this case, you could use the `mrconvert` command and specify the series you need as follows:

    > mrconvert -coord 3 0:3,8,10 dwi.mif dwi-[].img

In this example, `mrconvert` will select from the image data set `dwi.mif` the series specified by the number sequence `0:3,8,10`, corresponding to the numbers 0, 1, 2, 3, 8 & 10 (this assumes that the series axis is axis 3). The output images will be stored as a set of numbered Analyse format images, named `dwi-0.img`, `dwi-1.img`, etc. (the 'square brackets' syntax used here is explained below).

Note that a number sequence cannot contain any spaces, since it would then be interpreted as two arguments (see Basic usage). The syntax consists of a comma-separated list of any of the following items:

a
  the integer a.
a:b
  all integers from a to b inclusive.
  If a is greater than b, then the sequence will run down from a to b.
  The keyword `end` may be used instead of either `a` or `b` in certain cases where its meaning is unambiguous.
a:i:b
  the integers a, a+i, a+2i, ..., b.
  The sign of i will be set according to the relative magnitudes of a and b to ensure that the sequence is valid.

The square brackets used in the example above (`dwi-[].img`) are used to indicate a numbered sequence of images that should be interpreted as a single data set (e.g. a fMRI time series). In the previous case, the sequence was left empty, leaving the program to automatically number the filenames accordingly. These images can be accessed using a similar syntax. For example:

    > mrinfo dwi-[].img

will access all matching images as a 4-dimensional data set (assuming each of the individual images contains a 3D data set). If only one of the images is of interest, it can be accessed by specifying its filename as normal without the use of square brackets:

    > mrinfo dwi-1.img

Finally, to access a data set formed from a subset of the images, insert the appropriate number sequence within the square brackets:

    > mrinfo dwi-[1,3].img

Note that when using number sequences to specify a filename, any leading zeros in the number field will be ignored. For example, the images `dwi-1.img` and `dwi-001.img` will both be matched by the identifier `dwi-[1].img`.

top

## Data pipes

The output of one program can be fed straight through to the input of another program via pipes in a single command. The appropriate syntax is illustrated in this example:

    > dwi2tensor /data/DICOM_folder/ - | tensor2vector - ev.mif
    dwi2tensor: scanning DICOM folder "/data/DICOM_folder/"  - ok
    dwi2tensor: reading DICOM series "diff60_b3000_2.3_iPat2+ADC"... 100%
    dwi2tensor: DICOM image contains mosaic files - reformating... 100%
    dwi2tensor: converting DW images to tensor image... 100%
    tensor2vector: generating major eigenvector map... 100%

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. `tensor2vector` 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.

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

    > dwi2tensor - /data/DICOM_folder/ | tensor2vector - 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 `tensor2vector` to hang while it waits for `dwi2tensor` to provide some input.

### Advanced

The procedure used in MRtrix 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 data through the pipe would be prohibitively inefficient. MRtrix 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, MRtrix 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. These will normally be created within the current directory with a filename of the form `mrtrix-XXXXXX.xyz`. If a piped command has failed, and no other MRtrix programs are currently running, these can be safely deleted.

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

    > dwi2tensor /data/DICOM_folder/ - | tensor2vector - - | mrmult - mask.img - | mrview -
    dwi2tensor: scanning DICOM folder "/data/DICOM_folder/"  - ok
    dwi2tensor: reading DICOM series "diff60_b3000_2.3_iPat2+ADC"... 100%
    dwi2tensor: DICOM image contains mosaic files - reformating... 100%
    dwi2tensor: converting DW images to tensor image... 100%
    tensor2vector: generating major eigenvector map... 100%
    mrmult: multiplying... 100%

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. `tensor2vector` 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. `mrmult` will access the eigenvector data set from the pipe, multiply it by the image `mask.img`, 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.