voxelops.utils package

Utility functions for post-processing and BIDS compliance.

BIDS Utilities

Post-processing for HeudiConv output: IntendedFor injection, fieldmap validation, and cleanup of spurious .bvec/.bval files.

BIDS post-processing utilities for HeudiConv output.

add_intended_for_to_fmaps(participant_dir: Path, session: str | None = None, dry_run: bool = False) → Dict[str, Any][source]

Add IntendedFor fields to fieldmap JSON files.

Maps fieldmaps to target files based on acquisition type:

  • acq-dwi*_epi.json -> all dwi/*_dwi.nii.gz files

  • acq-func*_epi.json -> all func/*_bold.nii.gz files

Parameters:

  • participant_dir (Path) – Path to participant directory (or session directory if session exists).

  • session (Optional[str], optional) – Session ID (for building relative paths), by default None.

  • dry_run (bool, optional) – If True, report changes without modifying files, by default False.

Returns:

Dictionary with processing results.

Return type:

Dict[str, Any]

post_process_heudiconv_output(bids_dir: Path, participant: str, session: str | None = None, dry_run: bool = False) → Dict[str, Any][source]

Post-process HeudiConv output to ensure BIDS compliance.

Orchestrates all post-processing steps:

  1. Verify fieldmap EPI files exist

  2. Add IntendedFor fields to fmap JSONs

  3. Hide bval/bvec from fmap directories (rename with dot prefix)

Parameters:

  • bids_dir (Path) – Root BIDS directory.

  • participant (str) – Participant ID (without ‘sub-’ prefix).

  • session (Optional[str], optional) – Session ID (without ‘ses-’ prefix), if applicable, by default None.

  • dry_run (bool, optional) – If True, report changes without modifying files, by default False.

Returns:

A dictionary with results:

  • ’success’: bool

  • ’verification’: dict

  • ’intended_for’: dict

  • ’cleanup’: dict

  • ’errors’: list

Return type:

Dict[str, Any]

remove_bval_bvec_from_fmaps(participant_dir: Path, session: str | None = None, dry_run: bool = False) → Dict[str, Any][source]

Hide .bvec and .bval files from fmap directories by renaming with dot prefix.

These files are incorrectly generated by dcm2niix for fieldmaps and are not BIDS-compliant for EPI fieldmaps. Instead of deleting, we rename them with a leading dot to hide them (e.g., .filename.bvec).

Parameters:

  • participant_dir (Path) – Path to participant directory (or session directory if session exists).

  • session (Optional[str], optional) – Session ID (for logging purposes), by default None.

  • dry_run (bool, optional) – If True, report files to hide without renaming, by default False.

Returns:

Dictionary with cleanup results.

Return type:

Dict[str, Any]

verify_fmap_epi_files(participant_dir: Path, session: str | None = None) → Dict[str, Any][source]

Verify that expected fieldmap EPI files exist.

Checks for existence of *acq-dwi*_epi.nii.gz and .json in fmap/ directory.

Parameters:

  • participant_dir (Path) – Path to participant directory (or session directory if session exists).

  • session (Optional[str], optional) – Session ID (for logging purposes), by default None.

Returns:

Dictionary with verification results.

Return type:

Dict[str, Any]

Module contents

Utility modules for VoxelOps.