Qa Metrics¶
Module: spectralbridge.qa.metrics.
Reusable deterministic numerical diagnostics for scientific QA.
API glossary ยท Workflow / scientific context
Signatures and documentation below are collected from the current source. Advanced objects are not newly declared stable by inclusion here.
Audience: public. Also exported as spectralbridge.qa.reflectance_summary.
reflectance_summary ¶
reflectance_summary(values: ndarray, *, nodata: float | None = None, plausible_max: float = 1.2) -> dict[str, float | int | None]
Summarize valid support and distribution without changing reflectance scale.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
values
|
ndarray
|
Numeric reflectance values of any shape; stored scale is retained and finite values are summarized without clipping. |
required |
nodata
|
float | None
|
Optional numeric nodata sentinel excluded alongside nonfinite values; None excludes only nonfinite values. |
None
|
plausible_max
|
float
|
Upper reflectance screening threshold for the reported overbright fraction, in the input units; values are counted, not clipped. |
1.2
|
Returns:
| Type | Description |
|---|---|
dict[str, float | int | None]
|
Total/valid counts, valid/missing fractions, quantiles, extrema and negative/overbright fractions; unsupported numeric summaries are None. |
See Also
spectralbridge.pipelines.pipeline.process_one_flightline : Related source-derived API contract.
Examples:
>>> from spectralbridge.qa.metrics import reflectance_summary
>>> result = reflectance_summary([.1, .2, float("nan")])
>>> assert result["n_valid"] == 2
Audience: public. Also exported as spectralbridge.qa.linear_diagnostic.
linear_diagnostic ¶
linear_diagnostic(x: ndarray, y: ndarray) -> dict[str, float | int | None]
Fit y = intercept + slope*x for diagnostic, not inferential, use.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
x
|
ndarray
|
Paired numeric observations flattened to equal-length vectors; nonfinite pairs are omitted from descriptive linear fitting. |
required |
y
|
ndarray
|
Paired numeric observations flattened to equal-length vectors; nonfinite pairs are omitted from descriptive linear fitting. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, float | int | None]
|
Finite-pair count, intercept, slope, correlation, squared correlation and fitted-line RMSE; insufficient or constant-x support yields None metrics. |
See Also
spectralbridge.qa.metrics.reflectance_summary : Related source-derived API contract.
Examples:
>>> from spectralbridge.qa.metrics import linear_diagnostic
>>> result = linear_diagnostic([.1, .2, .3], [.2, .4, .6])
>>> assert abs(result["slope"] - 2) < 1e-12
Audience: public. Also exported as spectralbridge.qa.residual_metrics.
residual_metrics ¶
residual_metrics(observed: ndarray, predicted: ndarray) -> dict[str, float | int | None]
Return held-out-style residual metrics for paired observations.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
observed
|
ndarray
|
Paired measured/reference and predicted values in common units; nonfinite pairs are omitted and residuals are predicted minus observed. |
required |
predicted
|
ndarray
|
Paired measured/reference and predicted values in common units; nonfinite pairs are omitted and residuals are predicted minus observed. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, float | int | None]
|
Finite-pair count, predicted-minus-observed bias, MAE, RMSE, unbiased RMSE and descriptive fit diagnostics; no support yields None metrics. |
See Also
spectralbridge.qa.metrics.reflectance_summary : Related source-derived API contract.
Examples:
>>> from spectralbridge.qa.metrics import residual_metrics
>>> assert residual_metrics([.1, .2], [.1, .2])["rmse"] == 0
Audience: public. Also exported as spectralbridge.qa.seam_score.
seam_score ¶
seam_score(image: ndarray, *, chunk_rows: int, chunk_cols: int, nodata: float | None = None) -> dict[str, Any]
Compare gradients crossing chunk boundaries with interior neighbors.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image
|
ndarray
|
Raster diagnostic array; two-dimensional data or the established band-first cube convention is expected, with no implicit unit conversion. |
required |
chunk_rows
|
int
|
Positive computational block size in rows/columns, used to locate expected processing seams. |
required |
chunk_cols
|
int
|
Positive computational block size in rows/columns, used to locate expected processing seams. |
required |
nodata
|
float | None
|
Optional numeric nodata sentinel excluded alongside nonfinite values; None excludes only nonfinite values. |
None
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
Per-band seam/interior gradient ratios and median, 95th-percentile and maximum seam scores; landscape edges can also produce large ratios. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the supplied options, dimensions, support or provenance violate the input contract. |
Notes
A score near one means chunk boundaries are not unusually discontinuous. Scores above one require interpretation because genuine landscape edges can coincide with a computational boundary.
See Also
spectralbridge.qa.metrics.reflectance_summary : Related source-derived API contract.
Audience: public. Also exported as spectralbridge.qa.chunk_invariance_metrics.
chunk_invariance_metrics ¶
chunk_invariance_metrics(baseline: ndarray, candidate: ndarray, *, tolerance: float = 1e-06) -> dict[str, float | int | None]
Compare two outputs that should be scientifically identical.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
baseline
|
ndarray
|
Same-shaped reference and comparison outputs; only jointly finite cells contribute to invariance diagnostics. |
required |
candidate
|
ndarray
|
Same-shaped reference and comparison outputs; only jointly finite cells contribute to invariance diagnostics. |
required |
tolerance
|
float
|
Absolute numerical tolerance in the compared quantity: reflectance for chunk checks, additive RMSE for candidate ambiguity. |
1e-06
|
Returns:
| Type | Description |
|---|---|
dict[str, float | int | None]
|
Jointly finite count, absolute-difference quantiles, RMSE and fraction exceeding tolerance; invalid-support differences are not counted. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the supplied options, dimensions, support or provenance violate the input contract. |
See Also
spectralbridge.qa.metrics.reflectance_summary : Related source-derived API contract.
Examples:
>>> from spectralbridge.qa.metrics import chunk_invariance_metrics
>>> assert chunk_invariance_metrics([.1, .2], [.1, .2])["rmse"] == 0
Audience: public. Also exported as spectralbridge.qa.spectral_response_support.
spectral_response_support ¶
spectral_response_support(source_wavelengths: ndarray, response: ndarray, *, valid_source_mask: ndarray | None = None) -> dict[str, float | int | None]
Quantify SRF normalization and support on available source wavelengths.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source_wavelengths
|
ndarray
|
Finite wavelength coordinates in nanometers, aligned with spectral columns; numerical analysis routines require strictly increasing unique coordinates. |
required |
response
|
ndarray
|
Spectral-response weights aligned with source_wavelengths; finite nonnegative support determines normalization and effective wavelength. |
required |
valid_source_mask
|
ndarray | None
|
Optional boolean vector matching the spectral response; True marks available source coordinates for coverage reporting. |
None
|
Returns:
| Type | Description |
|---|---|
dict[str, float | int | None]
|
Response weight sum, effective wavelength in nanometers, admitted coverage fraction and source-support counts. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the supplied options, dimensions, support or provenance violate the input contract. |
See Also
spectralbridge.qa.metrics.reflectance_summary : Related source-derived API contract.