femic.hydrology.domain Module
The femic.hydrology.domain module owns FEMIC’s public hydrologic domain
and receptor contract. It defines layers, watersheds, downstream receptors,
hydrometric gauges, the public source registry, structural validation, and a
local file audit. It does not download layers or run a hydrology model.
Use this page when you are defining or auditing the spatial domain for forest hydrology and flood-risk work.
Start Here If…
Use this page first if you are trying to:
define a public watershed, stream, road, and DEM domain;
link downstream receptors and hydrometric gauges to watersheds;
register layer provenance, licences, checksums, and source IDs; or
audit whether a domain’s local layer files exist and match their checksums.
Typical Usage
from pathlib import Path
from femic.hydrology.domain import (
audit_hydrology_domain,
build_hydrology_domain,
write_hydrology_domain_manifest,
)
domain = build_hydrology_domain(...)
write_hydrology_domain_manifest(
domain,
Path("metadata/hydrology/domain.json"),
)
audit = audit_hydrology_domain(
Path("metadata/hydrology/domain.json"),
data_root=Path("."),
)
Key Entry Surfaces
hydrology_source_registry()Return the default public source families.find_hydrology_source()Resolve one source ID.build_hydrology_domain()Build and validate a domain manifest.validate_hydrology_domain()Check roles, IDs, cross-references, CRS, licences, and checksums.write_hydrology_domain_manifest()Persist the manifest as JSON.load_hydrology_domain_manifest()Load a manifest.audit_hydrology_domain()Validate and audit local layer files.HydrologyDomainManifestVersioned domain contract with layers, watersheds, receptors, gauges, and provenance.
Cross-References
Hydrologic domain and receptor contracts for forest flood-risk work.
P114.1 defines the public spatial domain, layer roles, watersheds, receptors, gauges, and provenance. It does not download data or run a hydrology model.
- class femic.hydrology.domain.HydrologyDomainAudit(domain_id, manifest_path, is_valid, checked_utc, layers, errors, warnings)[source]
Bases:
objectValidation and local-file audit for a hydrology domain.
- Parameters:
domain_id (str)
manifest_path (Path | None)
is_valid (bool)
checked_utc (str)
layers (tuple[HydrologyLayerAudit, ...])
errors (tuple[str, ...])
warnings (tuple[str, ...])
- checked_utc: str
- domain_id: str
- errors: tuple[str, ...]
- is_valid: bool
- layers: tuple[HydrologyLayerAudit, ...]
- manifest_path: Path | None
- warnings: tuple[str, ...]
- exception femic.hydrology.domain.HydrologyDomainError[source]
Bases:
RuntimeErrorRaised when a hydrologic domain or source contract is invalid.
- class femic.hydrology.domain.HydrologyDomainManifest(domain_id, name, created_utc, crs, resolution_m, layers, watersheds, receptors, gauges, caveats=(), provenance=<factory>, schema_version='femic.hydrology.domain.v1')[source]
Bases:
objectA versioned public hydrology domain and receptor contract.
- Parameters:
domain_id (str)
name (str)
created_utc (str)
crs (str)
resolution_m (float)
layers (tuple[HydrologyLayerSpec, ...])
watersheds (tuple[HydrologyWatershed, ...])
receptors (tuple[HydrologyReceptor, ...])
gauges (tuple[HydrologyGauge, ...])
caveats (tuple[str, ...])
provenance (dict[str, object])
schema_version (str)
- caveats: tuple[str, ...] = ()
- created_utc: str
- crs: str
- domain_id: str
- gauges: tuple[HydrologyGauge, ...]
- layers: tuple[HydrologyLayerSpec, ...]
- name: str
- provenance: dict[str, object]
- receptors: tuple[HydrologyReceptor, ...]
- resolution_m: float
- schema_version: str = 'femic.hydrology.domain.v1'
- to_dict()[source]
Return the domain manifest as a JSON-serializable mapping.
- Return type:
dict[str, object]
- watersheds: tuple[HydrologyWatershed, ...]
- class femic.hydrology.domain.HydrologyDomainValidation(is_valid, errors, warnings)[source]
Bases:
objectStructural validation outcome for a hydrology domain.
- Parameters:
is_valid (bool)
errors (tuple[str, ...])
warnings (tuple[str, ...])
- errors: tuple[str, ...]
- is_valid: bool
- to_dict()[source]
Return the validation as a JSON-serializable mapping.
- Return type:
dict[str, object]
- warnings: tuple[str, ...]
- class femic.hydrology.domain.HydrologyGauge(gauge_id, station_name, watershed_id, layer_id=None, drainage_area_km2=None, period_start=None, period_end=None, record_url=None)[source]
Bases:
objectOne hydrometric gauge linked to a watershed.
- Parameters:
gauge_id (str)
station_name (str)
watershed_id (str)
layer_id (str | None)
drainage_area_km2 (float | None)
period_start (str | None)
period_end (str | None)
record_url (str | None)
- drainage_area_km2: float | None = None
- gauge_id: str
- layer_id: str | None = None
- period_end: str | None = None
- period_start: str | None = None
- record_url: str | None = None
- station_name: str
- watershed_id: str
- class femic.hydrology.domain.HydrologyLayerAudit(layer_id, role, path, exists, size_bytes, expected_size_bytes, checksum_ok, issues=())[source]
Bases:
objectLocal file audit for one domain layer.
- Parameters:
layer_id (str)
role (str)
path (str)
exists (bool)
size_bytes (int | None)
expected_size_bytes (int | None)
checksum_ok (bool | None)
issues (tuple[str, ...])
- checksum_ok: bool | None
- exists: bool
- expected_size_bytes: int | None
- issues: tuple[str, ...] = ()
- layer_id: str
- path: str
- role: str
- size_bytes: int | None
- class femic.hydrology.domain.HydrologyLayerSpec(layer_id, role, path, format, crs, geometry_type=None, source_id=None, required_fields=(), description='', licence_id='OGL-BC', checksum_sha256=None, size_bytes=None, resolution_m=None)[source]
Bases:
objectOne spatial or tabular source layer in a hydrology domain.
- Parameters:
layer_id (str)
role (str)
path (str)
format (str)
crs (str)
geometry_type (str | None)
source_id (str | None)
required_fields (tuple[str, ...])
description (str)
licence_id (str)
checksum_sha256 (str | None)
size_bytes (int | None)
resolution_m (float | None)
- checksum_sha256: str | None = None
- crs: str
- description: str = ''
- format: str
- geometry_type: str | None = None
- layer_id: str
- licence_id: str = 'OGL-BC'
- path: str
- required_fields: tuple[str, ...] = ()
- resolution_m: float | None = None
- role: str
- size_bytes: int | None = None
- source_id: str | None = None
- class femic.hydrology.domain.HydrologyReceptor(receptor_id, name, receptor_type, watershed_id, layer_id, feature_id=None, capacity_m3s=None, damage_curve_id=None, notes='')[source]
Bases:
objectOne downstream flood-risk receptor.
- Parameters:
receptor_id (str)
name (str)
receptor_type (str)
watershed_id (str)
layer_id (str)
feature_id (str | None)
capacity_m3s (float | None)
damage_curve_id (str | None)
notes (str)
- capacity_m3s: float | None = None
- damage_curve_id: str | None = None
- feature_id: str | None = None
- layer_id: str
- name: str
- notes: str = ''
- receptor_id: str
- receptor_type: str
- to_dict()[source]
Return the receptor as a JSON-serializable mapping.
- Return type:
dict[str, object]
- watershed_id: str
- class femic.hydrology.domain.HydrologySourceSpec(source_id, title, role, catalogue_url, service_url, licence_id, native_crs, required_fields=(), notes=())[source]
Bases:
objectOne public source family available to a hydrology domain.
- Parameters:
source_id (str)
title (str)
role (str)
catalogue_url (str | None)
service_url (str | None)
licence_id (str)
native_crs (str)
required_fields (tuple[str, ...])
notes (tuple[str, ...])
- catalogue_url: str | None
- licence_id: str
- native_crs: str
- notes: tuple[str, ...] = ()
- required_fields: tuple[str, ...] = ()
- role: str
- service_url: str | None
- source_id: str
- title: str
- class femic.hydrology.domain.HydrologyWatershed(watershed_id, name, area_km2, layer_id, feature_id=None)[source]
Bases:
objectOne watershed or nested sub-watershed in the domain.
- Parameters:
watershed_id (str)
name (str)
area_km2 (float)
layer_id (str)
feature_id (str | None)
- area_km2: float
- feature_id: str | None = None
- layer_id: str
- name: str
- to_dict()[source]
Return the watershed as a JSON-serializable mapping.
- Return type:
dict[str, object]
- watershed_id: str
- femic.hydrology.domain.audit_hydrology_domain(manifest, *, data_root=None, checked_utc=None)[source]
Validate a domain and audit its local layer files.
Relative layer paths are resolved against
data_rootwhen provided, otherwise against the manifest directory (or the current directory for an in-memory manifest).- Parameters:
manifest (HydrologyDomainManifest | Path)
data_root (Path | None)
checked_utc (str | None)
- Return type:
- femic.hydrology.domain.build_hydrology_domain(*, domain_id, name, layers, watersheds, receptors, gauges, crs='EPSG:3005', resolution_m=25.0, caveats=(), provenance=None, created_utc=None)[source]
Build and validate one hydrology domain manifest.
- Raises:
HydrologyDomainError – If the domain is structurally invalid.
- Parameters:
domain_id (str)
name (str)
layers (Sequence[HydrologyLayerSpec])
watersheds (Sequence[HydrologyWatershed])
receptors (Sequence[HydrologyReceptor])
gauges (Sequence[HydrologyGauge])
crs (str)
resolution_m (float)
caveats (Sequence[str])
provenance (Mapping[str, object] | None)
created_utc (str | None)
- Return type:
- femic.hydrology.domain.find_hydrology_source(source_id)[source]
Resolve one source ID from the default registry.
- Parameters:
source_id (str)
- Return type:
HydrologySourceSpec | None
- femic.hydrology.domain.hydrology_source_registry()[source]
Return the default public hydrology source registry.
- Return type:
tuple[HydrologySourceSpec, …]
- femic.hydrology.domain.load_hydrology_domain_manifest(path)[source]
Load a hydrology domain manifest from JSON.
- Parameters:
path (Path)
- Return type:
- femic.hydrology.domain.validate_hydrology_domain(manifest)[source]
Validate structural, identification, and cross-reference rules.
- Parameters:
manifest (HydrologyDomainManifest)
- Return type:
- femic.hydrology.domain.write_hydrology_domain_manifest(manifest, path)[source]
Write a hydrology domain manifest as pretty-printed JSON.
- Parameters:
manifest (HydrologyDomainManifest)
path (Path)
- Return type:
Path