trx.utils

Utility functions for reference handling, coordinate flips, and file operations.

Attributes

dipy_available

Functions

close_or_delete_mmap(obj)	Close the memory-mapped file if it exists, otherwise set the object to None.
split_name_with_gz(filename)	Return the clean basename and extension of a file.
get_reference_info_wrapper(reference)	Extract spatial attributes from a reference object.
is_header_compatible(reference_1, reference_2)	Compare the spatial attributes of 2 references.
get_axis_shift_vector(flip_axes)	Return a shift vector for the given axes.
get_axis_flip_vector(flip_axes)	Return a flip vector for the given axes.
get_shift_vector(sft)	Return the shift vector for flipping a tractogram.
flip_sft(sft, flip_axes)	Flip the streamlines in a StatefulTractogram.
load_matrix_in_any_format(filepath)	Load a matrix from a txt file OR a npy file.
get_reverse_enum(space_str, origin_str)	Convert string representation to enums for the StatefulTractogram.
convert_data_dict_to_tractogram(data)	Convert data from a lazy tractogram to a tractogram.
append_generator_to_dict(gen, data)	Append items yielded by a tractogram generator into data dict.
verify_trx_dtype(trx, dict_dtype)	Verify that data dtypes in the trx match the given dict.

Module Contents

trx.utils.dipy_available = True

trx.utils.close_or_delete_mmap(obj)

Close the memory-mapped file if it exists, otherwise set the object to None.

Parameters:

objobject

The object that potentially has a memory-mapped file to be closed.

trx.utils.split_name_with_gz(filename)

Return the clean basename and extension of a file.

Correctly manages the “.nii.gz” extensions.

Parameters:

filenamestr

The filename to clean.

Returns:

basestr

Clean basename.

extstr

The full extension.

trx.utils.get_reference_info_wrapper(reference)

Extract spatial attributes from a reference object.

Parameters:

referencestr or dict or Nifti1Image or TrkFile or Nifti1Header or TrxFile

Reference that provides the spatial attribute.

Returns:

affinendarray (4, 4)

Transformation of VOX to RASMM, np.float32.

dimensionsndarray (3,)

Volume shape for each axis, int16.

voxel_sizesndarray (3,)

Size of voxel for each axis, float32.

voxel_orderstr

Typically ‘RAS’ or ‘LPS’.

trx.utils.is_header_compatible(reference_1, reference_2)

Compare the spatial attributes of 2 references.

Parameters:

reference_1Nifti or Trk filename, Nifti1Image or TrkFile,

Nifti1Header or trk.header (dict) Reference that provides the spatial attribute.

reference_2Nifti or Trk filename, Nifti1Image or TrkFile,

Nifti1Header or trk.header (dict) Reference that provides the spatial attribute.

Returns:

bool

Whether all the spatial attributes match.

trx.utils.get_axis_shift_vector(flip_axes)

Return a shift vector for the given axes.

Parameters:

flip_axeslist of str

String containing the axis to flip. Possible values are ‘x’, ‘y’, ‘z’.

Returns:

shift_vectornp.ndarray (3,)

Vector containing the axis to shift. Possible values are -1, 0.

trx.utils.get_axis_flip_vector(flip_axes)

Return a flip vector for the given axes.

Parameters:

flip_axeslist of str

String containing the axis to flip. Possible values are ‘x’, ‘y’, ‘z’.

Returns:

flip_vectornp.ndarray (3,)

Vector containing the axis to flip. Possible values are -1, 1.

trx.utils.get_shift_vector(sft)

Return the shift vector for flipping a tractogram.

When flipping a tractogram the shift vector is used to change the origin of the grid from the corner to the center of the grid.

Parameters:

sftStatefulTractogram

StatefulTractogram object.

Returns:

shift_vectorndarray

Shift vector to apply to the streamlines.

trx.utils.flip_sft(sft, flip_axes)

Flip the streamlines in a StatefulTractogram.

Use the spatial information to flip according to the center of the grid.

Parameters:

sftStatefulTractogram

StatefulTractogram to flip.

flip_axeslist of str

Axes to flip. Possible values are ‘x’, ‘y’, ‘z’.

Returns:

sftStatefulTractogram

StatefulTractogram with flipped axes.

trx.utils.load_matrix_in_any_format(filepath)

Load a matrix from a txt file OR a npy file.

Parameters:

filepathstr

Path to the matrix file.

Returns:

matrixnumpy.ndarray

The matrix.

trx.utils.get_reverse_enum(space_str, origin_str)

Convert string representation to enums for the StatefulTractogram.

Parameters:

space_strstr

String representing the space.

origin_strstr

String representing the origin.

Returns:

spaceSpace

Space enum value.

originOrigin

Origin enum value.

trx.utils.convert_data_dict_to_tractogram(data)

Convert data from a lazy tractogram to a tractogram.

Parameters:

datadict

The data dictionary to convert into a nibabel tractogram.

Returns:

Tractogram

A Tractogram object.

trx.utils.append_generator_to_dict(gen, data)

Append items yielded by a tractogram generator into data dict.

Parameters:

genTractogramItem class instance or np.ndarray

Item produced by a tractogram generator. Structured entries include per-point and per-streamline metadata.

datadict

Accumulator containing strs (positions), dpv and dps dictionaries that will be extended in-place.

Returns:

None

The function mutates data and returns None.

trx.utils.verify_trx_dtype(trx, dict_dtype)

Verify that data dtypes in the trx match the given dict.

Parameters:

trxTractogram

Tractogram to verify.

dict_dtypedict

Dictionary containing all elements dtype to verify.

Returns:

bool

True if the dtype is the same, False otherwise.