Skip to contents

Run Policy and Data Simulations

Source: R/run_simulation.R
run_simulation.Rd

Simulates the impact of policy changes (e.g., area closures) or changes in exogenous variables (e.g., fuel prices, expected catch) on redistributed fishing effort and economic welfare.

Usage

run_simulation(
  project,
  mod_name,
  closures = NULL,
  data_modifiers = NULL,
  betadraws = 500,
  marg_util_income = NULL,
  income_cost = FALSE
)

Arguments

project

Character. Name of the project.

mod_name

Character. Name of the fitted model to use for the simulation.

closures

List (Optional). A list of closure scenarios generated by zone_closure().

data_modifiers

List (Optional). A named list of new data vectors to inject into the model. Names must match variables in the model's design matrix or price vector.

betadraws

Integer. Number of multivariate normal draws for the simulation. Default is 1000.

marg_util_income

Character. For standard/zonal logit models: Name of the coefficient to use as the marginal utility of income to calculate welfare in dollars. Note this input will be ignored for EPMs.

income_cost

Logical. Default FALSE. Set to TRUE if the `marg_util_income` parameter represents a cost (flips the sign of the coefficient). Note this input will be ignored for EPMs.

Value

An object of class `fishset_policy` containing simulation results saved in the project database with the name [project]PolicySimulations.

Details

How to use data_modifiers: To create counterfactual data vectors, be sure to include your unique observation ID (e.g., trip or haul ID), date, and zone ID variables when formatting your data with format_model_data(). To guarantee the math aligns perfectly with the simulation matrices:

  1. Load your saved long-format dataset.

  2. Apply your mathematical transformation or merge in your external counterfactual data.

  3. Pass the raw, modified vector into the data_modifiers argument as a named list where the name exactly matches the column in the model (e.g., list(distance = new_dist)). For EPM price modifications, strictly use the name "price".

Analyzing results: Once your simulations have successfully run, use the companion summary functions to extract cleaned data frames and ggplot2 visualizations:

  • summarize_policy_welfare: Extracts compensating variation (economic impact) metrics and generates bar and density plots.

  • summarize_policy_effort: Extracts spatial effort redistribution and generates absolute, percentage, and spillover scatter plots.

See also

summarize_policy_welfare, summarize_policy_effort

Examples

if (FALSE) { # \dontrun{
# -----------------------------------------------------------------------
# Example 1: Standard Logit - Baseline & Closures
# -----------------------------------------------------------------------
# Run a baseline simulation (no closures)
run_simulation(
  project = "MyProject",
  mod_name = "clogit_model1",
  marg_util_income = "expected_catch"
)

# Run simulations for two separate spatial closures defined in your YAML
run_simulation(
  project = "MyProject",
  mod_name = "clogit_model1",
  closures = c("closure_1", "closure_2"),
  marg_util_income = "expected_catch"
)

# -----------------------------------------------------------------------
# Example 2: Standard Logit - Data Modifiers (e.g., Fuel Spike)
# -----------------------------------------------------------------------
library(data.table)

# 1. Load the formatted data to ensure perfect matrix alignment
# Note that this saves as a qs2 file if the package is available, and as a .rds file if not.
lf_data <- 
  qs2::qs_read("MyProject/Models/FormattedData/MyProjectLongFormatData.rds")[["format1"]]
# OR #
lf_data <- 
  readRDS("MyProject/Models/FormattedData/MyProjectLongFormatData.rds")[["format1"]]
new_distance <- as.numeric(lf_data$distance) * 1.5

# 2. Run the simulation
run_simulation(
  project = "MyProject",
  mod_name = "clogit_model1",
  data_modifiers = list(distance = new_distance), 
  marg_util_income = "expected_catch"
)

# -----------------------------------------------------------------------
# Example 3: Expected Profit Model - Closures AND Price Drop Combined
# -----------------------------------------------------------------------
# EPMs automatically calculate marginal utility of income, so it is omitted.
# The keyword "price" must be used for EPM revenue modifications.

new_price <- as.numeric(lf_data$price) * 0.80 # 20% price drop

run_simulation(
  project = "MyProject",
  mod_name = "epm_model1",
  closures = c("closure_1"),
  data_modifiers = list(price = new_price),
  betadraws = 1000
)
} # }