Skip to contents

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

save_observed_fire_targets.Rd

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(),
  severity_dist = NULL,
  mortality_share = NULL,
  min_size_ha = 1
)

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. 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 (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. Integer-coded fuel-type raster covering the LANDIS simulation extent.

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(). NA values mark non-fuel codes to be excluded. Default: bc_fuel_code_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.

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.

  • 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).

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(), build_calibration_scenario_template(), build_calibration_spinup_scenario(), calibrate_dynamic_fire(), calibration_par_names(), dedup_community_snapshot(), default_severity_prior_sturtevant2009(), 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()