Documents · API reference
Data and source configuration
Noun definitions and source facts live in Library. This page documents discovery, loading, provenance, schema and QA functions. Signatures and descriptions below come from the runtime docstrings.
Discovery
Source discovery metadata for CubeDynamics scientific nouns.
The catalog is intentionally small and declarative. It describes source flavors that are actually wired into the package; planned sources do not appear here until their loaders, tests, QA, and documentation exist.
list_sources()
Return implemented source flavors grouped by scientific noun.
sources(noun)
Return implemented source flavors for noun.
Planned integrations are deliberately omitted. An unknown noun raises a message that lists the vocabulary currently available.
describe(noun, source=None)
Return human-readable metadata for an implemented noun/source flavor.
Source-specific loaders
Provider-specific loaders remain supported alongside scientific nouns. Compare implemented source flavors before choosing.
Load a GRIDMET-like climate cube.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
lat
|
float
|
Latitude/longitude of a point of interest. When provided, a small bounding box is generated around the point so that GRIDMET pixels are fetched for the surrounding area. |
None
|
lon
|
float
|
Latitude/longitude of a point of interest. When provided, a small bounding box is generated around the point so that GRIDMET pixels are fetched for the surrounding area. |
None
|
bbox
|
sequence of float
|
Bounding box defined as |
None
|
aoi_geojson
|
mapping
|
GeoJSON Feature/FeatureCollection describing the area of interest. A bounding box is derived from the geometry. |
None
|
start
|
datetime - like
|
Temporal extent for the request. |
None
|
end
|
datetime - like
|
Temporal extent for the request. |
None
|
variable
|
str
|
GRIDMET variable to request. |
None
|
freq
|
str
|
Temporal frequency code. |
None
|
time_res
|
str
|
Temporal frequency code. |
None
|
chunks
|
mapping
|
Custom Dask chunk mapping. |
None
|
prefer_streaming
|
bool
|
Retained for compatibility. Both real paths read the authoritative annual gridMET NetCDF assets; the preferred path preserves Dask chunks. |
True
|
show_progress
|
bool
|
Display retrieval progress when available. Set to |
True
|
Notes
The modern API requires keyword arguments and exactly one AOI specification
(lat/lon, bbox or aoi_geojson). Legacy positional usage of
the form load_gridmet_cube(variable, start, end, aoi, ...) is still
supported but deprecated.
Load a PRISM climate cube.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
lat
|
float
|
Latitude/longitude of a point of interest. When provided, a small bounding box is generated around the point so that PRISM pixels are fetched for the surrounding area. |
None
|
lon
|
float
|
Latitude/longitude of a point of interest. When provided, a small bounding box is generated around the point so that PRISM pixels are fetched for the surrounding area. |
None
|
bbox
|
sequence of float
|
Bounding box defined as |
None
|
aoi
|
mapping
|
Backward-compatible alias for |
None
|
aoi_geojson
|
mapping
|
GeoJSON Feature/FeatureCollection describing the area of interest. A bounding box is derived from the geometry. |
None
|
start
|
datetime - like
|
Temporal extent for the request. |
None
|
end
|
datetime - like
|
Temporal extent for the request. |
None
|
variable
|
str or sequence of str
|
PRISM variable(s) to request. |
"ppt"
|
time_res
|
str
|
Temporal frequency code. |
"ME"
|
freq
|
str
|
Temporal frequency code. |
"ME"
|
chunks
|
mapping
|
Custom Dask chunk mapping. |
None
|
prefer_streaming
|
bool
|
Whether to use lazy, server-side AOI subsets from the PRISM THREDDS mirror. Daily slices are fetched only when Dask computes them. |
True
|
show_progress
|
bool
|
Display a progress bar while synthetic demo data are generated. Real streaming remains lazy and reports progress through the Dask scheduler. |
True
|
Notes
The modern API requires keyword arguments and exactly one AOI specification
(lat/lon, bbox or aoi_geojson). Legacy positional usage of
the form load_prism_cube(variables, start, end, aoi, ...) is still
supported but deprecated.
Real streaming currently supports daily ppt, tmean, tmin, and
tmax. Synthetic fallback is disabled unless allow_synthetic=True.
Sentinel-2 data access helpers.
load_s2_cube(lat, lon, start, end, edge_size=1028, resolution=10, cloud_lt=40, bands=None, chunks=None)
Stream Sentinel-2 L2A data via cubo and return a dask-backed xarray object.
load_s2_ndvi_cube(lat, lon, start, end, edge_size=1028, resolution=10, cloud_lt=40, bands=None, chunks=None)
Stream Sentinel-2 and return an NDVI cube ready for downstream ops.
Serving revisions
Source-controlled serving history and safe promotion/rollback queries.
serving_history(noun, source_flavor)
Return immutable history entries for one noun/source pair.
current_revision_record(noun, source_flavor)
Return the single current revision, rejecting ambiguous history.
validate_promotion(candidate, *, certification_outcome)
Validate a proposed promotion without rewriting source-controlled history.
rollback_target(noun, source_flavor)
Return the newest validated retired revision eligible for rollback.
Lifecycle decisions and records
Small source-lifecycle value objects used by the existing data catalog.
These types describe source maintenance and certification without changing the
public noun-and-pipe programming model. The authoritative noun/source records
remain in :mod:cubedynamics.data.catalog.
ServingRevision(noun, source_flavor, created, sequence)
dataclass
Immutable identifier for one CubeDynamics interpretation of a source.
parse(value)
classmethod
Parse noun.source@YYYY-MM-DD.N and reject ambiguous identifiers.
ServingRevisionRecord(revision_id, stage, status, created_at, promoted_at=None, adapter_version=None, schema_fingerprint=None, qa_evidence=None, normalization_contract=None, caveats=())
dataclass
Durable metadata that links an immutable revision to its evidence.
UpstreamIdentity(provider, product, endpoint, strategy, observed=dict(), retrieved_at=None)
dataclass
Provider-native identity observed for one bounded retrieval.
CertificationRecord(mode, outcome, gates, serving_revision, last_validated, evidence=dict(), caveats=())
dataclass
Machine-readable evidence summary for offline or live source QA.
decide_source_change(change, *, source_mode)
Translate a classified provider change into a deterministic response.
Schema normalization
Deterministic scientific schema descriptions for xarray source results.
normalize_xarray_schema(value)
Return scientifically relevant structural metadata in canonical order.
Array values, chunk shapes, retrieval timestamps, and dimension sizes are deliberately excluded so equivalent bounded requests share a fingerprint. Variable dimension order is retained because it can affect interpretation.
normalize_vector_schema(*, fields, geometry_type, crs, layer_id=None, coded_domains=None)
Normalize a vector schema without requiring a geospatial dependency.
normalize_api_schema(*, fields, units=None, parameter_ids=None, geography_ids=(), datetime_representation)
Normalize an API/tabular response contract for later source families.
schema_fingerprint(value)
Hash the canonical scientific schema without reading array values.
fingerprint_normalized_schema(normalized)
Hash any normalized schema representation deterministically.
compare_normalized_schemas(expected, observed)
Return deterministic, path-level schema drift evidence.
QA and certification
Reusable structural QA profiles for CubeDynamics source integrations.
Profiles evaluate scientific structure and metadata. Source-specific QA may add range, physics, checksum, or visual checks, but it should reuse one of these profiles instead of inventing a second source-registration system.
list_qa_profiles()
Return the stable names of the reusable QA profiles.
get_qa_profile(name)
Return one profile, naming available choices on error.
evaluate_qa_profile(name, value, *, context=None, caveats=())
Evaluate a reusable profile and return an explicit certification outcome.
Shared live-source certification built on the reusable QA profiles.
certify_live_sample(sample, *, qa_profile, serving_revision, endpoint_verified, bounded_access_verified, upstream_identity_verified, expected_schema=None, caveats=())
Certify one tiny remote sample with the same profile used offline.
blocked_live_certification(*, serving_revision, reason)
Represent unavailable credentials/services without inventing a pass.
write_live_certification(result, output)
Persist health/certification evidence as an uploadable JSON artifact.
See also
Source lifecycle contract · Source QA evidence · Legacy semantic helpers · Provenance lesson