Field validation API
Validation and normalization for field observations.
- class brushline.field.validation.FieldObservation(*, schema_version: ~typing.Literal['brushline.field-observation.v1'] = 'brushline.field-observation.v1', plot_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], visit_date: ~datetime.date, observer: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], unit_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], position: ~typing.Literal['center', 'edge'], latitude: ~typing.Annotated[float, ~annotated_types.Ge(ge=-90), ~annotated_types.Le(le=90)], longitude: ~typing.Annotated[float, ~annotated_types.Ge(ge=-180), ~annotated_types.Le(le=180)], gps_accuracy_m: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0)] = None, shrub_species: str | None = None, shrub_height_cm: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=500)] = None, shrub_cover_pct: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=100)] = None, shrub_stems: ~typing.Annotated[int | None, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=100000)] = None, recent_cut: bool | None = None, cut_height_cm: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=200)] = None, row_width_m: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=300)] = None, tree_species: str | None = None, tree_height_m: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=150)] = None, tree_distance_m: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=200)] = None, conductor_clearance_m: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=-20), ~annotated_types.Le(le=200)] = None, photo_ids: list[str] = <factory>, notes: str = '')[source]
Bases:
BaseModelOne normalized field-plot observation.
- schema_version
Observation schema.
- Type:
{“brushline.field-observation.v1”}
- plot_id
Planned plot identifier.
- Type:
str
- visit_date
Field visit date.
- Type:
datetime.date
- observer
Observer or crew lead.
- Type:
str
- unit_id
Planned corridor treatment unit.
- Type:
str
- position
Plot position within the corridor.
- Type:
{“center”, “edge”}
- latitude, longitude
WGS84 coordinates.
- Type:
float
- gps_accuracy_m
Receiver accuracy.
- Type:
float, optional
- shrub_height_cm, shrub_cover_pct, shrub_stems
Dominant shrub-layer measurements.
- Type:
float or int, optional
- recent_cut
Whether recent cutting was visible.
- Type:
bool, optional
- cut_height_cm
Stubble height where recent cutting was visible.
- Type:
float, optional
- row_width_m
Measured maintained right-of-way width.
- Type:
float, optional
- tree_species
Dominant tree at the plot.
- Type:
str, optional
- tree_height_m, tree_distance_m, conductor_clearance_m
Tree and clearance measurements.
- Type:
float, optional
- photo_ids
Photo file identifiers.
- Type:
list of str
- notes
Free text.
- Type:
str
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.field.validation.FieldPlotReference(*, plot_id: Annotated[str, MinLen(min_length=1)], unit_id: Annotated[str, MinLen(min_length=1)], position: Literal['center', 'edge'], latitude: Annotated[float, Ge(ge=-90), Le(le=90)], longitude: Annotated[float, Ge(ge=-180), Le(le=180)])[source]
Bases:
BaseModelPlanned plot location used to cross-check a field observation.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.field.validation.FieldValidationReport(*, schema_version: ~typing.Literal['brushline.field-validation.v1'] = 'brushline.field-validation.v1', source_csv: str, source_plots: str, valid: bool, plots_expected: int, observations: list[~brushline.field.validation.FieldObservation], errors: list[str] = <factory>, warnings: list[str] = <factory>)[source]
Bases:
BaseModelNormalized field observations plus validation findings.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- brushline.field.validation.validate_field_csv(csv_path: str | Path, plots_path: str | Path) FieldValidationReport[source]
Validate a field-observation CSV against planned plot references.
- Parameters:
csv_path (str or Path) – CSV exported from the field kit.
plots_path (str or Path) – GeoJSON FeatureCollection of planned plot points.
- Returns:
FieldValidationReport – Normalized observations, errors, and warnings.
- Raises:
ValueError – If the plots file cannot be read or has no point features.
- brushline.field.validation.write_field_validation(report: FieldValidationReport, path: str | Path) Path[source]
Write a normalized field-validation report as JSON.