Skip to content

API Reference

Core Functions

compute_frd

Compute the Fréchet Radiomics Distance between two image distributions.

This is the main entry point. Supports both FRDv0 and FRDv1 (default). All parameters work for both versions unless noted otherwise.

Params: -- paths : List of two paths (directories or file lists) or .npz files. -- frd_version : 'v0' or 'v1' (default). Determines default feature extraction, normalization, and post-processing strategy. -- features : List of feature class names (e.g. ['firstorder', 'glcm']). For v0: defaults to all 8 classes. For v1: None uses the YAML-configured classes; if specified, overrides the YAML. -- norm_type : 'minmax' or 'zscore'. Default depends on frd_version. -- norm_range : [min, max] for normalization rescaling. Default depends on frd_version. -- paths_masks : Optional list of two mask directory paths. -- resize_size : Optional pixel resize target (int or (w,h) tuple). -- verbose : Logging verbosity. -- save_features : Save features to CSV (default False). -- norm_ref : str, one of 'joint' (default), 'd1', or 'independent'. -- num_workers : CPU workers for multiprocessing (None = auto). -- image_types : List of pyradiomics image types, e.g. ['Original', 'LoG', 'Wavelet']. -- use_paper_log : bool. If True, apply paper Eq. 3 log transform: FRD = log(d_F). Default False uses the original code convention: FRD = log(d_F^2). -- log_sigma : list of float, LoG sigma values (e.g. [2.0, 3.0, 4.0, 5.0]). -- config_path : str, path to a custom pyradiomics YAML config file. When provided, overrides feature_groups, image_types, log_sigma, bin_width, and other extractor settings entirely. -- bin_width : int, pyradiomics binWidth setting. -- normalize_scale : float, pyradiomics normalizeScale setting. -- voxel_array_shift : float, pyradiomics voxelArrayShift setting. -- exclude_features : list of str, feature categories to exclude after extraction. Options: 'textural', 'wavelet', 'firstorder'. -- match_sample_count : bool, if True subsample the larger dataset to match the smaller. -- means_only : bool, if True compute FRD using only mean vectors (no covariance). -- settings_dict : dict, arbitrary pyradiomics settings passed directly to extractor. -- interpret : bool, if True run interpretability analysis after FRD computation. -- interpret_dir : str, directory for interpretability output files.

Returns: -- frd_value : The computed FRD score. For v1 this is log-transformed.

Parameters:

Parameter Type Description
paths list Two paths (directories, file lists, or .npz files)
frd_version str "v0" or "v1" (default)
features list[str] | None Feature class names (e.g. ["firstorder", "glcm"]). None = version default
norm_type str | None "minmax" or "zscore". None = version default
norm_range list[float] | None [min, max] for normalisation. None = version default
paths_masks list[str] | None Two mask directory paths
resize_size int | tuple | None Pixel resize target
verbose bool Enable detailed logging
save_features bool Save features to CSV
norm_ref str | None "joint", "d1", or "independent". None = version default
num_workers int | None CPU workers. None = auto
image_types list[str] | None PyRadiomics image types. None = version default
use_paper_log bool Use paper Eq. 3 log transform (v1 only)
log_sigma list[float] | None LoG sigma values
config_path str | None Custom PyRadiomics YAML config
bin_width int | None PyRadiomics bin width
normalize_scale float | None PyRadiomics normalise scale
voxel_array_shift float | None PyRadiomics voxel array shift
exclude_features list[str] | None Post-extraction exclusion: "textural", "wavelet", "firstorder", "shape"
match_sample_count bool Subsample larger set to match smaller
means_only bool Skip covariance (mean-only distance)
settings_dict dict | None Arbitrary PyRadiomics settings
interpret bool Run interpretability analysis
interpret_dir str Output directory for interpretability plots

Returns: float — the FRD score.

save_frd_stats

Compute and save feature statistics for a single distribution to a .npz file.

Note: use_paper_log is accepted for API consistency with compute_frd() but has no effect here since save_frd_stats only stores mu/sigma, not the final FRD score.

Parameters: Same as compute_frd(), except paths[0] is the input directory and paths[1] is the output .npz file path.

interpret_frd

Run interpretability analysis on extracted radiomic features.

Produces t-SNE visualizations and per-feature difference rankings.

Params: -- feature_list : list of two np.ndarray (n_samples, n_features), normalized features -- feature_names : list of str, feature names -- viz_dir : output directory for visualizations -- run_tsne : whether to run t-SNE embedding visualization

Returns: -- dict with interpretation results (top_changed_features, etc.)

Parameters:

Parameter Type Description
feature_list list[np.ndarray] Two arrays of shape (n_samples, n_features)
feature_names list[str] Feature names
viz_dir str Output directory
run_tsne bool Whether to produce t-SNE plot

Returns: dict with top_changed_features and n_features.

detect_ood

Out-of-distribution detection using radiomics features.

Params: -- feature_list : list of two np.ndarray [D1_features, D2_features], where D1 is in-distribution (reference) and D2 is test. -- detection_type : 'image' for per-image scoring, 'dataset' for nFRD. -- val_frac : fraction of D1 to hold out for threshold estimation. -- use_val_set : if True, hold out val_frac of D1 for threshold estimation. If False (default), use the full reference set for both the mean embedding and threshold estimation (no split). -- id_dist_assumption : 'gaussian', 't', or 'counting' for threshold estimation. -- output_dir : directory for saving OOD prediction CSVs. -- seed : random seed for reproducibility (val split, sample matching). -- filenames : list of filenames for the test set images (for CSV output).

Returns: -- dict with results (scores, predictions, nfrd, etc.)

Parameters:

Parameter Type Description
feature_list list[np.ndarray] [D1_features, D2_features] — D1 = reference, D2 = test
detection_type str "image" or "dataset"
val_frac float Fraction of D1 for threshold estimation
use_val_set bool Use hold-out validation split
id_dist_assumption str "gaussian", "t", or "counting"
output_dir str CSV output directory
seed int | None Random seed
filenames list[str] | None Filenames for CSV output

Returns: dict — keys depend on detection_type:

  • "image": threshold, scores, predictions, p_values
  • "dataset": nfrd

calculate_frechet_distance

Numpy implementation of the Frechet Distance.

d^2 = ||mu_1 - mu_2||^2 + Tr(C_1 + C_2 - 2sqrt(C_1C_2)).

If means_only=True, only the mean term is computed (no covariance). Stable version by Dougal J. Sutherland.

Constants

Quick import reference

Python
from frd_score import (
    # Core API
    compute_frd,
    save_frd_stats,
    interpret_frd,
    detect_ood,
    # Version constants
    FRD_VERSION_V0,           # "v0"
    FRD_VERSION_V1,           # "v1"
    FRD_VERSION_DEFAULT,      # "v1"
    # Image type defaults
    V0_DEFAULT_IMAGE_TYPES,   # ["Original"]
    V1_DEFAULT_IMAGE_TYPES,   # ["Original", "LoG", "Wavelet"]
    # Normalisation reference modes
    NORM_REF_JOINT,           # "joint"
    NORM_REF_D1,              # "d1"
    NORM_REF_INDEPENDENT,     # "independent"
    NORM_REF_DEFAULT,         # None (resolved per-version)
    V0_DEFAULT_NORM_REF,      # "joint"
    V1_DEFAULT_NORM_REF,      # "d1"
    # Feature exclusion
    EXCLUDE_TEXTURAL,         # "textural"
    EXCLUDE_WAVELET,          # "wavelet"
    EXCLUDE_FIRSTORDER,       # "firstorder"
    EXCLUDE_SHAPE,            # "shape"
    EXCLUDE_OPTIONS,          # {"textural", "wavelet", "firstorder", "shape"}
    # PyRadiomics defaults
    DEFAULT_BIN_WIDTH,        # 5
    DEFAULT_NORMALIZE_SCALE,  # 100
    DEFAULT_VOXEL_ARRAY_SHIFT,# 300
)