trx.workflows ============= .. py:module:: trx.workflows .. autoapi-nested-parse:: High-level processing workflows for tractogram operations. .. !! processed by numpydoc !! Attributes ---------- .. autoapisummary:: trx.workflows.dipy_available Functions --------- .. autoapisummary:: trx.workflows.convert_dsi_studio trx.workflows.convert_tractogram trx.workflows.tractogram_simple_compare trx.workflows.verify_header_compatibility trx.workflows.tractogram_visualize_overlap trx.workflows.validate_tractogram trx.workflows._load_streamlines_from_csv trx.workflows._load_streamlines_from_arrays trx.workflows._apply_spatial_transforms trx.workflows._write_header trx.workflows._write_streamline_data trx.workflows._normalize_dtype trx.workflows._write_data_array trx.workflows.generate_trx_from_scratch trx.workflows.manipulate_trx_datatype Module Contents --------------- .. py:data:: dipy_available :value: True .. py:function:: 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_tractogram** : str Input DSI-Studio TRK path (optionally .trk.gz). **in_dsi_fa** : str FA image (.nii.gz) used as reference anatomy. **out_tractogram** : str Destination tractogram path; ``.trx`` will be written using TRX writer. **remove_invalid** : bool, optional Remove streamlines falling outside the bounding box. Defaults to True. **keep_invalid** : bool, optional Keep invalid streamlines even if outside bounding box. Defaults to False. :Returns: None Writes the converted tractogram to disk. .. !! processed by numpydoc !! .. py:function:: convert_tractogram(in_tractogram, out_tractogram, reference, pos_dtype='float32', offsets_dtype='uint32') Convert tractograms between formats with dtype control. :Parameters: **in_tractogram** : str Input tractogram path. **out_tractogram** : str Output tractogram path. **reference** : str Reference anatomy required for formats without header affine. **pos_dtype** : str, optional Datatype for positions in TRX output. **offsets_dtype** : str, optional Datatype for offsets in TRX output. :Returns: None Writes the converted tractogram to disk. .. !! processed by numpydoc !! .. py:function:: tractogram_simple_compare(in_tractograms, reference) Compare tractograms against a reference and return a summary diff. :Parameters: **in_tractograms** : list of str Paths to tractograms to compare. **reference** : str Reference tractogram path. :Returns: dict Dictionary capturing differences across tractograms. .. !! processed by numpydoc !! .. py:function:: verify_header_compatibility(in_files) Verify that multiple tractogram headers are mutually compatible. :Parameters: **in_files** : list of str Paths to tractogram or NIfTI files to compare. :Returns: None Prints compatibility results to stdout. .. !! processed by numpydoc !! .. py:function:: tractogram_visualize_overlap(in_tractogram, reference, remove_invalid=True) Visualize overlap between tractogram density maps in different spaces. :Parameters: **in_tractogram** : str Input tractogram path. **reference** : str Reference anatomy (.nii or .nii.gz). **remove_invalid** : bool, optional Remove streamlines outside bounding box before visualization. :Returns: None Opens interactive windows when fury is available. .. !! processed by numpydoc !! .. py:function:: validate_tractogram(in_tractogram, reference, out_tractogram, remove_identical_streamlines=True, precision=1) Validate a tractogram and optionally remove invalid/duplicate streamlines. :Parameters: **in_tractogram** : str Input tractogram path. **reference** : str Reference anatomy for formats requiring it. **out_tractogram** : str or None Optional output path to save the cleaned tractogram. **remove_identical_streamlines** : bool, optional Remove duplicate streamlines based on hashing precision. **precision** : int, optional Number of decimals when hashing streamline points. :Returns: None Prints warnings and optionally writes a cleaned tractogram. .. !! processed by numpydoc !! .. py:function:: _load_streamlines_from_csv(positions_csv) Load streamlines from a CSV file. :Parameters: **positions_csv** : str Path to CSV containing flattened coordinates. :Returns: nibabel.streamlines.ArraySequence class instance Streamlines reconstructed from the CSV rows. .. !! processed by numpydoc !! .. py:function:: _load_streamlines_from_arrays(positions, offsets) Load streamlines from position and offset arrays. :Parameters: **positions** : str Path to positions array (.npy or text) shaped (N, 3). **offsets** : str Path to offsets array marking streamline boundaries. :Returns: tuple (ArraySequence, np.ndarray) of streamlines and offsets. .. !! processed by numpydoc !! .. py:function:: _apply_spatial_transforms(streamlines, reference, space_str, origin_str, verify_invalid, offsets) Apply spatial transforms and optionally remove invalid streamlines. :Parameters: **streamlines** : ArraySequence class instance Streamlines to transform. **reference** : str Reference anatomy used for space/origin. **space_str** : str Desired space (e.g., "rasmm"). **origin_str** : str Desired origin (e.g., "nifti"). **verify_invalid** : bool Remove streamlines outside bounding box when True. **offsets** : np.ndarray Offsets array to preserve after transforms. :Returns: ArraySequence class instance or None Transformed streamlines, or None if dipy is unavailable. .. !! processed by numpydoc !! .. py:function:: _write_header(tmp_dir_name, reference, streamlines) Write TRX header file to a temporary directory. :Parameters: **tmp_dir_name** : str Temporary directory where header.json is written. **reference** : str Reference anatomy used to derive affine and dimensions. **streamlines** : ArraySequence class instance Streamlines whose counts populate the header. .. !! processed by numpydoc !! .. py:function:: _write_streamline_data(tmp_dir_name, streamlines, positions_dtype, offsets_dtype) Write streamline position and offset data. :Parameters: **tmp_dir_name** : str Temporary directory to store binary arrays. **streamlines** : ArraySequence class instance Streamlines to serialize. **positions_dtype** : str Datatype for positions array. **offsets_dtype** : str Datatype for offsets array. .. !! processed by numpydoc !! .. py:function:: _normalize_dtype(dtype_str) Normalize dtype string format for file naming. :Parameters: **dtype_str** : str Input dtype string (e.g., "bool", "float32"). :Returns: str Normalized dtype string where ``bool`` is mapped to ``bit``. .. !! processed by numpydoc !! .. py:function:: _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_name** : str Base temporary directory. **subdir_name** : str Subdirectory name (dpv, dps, groups, dpg). **args** : tuple Tuple describing the array path and dtype (and group when dpg). **is_dpg** : bool, optional True when writing data_per_group arrays. :Returns: None Writes the array to disk. .. !! processed by numpydoc !! .. py:function:: 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: **reference** : str Reference anatomy used to set affine and dimensions. **out_tractogram** : str Output TRX filename. **positions_csv** : str or bool, optional CSV file containing streamline coordinates; False to disable. **positions** : str or bool, optional Binary positions array file; False to disable. **offsets** : str or bool, optional Offsets array file; False to disable. **positions_dtype** : str, optional Datatype for positions. **offsets_dtype** : str, optional Datatype for offsets. **space_str** : str, optional Desired space for generated streamlines. **origin_str** : str, optional Desired origin for generated streamlines. **verify_invalid** : bool, optional Remove invalid streamlines when True. **dpv** : list or None, optional Data per vertex definitions. **dps** : list or None, optional Data per streamline definitions. **groups** : list or None, optional Group definitions. **dpg** : list or None, optional Data per group definitions. :Returns: None Writes the generated TRX file to disk. .. !! processed by numpydoc !! .. py:function:: manipulate_trx_datatype(in_filename, out_filename, dict_dtype) Change dtype of positions, offsets, dpv, dps, dpg, and groups in a TRX. :Parameters: **in_filename** : str Input TRX file path. **out_filename** : str Output TRX file path. **dict_dtype** : dict Mapping describing target dtypes for each data category. :Returns: None Writes the converted TRX to ``out_filename``. .. !! processed by numpydoc !!