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 toparser
. 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
andadd_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
andadd_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.