voxelops.schemas package — VoxelOps 2.0.0 documentation

# voxelops.schemas package

Typed dataclass schemas for procedure inputs, expected outputs, and default configurations. Each procedure defines three dataclasses: `Inputs`, `Outputs`, and `Defaults`.

## HeudiConv

HeudiConv schemas: inputs, outputs, and defaults.

class HeudiconvDefaults(heuristic: Path | None = None, bids_validator: bool = True, overwrite: bool = False, converter: str = 'dcm2niix', bids: str | None = 'notop', grouping: str | None = 'all', docker_image: str = 'nipy/heudiconv:1.3.4', post_process: bool = True, post_process_dry_run: bool = False)

  Bases: `object`

  Default configuration for HeudiConv.

  Parameters:

    - heuristic (Optional[Path], optional) – Path to heuristic.py file (required for conversion), by default None.

    - bids_validator (bool, optional) – Run BIDS validator after conversion, by default True.

    - overwrite (bool, optional) – Overwrite existing output, by default False.

    - converter (str, optional) – DICOM converter to use, by default “dcm2niix”.

    - docker_image (str, optional) – Docker image to use, by default “nipy/heudiconv:1.3.4”.

    - post_process (bool, optional) – Enable post-heudiconv processing, by default True.

    - post_process_dry_run (bool, optional) – Test mode - report only, don’t modify, by default False.

  __post_init__()

    Ensure heuristic path is Path object if provided.

  bids: str | None = 'notop'
  bids_validator: bool = True
  converter: str = 'dcm2niix'
  docker_image: str = 'nipy/heudiconv:1.3.4'
  grouping: str | None = 'all'
  heuristic: Path | None = None
  overwrite: bool = False
  post_process: bool = True
  post_process_dry_run: bool = False

class HeudiconvInputs(dicom_dir: Path, participant: str, output_dir: Path | None = None, session: str | None = None, heuristic: Path | None = None)

  Bases: `object`

  Required inputs for HeudiConv DICOM to BIDS conversion.

  Parameters:

    - dicom_dir (Path) – Directory containing DICOM files.

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

    - output_dir (Optional[Path], optional) – Output BIDS directory, by default None. If None, defaults to dicom_dir/../bids.

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

    - heuristic (Optional[Path], optional) – Path to heuristic.py file, by default None.

  __post_init__()

    Ensure paths are Path objects.

  dicom_dir: Path
  heuristic: Path | None = None
  output_dir: Path | None = None
  participant: str
  session: str | None = None

class HeudiconvOutputs(bids_dir: Path, participant_dir: Path, dataset_description: Path)

  Bases: `object`

  Expected outputs from HeudiConv.

  Parameters:

    - bids_dir (Path) – Root BIDS directory.

    - participant_dir (Path) – Participant-specific directory (sub-XX/).

    - dataset_description (Path) – dataset_description.json file.

  bids_dir: Path
  dataset_description: Path
  classmethod from_inputs(inputs: HeudiconvInputs, output_dir: Path)

    Generate expected output paths from inputs.

    Parameters:

      - inputs (HeudiconvInputs) – HeudiconvInputs instance.

      - output_dir (Path) – Resolved output directory.

    Returns:

      HeudiconvOutputs with expected paths.

    Return type:

      HeudiconvOutputs

  participant_dir: Path

## QSIPrep

QSIPrep schemas: inputs, outputs, and defaults.

class QSIPrepDefaults(nprocs: int = 8, mem_mb: int = 16000, output_resolution: float = 1.6, anatomical_template: ~typing.List[str] = <factory>, longitudinal: bool = False, subject_anatomical_reference: str = 'unbiased', skip_bids_validation: bool = False, fs_license: ~pathlib.Path | None = None, docker_image: str = 'pennlinc/qsiprep:latest')

  Bases: `object`

  Default configuration for QSIPrep (brain bank standards).

  Parameters:

    - nprocs (int, optional) – Number of parallel processes, by default 8.

    - mem_gb (int, optional) – Memory limit in GB, by default 16000.

    - output_resolution (float, optional) – Output resolution in mm, by default 1.6.

    - anatomical_template (List[str], optional) – List of output spaces, by default [“MNI152NLin2009cAsym”].

    - longitudinal (bool, optional) – Enable longitudinal processing, by default False.

    - subject_anatomical_reference (str, optional) – Anatomical reference for longitudinal processing, by default “unbiased”.

    - skip_bids_validation (bool, optional) – Skip BIDS validation, by default False.

    - fs_license (Optional[Path], optional) – Path to FreeSurfer license file, by default None.

    - docker_image (str, optional) – Docker image to use, by default “pennlinc/qsiprep:latest”.

  __post_init__()

    Ensure fs_license is Path object if provided.

  anatomical_template: List[str]
  docker_image: str = 'pennlinc/qsiprep:latest'
  fs_license: Path | None = None
  longitudinal: bool = False
  mem_mb: int = 16000
  nprocs: int = 8
  output_resolution: float = 1.6
  skip_bids_validation: bool = False
  subject_anatomical_reference: str = 'unbiased'

class QSIPrepInputs(bids_dir: Path, participant: str, output_dir: Path | None = None, work_dir: Path | None = None, bids_filters: Path | None = None)

  Bases: `object`

  Required inputs for QSIPrep diffusion preprocessing.

  Parameters:

    - bids_dir (Path) – BIDS dataset directory.

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

    - output_dir (Optional[Path], optional) – Output directory, by default None. If None, defaults to bids_dir/../derivatives/qsiprep.

    - work_dir (Optional[Path], optional) – Working directory, by default None. If None, defaults to output_dir/../work/qsiprep.

    - bids_filters (Optional[Path], optional) – Path to BIDS filters JSON file, by default None.

  __post_init__()

    Ensure paths are Path objects.

  bids_dir: Path
  bids_filters: Path | None = None
  output_dir: Path | None = None
  participant: str
  work_dir: Path | None = None

class QSIPrepOutputs(qsiprep_dir: Path, participant_dir: Path, html_report: Path, work_dir: Path, figures_dir: Path)

  Bases: `object`

  Expected outputs from QSIPrep.

  Parameters:

    - qsiprep_dir (Path) – QSIPrep output directory.

    - participant_dir (Path) – Participant-specific directory.

    - html_report (Path) – HTML report file.

    - work_dir (Path) – Working directory.

    - figures_dir (Path) – QC figures directory.

  figures_dir: Path
  classmethod from_inputs(inputs: QSIPrepInputs, output_dir: Path, work_dir: Path)

    Generate expected output paths from inputs.

    Parameters:

      - inputs (QSIPrepInputs) – QSIPrepInputs instance.

      - output_dir (Path) – Resolved output directory.

      - work_dir (Path) – Resolved work directory.

    Returns:

      QSIPrepOutputs with expected paths.

    Return type:

      QSIPrepOutputs

  html_report: Path
  participant_dir: Path
  qsiprep_dir: Path
  work_dir: Path

## QSIRecon

QSIRecon schemas: inputs, outputs, and defaults.

class QSIReconDefaults(nprocs: int = 8, mem_mb: int = 16000, atlases: ~typing.List[str] = <factory>, fs_subjects_dir: ~pathlib.Path | None = None, fs_license: ~pathlib.Path | None = None, docker_image: str = 'pennlinc/qsirecon:latest')

  Bases: `object`

  Default configuration for QSIRecon (brain bank standards).

  Parameters:

    - nprocs (int, optional) – Number of parallel processes, by default 8.

    - mem_gb (int, optional) – Memory limit in GB, by default 16000.

    - atlases (List[str], optional) – List of atlases for connectivity, by default a long list of atlases.

    - fs_subjects_dir (Optional[Path], optional) – FreeSurfer subjects directory, by default None.

    - fs_license (Optional[Path], optional) – Path to FreeSurfer license file, by default None.

    - docker_image (str, optional) – Docker image to use, by default “pennlinc/qsirecon:latest”.

  __post_init__()

    Ensure paths are Path objects if provided.

  atlases: List[str]
  docker_image: str = 'pennlinc/qsirecon:latest'
  fs_license: Path | None = None
  fs_subjects_dir: Path | None = None
  mem_mb: int = 16000
  nprocs: int = 8

class QSIReconInputs(qsiprep_dir: Path, participant: str, output_dir: Path | None = None, work_dir: Path | None = None, recon_spec: Path | None = None, datasets: dict[str, Path] | None = None, atlases: List[str] | None = None)

  Bases: `object`

  Required inputs for QSIRecon diffusion reconstruction.

  Parameters:

    - qsiprep_dir (Path) – QSIPrep output directory.

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

    - output_dir (Optional[Path], optional) – Output directory, by default None. If None, defaults to qsiprep_dir/../qsirecon.

    - work_dir (Optional[Path], optional) – Working directory, by default None. If None, defaults to output_dir/../work/qsirecon.

    - recon_spec (Optional[Path], optional) – Path to reconstruction spec YAML file, by default None.

    - datasets (Optional[dict[str, Path]], optional) – Dictionary of dataset names and paths, by default None.

    - atlases (Optional[List[str]], optional) – List of atlases for connectivity, by default None.

  __post_init__()

    Ensure paths are Path objects.

  atlases: List[str] | None = None
  datasets: dict[str, Path] | None = None
  output_dir: Path | None = None
  participant: str
  qsiprep_dir: Path
  recon_spec: Path | None = None
  work_dir: Path | None = None

class QSIReconOutputs(qsirecon_dir: Path, participant_dir: Path, html_report: Path, work_dir: Path)

  Bases: `object`

  Expected outputs from QSIRecon.

  Parameters:

    - qsirecon_dir (Path) – QSIRecon output directory.

    - participant_dir (Path) – Participant-specific directory.

    - html_report (Path) – HTML report file.

    - work_dir (Path) – Working directory.

  classmethod from_inputs(inputs: QSIReconInputs, output_dir: Path, work_dir: Path)

    Generate expected output paths from inputs.

    Parameters:

      - inputs (QSIReconInputs) – QSIReconInputs instance.

      - output_dir (Path) – Resolved output directory.

      - work_dir (Path) – Resolved work directory.

    Returns:

      QSIReconOutputs with expected paths.

    Return type:

      QSIReconOutputs

  html_report: Path
  participant_dir: Path
  qsirecon_dir: Path
  work_dir: Path

## QSIParc

QSIParc schemas: inputs, outputs, and defaults.

class QSIParcDefaults(mask: str | None = 'gm', force: bool = False, background_label: int = 0, resampling_target: str | None = 'data', log_level: str = 'INFO', n_jobs: int | None = 1, n_procs: int | None = 1)

  Bases: `object`

  Default configuration for QSIParc (brain bank standards).

  Parameters:

    - mask (Optional[str], optional) – Mask to apply during parcellation (“gm”, “wm”, “brain”, or path), by default “gm”.

    - force (bool, optional) – Whether to overwrite existing outputs, by default False.

    - background_label (int, optional) – Label value for background voxels, by default 0.

    - resampling_target (Optional[str], optional) – Resampling strategy (“data”, “labels”, “atlas”, or None), by default “data”.

    - log_level (str, optional) – Logging verbosity (e.g., “INFO”, “DEBUG”), by default “INFO”.

    - n_jobs (Optional[int], optional) – Number of jobs to run in parallel, by default 1.

    - n_procs (Optional[int], optional) – Number of processors to use, by default 1.

  background_label: int = 0
  force: bool = False
  log_level: str = 'INFO'
  mask: str | None = 'gm'
  n_jobs: int | None = 1
  n_procs: int | None = 1
  resampling_target: str | None = 'data'

class QSIParcInputs(qsirecon_dir: Path, participant: str, output_dir: Path | None = None, session: str | None = None, atlases: list[parcellate.interfaces.models.AtlasDefinition] | None = None, n_jobs: int | None = None, n_procs: int | None = None)

  Bases: `object`

  Required inputs for QSIParc parcellation.

  Parameters:

    - qsirecon_dir (Path) – QSIRecon output directory.

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

    - output_dir (Optional[Path], optional) – Output directory, by default None. If None, defaults to qsirecon_dir parent.

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

    - atlases (Optional[list[AtlasDefinition]], optional) – List of atlas definitions, by default None.

    - n_jobs (Optional[int], optional) – Number of jobs to run in parallel, by default None.

    - n_procs (Optional[int], optional) – Number of processors to use, by default None.

  __post_init__()

    Ensure paths are Path objects.

  atlases: list[parcellate.interfaces.models.AtlasDefinition] | None = None
  n_jobs: int | None = None
  n_procs: int | None = None
  output_dir: Path | None = None
  participant: str
  qsirecon_dir: Path
  session: str | None = None

class QSIParcOutputs(output_dir: Path)

  Bases: `object`

  Expected outputs from QSIParc.

  Parameters:

    output_dir (Path) – Parcellation output directory.

  classmethod from_inputs(inputs: QSIParcInputs, output_dir: Path)

    Generate expected output paths from inputs.

    Parameters:

      - inputs (QSIParcInputs) – QSIParcInputs instance.

      - output_dir (Path) – Resolved output directory.

    Returns:

      QSIParcOutputs with expected paths.

    Return type:

      QSIParcOutputs

  output_dir: Path

## Module contents

Schemas for procedure inputs, outputs, and defaults.