Save observed fire-regime targets (NFDB-derived) for calibration loss

Pre-computes per-ecoregion observed summaries that downstream calibration loss components (loss_from_stats()) compare simulated fires against. Saves a single small .rds payload of base R types – so DEoptim workers can read it from disk without terra/sf in their environments.

Usage

save_observed_fire_targets(
  primary_points,
  primary_polys,
  fire_years,
  fuel_types_rast,
  path,
  secondary_points = NULL,
  secondary_polys = NULL,
  primary_label = "primary",
  secondary_label = "secondary",
  fuel_code_to_base = bc_fuel_code_to_base(),
  fuel_label_to_base = bc_fuel_label_to_base(),
  severity_dist = NULL,
  mortality_share = NULL,
  min_size_ha = 1,
  ignitions = NULL
)

Arguments

primary_points

SpatVector. NFDB ignition points for the primary ecoregion (the LANDIS simulation extent). Required.

primary_polys

SpatVector or NULL. Fire perimeter polygons for the primary ecoregion, not clipped to it. When supplied, a point's size is replaced by the SIZE_HA (e.g. NBAC's ADJ_HA) of a same-year polygon containing it, unless another ignition of 1 ha or more lies in that polygon or within 500 m of it (see observed_fire_sizes()), and area_by_fuel_ha is computed by rasterising the polys against fuel_types_rast. When NULL, fire_sizes_ha is the points' own SIZE_HA (NFDB agency-reported sizes) and area_by_fuel_ha is NULL on the primary summary.

fire_years

Integer vector. Years over which counts are normalised (denominator for lambda_obs).

fuel_types_rast

SpatRaster. Fuel-type raster covering the LANDIS simulation extent: categorical (with category labels), or integer-coded. See Details for how each is decoded.

path

Character. Output .rds path. Parent dir created if missing.

secondary_points, secondary_polys

SpatVector or NULL. Same, for an optional regional-context ecoregion. area_by_fuel_ha is NOT computed for the secondary (see Details).

primary_label, secondary_label

Character. Labels for the two ecoregions (e.g., "FRU59" / "FRT12"). Stored in the payload for reproducibility.

fuel_code_to_base

Named character vector. Mapping from fuel_types_rast integer codes (as character names) to the five base fuel types from defaultFuelTypeTable(), used when the raster is not categorical. NA values mark non-fuel codes to be excluded; a burned code missing from the names is an error. Default: bc_fuel_code_to_base().

fuel_label_to_base

Named character vector. Mapping from category labels to the five base fuel types, used when fuel_types_rast is categorical. NA values mark non-fuel labels to be excluded; a burned label missing from the names is an error. Default: bc_fuel_label_to_base().

severity_dist

Named numeric vector or NULL. Expected proportions across the 5 Dynamic Fire severity classes (names "1".."5"). Stored on the primary-ecoregion summary; consumed by loss_from_stats()'s L_severity component. NULL = skip severity calibration (the loss contributes 0). For a literature-prior default, see default_severity_prior_sturtevant2009().

mortality_share

Numeric scalar or NULL. Observed share of burned area that lost its dominant cohorts – a high-mortality burn-severity class expressed as a proportion of assessed burned area. Stored on the primary summary and consumed by loss_from_stats()'s mortality component, which compares it with landis_overstory_mortality_share() per replicate. NULL leaves that component at 0.

min_size_ha

Numeric scalar. Minimum fire size (ha) retained in fire_sizes_ha. Defaults to 1.0: NFDB systematically under-reports sub-1-ha fires (agencies don't document every spot fire) and NBAC's mapped polygons are also typically truncated below ~1 ha, so the observed distribution is effectively left-censored at this threshold. loss_from_stats() reads observed$min_size_ha and applies the same truncation symmetrically to sim_sizes so the KS distance compares like with like. Set to 0 to disable the floor.

ignitions

SpatVector or NULL. Ignition points tested as other fires in or near a perimeter polygon besides the point being sized, passed to observed_fire_sizes() for both ecoregions. Pass the whole point record, including both ecoregions' points. NULL uses each ecoregion's own points, which misses a fire that started outside the ecoregion.

Value

Character. Absolute path to the written file.

Details

Loss-component consumers:

• L_count uses n_fires_by_year (mean + sd for normalisation).

• L_size uses fire_sizes_ha (sorted vector; KS test against sim).

• L_area_fuel uses primary-ecoregion area_by_fuel_ha (Tier 2; weight 0 in Tier 1).

• L_severity stays NULL; populate from literature priors when Tier 2 severity matching is implemented.

Per ecoregion (primary_ecoregion, secondary_ecoregion):

• Fire counts come from NFDB IGNITION POINTS (one row = one ignition). NFDB polygons are sparser (only mapped for larger fires).

• Fire sizes come from observed_fire_sizes(): one per ignition point, its own SIZE_HA unless a same-year perimeter polygon contains it, then the polygon's SIZE_HA – or, where another ignition of 1 ha or more lies in the polygon or within 500 m of it, the area of the point's own group of the polygon's parts, or the point's own SIZE_HA.

• area_by_fuel_ha is computed for the PRIMARY ecoregion only via polygon overlay on fuel_types_rast. fuel_types_rast covers the LANDIS simulation domain; secondary-ecoregion polygons typically extend well beyond that extent, making a secondary computation misleading (it would just be the primary value over again).

A categorical fuel_types_rast is decoded by category label, through fuel_label_to_base; any other is decoded by integer code, through fuel_code_to_base. Labels are preferred because codes depend on how the raster was built: terra::rasterize() of a factor field numbers its categories from 0, and GeoTIFF storage can drop the labels that say what each number means. A burned cell that the table in use cannot decode is an error, not a silently dropped cell. The payload's fuel_code_to_base is the code mapping that was applied: for a categorical raster, each code's label looked up in fuel_label_to_base, with the raster's code-to-label table kept as fuel_code_labels (NULL for a raster decoded by code).

See also

Other Dynamic Fire calibration helpers: apply_calibrated_damage_age(), apply_calibrated_hi_prop(), apply_calibrated_ignprob(), apply_calibrated_num_fires(), bc_fuel_code_to_base(), bc_fuel_label_to_base(), build_calibration_scenario_template(), build_calibration_spinup_scenario(), calibrate_dynamic_fire(), calibration_par_names(), dedup_community_snapshot(), default_severity_prior_sturtevant2009(), fire_cohort_killed(), fire_cohort_mortality(), ground_fire_kill_par_names(), landis_dominant_cohorts(), landis_overstory_mortality_share(), loss_from_stats(), observed_fire_sizes(), parse_dynamic_fire_logs(), patch_fire_config(), run_calibration_spinup(), run_calibration_validation(), sim_landis(), sim_mock(), sim_r_reimpl()