voxelops.utils package — VoxelOps 2.0.0 documentation

# 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]

  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]

  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]

  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]

  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.