phenotypic.util.ImageMetricsCalculator#

class phenotypic.util.ImageMetricsCalculator(detect_mat: numpy.ndarray)[source]#

Bases: object

Computes image quality metrics from detection matrices.

This class extracts noise, contrast, structure, and background metrics used to assess image quality for colony detection. It provides the computational core shared by both the static matplotlib and the interactive Plotly diagnostics visualizations.

Parameters:

detect_mat (np.ndarray) – 2D grayscale detection matrix (typically image.detect_mat[:]).

bit_depth#

Image bit depth (8 or 16) inferred from max intensity.

Examples

>>> from phenotypic.data import load_synth_yeast_plate
>>> from phenotypic.util.image_metrics import ImageMetricsCalculator
>>> image = load_synth_yeast_plate()
>>> calc = ImageMetricsCalculator(image.detect_mat[:])
>>> noise = calc.compute_noise_metrics()
>>> print(f"SNR: {noise['snr']:.2f}")
SNR: ...
>>> contrast = calc.compute_contrast_metrics()
>>> print(f"RMS contrast: {contrast['rms_contrast']:.3f}")
RMS contrast: ...

Methods

__init__

compute_all

Compute all metrics and return comprehensive dict.

compute_background_metrics

Compute background uniformity metrics.

compute_contrast_metrics

Compute contrast-related metrics (parameter-free).

compute_local_contrast

Compute local Weber contrast map.

compute_local_variance

Compute local variance map.

compute_noise_metrics

Compute noise-related metrics (parameter-free).

compute_psd

Compute radially averaged power spectral density.

compute_quality_scores

Compute normalized 0-1 quality scores for radar chart.

compute_structure_metrics

Compute structure tensor and ridge detection metrics.

generate_interpretation

Generate human-readable interpretation text.

generate_recommendations

Generate actionable preprocessing recommendations.

Attributes

bit_depth

Image bit depth (8 or 16) inferred from max intensity.

max_intensity

Maximum intensity value based on image bit depth.
property bit_depth: int#

Image bit depth (8 or 16) inferred from max intensity.

property max_intensity: float#

Maximum intensity value based on image bit depth.

compute_psd(img: np.ndarray | None = None) → tuple[np.ndarray, np.ndarray][source]#

Compute radially averaged power spectral density.

Parameters:

img (np.ndarray | None) – Input image array. If None, uses the stored detection matrix.

Returns:

Tuple of (frequencies, radial_psd).

Return type:

tuple[np.ndarray, np.ndarray]

compute_local_contrast(img: np.ndarray | None = None, window_size: int = 15) → np.ndarray[source]#

Compute local Weber contrast map.

Parameters:

  • img (np.ndarray | None) – Input image array. If None, uses the stored detection matrix.

  • window_size (int) – Size of local window.

Returns:

Local contrast map.

Return type:

np.ndarray

compute_local_variance(img: np.ndarray | None = None, window_size: int = 15) → np.ndarray[source]#

Compute local variance map.

Parameters:

  • img (np.ndarray | None) – Input image array. If None, uses the stored detection matrix.

  • window_size (int) – Size of local window.

Returns:

Local variance map.

Return type:

np.ndarray

compute_noise_metrics() → NoiseMetrics[source]#

Compute noise-related metrics (parameter-free).

Returns:

Dictionary with SNR, sigma_mad, and correlation_length.

Return type:

NoiseMetrics

compute_contrast_metrics() → ContrastMetrics[source]#

Compute contrast-related metrics (parameter-free).

Returns:

Dictionary with rms_contrast, michelson, dynamic_range, p1, and p99.

Return type:

ContrastMetrics

compute_structure_metrics(sigma: float = 1.5, scales: list[float] | None = None, ridge_method: Literal['meijering', 'frangi', 'hessian'] = 'meijering') → StructureMetrics[source]#

Compute structure tensor and ridge detection metrics.

Parameters:

  • sigma (float) – Sigma for structure tensor computation.

  • scales (list[float] | None) – List of scales for multiscale ridge detection. Defaults to [0.5, 1.0, 1.5, 2.0, 3.0, 4.0, 5.0].

  • ridge_method (Literal['meijering', 'frangi', 'hessian']) – Method for ridge detection: “meijering” (default), “frangi”, or “hessian”.

Returns:

Dictionary with mean_coherence, optimal_scale, peak_response, ridge_responses, scales, ridge_method, and coherence_map.

Return type:

StructureMetrics

compute_background_metrics(sigma: float = 50.0) → BackgroundMetrics[source]#

Compute background uniformity metrics.

Parameters:

sigma (float) – Sigma for background estimation (Gaussian smoothing).

Returns:

Dictionary with nonuniformity_ratio, mean_gradient, and background_estimate.

Return type:

BackgroundMetrics

compute_quality_scores(noise: NoiseMetrics, contrast: ContrastMetrics, structure: StructureMetrics, background: BackgroundMetrics) → QualityScores[source]#

Compute normalized 0-1 quality scores for radar chart.

Parameters:

  • noise (NoiseMetrics) – Noise metrics from compute_noise_metrics().

  • contrast (ContrastMetrics) – Contrast metrics from compute_contrast_metrics().

  • structure (StructureMetrics) – Structure metrics from compute_structure_metrics().

  • background (BackgroundMetrics) – Background metrics from compute_background_metrics().

Returns:

Dictionary of quality scores (SNR, Contrast, Coherence, Uniformity, Sharpness), all normalized to [0, 1].

Return type:

QualityScores

static generate_interpretation(section: Literal['noise', 'contrast', 'structure', 'background'], metrics: dict[str, Any]) → str[source]#

Generate human-readable interpretation text.

Parameters:

  • section (Literal['noise', 'contrast', 'structure', 'background']) – Section name (“noise”, “contrast”, “structure”, “background”).

  • metrics (dict[str, Any]) – Computed metrics for the section.

Returns:

Interpretation text string.

Return type:

str

static generate_recommendations(noise: NoiseMetrics, contrast: ContrastMetrics, structure: StructureMetrics, background: BackgroundMetrics) → list[str][source]#

Generate actionable preprocessing recommendations.

Parameters:

  • noise (NoiseMetrics) – Noise metrics from compute_noise_metrics().

  • contrast (ContrastMetrics) – Contrast metrics from compute_contrast_metrics().

  • structure (StructureMetrics) – Structure metrics from compute_structure_metrics().

  • background (BackgroundMetrics) – Background metrics from compute_background_metrics().

Returns:

List of recommendation strings.

Return type:

list[str]

compute_all(structure_sigma: float = 1.5, ridge_scales: list[float] | None = None, ridge_method: Literal['meijering', 'frangi', 'hessian'] = 'meijering', background_sigma: float = 50.0, include_non_serializable: bool = False) → dict[str, Any][source]#

Compute all metrics and return comprehensive dict.

Parameters:

  • structure_sigma (float) – Sigma for structure tensor computation.

  • ridge_scales (list[float] | None) – Scales for ridge detection.

  • ridge_method (Literal['meijering', 'frangi', 'hessian']) – Ridge detection algorithm.

  • background_sigma (float) – Sigma for background estimation.

  • include_non_serializable (bool) – If False, removes numpy arrays from output.

Returns:

bit_depth, noise, contrast, structure, background, quality_scores, interpretations, recommendations.

Return type:

Dict with keys