Bulk Registry

Module: spectralbridge.bulk.registry.

Generic product, translation-pair, and analysis-profile contracts.

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.ProductDescriptor.

ProductDescriptor dataclass

ProductDescriptor(key: str, product_role: str, filename_patterns: tuple[str, ...], sensor_name: str | None = None, matching_group: str | None = None, processing_stage: str | None = None, product_semantics: str | None = None, extraction_mode: str | None = None, expected_band_count: int | None = None, header_required: bool = True, include_undarkened: bool = False)

Recognize and describe one persisted raster-product convention.

Attributes:

Name	Type	Description
key	str	Unique registry key identifying this descriptor or translation relationship.
product_role	str	Scientific role of this product within the analysis profile, distinct from its storage format.
filename_patterns	tuple[str, ...]	Recognized canonical filename glob patterns; matching does not alone establish scientific eligibility.
sensor_name	str | None, default=None	Canonical sensor identity used to match registered products and translation relationships.
matching_group	str | None, default=None	Registry key declaring products that can be paired on common spatial/observational support.
processing_stage	str | None, default=None	Recorded processing lineage, such as raw, corrected or translated; stages are not silently interchangeable.
product_semantics	str | None, default=None	Declared meaning of the product values and their role in the evidence chain.
extraction_mode	str | None, default=None	'full' writes pixel Parquet, 'polygon' requires polygons; None preserves the entry point's documented default extraction behavior.
expected_band_count	int | None, default=None	Required number of spectral bands under this descriptor; metadata and actual products are validated separately.
header_required	bool, default=True	Require a companion raster header for this product descriptor.
include_undarkened	bool, default=False	Include the matching undarkened product convention when recognizing these filenames.

matches

matches(path: str | Path) -> bool

Check whether the filename matches this registered product convention.

Parameters:

Name	Type	Description	Default
path	str | Path	Existing source path to match against registered canonical filename patterns.	required

Returns:

Type	Description
bool	Whether the recorded state satisfies this method's predicate; no source processing is performed.

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

TabularProductDescriptor dataclass

TabularProductDescriptor(key: str, product_role: str, filename_patterns: tuple[str, ...], sensor_name: str | None = None, processing_stage: str | None = None, product_semantics: str | None = None, extraction_mode: str | None = None, expected_spectral_band_count: int | None = None, required_columns: tuple[str, ...] = ())

Recognize one canonical per-flight tabular product convention.

Tabular products are catalog inputs, not implicit regression inputs. The descriptor keeps storage layout separate from the raster relationship used by the bounded statistics reader.

Attributes:

Name	Type	Description
key	str	Unique registry key identifying this descriptor or translation relationship.
product_role	str	Scientific role of this product within the analysis profile, distinct from its storage format.
filename_patterns	tuple[str, ...]	Recognized canonical filename glob patterns; matching does not alone establish scientific eligibility.
sensor_name	str | None, default=None	Canonical sensor identity used to match registered products and translation relationships.
processing_stage	str | None, default=None	Recorded processing lineage, such as raw, corrected or translated; stages are not silently interchangeable.
product_semantics	str | None, default=None	Declared meaning of the product values and their role in the evidence chain.
extraction_mode	str | None, default=None	'full' writes pixel Parquet, 'polygon' requires polygons; None preserves the entry point's documented default extraction behavior.
expected_spectral_band_count	int | None, default=None	Required number of spectral bands under this descriptor; metadata and actual products are validated separately.
required_columns	tuple[str, ...], default=()	Required tabular column names for metadata validation; not a request to materialize all observation rows.

matches

matches(path: str | Path) -> bool

Check whether the filename matches this registered product convention.

Parameters:

Name	Type	Description	Default
path	str | Path	Existing source path to match against registered canonical filename patterns.	required

Returns:

Type	Description
bool	Whether the recorded state satisfies this method's predicate; no source processing is performed.

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

TranslationPair dataclass

TranslationPair(key: str, source_sensor: str, target_sensor: str, matching_group: str, band_pairs: tuple[tuple[int, int], ...] = (), expected_source_bands: int | None = None, expected_target_bands: int | None = None, compatible_target_band_counts: tuple[int, ...] = (), evidence_boundary: str | None = None)

A scientifically defined relationship between two sensor products.

Attributes:

Name	Type	Description
key	str	Unique registry key identifying this descriptor or translation relationship.
source_sensor	str	Canonical sensor identity used to match registered products and translation relationships.
target_sensor	str	Canonical target sensor key present in the reviewed drone coefficient registry.
matching_group	str	Registry key declaring products that can be paired on common spatial/observational support.
band_pairs	tuple[tuple[int, int], ...], default=()	Explicit source/target band relationships in the registry convention; preserve their declared index convention.
expected_source_bands	int | None, default=None	Declared source/target band-count contract for this registered translation relationship.
expected_target_bands	int | None, default=None	Declared source/target band-count contract for this registered translation relationship.
compatible_target_band_counts	tuple[int, ...], default=()	Declared source/target band-count contract for this registered translation relationship.
evidence_boundary	str | None, default=None	Scientific limitation attached to this relationship; common-source synthetic products do not become independent calibration observations.

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

AnalysisProfile dataclass

AnalysisProfile(name: str, required_product_roles: tuple[str, ...] = (), optional_product_roles: tuple[str, ...] = ('raw_hyperspectral', 'corrected_hyperspectral', 'qa', 'metadata'), allowed_sensors: tuple[str, ...] | None = None, allowed_matching_groups: tuple[str, ...] | None = None, require_translation_pair: bool = False, require_qa: bool = False, require_original_hyperspectral: bool = False, require_corrected_hyperspectral: bool = False, require_nonzero_files: bool = True, require_readable_metadata: bool = True, require_valid_dimensions: bool = True, require_compatible_band_schema: bool = True)

Product and integrity requirements for one bulk analysis.

Attributes:

Name	Type	Description
name	str	Stable parser/profile identifier used in configuration and provenance.
required_product_roles	tuple[str, ...], default=()	Product roles required or additionally recognized by this analysis profile.
optional_product_roles	tuple[str, ...], default=('raw_hyperspectral', 'corrected_hyperspectral', 'qa', 'metadata')	Product roles required or additionally recognized by this analysis profile.
allowed_sensors	tuple[str, ...] | None, default=None	Optional registry restrictions on sensor identities or common-support matching groups.
allowed_matching_groups	tuple[str, ...] | None, default=None	Optional registry restrictions on sensor identities or common-support matching groups.
require_translation_pair	bool, default=False	Require at least one compatible registered translation relationship for eligibility.
require_qa	bool, default=False	Require the profile's QA artifacts during source validation.
require_original_hyperspectral	bool, default=False	Require the corresponding original/corrected hyperspectral source role for this profile.
require_corrected_hyperspectral	bool, default=False	Require the corresponding original/corrected hyperspectral source role for this profile.
require_nonzero_files	bool, default=True	Reject zero-byte product artifacts during completeness validation.
require_readable_metadata	bool, default=True	Require metadata to be readable before admitting a candidate.
require_valid_dimensions	bool, default=True	Require compatible positive raster dimensions during validation.
require_compatible_band_schema	bool, default=True	Require product band metadata to satisfy the selected relationship contract.

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

ProductRegistry dataclass

ProductRegistry(products: tuple[ProductDescriptor, ...], translation_pairs: tuple[TranslationPair, ...], tabular_products: tuple[TabularProductDescriptor, ...] = ())

Immutable registry used by discovery, extraction, and analysis.

Attributes:

Name	Type	Description
products	tuple[ProductDescriptor, ...]	Immutable collection of raster/tabular descriptors recognized by this registry.
translation_pairs	tuple[TranslationPair, ...]	Explicit registered source-to-target relationships to analyze; None uses the selected registry/profile defaults.
tabular_products	tuple[TabularProductDescriptor, ...], default=()	Immutable collection of raster/tabular descriptors recognized by this registry.

recognize

recognize(path: str | Path) -> ProductDescriptor | None

Return the raster descriptor matching this product filename.

Parameters:

Name	Type	Description	Default
path	str | Path	Existing source path to match against registered canonical filename patterns.	required

Returns:

Type	Description
ProductDescriptor | None	Matching raster ProductDescriptor, or None when no filename convention matches.

product_for_sensor

product_for_sensor(sensor_name: str) -> ProductDescriptor | None

Return the registered raster descriptor for a sensor identity.

Parameters:

Name	Type	Description	Default
sensor_name	str	Canonical sensor identity used to match registered products and translation relationships.	required

Returns:

Type	Description
ProductDescriptor | None	ProductDescriptor for the requested canonical sensor name, or None when no descriptor exists.

recognize_tabular

recognize_tabular(path: str | Path) -> TabularProductDescriptor | None

Return the tabular descriptor matching this product filename.

Parameters:

Name	Type	Description	Default
path	str | Path	Existing source path to match against registered canonical filename patterns.	required

Returns:

Type	Description
TabularProductDescriptor | None	Matching TabularProductDescriptor, or None when no tabular filename convention matches.

select_pairs

select_pairs(*, sensors: Sequence[str] | None = None, translation_pairs: Sequence[str | TranslationPair] | None = None, allowed_sensors: Sequence[str] | None = None, allowed_matching_groups: Sequence[str] | None = None, allow_empty: bool = False) -> tuple[TranslationPair, ...]

Resolve and validate the requested registered sensor relationships.

Parameters:

Name	Type	Description	Default
sensors	Sequence[str] | None	Optional sensor-name selection passed to the product registry; None retains profile-compatible sensors.	None
translation_pairs	Sequence[str | TranslationPair] | None	Explicit registered source-to-target relationships to analyze; None uses the selected registry/profile defaults.	None
allowed_sensors	Sequence[str] | None	Optional registry restrictions on sensor identities or common-support matching groups.	None
allowed_matching_groups	Sequence[str] | None	Optional registry restrictions on sensor identities or common-support matching groups.	None
allow_empty	bool	Allow an empty relationship selection rather than raising an error.	False

Returns:

Type	Description
tuple[TranslationPair, ...]	Ordered tuple of compatible TranslationPair records selected from this registry.

Raises:

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

Audience: advanced.

resolve_analysis_profile

resolve_analysis_profile(value: str | AnalysisProfile) -> AnalysisProfile

Resolve a registered profile name or retain an explicit AnalysisProfile; reject unknown names.

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
TRANSLATION_PROFILE	AnalysisProfile(name='translation', required_product_roles=('target_sensor',), require_translation_pair=True)
ANALYSIS_PROFILES	{TRANSLATION_PROFILE.name: TRANSLATION_PROFILE}
DEFAULT_PRODUCT_REGISTRY	ProductRegistry(products=_BUILTIN_PRODUCTS, translation_pairs=_BUILTIN_PAIRS, tabular_products=_BUILTIN_TABULAR_PRODUCTS)