trx.workflows

High-level processing workflows for tractogram operations.

Attributes

dipy_available

Functions

convert_dsi_studio(in_dsi_tractogram, in_dsi_fa, ...)	Convert a DSI-Studio TRK file to TRX, fixing space metadata.
convert_tractogram(in_tractogram, out_tractogram, ...)	Convert tractograms between formats with dtype control.
tractogram_simple_compare(in_tractograms, reference)	Compare tractograms against a reference and return a summary diff.
verify_header_compatibility(in_files)	Verify that multiple tractogram headers are mutually compatible.
tractogram_visualize_overlap(in_tractogram, reference)	Visualize overlap between tractogram density maps in different spaces.
validate_tractogram(in_tractogram, reference, ...[, ...])	Validate a tractogram and optionally remove invalid/duplicate streamlines.
_load_streamlines_from_csv(positions_csv)	Load streamlines from a CSV file.
_load_streamlines_from_arrays(positions, offsets)	Load streamlines from position and offset arrays.
_apply_spatial_transforms(streamlines, reference, ...)	Apply spatial transforms and optionally remove invalid streamlines.
_write_header(tmp_dir_name, reference, streamlines)	Write TRX header file to a temporary directory.
_write_streamline_data(tmp_dir_name, streamlines, ...)	Write streamline position and offset data.
_normalize_dtype(dtype_str)	Normalize dtype string format for file naming.
_write_data_array(tmp_dir_name, subdir_name, args[, ...])	Write a data array (dpv/dps/group/dpg) to disk.
generate_trx_from_scratch(reference, out_tractogram[, ...])	Generate TRX file from scratch using various input formats.
manipulate_trx_datatype(in_filename, out_filename, ...)	Change dtype of positions, offsets, dpv, dps, dpg, and groups in a TRX.

Module Contents

trx.workflows.dipy_available = True

trx.workflows.convert_dsi_studio(in_dsi_tractogram, in_dsi_fa, out_tractogram, remove_invalid=True, keep_invalid=False)

Convert a DSI-Studio TRK file to TRX, fixing space metadata.

Parameters:

in_dsi_tractogramstr

Input DSI-Studio TRK path (optionally .trk.gz).

in_dsi_fastr

FA image (.nii.gz) used as reference anatomy.

out_tractogramstr

Destination tractogram path; .trx will be written using TRX writer.

remove_invalidbool, optional

Remove streamlines falling outside the bounding box. Defaults to True.

keep_invalidbool, optional

Keep invalid streamlines even if outside bounding box. Defaults to False.

Returns:

None

Writes the converted tractogram to disk.

trx.workflows.convert_tractogram(in_tractogram, out_tractogram, reference, pos_dtype='float32', offsets_dtype='uint32')

Convert tractograms between formats with dtype control.

Parameters:

in_tractogramstr

Input tractogram path.

out_tractogramstr

Output tractogram path.

referencestr

Reference anatomy required for formats without header affine.

pos_dtypestr, optional

Datatype for positions in TRX output.

offsets_dtypestr, optional

Datatype for offsets in TRX output.

Returns:

None

Writes the converted tractogram to disk.

trx.workflows.tractogram_simple_compare(in_tractograms, reference)

Compare tractograms against a reference and return a summary diff.

Parameters:

in_tractogramslist of str

Paths to tractograms to compare.

referencestr

Reference tractogram path.

Returns:

dict

Dictionary capturing differences across tractograms.

trx.workflows.verify_header_compatibility(in_files)

Verify that multiple tractogram headers are mutually compatible.

Parameters:

in_fileslist of str

Paths to tractogram or NIfTI files to compare.

Returns:

None

Prints compatibility results to stdout.

trx.workflows.tractogram_visualize_overlap(in_tractogram, reference, remove_invalid=True)

Visualize overlap between tractogram density maps in different spaces.

Parameters:

in_tractogramstr

Input tractogram path.

referencestr

Reference anatomy (.nii or .nii.gz).

remove_invalidbool, optional

Remove streamlines outside bounding box before visualization.

Returns:

None

Opens interactive windows when fury is available.

trx.workflows.validate_tractogram(in_tractogram, reference, out_tractogram, remove_identical_streamlines=True, precision=1)

Validate a tractogram and optionally remove invalid/duplicate streamlines.

Parameters:

in_tractogramstr

Input tractogram path.

referencestr

Reference anatomy for formats requiring it.

out_tractogramstr or None

Optional output path to save the cleaned tractogram.

remove_identical_streamlinesbool, optional

Remove duplicate streamlines based on hashing precision.

precisionint, optional

Number of decimals when hashing streamline points.

Returns:

None

Prints warnings and optionally writes a cleaned tractogram.

trx.workflows._load_streamlines_from_csv(positions_csv)

Load streamlines from a CSV file.

Parameters:

positions_csvstr

Path to CSV containing flattened coordinates.

Returns:

nibabel.streamlines.ArraySequence class instance

Streamlines reconstructed from the CSV rows.

trx.workflows._load_streamlines_from_arrays(positions, offsets)

Load streamlines from position and offset arrays.

Parameters:

positionsstr

Path to positions array (.npy or text) shaped (N, 3).

offsetsstr

Path to offsets array marking streamline boundaries.

Returns:

tuple

(ArraySequence, np.ndarray) of streamlines and offsets.

trx.workflows._apply_spatial_transforms(streamlines, reference, space_str, origin_str, verify_invalid, offsets)

Apply spatial transforms and optionally remove invalid streamlines.

Parameters:

streamlinesArraySequence class instance

Streamlines to transform.

referencestr

Reference anatomy used for space/origin.

space_strstr

Desired space (e.g., “rasmm”).

origin_strstr

Desired origin (e.g., “nifti”).

verify_invalidbool

Remove streamlines outside bounding box when True.

offsetsnp.ndarray

Offsets array to preserve after transforms.

Returns:

ArraySequence class instance or None

Transformed streamlines, or None if dipy is unavailable.

trx.workflows._write_header(tmp_dir_name, reference, streamlines)

Write TRX header file to a temporary directory.

Parameters:

tmp_dir_namestr

Temporary directory where header.json is written.

referencestr

Reference anatomy used to derive affine and dimensions.

streamlinesArraySequence class instance

Streamlines whose counts populate the header.

trx.workflows._write_streamline_data(tmp_dir_name, streamlines, positions_dtype, offsets_dtype)

Write streamline position and offset data.

Parameters:

tmp_dir_namestr

Temporary directory to store binary arrays.

streamlinesArraySequence class instance

Streamlines to serialize.

positions_dtypestr

Datatype for positions array.

offsets_dtypestr

Datatype for offsets array.

trx.workflows._normalize_dtype(dtype_str)

Normalize dtype string format for file naming.

Parameters:

dtype_strstr

Input dtype string (e.g., “bool”, “float32”).

Returns:

str

Normalized dtype string where bool is mapped to bit.

trx.workflows._write_data_array(tmp_dir_name, subdir_name, args, is_dpg=False)

Write a data array (dpv/dps/group/dpg) to disk.

Parameters:

tmp_dir_namestr

Base temporary directory.

subdir_namestr

Subdirectory name (dpv, dps, groups, dpg).

argstuple

Tuple describing the array path and dtype (and group when dpg).

is_dpgbool, optional

True when writing data_per_group arrays.

Returns:

None

Writes the array to disk.

trx.workflows.generate_trx_from_scratch(reference, out_tractogram, positions_csv=False, positions=False, offsets=False, positions_dtype='float32', offsets_dtype='uint64', space_str='rasmm', origin_str='nifti', verify_invalid=True, dpv=None, dps=None, groups=None, dpg=None)

Generate TRX file from scratch using various input formats.

Parameters:

referencestr

Reference anatomy used to set affine and dimensions.

out_tractogramstr

Output TRX filename.

positions_csvstr or bool, optional

CSV file containing streamline coordinates; False to disable.

positionsstr or bool, optional

Binary positions array file; False to disable.

offsetsstr or bool, optional

Offsets array file; False to disable.

positions_dtypestr, optional

Datatype for positions.

offsets_dtypestr, optional

Datatype for offsets.

space_strstr, optional

Desired space for generated streamlines.

origin_strstr, optional

Desired origin for generated streamlines.

verify_invalidbool, optional

Remove invalid streamlines when True.

dpvlist or None, optional

Data per vertex definitions.

dpslist or None, optional

Data per streamline definitions.

groupslist or None, optional

Group definitions.

dpglist or None, optional

Data per group definitions.

Returns:

None

Writes the generated TRX file to disk.

trx.workflows.manipulate_trx_datatype(in_filename, out_filename, dict_dtype)

Change dtype of positions, offsets, dpv, dps, dpg, and groups in a TRX.

Parameters:

in_filenamestr

Input TRX file path.

out_filenamestr

Output TRX file path.

dict_dtypedict

Mapping describing target dtypes for each data category.

Returns:

None

Writes the converted TRX to out_filename.