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:
BaseModelNon-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:
BaseModelValidated 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:
BaseModelOne 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:
BaseModelPlanned 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:
BaseModelUnit-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.