Field comparison API

Compare validated field observations with planned LiDAR targets.

class brushline.field.comparison.FieldCalibrationSuggestion(*, status: Literal['insufficient', 'provisional', 'adequate'], sample_size_cover: int, sample_size_height: int, cover_multiplier: float | None, height_multiplier: float | None, treatment_response_status: Literal['not_tested'] = 'not_tested')[source]

Bases: BaseModel

Non-applied review factors and treatment-evidence status.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class brushline.field.comparison.FieldComparisonReport(*, schema_version: ~typing.Literal['brushline.field-comparison.v1'] = 'brushline.field-comparison.v1', source_observations: str, source_plots: str, created_utc: ~datetime.datetime, status: ~typing.Literal['insufficient', 'provisional', 'adequate'], observations_compared: int, plots_compared: int, rows: list[~brushline.field.comparison.FieldComparisonRow], units: list[~brushline.field.comparison.FieldUnitComparison], calibration: ~brushline.field.comparison.FieldCalibrationSuggestion, recommendations: list[str], warnings: list[str], caveats: list[str] = <factory>)[source]

Bases: BaseModel

Validated field evidence compared with LiDAR targets.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class brushline.field.comparison.FieldComparisonRow(*, plot_id: str, unit_id: str, position: Literal['center', 'edge'], planned_year: int | None, observed_shrub_cover_pct: float | None, target_mean_cover_pct: float | None, cover_delta_pct: float | None, cover_ratio: float | None, observed_shrub_height_cm: float | None, target_max_shrub_height_m: float | None, height_delta_cm: float | None, height_ratio: float | None, recent_cut: bool | None, status: Literal['complete', 'partial'])[source]

Bases: BaseModel

One plot’s observed-to-target comparison.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class brushline.field.comparison.FieldPlotTarget(*, plot_id: str, unit_id: str, position: Literal['center', 'edge'], planned_year: int | None = None, target_shrub_patches: int | None = None, target_mean_cover_pct: float | None = None, target_max_shrub_height_m: float | None = None, target_tree_clumps: int | None = None, target_canopy_height_m: float | None = None)[source]

Bases: BaseModel

Planned plot target metrics from the field-kit GeoJSON.

model_config = {'extra': 'ignore', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class brushline.field.comparison.FieldUnitComparison(*, unit_id: str, n_plots: int, n_cover: int, n_height: int, cover_bias_pct: float | None, cover_mae_pct: float | None, cover_rmse_pct: float | None, height_bias_cm: float | None, height_mae_cm: float | None, height_rmse_cm: float | None)[source]

Bases: BaseModel

Unit-level residual summary.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

brushline.field.comparison.compare_field_data(validation: FieldValidationReport, plots_path: str | Path, created_utc: datetime | None = None) → FieldComparisonReport[source]

Compare validated observations with planned plot targets.

Parameters:
  • validation (FieldValidationReport) – Normalized field observations.

  • plots_path (str or Path) – GeoJSON with planned plot target metrics.

  • created_utc (datetime, optional) – Creation time; defaults to the current UTC time.

Returns:

FieldComparisonReport – Residuals, unit summaries, sample status, and non-applied recommendations.

Raises:

ValueError – If the plots file is missing or has no plot targets.

brushline.field.comparison.compare_field_files(observations_path: str | Path, plots_path: str | Path, created_utc: datetime | None = None) → FieldComparisonReport[source]

Load a validated observation report and compare it with plot targets.

brushline.field.comparison.write_field_comparison(report: FieldComparisonReport, path: str | Path) → Path[source]

Write a field comparison report as JSON.