CLI: Command Line Interface¶
Talon provides a handy command line interface that allows to filter a tractogram file and obtain the streamline coefficients in text format.
The main command is talon
, which is installed together with the package (see
Installation) and allows to filter and voxelize a tractogram.
>>> talon --help
usage: talon [-h] {filter,voxelize} ...
Tractograms As Linear Operators in Neuroimaging - command line interface
positional arguments:
{filter,voxelize}
filter Filter a tractogram using TALON.
voxelize Voxelize a tractogram using TALON.
optional arguments:
-h, --help show this help message and exit
Copyright: CoBCoM 2021.
talon filter
¶
The talon filter
command allows to filter a given tractogram as in
Solving the inverse problem, but without the need to write any Python code.
The basic syntax that you’ll have to use is
talon filter streamlines.tck data.nii.gz streamline_weights.txt
where streamline.tck
is the tractogram to be filtered, data.nii.gz
is
what is being fit by the filtering process (we will get to that later) and
streamline_weights.txt
is the text file where the streamline weights will
be saved.
Streamlines¶
The input tractogram must be in NiBabel-readable format,
i.e., in tck
or trk
format. In both cases, it is required to be in
RAS+ and mm space. The streamline coordinate (0,0,0) refers to the center of
the voxel.
Data¶
The input data must be a .nii/.nii.gz
volume registered with the
tractogram. It contains the data fitted by talon. For the volume-fraction
model used by talon filter
it has to encode the intra-axonal volume
fraction in each voxel.
Output weights¶
The output is a text file where the n-th row contains the weight computed for the n-th streamline.
Group sparsity regularization¶
The command is able to take into account the bundle organization of the
streamlines. For a detailed presentation of how this is encoded as a
regularization term, please refer to Structured Sparsity.
This prior is activated by passing the option
--streamline-assignment sa.txt
to talon solve
.
The sa.txt
file contains one row per streamline and the n-th row contains
the labels of the two regions connected by the n-th streamline.
For instance, a tractogram with three streamlines could correspond to the
following assignment file.
# assignment file of subject ABC1234
3 15
7 2
15 3
The first row starts with #
, hence will not be read by the program.
Then we have a streamline connecting regions 3 and 15, a second one connecting
regions 7 and 2 and a third streamline connecting regions 15 and 3.
The order of the labels is ignored by the program, hence the first and the
third streamlines are bundled together, while the second streamline forms
another bundle.
The assignment file is typically obtained via tck2connectome
, which is
part of the
Mrtrix’s suite.
tck2connectome \
streamlines.tck atlas.nii.gz connectome.txt \
-out_assignment streamline_assignment.txt
Using GPUs¶
Using a GPU can significantly speed up the execution. Before attempting to use
it, be sure to have PyOpenCL installed.
The use of the GPU processing capabilities is triggered by the
--operator-type
option as follows.
--operator-type opencl
Other options¶
>>> talon filter --help
usage: talon filter [-h] [--operator-type {reference,fast,opencl}]
[--ndir number] [--allow-negative-x] [--sigma value]
[--streamline-assignment file] [--connectome file]
[--objective-relative-tolerance value]
[--x-absolute-tolerance value] [--maxiter count]
[--precomputed-indices-weights file_idx file_wei]
[--save-generators-indices-weights file_gen file_idx file_wei | --save-operator-pickle file]
[--force] [--quiet | --warn | --info | --debug]
in_tracks in_data out_weights
Use TALON to filter a tractogram with the Volume Fraction forward model.
positional arguments:
in_tracks Input tractogram file in RAS+ and mm space. The
streamline coordinate (0,0,0) refers to the center of
the voxel. Must be in NiBabel-readable format (.trk or
.tck).
in_data Input data to be fitted. Serves also as reference
space for tractogram. Must be in NiBabel-readable
format (.nii or .nii.gz).
out_weights Output text file containing the streamline weights.
optional arguments:
-h, --help show this help message and exit
--operator-type {reference,fast,opencl}
Type of operator to use. Default: `fast`.
--ndir number Number of directions for the voxelization. Default:
1000.
--precomputed-indices-weights file_idx file_wei
Uses the indices and weights passed as input to build
the linear operator. E.g. `--precomputed-indices-
weights <indices>.npz <weights>.npz`. The two matrices
must be defined on the same number of directions as
the ones that are used at the call of this script.
--save-generators-indices-weights file_gen file_idx file_wei
Saves the linear operator as three separate files
`<generators>.npy <indices>.npz <weights>.npz`. All
types of operator can be saved in this format.
--save-operator-pickle file
Saves the linear operator with pickle. Only available
when --operator-type is set to `reference` or `fast`.
--force Overwrite existing files.
--quiet Do not display messages.
--warn Display warning messages.
--info Display information messages.
--debug Display debug messages.
Solver options:
--allow-negative-x Disables the non negativity constraint.
--sigma value Sets the regularization scale parameter as in (Frigo,
2021). The final value of lambda is
`sigma*max(||At*data||/gwei)`, where sigma is the
passed parameter, `||At*data||` is the 2-norm of the
product between the transposed linear operator and the
data, and `gwei` is the vector of the weights
associated to each group of streamlines. Default: 0.0.
--streamline-assignment file
Activates the group sparsity regularization by
specifying the node assignments of each streamline to
some parcellation. Typically, this file is produced by
the Mrtrix3 command `tck2connectome` with the option
`-out_assignment`. The file is expected to be in text
format with one row per streamline. E.g., if the first
row is [5, 14], the first streamline will be bundled
together with all the streamlines corresponding rows
having [5, 14] or [14, 5].
--connectome file Activates the FIT regularization by specifying the
connectivity matrix. Each streamline bundle is
associated to the entry in the connectivity matrix
corresponding to the region lables that it connects.
E.g., the bundle connecting regions 5 and 14 is
associated to the entry [5, 14] of the connectivity
matrix. Notice that the first row and column
correspond to the zero label. Must be used together
with `--streamline-assignment`.
--objective-relative-tolerance value
Sets relative tolerance on cost function. Default:
1e-06.
--x-absolute-tolerance value
Sets absolute tolerance on variable. Default: 1e-06.
--maxiter count Sets maximum number of iterations. Default: 1000.
talon voxelize
¶
The talon filter
command allows to create the indices and weights
matrices that are necessary to define a talon linear operator as in
Getting started, but without the need to write any Python code.
The basic syntax that you’ll have to use is
talon voxelize streamlines.tck image.nii.gz indices.npz weights.npz
where streamline.tck
is the tractogram to be voxelized, image.nii.gz
is
a reference image that defines the shape of the linear operator (typically the
data that is going to be fitted in the filtering process) and indices.npz
and weights.npz
are the two
COO sparse matrices
that define the indices and weights of the linear operator respectively.
Streamlines¶
The input tractogram must be in NiBabel-readable format,
i.e., in tck
or trk
format. In both cases, it is required to be in
RAS+ and mm space. The streamline coordinate (0,0,0) refers to the center of
the voxel.
Output matrices¶
The two COO matrices are saved in .npz
format. If the
suffix is not present in the filename, it is automatically appended.
Other options¶
>>> talon voxelize --help
usage: talon voxelize [-h] [--ndir number] [--force]
[--quiet | --warn | --info | --debug]
in_tracks in_img out_ind out_wei
Transform a tractogram into the `indices` and `weights` matrices that are used
in the definition of the linear operator used by TALON.
positional arguments:
in_tracks Tractogram file to be voxelized in RAS+ and mm space. The
streamline coordinate (0,0,0) refers to the center of the
voxel. Must be in NiBabel-readable format (.trk or .tck).
in_img Image serving as space reference. Must be in NiBabel-readable
format (.nii or .nii.gz).
out_ind Path where the indices will be saved in .npz format.
out_wei Path where the weights will be saved in .npz format.
optional arguments:
-h, --help show this help message and exit
--ndir number Number of directions for the voxelization. Default: 1000.
--force Overwrite existing files.
--quiet Do not display messages.
--warn Display warning messages.
--info Display information messages.
--debug Display debug messages.