Spectral-library inspection and reports

Module: spectralbridge.bulk.analyses.spectral_library.

Bounded summaries and low-alpha reports for an existing spectral library.

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: advanced.

SpectralBand dataclass

SpectralBand(column: str, stage: str, band_index: int, wavelength_nm: float)

Record one wavelength-bearing Parquet column and its band index and nanometer coordinate.

Audience: advanced.

SpectralLibrarySchema dataclass

SpectralLibrarySchema(source: Path, source_signature_sha256: str, row_count: int, species_field: str, polygon_field: str | None, flightline_field: str | None, site_field: str | None, acquisition_date_field: str | None, pixel_field: str | None, spectral_stage: str, bands: tuple[SpectralBand, ...], available_spectral_stages: tuple[str, ...], detected_nodata_values: tuple[float, ...])

Record the detected group fields, source fingerprint and selected wavelength-bearing spectral stage.

wavelengths_nm property

wavelengths_nm: tuple[float, ...]

to_dict

to_dict() -> dict[str, Any]

Audience: public. Also exported as spectralbridge.bulk.SpectralLibraryPlotConfig, spectralbridge.bulk.analyses.SpectralLibraryPlotConfig.

SpectralLibraryPlotConfig dataclass

SpectralLibraryPlotConfig(species_field: str | None = None, spectral_stage: str | None = None, species_sort: str = 'count_desc', panels_per_page: int = 4, trace_batch_size: int = 2000, summary_band_batch_size: int = 32, max_traces_per_group: int | None = None, sampling_seed: int = 0, raster_dpi: int = 150, quantiles: tuple[float, ...] = DEFAULT_QUANTILES, plot_y_quantiles: tuple[float, float] = DEFAULT_PLOT_Y_QUANTILES, species_y_scale: str = 'global_robust', spectral_plot_minimum_reflectance: float | None = None, nodata_values: tuple[float, ...] = DEFAULT_NODATA_VALUES, nodata_tolerance: float = 0.01, max_extreme_spectra_per_species: int = 100)

Explicit controls for potentially expensive spectral-library reports.

Attributes:

Name	Type	Description
species_field	str | None, default=None	Parquet column containing species/group names; None requests schema-based detection.
spectral_stage	str | None, default=None	One wavelength-bearing column prefix to analyze; specify it when multiple processing stages are present.
species_sort	str, default='count_desc'	Panel ordering: 'count_desc' (default) sorts by group size; 'alphabetical' sorts by species name.
panels_per_page	int, default=4	Maximum number of group panels per report page, from 1 through 8.
trace_batch_size	int, default=2000	Positive bounded trace-row or summary-band processing batch size, controlling memory rather than scientific support.
summary_band_batch_size	int, default=32	Positive bounded trace-row or summary-band processing batch size, controlling memory rather than scientific support.
max_traces_per_group	int | None, default=None	Optional cap on rendered traces per group; None retains all eligible traces. Numerical summaries retain their own declared full support.
sampling_seed	int, default=0	Seed controlling reproducible trace sampling when a render cap is configured.
raster_dpi	int, default=150	Positive output rendering resolution in dots per inch; rasterization controls file size without changing analytical summaries.
quantiles	tuple[float, ...], default=DEFAULT_QUANTILES	Nonempty sorted probability tuple strictly between 0 and 1, including 0.5 for the median; compact distribution summaries, not fitted boosted quantile models.
plot_y_quantiles	tuple[float, float], default=DEFAULT_PLOT_Y_QUANTILES	Lower/upper probability bounds used for robust display limits only; analytical values are not clipped.
species_y_scale	str, default='global_robust'	Display bounds policy: 'global_robust', 'global_full', or 'per_group_robust'. Graphical limits do not clip analytical summaries.
spectral_plot_minimum_reflectance	float | None, default=None	Optional stored-unit lower visualization bound; finite negative corrected reflectance is not automatically nodata.
nodata_values	tuple[float, ...], default=DEFAULT_NODATA_VALUES	Explicit stored-value sentinels excluded from visualization support.
nodata_tolerance	float, default=0.01	Absolute stored-unit tolerance used when comparing values with configured nodata sentinels.
max_extreme_spectra_per_species	int, default=100	Bounded number of extreme group traces retained with source identities for display-bound diagnostics.

validate

validate() -> None

Validate configuration ranges and supported option combinations.

Returns:

Type	Description
None	No return value; unsupported report settings raise ValueError before rendering.

Raises:

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

Audience: advanced.

SpectralLibraryPaths dataclass

SpectralLibraryPaths(analysis_dir: Path, figures_dir: Path)

Resolve compact spectral-library summaries, trace diagnostics and report locations.

species_summary property

species_summary: Path

species_band_summary property

species_band_summary: Path

species_quantiles property

species_quantiles: Path

species_medians property

species_medians: Path

group_counts property

group_counts: Path

species_plot_ranges property

species_plot_ranges: Path

extreme_spectra property

extreme_spectra: Path

metadata property

metadata: Path

species_variability property

species_variability: Path

species_variability_full_range property

species_variability_full_range: Path

species_quantile_report property

species_quantile_report: Path

species_median_report property

species_median_report: Path

observation_counts property

observation_counts: Path

hierarchy_report property

hierarchy_report: Path

site_variability property

site_variability: Path

flightline_variability property

flightline_variability: Path

from_bulk_paths classmethod

from_bulk_paths(paths: BulkAnalysisPaths) -> SpectralLibraryPaths

Audience: public. Also exported as spectralbridge.bulk.analyses.inspect_spectral_library, spectralbridge.bulk.inspect_spectral_library.

inspect_spectral_library

inspect_spectral_library(path: str | Path, *, species_field: str | None = None, spectral_stage: str | None = None) -> SpectralLibrarySchema

Inspect a merged polygon Parquet and select one coherent spectral stage.

Parameters:

Name	Type	Description	Default
path	str | Path	Existing merged polygon Parquet to inspect in place; no spectral rows are copied into a cache.	required
species_field	str | None	Parquet column containing species/group names; None requests schema-based detection.	None
spectral_stage	str | None	One wavelength-bearing column prefix to analyze; specify it when multiple processing stages are present.	None

Returns:

Type	Description
SpectralLibrarySchema	Detected source identity, species/group fields, selected spectral stage and ordered wavelength-bearing bands.

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.

See Also

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

Audience: advanced.

trace_alpha

trace_alpha(trace_count: int) -> float

Deterministic low-alpha rule for qualitative trace-density ensembles.

Audience: public. Also exported as spectralbridge.bulk.analyses.inspect_spectral_library_preflight, spectralbridge.bulk.inspect_spectral_library_preflight, spectralbridge.inspect_spectral_library_preflight.

inspect_spectral_library_preflight

inspect_spectral_library_preflight(path: str | Path, *, config: SpectralLibraryPlotConfig | None = None) -> dict[str, Any]

Inspect schema, exact group counts, and approximate report cost without PDFs.

Parameters:

Name	Type	Description	Default
path	str | Path	Existing merged polygon Parquet to inspect in place; no spectral rows are copied into a cache.	required
config	SpectralLibraryPlotConfig | None	Configuration object for this workflow; None selects the documented defaults of its configuration class.	None

Returns:

Type	Description
dict[str, Any]	Detected schema, validity/group counts, largest groups, expected pages and approximate scan/render cost; no PDFs are written.

See Also

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

Examples:

The supplied path must be a real existing library. For a fully executable invented-data example, run python examples/first_example.py from a checkout.

>>> from spectralbridge import inspect_spectral_library_preflight
>>> result = inspect_spectral_library_preflight(library_path)

Audience: advanced.

iter_group_spectra

iter_group_spectra(con: DuckDBPyConnection, schema: SpectralLibrarySchema, *, grouping_field: str, group_value: str, batch_size: int, max_traces: int | None = None, sampling_seed: int = 0, config: SpectralLibraryPlotConfig | None = None) -> Iterator[np.ndarray]

Yield one group's spectra as bounded NumPy batches without pandas.

Audience: public. Also exported as spectralbridge.bulk.analyses.run_spectral_library_analysis, spectralbridge.bulk.run_spectral_library_analysis, spectralbridge.run_spectral_library_analysis.

run_spectral_library_analysis

run_spectral_library_analysis(con: DuckDBPyConnection, bulk_paths: BulkAnalysisPaths, *, spectral_library: str | Path, analysis_run_id: str, config: SpectralLibraryPlotConfig | None = None, make_summary_plots: bool = True, make_full_spectral_reports: bool = False, minimum_reflectance: float | None = None) -> dict[str, Any]

Build compact summaries and requested PDFs without copying source spectra.

Parameters:

Name	Type	Description	Default
con	DuckDBPyConnection	Open DuckDB connection prepared by the bulk workflow with the required catalog and observation views; the caller owns its lifetime.	required
bulk_paths	BulkAnalysisPaths	BulkAnalysisPaths instance selecting isolated catalog, database, analysis and report locations.	required
spectral_library	str | Path	Existing merged polygon Parquet with wavelength-bearing columns; read in place without copying the source dataset.	required
analysis_run_id	str	Provenance identifier written into generated tables and restart metadata for this run.	required
config	SpectralLibraryPlotConfig | None	Configuration object for this workflow; None selects the documented defaults of its configuration class.	None
make_summary_plots	bool	Write compact spectral-summary figures in addition to numerical summaries.	True
make_full_spectral_reports	bool	Explicitly enable potentially expensive full trace reports; inspect preflight costs before enabling.	False
minimum_reflectance	float | None	Lower screening bound in the stored reflectance units; used for regression validity, not automatic unit conversion.	None

Returns:

Type	Description
dict[str, Any]	Analysis metadata, validity/count summaries and output paths; compact summaries and explicitly enabled report files are persisted beneath bulk_paths.

Raises:

Type	Description
ValueError	If the supplied options, dimensions, support or provenance violate the input contract.

See Also

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

Examples:

Use a bulk-prepared connection and isolated paths object. Read the existing library in place; full trace reports remain opt-in.

>>> from spectralbridge import run_spectral_library_analysis
>>> result = run_spectral_library_analysis(con, bulk_paths, spectral_library=library_path, analysis_run_id=run_id, make_full_spectral_reports=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
SPECTRAL_LIBRARY_SCHEMA_VERSION	2
DEFAULT_QUANTILES	(0.025, 0.1, 0.25, 0.5, 0.75, 0.9, 0.975)