Bulk Results

Module: spectralbridge.bulk.results.

Interpret completed bulk translations from compact result tables only.

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.bulk.BulkResultsConfig.

BulkResultsConfig dataclass

BulkResultsConfig(representative_source_value: float | None = None, r2_review_threshold: float = 0.9, absolute_correction_review_threshold_pct: float = 20.0, weighting_slope_spread_review_threshold: float = 0.05, flightline_slope_iqr_review_threshold: float = 0.05, site_slope_range_review_threshold: float = 0.05, loso_r2_review_threshold: float = 0.8, correction_denominator_floor: float = 1e-08, figure_dpi: int = 150)

Configurable review criteria for compact bulk translation results.

Thresholds are report-screening defaults, not scientific acceptance criteria. A result that triggers no warning is not automatically approved for universal calibration or extrapolation beyond the evaluated domain.

Attributes:

Name	Type	Description
representative_source_value	float | None, default=None	Source reflectance value at which relative correction magnitude is reported; use the same reflectance units as the fitted coefficients.
r2_review_threshold	float, default=0.9	R-squared screening threshold for descriptive/held-site attention flags; not a universal acceptance criterion.
absolute_correction_review_threshold_pct	float, default=20.0	Absolute predicted correction review bound in percent at representative_source_value.
weighting_slope_spread_review_threshold	float, default=0.05	Dimensionless slope heterogeneity screening threshold for weighting, flightline or site comparisons; flags require scientific interpretation.
flightline_slope_iqr_review_threshold	float, default=0.05	Dimensionless slope heterogeneity screening threshold for weighting, flightline or site comparisons; flags require scientific interpretation.
site_slope_range_review_threshold	float, default=0.05	Dimensionless slope heterogeneity screening threshold for weighting, flightline or site comparisons; flags require scientific interpretation.
loso_r2_review_threshold	float, default=0.8	R-squared screening threshold for descriptive/held-site attention flags; not a universal acceptance criterion.
correction_denominator_floor	float, default=1e-08	Positive denominator floor in reflectance units used to avoid unstable relative correction percentages near zero.
figure_dpi	int, default=150	Positive output rendering resolution in dots per inch; rasterization controls file size without changing analytical summaries.

validate

validate() -> None

Validate configuration ranges and supported option combinations.

Returns:

Type	Description
None	No return value; validation raises on unsupported configuration and directory creation persists the canonical hierarchy.

Raises:

Type	Description
ValueError	If option values violate the configuration or relationship-selection contract.

Audience: public. Also exported as spectralbridge.bulk.BulkResultsPaths.

BulkResultsPaths dataclass

BulkResultsPaths(bulk_output: Path)

Canonical compact inputs and interpretation outputs for one bulk run.

Attributes:

Name	Type	Description
bulk_output	Path	Root of an existing completed bulk run, containing its manifest and compact model tables.

manifest property

manifest: Path

Resolve the canonical manifest location.

Returns:

Type	Description
Path	Path computed as self.bulk_output / 'catalog' / 'bulk_manifest.json'. Accessing this property does not create or validate the artifact.

candidates property

candidates: Path

Resolve the canonical candidates location.

Returns:

Type	Description
Path	Path computed as self.bulk_output / 'coefficients' / 'candidate_translation_coefficients.parquet'. Accessing this property does not create or validate the artifact.

per_flightline property

per_flightline: Path

Resolve the canonical per flightline location.

Returns:

Type	Description
Path	Path computed as self.bulk_output / 'analyses' / 'sensor_translation' / 'per_flightline.parquet'. Accessing this property does not create or validate the artifact.

per_site property

per_site: Path

Resolve the canonical per site location.

Returns:

Type	Description
Path	Path computed as self.bulk_output / 'analyses' / 'sensor_translation' / 'per_site.parquet'. Accessing this property does not create or validate the artifact.

loso property

loso: Path

Resolve the canonical loso location.

Returns:

Type	Description
Path	Path computed as self.bulk_output / 'analyses' / 'leave_one_site_out' / 'leave_one_site_out.parquet'. Accessing this property does not create or validate the artifact.

analysis_dir property

analysis_dir: Path

Resolve the canonical analysis dir location.

Returns:

Type	Description
Path	Path computed as self.bulk_output / 'analyses' / 'bulk_results'. Accessing this property does not create or validate the artifact.

figures_dir property

figures_dir: Path

Resolve the canonical figures dir location.

Returns:

Type	Description
Path	Path computed as self.bulk_output / 'figures' / 'bulk_results'. Accessing this property does not create or validate the artifact.

diagnostics_dir property

diagnostics_dir: Path

Resolve the canonical diagnostics dir location.

Returns:

Type	Description
Path	Path computed as self.figures_dir / 'diagnostics'. Accessing this property does not create or validate the artifact.

publication_dir property

publication_dir: Path

Resolve the canonical publication dir location.

Returns:

Type	Description
Path	Path computed as self.figures_dir / 'publication'. Accessing this property does not create or validate the artifact.

summary_dir property

summary_dir: Path

Resolve the canonical summary dir location.

Returns:

Type	Description
Path	Path computed as self.figures_dir / 'summary'. Accessing this property does not create or validate the artifact.

report_dir property

report_dir: Path

Resolve the canonical report dir location.

Returns:

Type	Description
Path	Path computed as self.bulk_output / 'reports' / 'bulk_results'. Accessing this property does not create or validate the artifact.

pair_band_summary property

pair_band_summary: Path

Resolve the canonical pair band summary location.

Returns:

Type	Description
Path	Path computed as self.analysis_dir / 'pair_band_summary.parquet'. Accessing this property does not create or validate the artifact.

weighting_comparison property

weighting_comparison: Path

Resolve the canonical weighting comparison location.

Returns:

Type	Description
Path	Path computed as self.analysis_dir / 'weighting_comparison.parquet'. Accessing this property does not create or validate the artifact.

flightline_stability property

flightline_stability: Path

Resolve the canonical flightline stability location.

Returns:

Type	Description
Path	Path computed as self.analysis_dir / 'flightline_stability.parquet'. Accessing this property does not create or validate the artifact.

site_stability property

site_stability: Path

Resolve the canonical site stability location.

Returns:

Type	Description
Path	Path computed as self.analysis_dir / 'site_stability.parquet'. Accessing this property does not create or validate the artifact.

loso_transferability property

loso_transferability: Path

Resolve the canonical loso transferability location.

Returns:

Type	Description
Path	Path computed as self.analysis_dir / 'loso_transferability.parquet'. Accessing this property does not create or validate the artifact.

attention_flags property

attention_flags: Path

Resolve the canonical attention flags location.

Returns:

Type	Description
Path	Path computed as self.analysis_dir / 'attention_flags.parquet'. Accessing this property does not create or validate the artifact.

metadata property

metadata: Path

Resolve the canonical metadata location.

Returns:

Type	Description
Path	Path computed as self.analysis_dir / 'bulk_results_summary.json'. Accessing this property does not create or validate the artifact.

coefficient_figure property

coefficient_figure: Path

Resolve the canonical coefficient figure location.

Returns:

Type	Description
Path	Path computed as self.diagnostics_dir / 'translation_coefficients_and_fit.png'. Accessing this property does not create or validate the artifact.

correction_figure property

correction_figure: Path

Resolve the canonical correction figure location.

Returns:

Type	Description
Path	Path computed as self.diagnostics_dir / 'fitted_correction_magnitude.png'. Accessing this property does not create or validate the artifact.

transferability_figure property

transferability_figure: Path

Resolve the canonical transferability figure location.

Returns:

Type	Description
Path	Path computed as self.diagnostics_dir / 'stability_and_transferability.png'. Accessing this property does not create or validate the artifact.

summary_figure_stem property

summary_figure_stem: Path

Resolve the canonical summary figure stem location.

Returns:

Type	Description
Path	Path computed as self.summary_dir / 'bulk_qa_summary'. Accessing this property does not create or validate the artifact.

publication_stems property

publication_stems: tuple[Path, ...]

Resolve the canonical publication stems location.

Returns:

Type	Description
tuple[Path, ...]	Path computed as tuple((self.publication_dir / name for name in ('translation_performance', 'translation_stability', 'generalization_and_failures'))). Accessing this property does not create or validate the artifact.

report property

report: Path

Resolve the canonical report location.

Returns:

Type	Description
Path	Path computed as self.report_dir / 'bulk_translation_results.md'. Accessing this property does not create or validate the artifact.

report_pdf property

report_pdf: Path

Resolve the canonical report pdf location.

Returns:

Type	Description
Path	Path computed as self.report_dir / 'bulk_translation_results.pdf'. Accessing this property does not create or validate the artifact.

required_inputs property

required_inputs: tuple[Path, ...]

Resolve the canonical required inputs location.

Returns:

Type	Description
tuple[Path, ...]	Path computed as (self.manifest, self.candidates, self.per_flightline, self.per_site, self.loso). Accessing this property does not create or validate the artifact.

Audience: public. Also exported as spectralbridge.bulk.summarize_bulk_results, spectralbridge.summarize_bulk_results.

summarize_bulk_results

summarize_bulk_results(bulk_output: str | Path, *, config: BulkResultsConfig | None = None, make_figures: bool = True, make_report: bool = True, force: bool = False) -> dict[str, Any]

Summarize completed translation results without the source archive.

Parameters:

Name	Type	Description	Default
bulk_output	str | Path	Root of an existing completed bulk run, containing its manifest and compact model tables.	required
config	BulkResultsConfig | None	Configuration object for this workflow; None selects the documented defaults of its configuration class.	None
make_figures	bool	Render interpretation figures from completed compact results.	True
make_report	bool	Write the human-readable interpretation report alongside machine-readable summaries.	True
force	bool	Regenerate the requested outputs instead of reusing an otherwise valid checkpoint or report.	False

Returns:

Type	Description
dict[str, Any]	Created/reused interpretation metadata, attention flags, compact summaries and enabled figure/report paths.

Raises:

Type	Description
FileNotFoundError	If a required source or completed artifact is absent.
ValueError	If the supplied options, dimensions, support or provenance violate the input contract.

Notes

Only the completed bulk manifest and compact model-result Parquets are read. Source rasters, sufficient-statistics checkpoints, diagnostic pixel samples, and observation datasets are neither required nor opened.

See Also

spectralbridge.pipelines.bulk.run_bulk_pipeline : Related source-derived API contract.

Examples:

Use the directory returned by a completed bulk run; original rasters are not needed.

>>> from spectralbridge import summarize_bulk_results
>>> result = summarize_bulk_results(completed_bulk_dir, make_figures=False)

Explicitly exported constants and type aliases

These values describe package metadata, schemas or configuration; they are not observations from a production dataset.

Name	Source expression
BULK_RESULTS_SCHEMA_VERSION	3