Plant Spectral Atlas

Module: spectralbridge.plant_spectral_atlas.

Plant-balanced atlas for union-schema corrected polygon extraction tables.

Reads projected spectral batches; never copies the source pixel table. Global plant identity is explicit: repeated flight observations receive equal weight.

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.

harmonize_spectrum

harmonize_spectrum(wavelengths, values, target, *, excluded=((1340, 1450), (1790, 2000)), max_gap_nm=8) -> np.ndarray

Linearly harmonize one spectrum without bridging unsupported intervals.

Parameters:

Name	Type	Description	Default
wavelengths	array - like	Increasing native coordinates in nm, shape (B,).	required
values	array - like	Same-shape stored reflectance values; nonfinite entries break support. Finite negatives and zeros are preserved.	required
target	array - like	Output wavelength coordinates in nm.	required
excluded	sequence	Inclusive wavelength intervals in nm to omit.	((1340, 1450), (1790, 2000))
max_gap_nm	float	Largest adjacent native interval to interpolate.	8

Returns:

Type	Description
ndarray	numpy.ndarray: Target-shaped values in unchanged input units. Unsupported coordinates are NaN; no extrapolation, scaling or clipping occurs.

Raises:

Type	Description
ValueError	Native lengths differ or coordinates are not increasing.

Exact isolated samples survive, but do not connect across gaps.

Audience: advanced.

run_plant_spectral_atlas

run_plant_spectral_atlas(source, output_dir, **kwargs) -> dict

Create/reuse empirical plant-atlas derivatives without copying source pixels.

Parameters:

Name	Type	Description	Default
source	str or Path	Existing merged polygon Parquet, read in place.	required
output_dir	str or Path	Directory for compact products/manifest.	required
**kwargs	object	Atlas options: plant_field='GlobalID', flight_field='flight_id', source_field='source_image', species_field='species', min_plants_per_species=10, spectral_stage='corr', grid_step_nm=5, max_gap_nm=8, excluded=((1340,1450),(1790,2000)), band_batch_size=32, dpi=350, supplementary=True, make_figures=True. Set grid_step_nm=None for exact shared discrete sensor coordinates; make_figures=False skips figures. Wavelengths are nm; stored reflectance units unchanged.	{}

Returns:

Name	Type	Description
dict	dict	Audit counts, grids, support and output provenance. Derivative Parquets/CSVs and optional PDF/PNG/SVG persist in output_dir.

Raises:

Type	Description
ValueError	Missing/conflicting identities, ambiguous native grids, undeclared nodata sentinel, or no sufficiently supported taxa.
OSError	Source/products cannot be read or written.

Pixel medians form polygon/flight/source observations, then equal-observation plant medians. Structural NaNs are native-grid absence, not zero values. Completed output is reused only when source/options/code/output hashes match. Failed reruns preserve completed products. Years require the separate year-aware workflow; this default atlas aggregates across observations.