CLI module

These functions are available at the talon.cli module, which must be imported separately.

# import talon
import talon.cli

Utils

talon.cli.utils.add_ndir_to_input(parser: argparse.ArgumentParser)[source]

This function adds the number of directions as input argument to a parser.

The --ndir argument is added to parser. The argument takes as input an integer which by default is equal to 1000.

Parameters

parser – argparse.ArgumentParser Argument parser.

talon.cli.utils.add_verbosity_and_force_to_parser(parser: argparse.ArgumentParser)[source]

This function adds the verbosity and force parameters to a parser.

After calling this method, the input parser will have the following boolean arguments.

  • --force

  • --quiet

  • --warn

  • --info

  • --debug

Parameters

parser – argparse.ArgumentParser Argument parser.

talon.cli.utils.assignment_to_mapping(fpath: str, undirected: bool = True) → collections.defaultdict[source]

This function creates a mapping object from a streamline assignment file.

Parameters

  • fpath – str Path to the file whose rows contain the assignment of each streamline. E.g., if the n-th row is ‘5 17’, the n-th streamline is assigned to regions 5 and 17. The region labels must be integer values and separated by a blank space. Lines starting with # are skipped.

  • undirected – bool True if the mapping must be undirected, False otherwise.

Returns

defaultdict

Dictionary with keys being pairs of regions connected by streamlines and values being the list of streamline indices of those streamlines connecting the corresponding regions.

talon.cli.utils.check_can_write_file(fpath: str, force: bool = False)[source]

Check if a file can be written.

The function checks if the file already exists, the user has the permission to write it, overwriting can be forced and, if the file does not exist, if the parent directory exists and is writable.

Parameters

  • fpath – str path of the file to be checked.

  • force – bool True if the file can be overwritten, False otherwise.

Raises

  • FileExistsError – if the file exists and can not be overwritten.

  • PermissionError – if the file esists and the user does not have the permission to write it.

  • PermissionError – if the file does not exist, the parent directory exists and the user does not have the permission to write a file in it.

  • FileNotFoundError – if file does not exist and the parent directory does not exist.

talon.cli.utils.mapping_to_groups_weights(mapping: collections.defaultdict, connectome: Optional[numpy.ndarray] = None) -> (<class 'list'>, <class 'numpy.ndarray'>)[source]

Extract the streamline groups and weights from a mapping object.

Groups are lists of streamline indices that form a bundle. Weights are defined as follows: let \(N_g\) be the number of streamlines in group \(g\), and let \(c_g\) be the connectivity between the regions linked by streamline bundle \(g\). Each group \(g\) is then associated to a weight equal to

\[w_g = [N_g \cdot (1 + c_g)]^{-1}.\]
Parameters

  • mapping – defaultdict dictionary with keys being pairs of regions connected by streamlines and values being the list of streamline indices of those streamlines connecting the corresponding regions.

  • connectome – np.ndarray connectivity matrix to be employed. The first row and column correspond to the zero label.

Returns

tuple of length 2

  • list of groups

  • 1-dimensional np.ndarray with one weight per group

talon.cli.utils.parse_verbosity(args: argparse.Namespace)[source]

This function applies the wanted verbosity level in logging specified by the parsed arguments given in input.

The default level is logging.WARNING.

Parameters

args – argparse.Namespace Namespace parsed from inputs.

talon.cli.utils.setup_parser(**kwargs) → argparse.ArgumentParser[source]

Setup TALON argument parser.

This function returns an argparse.ArgumentParser object with allow_abbrev=True and add_help=True.

Parameters

kwargs – dict dictionary that will be passed to the constructor of argparse.ArgumentParser.

Returns

argparse.ArgumentParser object with the passed options plus allow_abbrev=True and add_help=True

Commands

Filter

talon.cli.commands.filter.run(in_tracks: str, in_data: str, out_weights: str, force: bool, ndir: int, precomputed_indices_weights: List[str], save_generators_indices_weights: List[str], save_operator_pickle: str, operator_type: str, streamline_assignment: str, connectome: str, sigma: float, allow_negative_x: bool, maxiter: int, objective_relative_tolerance: float, x_absolute_tolerance: float, **kwargs)[source]
Parameters

  • in_tracks – str 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 – str Input data to be fitted. Serves also as reference space for tractogram. Must be in NiBabel-readable format (.nii or .nii.gz).

  • out_weights – str Output text file containing the streamline weights.

  • force – bool True if the file can be overwritten, False otherwise.

  • ndir – int Number of directions for the voxelization.

  • precomputed_indices_weights – List Uses the indices and weights passed as input to build the linear operator. The two matrices must be defined on the same number of directions (ndir) as the ones that are used at the call of this script.

  • save_generators_indices_weights – List Saves the linear operator as three separate files.

  • save_operator_pickle – str Saves the linear operator with pickle. Only available when operator_type is ‘fast’ or ‘reference’.

  • operator_type – str Type of operator to use. Default: fast. Choiches: ‘reference’, ‘fast’, ‘opencl’.

  • streamline_assignment – str Path to the file whose rows contain the assignment of each streamline. E.g., if the n-th row is ‘5 17’, the n-th streamline is assigned to regions 5 and 17. The region labels must be integer values and separated by a blank space. Lines starting with # are skipped.

  • connectome – str Path to the connectivity matrix to be employed in txt format. The first row and column correspond to the zero label.

  • sigma – float 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.

  • allow_negative_x – bool Disables the non negativity constraint.

  • maxiter – int Sets maximum number of iterations. Default: 1000.

  • objective_relative_tolerance – float Sets relative tolerance on cost function. Default: 1e-6.

  • x_absolute_tolerance – float Sets absolute tolerance on variable. Default: 1e-6.

Voxelize

talon.cli.commands.voxelize.run(in_tracks, in_img, out_ind, out_wei, force, ndir, **kwargs)[source]

This function reads tractogram files and writes the corresponding indices and weights files.

Parameters

  • in_tracks – str 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 – str Image serving as space reference. Must be in NiBabel-readable format (.nii or .nii.gz).

  • out_ind – str Path where the indices will be saved in .npz format.

  • out_wei – str Path where the weights will be saved in .npz format.

  • force – bool True if the file can be overwritten, False otherwise.

  • ndir – Number of directions for the voxelization.