BatchPreprocessor#

class zrad.batch.preprocessing.BatchPreprocessor(input_directory: str | Path, output_directory: str | Path, input_data_type: str, modality: str, number_of_threads: int = 1, patient_folders: Sequence[str] | None = None, start_folder: str | int | None = None, stop_folder: str | int | None = None, structures: Sequence[str] | None = None, use_all_structures: bool = False, nifti_image_name: str | None = None, just_save_as_nifti: bool = False, resample_resolution: float | None = None, resample_dimension: str | None = None, image_interpolation_method: str | None = None, mask_interpolation_method: str | None = None, mask_interpolation_threshold: float = 0.5, mask_union: bool = False, parallel_backend: str = 'processes')[source]#

Run preprocessing over many case folders and write NIfTI outputs.

BatchPreprocessor is the batch counterpart to the lower-level preprocessing classes. It discovers case folders, loads DICOM or NIfTI images and masks, optionally resamples them, and writes one output folder per case. The API is save-to-disk only; images and masks are summarized in the returned BatchResult rather than returned in memory.

Parameters:

  • input_directory (str or pathlib.Path) – Directory containing one subfolder per case.

  • output_directory (str or pathlib.Path) – Directory where preprocessed case folders are written.

  • input_data_type ({"dicom", "nifti"}) – Input format. Values are normalized to lower-case during validation.

  • modality ({"CT", "MRI", "PET", "MG", "US", "RTDOSE"}) – Image modality used by the image reader. Values are normalized to upper-case during validation.

  • number_of_threads (int, optional) – Number of cases to process in parallel. The default is 1.

  • patient_folders (sequence of str or str, optional) – Explicit case folders to process. Comma-separated strings are accepted.

  • start_folder (str or int, optional) – Inclusive numeric folder range. Both values must be provided together.

  • stop_folder (str or int, optional) – Inclusive numeric folder range. Both values must be provided together.

  • structures (sequence of str or str, optional) – Structure names to process. For NIfTI input these are mask file names.

  • use_all_structures (bool, optional) – For DICOM input, process all structures found in the RTSTRUCT or SEG object.

  • nifti_image_name (str, optional) – Image file name or stem used for NIfTI input.

  • just_save_as_nifti (bool, optional) – If True, convert inputs to NIfTI without resampling.

  • resample_resolution (float, optional) – Target in-plane or isotropic resolution in millimetres when resampling.

  • resample_dimension ({"2D", "3D"}, optional) – Use "2D" to keep the original slice spacing or "3D" for isotropic resampling.

  • image_interpolation_method (str, optional) – Interpolation method for images when resampling.

  • mask_interpolation_method (str, optional) – Interpolation method for masks when resampling.

  • mask_interpolation_threshold (float, optional) – Threshold applied to interpolated masks. The default is 0.5.

  • mask_union (bool, optional) – If True, write a binary union of all successfully processed masks.

  • parallel_backend ({"processes", "threads"}, optional) – Joblib backend preference used when number_of_threads is greater than one. The default is "processes".

Notes

validate() normalizes public attributes in place. After validation, directories are Path objects, input_data_type is lower-case, modality is upper-case, and comma-separated folders or structures are stored as lists.

Methods

plan()

Return the case folders selected for preprocessing.

run([progress_callback])

Run preprocessing and write NIfTI outputs.

validate()

Validate and normalize preprocessing configuration.
BatchPreprocessor.plan() → list[str][source]#

Return the case folders selected for preprocessing.

Returns:

folders – Deterministically ordered case folder names selected by patient_folders or the numeric start_folder / stop_folder range. If neither option is set, all non-hidden subfolders are returned.

Return type:

list of str

Raises:

InvalidInputParametersError – If validation fails before folder selection.

BatchPreprocessor.run(progress_callback: Callable[[int], None] | None = None) → BatchResult[source]#

Run preprocessing and write NIfTI outputs.

Parameters:

progress_callback (callable, optional) – Function called as progress_callback(step_count) after cases complete. step_count may be greater than one during parallel execution.

Returns:

result – Aggregate result with one PreprocessingCaseResult per selected case.

Return type:

BatchResult

Notes

Case-level failures are recorded in the returned result and do not stop the batch.

BatchPreprocessor.validate() → None[source]#

Validate and normalize preprocessing configuration.

Raises:

InvalidInputParametersError – If the input directory, data type, modality, folder selection, structure selection, threading, backend, or resampling settings are invalid.