linumpy.metrics#

Metrics module for collecting and saving quality metrics from pipeline steps.

This module provides utilities for recording, saving, and aggregating metrics from various processing steps in the 3D reconstruction pipeline.

Usage:: # Use step-specific collectors (recommended) from linumpy.metrics import collect_pairwise_registration_metrics

Submodules#

linumpy.metrics.image_quality

Attributes#

logger

Classes#

`MetricsEncoder`	Custom JSON encoder to handle numpy types.
`PipelineMetrics`	Class for collecting and managing metrics from pipeline steps.

Functions#

`collect_normalization_metrics`(vol_normalized, ...[, ...])	Collect metrics for intensity normalization step.
`collect_xy_transform_metrics`(transform, ...[, ...])	Collect metrics for XY transform estimation step.
`collect_pairwise_registration_metrics`(...[, ...])	Collect metrics for pairwise registration step.
`collect_interface_crop_metrics`(detected_interface, ...)	Collect metrics for interface cropping step.
`collect_psf_compensation_metrics`(psf, ...[, ...])	Collect metrics for PSF compensation step.
`collect_stack_metrics`(output_shape, z_offsets, ...[, ...])	Collect metrics for slice stacking step.
`collect_stitch_3d_metrics`(input_shape, output_shape, ...)	Collect metrics for 3D tile stitching step.
`load_metrics`(filepath)	Load metrics from a JSON file.
`aggregate_metrics`(metrics_dir[, pattern])	Aggregate all metrics files from a directory.
`compute_summary_statistics`(metrics_list)	Compute summary statistics for a list of metrics from the same step.

Package Contents#

linumpy.metrics.logger[source]#

class linumpy.metrics.MetricsEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]#

Bases: json.JSONEncoder

Custom JSON encoder to handle numpy types.

default(o)[source]#

Serialize numpy integer and float types to Python builtins.

Parameters:: o (Any)
Return type:: Any

class linumpy.metrics.PipelineMetrics(step_name, output_dir=None)[source]#

Class for collecting and managing metrics from pipeline steps.

Each step can record multiple metrics with associated quality indicators. Metrics are saved as JSON files for later aggregation and report generation.

Parameters:

step_name (str)
output_dir (str | None)

DEFAULT_THRESHOLDS: ClassVar[dict][source]#

step_name[source]#

output_dir[source]#

metrics: dict[str, Any][source]#

warnings: list[str] = [][source]#

errors: list[str] = [][source]#

timestamp[source]#

add_metric(name, value, unit=None, threshold_name=None, custom_thresholds=None, description=None)[source]#

Add a metric with optional quality assessment.

Parameters:

name (str) – Name of the metric.
value (Any) – Value of the metric.
unit (str, optional) – Unit of measurement.
threshold_name (str, optional) – Name of threshold to use from DEFAULT_THRESHOLDS.
custom_thresholds (dict, optional) – Custom thresholds {‘warning’: val, ‘error’: val, ‘higher_is_better’: bool}
description (str, optional) – Human-readable description of the metric.

Return type:

None

add_info(name, value, description=None)[source]#

Add informational data (not quality-assessed).

Parameters:

name (str) – Name of the info field.
value (Any) – Value of the info field.
description (str, optional) – Human-readable description.

Return type:

None

get_overall_status()[source]#

Get overall status based on all metrics.

Returns:: ‘error’, ‘warning’, or ‘ok’
Return type:: str

to_dict()[source]#

Convert metrics to dictionary format.

Returns:: Dictionary containing all metrics and metadata.
Return type:: dict

save(filename=None)[source]#

Save metrics to JSON file.

Parameters:: filename (str, optional) – Filename for metrics file. Defaults to ‘{step_name}_metrics.json’
Returns:: Path to the saved metrics file.
Return type:: Path

log_issues()[source]#

Log any warnings or errors to the logger.

Return type:: None

linumpy.metrics.collect_normalization_metrics(vol_normalized, agarose_mask, otsu_threshold, background_thresholds, output_path, input_path=None, params=None)[source]#

Collect metrics for intensity normalization step.

Parameters:

vol_normalized (np.ndarray) – The normalized volume.
agarose_mask (np.ndarray) – The agarose mask used.
otsu_threshold (float) – Otsu threshold computed.
background_thresholds (np.ndarray) – Background thresholds per slice.
output_path (str or Path) – Path to the output file.
input_path (str, optional) – Path to the input image.
params (dict, optional) – Dictionary of parameters used.

Returns:

Metrics object (already saved).

Return type:

PipelineMetrics

linumpy.metrics.collect_xy_transform_metrics(transform, tile_pairs_used, tile_shape, residuals, output_path, input_paths=None, params=None, n_tiles_x=None, n_tiles_y=None)[source]#

Collect metrics for XY transform estimation step.

Parameters:

transform (np.ndarray) – The estimated 2x2 transform matrix.
tile_pairs_used (int) – Number of tile pairs used for estimation.
tile_shape (tuple) – Tile shape (rows, cols).
residuals (np.ndarray) – Residuals from least squares fit.
output_path (str or Path) – Path to the output transform file.
input_paths (list, optional) – List of input image paths.
params (dict, optional) – Dictionary of parameters used.
n_tiles_x (int, optional) – Number of tiles in the X (column) direction.
n_tiles_y (int, optional) – Number of tiles in the Y (row) direction.

Returns:

Metrics object (already saved).

Return type:

PipelineMetrics

linumpy.metrics.collect_pairwise_registration_metrics(registration_error, tx, ty, rotation_deg, best_z_index, expected_z_index, output_path, fixed_path=None, moving_path=None, params=None, z_correlation=0.0)[source]#

Collect metrics for pairwise registration step.

Parameters:

registration_error (float) – Registration error value.
tx (float) – Translation in X and Y.
ty (float) – Translation in X and Y.
rotation_deg (float) – Rotation in degrees.
best_z_index (int) – Best matching z-index.
expected_z_index (int) – Expected z-index based on slice interval.
output_path (str or Path) – Path to the output directory.
fixed_path (str, optional) – Paths to fixed and moving volumes.
moving_path (str, optional) – Paths to fixed and moving volumes.
params (dict, optional) – Dictionary of parameters used.
z_correlation (float, optional) – Normalized cross-correlation score from Z-matching (0-1). Higher values indicate a reliable Z-match between the two slices.

Returns:

Metrics object (already saved).

Return type:

PipelineMetrics

linumpy.metrics.collect_interface_crop_metrics(detected_interface, crop_depth_px, start_idx, end_idx, input_shape, output_shape, resolution_um, output_path, input_path=None, padding_needed=False)[source]#

Collect metrics for interface cropping step.

Parameters:

detected_interface (int) – Detected interface depth in voxels.
crop_depth_px (int) – Cropping depth in voxels.
start_idx (int) – Start and end indices for cropping.
end_idx (int) – Start and end indices for cropping.
input_shape (tuple) – Input and output volume shapes.
output_shape (tuple) – Input and output volume shapes.
resolution_um (float) – Resolution in microns.
output_path (str or Path) – Path to the output file.
input_path (str, optional) – Path to the input file.
padding_needed (bool) – Whether padding was required.

Returns:

Metrics object (already saved).

Return type:

PipelineMetrics

linumpy.metrics.collect_psf_compensation_metrics(psf, agarose_coverage, output_path, input_path=None, fit_gaussian=False)[source]#

Collect metrics for PSF compensation step.

Parameters:

psf (np.ndarray) – The estimated PSF profile.
agarose_coverage (float) – Fraction of image classified as agarose.
output_path (str or Path) – Path to the output file.
input_path (str, optional) – Path to the input file.
fit_gaussian (bool) – Whether Gaussian fit was used.

Returns:

Metrics object (already saved).

Return type:

PipelineMetrics

linumpy.metrics.collect_stack_metrics(output_shape, z_offsets, num_slices, resolution, output_path, blend_enabled=False, normalize_enabled=False)[source]#

Collect metrics for slice stacking step.

Parameters:

output_shape (tuple) – Final output shape.
z_offsets (np.ndarray) – Z-offsets between consecutive slices.
num_slices (int) – Number of slices stacked.
resolution (list) – Output resolution.
output_path (str or Path) – Path to the output file.
blend_enabled (bool) – Whether blending was enabled.
normalize_enabled (bool) – Whether normalization was enabled.

Returns:

Metrics object (already saved).

Return type:

PipelineMetrics

linumpy.metrics.collect_stitch_3d_metrics(input_shape, output_shape, num_tiles, resolution, output_path, input_path=None, blending_method='diffusion')[source]#

Collect metrics for 3D tile stitching step.

Parameters:

input_shape (tuple) – Input mosaic grid shape.
output_shape (tuple) – Output stitched volume shape.
num_tiles (int) – Number of tiles stitched.
resolution (list) – Output resolution.
output_path (str or Path) – Path to the output file.
input_path (str, optional) – Path to the input file.
blending_method (str) – Blending method used.

Returns:

Metrics object (already saved).

Return type:

PipelineMetrics

linumpy.metrics.load_metrics(filepath)[source]#

Load metrics from a JSON file.

Parameters:: filepath (str or Path) – Path to the metrics JSON file.
Returns:: Loaded metrics dictionary.
Return type:: dict

linumpy.metrics.aggregate_metrics(metrics_dir, pattern='*_metrics.json')[source]#

Aggregate all metrics files from a directory.

Parameters:

metrics_dir (str or Path) – Directory containing metrics files.
pattern (str) – Glob pattern to match metrics files.

Returns:

Dictionary with step names as keys and lists of metrics as values.

Return type:

dict

linumpy.metrics.compute_summary_statistics(metrics_list)[source]#

Compute summary statistics for a list of metrics from the same step.

Parameters:: metrics_list (list) – List of metrics dictionaries from the same step.
Returns:: Summary statistics for numerical metrics.
Return type:: dict