Skip to contents

Seeded Monte Carlo expected annual damage (EAD) simulation

Source: R/simulation.R
ead_simulation.Rd

The HEC-FDA impact-area EAD compute: assemble a frequency function, a stage transform, and one or more stage-damage curves with uncertainty, then integrate damage against frequency over a seeded Monte Carlo (or a single deterministic pass). Wraps the ported ImpactAreaScenarioSimulation. Random seeds are fixed per-curve constants ported from the C# (frequency 1234, flow-stage 3456, stage-damage 6789, ...), so results are reproducible and identical across R, Python, and the upstream HEC-FDA.

Usage

ead_simulation(
  stage_damage,
  impact_area_id = 1L,
  flow_frequency = NULL,
  flow_stage = NULL,
  frequency_stage = NULL,
  threshold = NULL,
  levee = NULL,
  min_iterations = 100L,
  max_iterations = 100000L,
  deterministic = FALSE,
  non_failure_stage_damage = NULL
)

Arguments

stage_damage

list of stage-damage curve specs. A curve spec is list(x, dist, params, damage_category, asset_category): x the stages, dist distribution family name(s) (recycled), params a list of parameter vectors (or a matrix, one row per point).

impact_area_id

integer impact area label.

flow_frequency

dist spec list(dist, params) for the analytical flow frequency.

flow_stage

curve spec transforming flow to stage.

frequency_stage

graphical stage-frequency spec list(probabilities, stages, erl, damage_category, asset_category).

threshold

optional list(id, value) performance threshold (exterior stage).

levee

optional levee fragility curve spec plus top_of_levee_elevation.

min_iterations, max_iterations

Monte Carlo convergence bounds. Use 1, 1 with deterministic = TRUE for a single mean-value pass.

deterministic

when TRUE, every distribution collapses to its mean (no sampling).

non_failure_stage_damage

optional stage-damage curves used when the system does not fail. Uses the same curve schema as stage_damage.

Value

A list: ead (data frame: damage_category, asset_category, mean_ead), total_ead (all categories), mean_aep (default threshold annual exceedance probability), and ead_by_risk (data frame: damage_category, asset_category, risk_type, mean_ead). Fail and Non_Fail are stored identities; the aggregate uses Total only as a query wildcard. The first three entries retain the 0.1.1 schema and order.

Details

Supply either flow_frequency + flow_stage, or frequency_stage (a graphical stage frequency), not both.

Examples

res = ead_simulation(
  stage_damage = list(list(
    x = c(0, 15, 30), dist = "Uniform",
    params = list(c(0, 0, 10), c(0, 600000, 10), c(0, 600000, 10)),
    damage_category = "residential", asset_category = "Structure"
  )),
  flow_frequency = list(dist = "Uniform", params = c(0, 100000, 1000)),
  flow_stage = list(
    x = c(0, 100000), dist = "Uniform",
    params = list(c(0, 0, 10), c(0, 30, 10))
  ),
  min_iterations = 1L, max_iterations = 1L, deterministic = TRUE
)
res$total_ead # 150000 (the deterministic HEC-FDA oracle)
#> [1] 150000