BatchRadiomicsExtractor#
- class zrad.batch.radiomics.BatchRadiomicsExtractor(input_directory: str | Path, output_directory: str | Path, input_data_type: str, modality: str, aggregation_dimension: str, aggregation_method: str, discretization_method: 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, nifti_filtered_image_name: str | None = None, slice_weighting: bool = False, slice_median: bool = False, number_of_bins: int | str | None = None, bin_size: float | str | None = None, intensity_range: Sequence[float] | None = None, outlier_range: float | str | None = None, output_filename: str = 'radiomics.csv', parallel_backend: str = 'processes', ivh_method: str | None = None, ivh_number_of_bins: int | str | None = None, ivh_bin_size: float | str | None = None)[source]#
Extract radiomics features for many case folders and write one CSV.
BatchRadiomicsExtractoris the batch counterpart tozrad.radiomics.Radiomics. It discovers case folders, loads images and masks, prepares ROI data, extracts radiomics features for each requested structure, and writes one CSV file for the whole batch. The API is save-to-disk first; feature rows are written to disk and only summaries are returned in memory.- Parameters:
input_directory (str or pathlib.Path) – Directory containing one subfolder per case.
output_directory (str or pathlib.Path) – Directory where the radiomics CSV is 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 and to select automatic IVH preparation for unfiltered input.
aggregation_dimension ({"2D", "2.5D", "3D"}) – Spatial aggregation dimensionality for texture features.
aggregation_method ({"MERG", "AVER", "SLICE_MERG", "DIR_MERG"}) – Texture aggregation strategy across directions and slices.
discretization_method ({"Number of Bins", "Bin Size"}) – Texture discretization strategy.
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 extract. For NIfTI input these are mask file names and are required.
use_all_structures (bool, optional) – For DICOM input, extract all structures found in the RTSTRUCT or SEG object.
nifti_image_name (str, optional) – Image file name or stem used for NIfTI input.
nifti_filtered_image_name (str, optional) – Optional filtered-image file name or stem used for NIfTI input.
slice_weighting (bool, optional) – Weight 2D slice-wise texture averages by slice ROI size.
slice_median (bool, optional) – Aggregate 2D slice-wise texture values by median instead of mean.
number_of_bins (int, optional) – Number of bins used with
"Number of Bins"discretization.bin_size (float, optional) – Bin size used with
"Bin Size"discretization.intensity_range (sequence of float, optional) – Two-value lower and upper intensity range used for re-segmentation and fixed-bin-size texture discretization. It also sets the IVH bounds for unfiltered images.
outlier_range (float, optional) – Positive outlier range used during re-segmentation.
output_filename (str, optional) – CSV file name written in
output_directory. The default is"radiomics.csv".parallel_backend ({"processes", "threads"}, optional) – Joblib backend preference used when
number_of_threadsis greater than one. The default is"processes".ivh_method ({"direct", "fixed_bin_size", "fixed_bin_number"}, optional) – IVH preparation strategy. If omitted, filtered images use 1000 fixed-number bins; otherwise the modality selects the strategy.
ivh_number_of_bins (int, optional) – Number of IVH bins required with
ivh_method="fixed_bin_number".ivh_bin_size (float, optional) – IVH bin width required with
ivh_method="fixed_bin_size".
Notes
IVH preparation is independent of texture discretization. See IVH-specific discretization for modality-specific defaults and range behavior.
validate()normalizes public attributes in place. After validation, directories arePathobjects,input_data_typeis lower-case, modality and aggregation values are upper-case where applicable, and numeric settings are converted to numeric Python values.
Methods
|
Return the case folders selected for radiomics extraction. |
|
Run radiomics extraction and write the output CSV. |
|
Validate and normalize radiomics batch configuration. |
- BatchRadiomicsExtractor.plan() list[str][source]#
Return the case folders selected for radiomics extraction.
- Returns:
folders – Deterministically ordered case folder names selected by
patient_foldersor the numericstart_folder/stop_folderrange. If neither option is set, all non-hidden subfolders are returned.- Return type:
list of str
- Raises:
InvalidInputParametersError – If validation fails before folder selection.
- BatchRadiomicsExtractor.run(progress_callback: Callable[[int], None] | None = None) BatchResult[source]#
Run radiomics extraction and write the output CSV.
- Parameters:
progress_callback (callable, optional) – Function called as
progress_callback(step_count)after cases complete.step_countmay be greater than one during parallel execution.- Returns:
result – Aggregate result with one
RadiomicsCaseResultper selected case.- Return type:
Notes
Missing masks and per-structure extraction failures are recorded as skipped structures. IVH failures retain the other features and are recorded in
omitted_ivh_structures. Case-level failures are recorded in the returned result and do not stop the batch. If no feature rows are produced, an empty CSV file is still created.