Skip to contents

Parse a Dynamic Fire run's event and summary logs

parse_dynamic_fire_logs.Rd

Reads <rep_dir>/fire/dynamic-fire-event-log.csv (one row per fire event) and <rep_dir>/fire/dynamic-fire-summary-log.csv (one row per simulation year per fire ecoregion), returning a small list of summary statistics suitable for loss-function comparison.

Usage

parse_dynamic_fire_logs(
  rep_dir,
  pixel_area_ha = 1,
  by_class = FALSE,
  engine_rule = FALSE,
  event_fields = FALSE
)

Arguments

rep_dir

Character. Path to the per-rep directory (the rep01/ under the scenario directory). Must contain fire/dynamic-fire-event-log.csv and fire/dynamic-fire-summary-log.csv.

pixel_area_ha

Numeric. Hectares per cell. Default 1.0.

by_class, engine_rule

Logical. Passed to landis_overstory_mortality_share(), which gives overstory_mortality: by_class adds its per-class cell counts, and engine_rule makes the damage table's age test in single precision, as the extension does.

event_fields

Logical. Add five columns to events, in this order after the default ones: selected_size (double, the log's SelectedSizeOrDuration), season (character, the index in FireSeason: "0", "1" or "2"), and size_bin, init_row and init_col (integer, SizeBin, InitSiteRow and InitSiteColumn). A log with no events gives the columns typed and empty; a log with events that lacks one of the five source columns is an error naming it. FALSE, the default, leaves events as it was.

Value

Named list with n_fires_by_year (tibble: year, n_fires), fire_sizes_ha (sorted numeric vector), events (per-event tibble), total_sites_burned (integer), n_events (integer), and area_by_fuel_ha (tibble with fuel_code, fuel_index, base, cells and area_ha columns, or NULL when the per-timestep severity x fuel-type rasters aren't on disk – e.g. mock-simulator trials).

Details

Columns parsed (Dynamic Fire System v4):

  • event-log: Time, InitFireRegion, InitFuel, SitesChecked, DamagedSites, MeanSeverity.

  • summary-log: Time, NumberFires, TotalSitesBurned.

A fire's size is taken from SitesChecked. The published extension logs DamagedSites as one more than the cells the fire burned, on every event, while SitesChecked equals the burned cells on the timestep's severity map. MeanSeverity is divided by that inflated count, so the returned mean_severity is rescaled to MeanSeverity * DamagedSites / SitesChecked, the mean over the burned cells. A build with the count fixed logs DamagedSites == SitesChecked, which the same rescaling leaves unchanged. A log that holds neither relation on every event warns.

Cells -> hectares uses pixel_area_ha (1 ha for a 100 m x 100 m grid).

The area_by_fuel_ha summary is computed by intersecting the per-timestep Dynamic Fire severity rasters (cells with severity > 1 = burned; values 0 and 1 are inactive and active-but-unburned respectively) with the matching per-timestep Dynamic Fuels FuelType rasters from the same <rep_dir>/fire/ subdirectory. Cell-fuel-timestep is the unit of accounting: a cell that burns in two distinct timesteps contributes twice (consistent with NBAC's per-fire-perimeter accounting on the observed side). This replaces the earlier convention of attributing each event's entire DamagedSites count to its InitFuel, which biased simulated burn area toward the dominant-cover fuel since fires ignite where there's igniteable fuel and then spread anywhere.

Dynamic Fuels writes each active cell of a FuelType map as its fuel-type index plus one, and an inactive cell as 0. fuel_code is that raw map value, fuel_index is fuel_code - 1 (0 for an active cell with no fuel type), and base is the base fuel type of that index in the run's own FuelTypeTable, read from <rep_dir>/dynamic-fire.txt. Index 0, and an index the table does not list, have no base (NA) and are not scored; the latter also warns. If the file or its FuelTypeTable is missing, defaultFuelTypeTable() is used instead, with a warning.

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(), patch_fire_config(), run_calibration_spinup(), run_calibration_validation(), save_observed_fire_targets(), sim_landis(), sim_mock(), sim_r_reimpl()