autods_pet.ops.mask_discovery#

Discover manual lesion masks (NIfTI/NRRD/DICOM SEG) for a patient.

This module is the single source of truth for finding the file (or DICOM segment) that backs each configured target ROI section.

Two complementary lookup mechanisms run in parallel:

  • DICOM SEG path - recursively walks the patient input directory, filters .dcm files via is_dicom_seg(), keeps only those whose ReferencedSeriesSequence includes the patient’s PET SeriesInstanceUID, then matches each segment’s SegmentLabel (case-insensitive) against the segment_label keys configured in the target sections. One SEG file may supply multiple targets.

  • File path - recursively walks for .nii.gz / .nii / .nrrd files whose stem matches one of the mask_filename values configured in the target sections.

When a target has both a DICOM SEG match and a file match, DICOM SEG wins. The walker is bounded by max_depth and skips the global output_dir (when nested under input_dir) so that previously written result masks are not rediscovered as inputs.

class autods_pet.ops.mask_discovery.DiscoveredMask(target_name, path, format, segment_label=None, segment_number=None)[source]#

Bases: object

A resolved manual mask for a single target ROI.

Parameters:

  • target_name (str)

  • path (Path)

  • format (Literal['dicom_seg', 'nifti', 'nrrd'])

  • segment_label (str | None)

  • segment_number (int | None)

target_name: str#

Config section name ("focal_lesion", "paramedullary", "extramedullary", or a custom targets.<name> key).

path: Path#

File on disk that contains the mask.

format: Literal['dicom_seg', 'nifti', 'nrrd']#

Storage format.

segment_label: str | None = None#

For DICOM SEG, the matched SegmentLabel (as written in the SEG, not the user pattern). None for NIfTI/NRRD.

segment_number: int | None = None#

For DICOM SEG, the matched segment number. None for NIfTI/NRRD.

autods_pet.ops.mask_discovery.discover_file_masks(input_dir, targets, *, max_depth=4, skip_dirs=None)[source]#

Recursively find NIfTI/NRRD masks for each target by filename stem.

Parameters:

  • input_dir (Path) – Patient input directory to walk recursively.

  • targets (list[dict[str, Any]]) – Target config entries (from autods_pet.config.get_all_targets()).

  • max_depth (int (default: 4)) – Maximum recursion depth.

  • skip_dirs (set[Path] | None (default: None)) – Absolute directories to exclude from the walk (e.g. the global output_dir when nested under input_dir).

Returns:

Map from target name to the first matching file found.

Return type:

dict[str, DiscoveredMask]

autods_pet.ops.mask_discovery.discover_dicom_seg_masks(input_dir, targets, pet_series_uid, *, max_depth=4, skip_dirs=None)[source]#

Recursively find DICOM SEG masks for each target by SegmentLabel.

Parameters:

  • input_dir (Path) – Patient input directory to walk recursively.

  • targets (list[dict[str, Any]]) – Target config entries.

  • pet_series_uid (str | None) – The patient’s PET SeriesInstanceUID. When None the UID match is bypassed (any DICOM SEG is considered) and an informational message is added to the warnings list.

  • max_depth (int (default: 4)) – Maximum recursion depth.

  • skip_dirs (set[Path] | None (default: None)) – Absolute directories to exclude from the walk.

Returns:

(matches, info_messages). Info messages capture unmatched-segment notes and “found SEG but UID didn’t match” notes that callers may want to log.

Return type:

tuple[dict[str, DiscoveredMask], list[str]]

autods_pet.ops.mask_discovery.discover_all_masks(input_dir, targets, pet_series_uid, *, max_depth=4, skip_dirs=None)[source]#

Discover masks for every target via both DICOM SEG and file paths.

DICOM SEG matches override file matches when both formats resolve the same target.

Returns:

(target_name -> DiscoveredMask, warnings). warnings contains caller-actionable messages: missing-mask warnings (one per target whose section is enabled but no match was found), unmatched-segment notes, and conflict notes when both formats matched the same target.

Return type:

tuple[dict[str, DiscoveredMask], list[str]]

Parameters: