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.

  • HydrologyDomainManifest Versioned 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: object

Validation 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
to_dict()[source]

Return the audit as a JSON-serializable mapping.

Return type:

dict[str, object]

warnings: tuple[str, ...]
exception femic.hydrology.domain.HydrologyDomainError[source]

Bases: RuntimeError

Raised 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: object

A versioned public hydrology domain and receptor contract.

Parameters:
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: object

Structural 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: object

One 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
to_dict()[source]

Return the gauge as a JSON-serializable mapping.

Return type:

dict[str, object]

watershed_id: str
class femic.hydrology.domain.HydrologyLayerAudit(layer_id, role, path, exists, size_bytes, expected_size_bytes, checksum_ok, issues=())[source]

Bases: object

Local 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
to_dict()[source]

Return the layer audit as a JSON-serializable mapping.

Return type:

dict[str, object]

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: object

One 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
to_dict()[source]

Return the layer spec as a JSON-serializable mapping.

Return type:

dict[str, object]

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: object

One 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: object

One 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
to_dict()[source]

Return the source spec as a JSON-serializable mapping.

Return type:

dict[str, object]

class femic.hydrology.domain.HydrologyWatershed(watershed_id, name, area_km2, layer_id, feature_id=None)[source]

Bases: object

One 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_root when provided, otherwise against the manifest directory (or the current directory for an in-memory manifest).

Parameters:
Return type:

HydrologyDomainAudit

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:
Return type:

HydrologyDomainManifest

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:

HydrologyDomainManifest

femic.hydrology.domain.validate_hydrology_domain(manifest)[source]

Validate structural, identification, and cross-reference rules.

Parameters:

manifest (HydrologyDomainManifest)

Return type:

HydrologyDomainValidation

femic.hydrology.domain.write_hydrology_domain_manifest(manifest, path)[source]

Write a hydrology domain manifest as pretty-printed JSON.

Parameters:
Return type:

Path