Bulk Catalog¶

Module: spectralbridge.bulk.catalog.

Read-only discovery and canonical flightline catalog construction.

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

canonical_identity_from_product ¶

canonical_identity_from_product(path: str | Path, *, identity_parsers: Sequence[FlightlineIdentityParser] = DEFAULT_IDENTITY_PARSERS) -> dict[str, str | None]

Recover scientific identity from a canonical merged-product filename.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Canonical merged-product path whose filename or parent manifest carries scientific identity.	required
`identity_parsers`	`Sequence[FlightlineIdentityParser]`	Ordered parsers for canonical scientific identity from filenames or manifests; outer run-folder names are not scientific identifiers.	`DEFAULT_IDENTITY_PARSERS`

Returns:

Type	Description
`dict[str, str \| None]`	Canonical flightline ID, identity source, site and ISO acquisition date recovered without guessing outer folder identity.

Raises:

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

Notes

Outer folder names are intentionally ignored. A product whose filename cannot be parsed as a NEON reflectance identity is rejected rather than assigned a guessed identity.

discover_bulk_sources ¶

discover_bulk_sources(input_path: str | Path, *, input_kind: BulkInputKind = 'full', exclude_dir: str | Path | None = None, product_registry: ProductRegistry = DEFAULT_PRODUCT_REGISTRY, sensors: Sequence[str] | None = None, translation_pairs: Sequence[str | TranslationPair] | None = None, identity_parsers: Sequence[FlightlineIdentityParser] = DEFAULT_IDENTITY_PARSERS) -> list[SourceFileRecord]

Recursively inventory full and polygon merged-Parquet candidates.

Parameters:

Name	Type	Description	Default
`input_path`	`str \| Path`	Existing source tree or merged Parquet to inventory; input products are read in place.	required
`input_kind`	`BulkInputKind`	Select eligible 'full', 'polygon', or 'both' table products; discovery still records companions for transparency.	`'full'`
`exclude_dir`	`str \| Path \| None`	Optional output subtree to omit from recursive discovery to avoid treating generated products as sources.	`None`
`product_registry`	`ProductRegistry`	ProductRegistry describing recognized filenames, sensor roles, band contracts and translation relationships.	`DEFAULT_PRODUCT_REGISTRY`
`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`
`identity_parsers`	`Sequence[FlightlineIdentityParser]`	Ordered parsers for canonical scientific identity from filenames or manifests; outer run-folder names are not scientific identifiers.	`DEFAULT_IDENTITY_PARSERS`

Returns:

Type	Description
`list[SourceFileRecord]`	Deterministically ordered source records, including rejected candidates and their reasons.

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

Both product kinds are cataloged so companion availability is visible. input_kind controls later scientific selection, not discovery. Invalid candidates remain explicit rejected records.

build_bulk_catalog ¶

build_bulk_catalog(input_path: str | Path, *, input_kind: BulkInputKind = 'full', exclude_dir: str | Path | None = None, analysis_profile: str | AnalysisProfile = 'translation', product_registry: ProductRegistry = DEFAULT_PRODUCT_REGISTRY, sensors: Sequence[str] | None = None, translation_pairs: Sequence[str | TranslationPair] | None = None, identity_parsers: Sequence[FlightlineIdentityParser] = DEFAULT_IDENTITY_PARSERS) -> tuple[list[SourceFileRecord], list[FlightlineRecord]]

Build source-file and canonical-flightline catalogs.

Parameters:

Name	Type	Description	Default
`input_path`	`str \| Path`	Existing source tree or merged Parquet to inventory; input products are read in place.	required
`input_kind`	`BulkInputKind`	Select eligible 'full', 'polygon', or 'both' table products; discovery still records companions for transparency.	`'full'`
`exclude_dir`	`str \| Path \| None`	Optional output subtree to omit from recursive discovery to avoid treating generated products as sources.	`None`
`analysis_profile`	`str \| AnalysisProfile`	Registered analysis profile name or AnalysisProfile controlling required products and permissible sensor pairs.	`'translation'`
`product_registry`	`ProductRegistry`	ProductRegistry describing recognized filenames, sensor roles, band contracts and translation relationships.	`DEFAULT_PRODUCT_REGISTRY`
`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`
`identity_parsers`	`Sequence[FlightlineIdentityParser]`	Ordered parsers for canonical scientific identity from filenames or manifests; outer run-folder names are not scientific identifiers.	`DEFAULT_IDENTITY_PARSERS`

Returns:

Type	Description
`tuple[list[SourceFileRecord], list[FlightlineRecord]]`	Source-file records and canonical-flightline records; duplicate identities remain explicitly excluded.

Notes

Duplicate canonical IDs in different source directories are explicitly excluded. Multiple different IDs in one machine/run directory remain independent scientific flightlines.

catalog_signature_records ¶

catalog_signature_records(source_files: Iterable[SourceFileRecord], flightlines: Iterable[FlightlineRecord]) -> dict[str, list[dict[str, Any]]]

Return deterministic manifest-ready catalog records.