brushline.vegetation.hazards
The clearance, fall-in, fuel-connectivity, access, and reliability indicators, their formulas and config, and the hazard-report validator.
Hazard and service indicators from the vegetation state and corridor context.
The indicators are decision aids, not engineering certifications. Each component records its formula, units, inputs, and caveat. A missing input is unknown, never zero. The reliability proxy is a declared weighted combination of the available components.
- class brushline.vegetation.hazards.AccessEvidence(*, slope_deg: Annotated[float, Ge(ge=0), Le(le=90)], road_status: Annotated[str, MinLen(min_length=1)], road_status_source: Annotated[str, MinLen(min_length=1)], road_score: Annotated[float, Ge(ge=0), Le(le=1)], distance_m: Annotated[float, Ge(ge=0)])[source]
Bases:
BaseModelSource-preserving road and slope evidence.
- Parameters:
slope_deg (float) – Local slope.
road_status (str) – Source road status, such as
class_1.road_status_source (str) – Source name for the status.
road_score (float) – Explicit source-preserving score from 0 to 1.
distance_m (float) – Distance to the road evidence.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.vegetation.hazards.AccessIndicator(*, status: str, slope_deg: float | None = None, slope_factor: Annotated[float | None, Ge(ge=0), Le(le=1)] = None, road_status: str = '', road_status_source: str = '', road_score: Annotated[float | None, Ge(ge=0), Le(le=1)] = None, distance_m: Annotated[float | None, Ge(ge=0)] = None, proxy: Annotated[float | None, Ge(ge=0), Le(le=1)] = None, formula: str = 'proxy = clamp(1 - slope / zero_slope, 0, 1) * road_score')[source]
Bases:
BaseModelSlope and source-preserving road access proxy.
- Parameters:
status (str) –
high,moderate,low, orunknown.slope_deg (float or None) – Local slope.
slope_factor (float or None) – Slope factor from 0 to 1.
road_status (str) – Source road status.
road_status_source (str) – Source name.
road_score (float or None) – Source score.
distance_m (float or None) – Distance to road evidence.
proxy (float or None) – Access proxy from 0 to 1.
formula (str) – Formula description.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.vegetation.hazards.ClearanceIndicator(*, status: str, height_m: float, max_height_m: float, min_clearance_m: float, asset_height_m: float | None, height_margin_m: float, clearance_gap_m: float | None, formula: str = 'height_margin = max_height - height; gap = asset_height - height - min_clearance')[source]
Bases:
BaseModelClearance versus the service standard and optional asset.
- Parameters:
status (str) –
clear,at_risk,exceeded, orunknown.height_m (float) – Vegetation height.
max_height_m (float) – Service-standard maximum.
min_clearance_m (float) – Service-standard clearance.
asset_height_m (float or None) – Asset height, when supplied.
height_margin_m (float) – Service maximum minus vegetation height.
clearance_gap_m (float or None) – Asset height minus vegetation height and minimum clearance.
formula (str) – Formula description.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.vegetation.hazards.FallInIndicator(*, status: str, edge_height_m: float | None, edge_distance_m: float | None, wind_factor: float, reach_m: float | None, risk: Annotated[float | None, Ge(ge=0), Le(le=1)] = None, formula: str = 'reach = edge_height * wind_factor; risk = clamp(1 - distance / reach, 0, 1)')[source]
Bases:
BaseModelMature-edge fall-in reach and risk.
- Parameters:
status (str) –
low,moderate,high, orunknown.edge_height_m (float or None) – Tree height.
edge_distance_m (float or None) – Distance to the asset.
wind_factor (float) – Reach multiplier.
reach_m (float or None) – Fall-in reach.
risk (float or None) – Risk from 0 to 1.
formula (str) – Formula description.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.vegetation.hazards.FuelIndicator(*, status: str, connectivity: Annotated[float | None, Ge(ge=0), Le(le=1)] = None, neighbor_count: Annotated[int, Ge(ge=0)], formula: str = 'distance-weighted mean neighbour cover / 100')[source]
Bases:
BaseModelFuel continuity from adjacent segments.
- Parameters:
status (str) –
low,moderate,high, orunknown.connectivity (float or None) – Connectivity from 0 to 1.
neighbor_count (int) – Number of neighbours.
formula (str) – Formula description.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.vegetation.hazards.FuelNeighbor(*, segment_id: Annotated[str, MinLen(min_length=1)], cover_pct: Annotated[float, Ge(ge=0), Le(le=100)], distance_m: Annotated[float, Ge(ge=0)])[source]
Bases:
BaseModelOne adjacent segment’s fuel evidence.
- Parameters:
segment_id (str) – Neighbour segment id.
cover_pct (float) – Neighbour cover.
distance_m (float) – Distance from the segment.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.vegetation.hazards.HazardConfig(*, clearance_warning_m: Annotated[float, ~annotated_types.Ge(ge=0)] = 1.0, wind_factor: Annotated[float, ~annotated_types.Gt(gt=0)] = 1.5, fuel_distance_scale_m: Annotated[float, ~annotated_types.Gt(gt=0)] = 50.0, access_slope_zero_deg: Annotated[float, ~annotated_types.Gt(gt=0)] = 30.0, weights: dict[str, float]=<factory>)[source]
Bases:
BaseModelThresholds, weights, and formula assumptions.
- Parameters:
clearance_warning_m (float, optional) – Margin at or below which clearance is at risk. Defaults to
1.wind_factor (float, optional) – Fall-in reach multiplier. Defaults to
1.5.fuel_distance_scale_m (float, optional) – Neighbour decay distance. Defaults to
50.access_slope_zero_deg (float, optional) – Slope at which the access slope factor reaches zero. Defaults to
30.weights (dict of str to float, optional) – Reliability weights.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.vegetation.hazards.HazardReport(*, schema_version: Literal['brushline.hazards.v1'] = 'brushline.hazards.v1', created_utc: datetime, segment_id: str, clearance: ClearanceIndicator, fall_in: FallInIndicator, fuel: FuelIndicator, access: AccessIndicator, reliability: ReliabilityIndicator, caveats: list[str] = <factory>)[source]
Bases:
BaseModelThe hazard report for one segment.
- Parameters:
schema_version ({"brushline.hazards.v1"}) – Report schema version.
created_utc (datetime) – Timezone-aware creation time.
segment_id (str) – Segment id.
clearance (ClearanceIndicator) – Clearance evidence.
fall_in (FallInIndicator) – Fall-in evidence.
fuel (FuelIndicator) – Fuel continuity evidence.
access (AccessIndicator) – Access evidence.
reliability (ReliabilityIndicator) – Weighted reliability proxy.
caveats (list of str) – Decision-support caveats.
- model_config = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.vegetation.hazards.HazardRequest(*, segment_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], height_m: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], cover_pct: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=100)], height_sd_m: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)] = 0.0, service_standard: ~brushline.model.corridor.ServiceStandard, asset_height_m: ~typing.Annotated[float | None, ~annotated_types.Gt(gt=0)] = None, edge_height_m: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0)] = None, edge_distance_m: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0)] = None, neighbors: list[~brushline.vegetation.hazards.FuelNeighbor] = <factory>, access: ~brushline.vegetation.hazards.AccessEvidence | None = None)[source]
Bases:
BaseModelOne segment’s hazard inputs.
- Parameters:
segment_id (str) – Segment id.
height_m (float) – Mean vegetation height.
cover_pct (float) – Mean vegetation cover.
height_sd_m (float, optional) – Height standard deviation.
service_standard (ServiceStandard) – Service standard.
asset_height_m (float or None, optional) – Conductor or asset height above ground.
edge_height_m (float or None, optional) – Mature-edge tree height.
edge_distance_m (float or None, optional) – Distance from the mature edge to the asset.
neighbors (list of FuelNeighbor, optional) – Adjacent fuel evidence.
access (AccessEvidence or None, optional) – Road and slope evidence.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.vegetation.hazards.ReliabilityIndicator(*, status: str, score: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)] = None, weights: dict[str, float], components: dict[str, float] = <factory>, formula: str = 'weighted mean of available clearance, fall-in, fuel, and access scores')[source]
Bases:
BaseModelWeighted reliability proxy.
- Parameters:
status (str) –
high,moderate,low, orunknown.score (float or None) – Score from 0 to 1.
weights (dict of str to float) – Weights used.
components (dict of str to float) – Available component scores.
formula (str) – Formula description.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- brushline.vegetation.hazards.assess_hazards(request: HazardRequest, config: HazardConfig | None = None, *, created_utc: datetime | None = None) HazardReport[source]
Assess the hazard and service indicators for one segment.
- Parameters:
request (HazardRequest) – Vegetation, service standard, and context.
config (HazardConfig, optional) – Thresholds and weights.
created_utc (datetime, optional) – Report time.
- Returns:
HazardReport – Component indicators and the reliability proxy.
- brushline.vegetation.hazards.validate_hazard_report(report: HazardReport) ContractValidation[source]
Validate the hazard statuses, ranges, and reliability composition.
- Parameters:
report (HazardReport) – Report to validate.
- Returns:
ContractValidation – Errors, warnings, and counts.