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

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

Planned 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: BaseModel

Normalized 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.