Evaluation and metrics¶
Use composed evaluation for a complete reconstruction and direct metrics for
individual images or fields. All residual signs follow estimate - reference.
The metrics guide defines normalization and mask behavior.
evaluate_reconstruction(
result: ReconstructionResult,
truth: ComplexArray,
*,
problem: ReconstructionProblem | None = None,
reference_model: ImagePlaneModel | None = None,
valid_object_mask: MaskArray | None = None,
) -> dict[str, Any]
Evaluate a reconstruction against a complex ground-truth field.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
result
|
ReconstructionResult
|
Completed reconstruction to evaluate. |
required |
truth
|
ComplexArray
|
Complex128 reference field shaped like |
required |
problem
|
ReconstructionProblem | None
|
Optional reconstruction problem. When supplied, predicted intensities are compared with its measured frames. |
None
|
reference_model
|
ImagePlaneModel | None
|
Optional model containing reference pupil and illumination calibration. |
None
|
valid_object_mask
|
MaskArray | None
|
Optional uint8 object-space mask; zero excludes a pixel. |
None
|
Returns:
| Type | Description |
|---|---|
dict
|
Nested |
Notes
Complex-field and phase metrics remove the best global phase offset before comparison. Object and pupil arrays use their respective grid shapes.
radial_fourier_spectrum(
field: ComplexArray,
) -> dict[str, list[float] | list[int]]
Return radial bins, normalized Fourier power, and sample counts.
This is the package-level alias of
fpm_rs.metrics.radial_fourier_spectrum.
field must be a nonempty two-dimensional complex array.
Direct, domain-agnostic metric calculations.
All two-image functions use reference and estimate terminology.
Signed residuals are estimate - reference. These reporting metrics are
separate from reconstruction objectives in Rust's algorithms::objective.
Bases: TypedDict
Summary statistics for one intensity image.
instance-attribute
¶
saturated_pixels: int
Pixels at or above the requested saturation value, or zero if omitted.
Bases: TypedDict
Aggregate residual statistics for matching intensity images.
instance-attribute
¶
residual_std: float
Population standard deviation of valid residuals.
instance-attribute
¶
normalized_l2: float
Residual L2 norm divided by reference L2 norm.
instance-attribute
¶
saturated_pixels: int | None
Valid estimate pixels at saturation, or None when no threshold is given.
stats(
image: Any, saturation_value: float | None = None
) -> IntensityStats
Return summary statistics for one non-empty intensity image.
compare_intensity(
reference: Any,
estimate: Any,
*,
valid_mask: Any | None = None,
saturation_value: float | None = None,
) -> IntensityComparison
Return aggregate residual statistics for a reference/estimate pair.
bias(
reference: Any,
estimate: Any,
*,
valid_mask: Any | None = None,
) -> float
Return mean signed residual, estimate - reference.
mae(
reference: Any,
estimate: Any,
*,
valid_mask: Any | None = None,
) -> float
Return mean absolute error over valid pixels.
mse(
reference: Any,
estimate: Any,
*,
valid_mask: Any | None = None,
) -> float
Return mean squared error over valid pixels.
rmse(
reference: Any,
estimate: Any,
*,
valid_mask: Any | None = None,
) -> float
Return root mean squared error over valid pixels.
relative_l1(
reference: Any,
estimate: Any,
*,
valid_mask: Any | None = None,
) -> float
Return L1 residual divided by the reference L1 norm.
nrmse(
reference: Any,
estimate: Any,
*,
valid_mask: Any | None = None,
) -> float
Return residual L2 norm divided by the reference L2 norm.
amplitude_nrmse(
reference: Any,
estimate: Any,
*,
valid_mask: Any | None = None,
) -> float
Compare square-root intensities, normalized by reference amplitude energy.
correlation(
reference: Any,
estimate: Any,
*,
valid_mask: Any | None = None,
) -> float
Return Pearson correlation over valid pixels.
psnr(
reference: Any,
estimate: Any,
*,
valid_mask: Any | None = None,
data_range: float,
) -> float
Return PSNR in dB for an explicit finite, positive data_range.
ssim(
reference: Any,
estimate: Any,
*,
valid_mask: Any | None = None,
data_range: float,
) -> float
Return canonical single-scale SSIM using an 11×11 Gaussian window (σ=1.5).
References
Wang, Bovik, Sheikh, and Simoncelli, Image quality assessment: From error visibility to structural similarity (2004), IEEE Transactions on Image Processing 13(4), 600–612.
compare_complex_fields(
reference: Any,
candidate: Any,
*,
valid_mask: Any | None = None,
) -> dict[str, float]
Compare two complex128 fields after removing their global phase offset.
Returns amplitude, complex-field, phase, and Fourier error metrics plus the fitted global phase in radians. Arrays and the optional boolean mask must have matching nonempty two-dimensional shapes.
poisson_deviance(
reference: Any,
estimate: Any,
*,
valid_mask: Any | None = None,
epsilon: float,
) -> float
Return summed Poisson deviance; epsilon floors estimate intensity.
radial_fourier_spectrum(
field: Any,
) -> dict[str, list[float] | list[int]]
Radially bin normalized centered-Fourier power for a complex 2D field.
The returned mapping contains radial bin indices, normalized power, and the number of Fourier samples in each bin.
mean_poisson_deviance(
reference: Any,
estimate: Any,
*,
valid_mask: Any | None = None,
epsilon: float,
) -> float
Return Poisson deviance averaged over valid pixels.
fitted_gain(
reference: Any,
estimate: Any,
*,
valid_mask: Any | None = None,
) -> float
Fit the least-squares gain in estimate ≈ gain × reference.
_comparison_inputs(
reference: Any, estimate: Any, valid_mask: Any | None
) -> tuple[ndarray, ndarray, ndarray | None]
_scalar_metric(
function: Any,
reference: Any,
estimate: Any,
valid_mask: Any | None,
) -> float