# Inputs and Outputs Structure

## Understanding Input Parameters

The EPIC model uses configuration files to define all input parameters. Default input values are loaded from JSON configuration files (e.g., `config_canada.json` or `config_us.json`). You can retrieve these values using `get_input()`.

### Retrieving Input Parameters

    # Get default inputs for Canada (default)
    library(epicR)
    #> epicR: Using config files from: /home/amin/.config/R/epicR/config
    #> To reset configs to defaults, use: reset_user_configs()
    #>
    #> Attaching package: 'epicR'
    #> The following object is masked from 'package:stats':
    #>
    #>     simulate
    input <- get_input()

    # Get inputs for US
    input_us <- get_input(jurisdiction = "us")

    # The function returns a nested list with three components:
    # - values: The actual parameter values used in simulation
    # - help: Descriptions of what each parameter means
    # - ref: Literature references for each parameter

### Input Structure Overview

The `input$values` list contains the following main categories:

Category | Description
--- | ---
`global_parameters` | Time horizon, age ranges, discount rates, cohort settings
`agent` | Population demographics, mortality, height/weight distributions
`smoking` | Smoking initiation, cessation, relapse rates, mortality factors
`COPD` | COPD prevalence and incidence equations
`lung_function` | FEV1 baseline, decline, and prediction equations
`exacerbation` | Exacerbation rates, severity, duration, and mortality
`symptoms` | Cough, phlegm, dyspnea, wheeze probabilities
`outpatient` | GP visit rates
`diagnosis` | Diagnosis probabilities, case detection parameters
`medication` | Medication adherence, effectiveness, costs, utilities
`cost` | Healthcare costs (exacerbations, maintenance, visits)
`utility` | Quality of life utilities by disease stage
`manual` | Advanced calibration parameters

## Detailed Input Categories

### Global Parameters (`global_parameters`)

Controls overall simulation settings.

Parameter | Description | Default (Canada)
--- | --- | ---
`age0` | Starting age in the model | 40
`time_horizon` | Model time horizon in years | 20
`discount_cost` | Annual discount rate for costs | 0
`discount_qaly` | Annual discount rate for QALYs | 0.03
`closed_cohort` | 0 = open population (new agents enter), 1 = closed cohort | 0

    # Example: Modify global parameters
    input <- get_input()
    input$values$global_parameters$time_horizon <- 10
    input$values$global_parameters$discount_cost <- 0.015
    input$values$global_parameters$discount_qaly <- 0.015

    results <- simulate(input = input$values)
    #> === EPIC Simulation Configuration ===
    #> Jurisdiction: CANADA
    #> Time horizon: 10 years
    #> Number of agents: 60,000
    #> Event recording: DISABLED
    #> =====================================
    #>
    #> Starting simulation...
    #> No active session - initializing automatically
    #> Initializing the session
    #> Working directory: /tmp/RtmpgeOOvt/Rbuild21f45248fe3d07/epicR/vignettes
    #> Running EPIC model (with custom input parameters)
    #> Record mode: record_mode_none (0)
    #> Note: No events will be recorded. Use record_mode_event (2) or record_mode_agent (1) to record events.
    #> Simulating 60000 base agents: 10% 20% 30% 40% 50%
    #> 60% 70% 80% 90% 100%
    #> Simulation completed in 1.1 seconds
    #> Collecting results...
    #> Collecting extended results...
    #> Terminating the session
    #> Done!

### Agent Demographics (`agent`)

Defines the simulated population characteristics.

Parameter | Description
--- | ---
`p_female` | Proportion of females in the population (default: 0.5)
`height_0_betas` | Regression coefficients for baseline height (meters)
`height_0_sd` | Standard deviation of baseline height
`weight_0_betas` | Regression coefficients for baseline weight (kg)
`weight_0_sd` | Standard deviation of baseline weight
`height_weight_rho` | Correlation between height and weight
`p_prevalence_age` | Age distribution at baseline (111 values, ages 0-110)
`p_incidence_age` | Age distribution for new population entering model
`p_bgd_by_sex` | Life table - annual probability of background death by age and sex
`l_inc_betas` | Log-rate of new population incidence
`ln_h_bgd_betas` | Modifiers for background mortality (time trends, etc.)

    # Example: Change population sex distribution
    input <- get_input()
    input$values$agent$p_female <- 0.52  # 52% female

    results <- simulate(input = input$values)
    #> === EPIC Simulation Configuration ===
    #> Jurisdiction: CANADA
    #> Time horizon: 20 years
    #> Number of agents: 60,000
    #> Event recording: DISABLED
    #> =====================================
    #>
    #> Starting simulation...
    #> No active session - initializing automatically
    #> Initializing the session
    #> Working directory: /tmp/RtmpgeOOvt/Rbuild21f45248fe3d07/epicR/vignettes
    #> Running EPIC model (with custom input parameters)
    #> Record mode: record_mode_none (0)
    #> Note: No events will be recorded. Use record_mode_event (2) or record_mode_agent (1) to record events.
    #> Simulating 60000 base agents: 10% 20% 30% 40% 50%
    #> 60% 70% 80% 90% 100%
    #> Simulation completed in 2.2 seconds
    #> Collecting results...
    #> Collecting extended results...
    #> Terminating the session
    #> Done!

### Smoking Parameters (`smoking`)

Controls smoking behavior and its health effects.

Parameter | Description
--- | ---
`logit_p_current_smoker_0_betas` | Probability of being current smoker at creation
`logit_p_never_smoker_con_not_current_0_betas` | Probability of being never-smoker (given not current)
`minimum_smoking_prevalence` | Floor for smoking prevalence
`mortality_factor_current` | Mortality multipliers for current smokers by age group
`mortality_factor_former` | Mortality multipliers for former smokers by age group
`pack_years_0_betas` | Pack-years regression at baseline
`pack_years_0_sd` | Standard deviation of pack-years
`ln_h_inc_betas` | Log-hazard of smoking initiation/relapse
`ln_h_ces_betas` | Log-hazard of smoking cessation
`smoking_ces_coefficient` | Decay rate for cessation treatment effect
`smoking_cessation_adherence` | Proportion adhering to cessation treatment

    # Example: Increase smoking cessation rate
    input <- get_input()
    # The first coefficient is the intercept - increasing it increases cessation rate
    input$values$smoking$ln_h_ces_betas[1] <- input$values$smoking$ln_h_ces_betas[1] + 0.5

    results <- simulate(input = input$values)
    #> === EPIC Simulation Configuration ===
    #> Jurisdiction: CANADA
    #> Time horizon: 20 years
    #> Number of agents: 60,000
    #> Event recording: DISABLED
    #> =====================================
    #>
    #> Starting simulation...
    #> No active session - initializing automatically
    #> Initializing the session
    #> Working directory: /tmp/RtmpgeOOvt/Rbuild21f45248fe3d07/epicR/vignettes
    #> Running EPIC model (with custom input parameters)
    #> Record mode: record_mode_none (0)
    #> Note: No events will be recorded. Use record_mode_event (2) or record_mode_agent (1) to record events.
    #> Simulating 60000 base agents: 10% 20% 30% 40% 50%
    #> 60% 70% 80% 90% 100%
    #> Simulation completed in 2.2 seconds
    #> Collecting results...
    #> Collecting extended results...
    #> Terminating the session
    #> Done!

### COPD Parameters (`COPD`)

Defines COPD prevalence and incidence.

Parameter | Description
--- | ---
`logit_p_COPD_betas_by_sex` | Logit-probability of having COPD at creation (by sex)
`ln_h_COPD_betas_by_sex` | Log-hazard of developing COPD over time (by sex)

The beta coefficients typically include:

- Intercept
- Age effect
- Age-squared effect
- Pack-years effect
- Current smoking effect
- Calendar time effect

### Lung Function Parameters (`lung_function`)

Controls FEV1 modeling.

Parameter | Description
--- | ---
`fev1_0_prev_betas_by_sex` | FEV1 at creation for prevalent COPD cases
`fev1_0_prev_sd_by_sex` | SD of FEV1 at creation (prevalent)
`fev1_0_inc_betas_by_sex` | FEV1 at COPD onset for incident cases
`fev1_0_inc_sd_by_sex` | SD of FEV1 at COPD onset
`fev1_0_ZafarCMAJ_by_sex` | Coefficients for Zafari CMAJ FEV1 decline model
`pred_fev1_betas_by_sex` | Predicted FEV1 calculation coefficients
`fev1_betas_by_sex` | Mixed-effects model for FEV1 decline
`dfev1_sigmas` | Random effect variances for FEV1 decline
`dfev1_re_rho` | Correlation between random effects

### Exacerbation Parameters (`exacerbation`)

Controls exacerbation occurrence and outcomes.

Parameter | Description
--- | ---
`ln_rate_betas` | Log-rate of exacerbation (10 coefficients)
`ln_rate_intercept_sd` | Random intercept SD for exacerbation rate
`logit_severity_betas` | Proportional odds model for severity (9 coefficients)
`logit_severity_intercept_sd` | Random intercept SD for severity
`rate_severity_intercept_rho` | Correlation between rate and severity random effects
`exac_end_rate` | Rate of exacerbation resolution by severity (4 values)
`logit_p_death_by_sex` | Probability of death during exacerbation

Exacerbation severity levels:

Level | Severity
--- | ---
1 | Mild
2 | Moderate
3 | Severe
4 | Very severe

    # Example: Reduce exacerbation rate
    input <- get_input()
    # Reduce the baseline rate (first coefficient is intercept)
    input$values$exacerbation$ln_rate_betas[1] <- input$values$exacerbation$ln_rate_betas[1] - 0.2

    results <- simulate(input = input$values)
    #> === EPIC Simulation Configuration ===
    #> Jurisdiction: CANADA
    #> Time horizon: 20 years
    #> Number of agents: 60,000
    #> Event recording: DISABLED
    #> =====================================
    #>
    #> Starting simulation...
    #> No active session - initializing automatically
    #> Initializing the session
    #> Working directory: /tmp/RtmpgeOOvt/Rbuild21f45248fe3d07/epicR/vignettes
    #> Running EPIC model (with custom input parameters)
    #> Record mode: record_mode_none (0)
    #> Note: No events will be recorded. Use record_mode_event (2) or record_mode_agent (1) to record events.
    #> Simulating 60000 base agents: 10% 20% 30% 40% 50%
    #> 60% 70% 80% 90% 100%
    #> Simulation completed in 2.2 seconds
    #> Collecting results...
    #> Collecting extended results...
    #> Terminating the session
    #> Done!

### Symptom Parameters (`symptoms`)

Controls respiratory symptoms.

Parameter | Description
--- | ---
`logit_p_cough_COPD_by_sex` | Cough probability for COPD patients
`logit_p_cough_nonCOPD_by_sex` | Cough probability for non-COPD
`logit_p_phlegm_COPD_by_sex` | Phlegm probability for COPD patients
`logit_p_phlegm_nonCOPD_by_sex` | Phlegm probability for non-COPD
`logit_p_dyspnea_COPD_by_sex` | Dyspnea probability for COPD patients
`logit_p_dyspnea_nonCOPD_by_sex` | Dyspnea probability for non-COPD
`logit_p_wheeze_COPD_by_sex` | Wheeze probability for COPD patients
`logit_p_wheeze_nonCOPD_by_sex` | Wheeze probability for non-COPD
`covariance_COPD` | 4x4 covariance matrix for symptom random effects (COPD)
`covariance_nonCOPD` | 4x4 covariance matrix for symptom random effects (non-COPD)

### Outpatient Parameters (`outpatient`)

Controls GP visit frequency.

Parameter | Description
--- | ---
`ln_rate_gpvisits_COPD_by_sex` | GP visit rate for COPD patients
`dispersion_gpvisits_COPD` | Dispersion parameter for COPD GP visits
`ln_rate_gpvisits_nonCOPD_by_sex` | GP visit rate for non-COPD
`dispersion_gpvisits_nonCOPD` | Dispersion parameter for non-COPD GP visits

### Diagnosis Parameters (`diagnosis`)

Controls COPD diagnosis and case detection.

Parameter | Description
--- | ---
`p_case_detection` | Vector of case detection probabilities by year
`case_detection_start_end_yrs` | Years when case detection program is active
`years_btw_case_detection` | Interval between case detection opportunities
`min_cd_age` | Minimum age for case detection
`min_cd_pack_years` | Minimum pack-years for case detection eligibility
`min_cd_symptoms` | Require symptoms for case detection (0 or 1)
`case_detection_methods` | Sensitivity, specificity, cost for each method
`case_detection_methods_eversmokers` | Methods for ever-smoker population
`case_detection_methods_symptomatic` | Methods for symptomatic population
`logit_p_prevalent_diagnosis_by_sex` | Probability of diagnosis at baseline
`logit_p_diagnosis_by_sex` | Probability of diagnosis during follow-up
`p_hosp_diagnosis` | Probability of diagnosis during hospitalization
`logit_p_overdiagnosis_by_sex` | Probability of false COPD diagnosis
`p_correct_overdiagnosis` | Probability of correcting overdiagnosis

    # Example: Enable case detection program
    input <- get_input()
    input$values$diagnosis$case_detection_start_end_yrs <- c(0, 20)  # Active years 0-20
    input$values$diagnosis$p_case_detection <- rep(0.1, 20)  # 10% annual probability

    results <- simulate(input = input$values)
    #> === EPIC Simulation Configuration ===
    #> Jurisdiction: CANADA
    #> Time horizon: 20 years
    #> Number of agents: 60,000
    #> Event recording: DISABLED
    #> =====================================
    #>
    #> Starting simulation...
    #> No active session - initializing automatically
    #> Initializing the session
    #> Working directory: /tmp/RtmpgeOOvt/Rbuild21f45248fe3d07/epicR/vignettes
    #> Running EPIC model (with custom input parameters)
    #> Record mode: record_mode_none (0)
    #> Note: No events will be recorded. Use record_mode_event (2) or record_mode_agent (1) to record events.
    #> Simulating 60000 base agents: 10% 20% 30% 40% 50%
    #> 60% 70% 80% 90% 100%
    #> Simulation completed in 2.2 seconds
    #> Collecting results...
    #> Collecting extended results...
    #> Terminating the session
    #> Done!

### Medication Parameters (`medication`)

Controls medication use and effects.

Parameter | Description
--- | ---
`medication_adherence` | Proportion adhering to medication (default: 0.7)
`medication_ln_hr_exac` | Log hazard ratio for exacerbation reduction by treatment
`medication_costs` | Annual costs by medication class
`medication_utility` | Utility gain by medication class

Medication Classes:

Class | Code | Description
--- | --- | ---
`none` | 0 | No medication
`SABA` | 1 | Short-acting beta-agonist
`LAMA` | 4 | Long-acting muscarinic antagonist
`LAMA/LABA` | 6 | Long-acting muscarinic antagonist/Long-acting beta-agonist
`ICS/LAMA/LABA` | 14 | Triple Therapy

Combinations are represented as sums (e.g., ICS+LAMA+LABA = 8+4+2 = 14).

### Cost Parameters (`cost`)

All costs are in local currency (CAD for Canada, USD for US).

Parameter | Description
--- | ---
`bg_cost_by_stage` | Annual maintenance costs by GOLD stage (0=no COPD, 1-4=GOLD stages)
`exac_dcost` | Incremental cost per exacerbation by severity (4 values)
`cost_case_detection` | Cost of case detection procedure
`cost_outpatient_diagnosis` | Cost of outpatient diagnosis
`cost_gp_visit` | Cost per GP visit
`cost_smoking_cessation` | Cost of smoking cessation treatment

    # Example: View and modify costs
    input <- get_input()

    # View default exacerbation costs
    print(input$values$cost$exac_dcost)
    #>         [,1]     [,2]     [,3]    [,4]
    #> [1,] 30.5312 764.2128 9699.226 21226.9
    # Columns: mild, moderate, severe, very_severe

    # Double the cost of severe exacerbations
    input$values$cost$exac_dcost[3] <- input$values$cost$exac_dcost[3] * 2

    results <- simulate(input = input$values)
    #> === EPIC Simulation Configuration ===
    #> Jurisdiction: CANADA
    #> Time horizon: 20 years
    #> Number of agents: 60,000
    #> Event recording: DISABLED
    #> =====================================
    #>
    #> Starting simulation...
    #> No active session - initializing automatically
    #> Initializing the session
    #> Working directory: /tmp/RtmpgeOOvt/Rbuild21f45248fe3d07/epicR/vignettes
    #> Running EPIC model (with custom input parameters)
    #> Record mode: record_mode_none (0)
    #> Note: No events will be recorded. Use record_mode_event (2) or record_mode_agent (1) to record events.
    #> Simulating 60000 base agents: 10% 20% 30% 40% 50%
    #> 60% 70% 80% 90% 100%
    #> Simulation completed in 2.3 seconds
    #> Collecting results...
    #> Collecting extended results...
    #> Terminating the session
    #> Done!

### Utility Parameters (`utility`)

Quality of life values (0-1 scale, where 1 = perfect health).

Parameter | Description
--- | ---
`bg_util_by_stage` | Background utility by GOLD stage (5 values: no COPD + 4 stages)
`exac_dutil` | Utility decrement during exacerbation (4x4 matrix: severity x GOLD)

    # Example: View utility values
    input <- get_input()

    # Background utilities by stage
    print(input$values$utility$bg_util_by_stage)
    #>      [,1] [,2] [,3] [,4] [,5]
    #> [1,] 0.86 0.81 0.72 0.68 0.58
    # Typical values: No COPD=0.86, GOLD1=0.81, GOLD2=0.72, GOLD3=0.68, GOLD4=0.58

    # Exacerbation disutility matrix
    print(input$values$utility$exac_dutil)
    #>        gold1   gold2   gold3   gold4
    #> [1,] -0.0225 -0.0155 -0.0488 -0.0488
    #> [2,] -0.0225 -0.0155 -0.0488 -0.0488
    #> [3,] -0.0728 -0.0683 -0.0655 -0.0655
    #> [4,] -0.0728 -0.0683 -0.0655 -0.0655

### Manual/Advanced Parameters (`manual`)

Calibration and advanced settings.

Parameter | Description
--- | ---
`MORT_COEFF` | Global mortality coefficient multiplier
`smoking$intercept_k` | Smoking intercept adjustment
`explicit_mortality_by_age_sex` | COPD-attributable mortality to subtract from background

## Accessing Parameter Help and References

    input <- get_input()

    # Get help text for a parameter
    input$help$exacerbation$ln_rate_betas
    #> [1] "Regression coefficients for the random-effects log-hazard model of exacerbation (of any severity)"
    # Returns: "Regression coefficients for the random-effects log-hazard model..."

    # Get literature reference
    input$ref$smoking$mortality_factor_current
    #> [1] "Meta-analysis. doi:10.1001/archinternmed.2012.1397"
    # Returns: "Meta-analysis. doi:10.1001/archinternmed.2012.1397"

    # List all help for a category
    names(input$help$cost)
    #> [1] "bg_cost_by_stage"          "exac_dcost"
    #> [3] "cost_case_detection"       "cost_outpatient_diagnosis"
    #> [5] "cost_gp_visit"             "cost_smoking_cessation"

## Running Simulations with Custom Inputs

    # Complete workflow example
    input <- get_input(jurisdiction = "canada")

    # Modify multiple parameters
    input$values$global_parameters$time_horizon <- 10
    input$values$agent$p_female <- 0.52
    input$values$smoking$ln_h_ces_betas[1] <- input$values$smoking$ln_h_ces_betas[1] + 0.3

    # Run simulation
    results <- simulate(input = input$values, n_agents = 50000)
    #> === EPIC Simulation Configuration ===
    #> Jurisdiction: CANADA
    #> Time horizon: 10 years
    #> Number of agents: 50,000
    #> Event recording: DISABLED
    #> =====================================
    #>
    #> Starting simulation...
    #> No active session - initializing automatically
    #> Initializing the session
    #> Working directory: /tmp/RtmpgeOOvt/Rbuild21f45248fe3d07/epicR/vignettes
    #> Running EPIC model (with custom input parameters)
    #> Record mode: record_mode_none (0)
    #> Note: No events will be recorded. Use record_mode_event (2) or record_mode_agent (1) to record events.
    #> Simulating 50000 base agents: 10% 20% 30% 40% 50%
    #> 60% 70% 80% 90% 100%
    #> Simulation completed in 0.9 seconds
    #> Collecting results...
    #> Collecting extended results...
    #> Terminating the session
    #> Done!

    # Access results
    print(results$basic)
    #> $n_agents
    #> [1] 63662
    #>
    #> $cumul_time
    #> [1] 518663.4
    #>
    #> $n_deaths
    #> [1] 8364
    #>
    #> $n_COPD
    #> [1] 8645
    #>
    #> $total_exac
    #> [1]  3921 21600  2183   162
    #>
    #> $total_exac_time
    #> [1] 0.5870340 3.8793966 4.3415899 0.4914473
    #>
    #> $total_pack_years
    #> [1] 795402.1
    #>
    #> $total_cost
    #> [1] 70941522
    #>
    #> $total_qaly
    #> [1] 373587.7
    #>
    #> $total_diagnosed_time
    #> [1] 18757.4

## Output Structure

The `simulate()` function returns a list with simulation results.

### Basic Output (`results$basic`)

Summary statistics from the simulation.

Output | Description
--- | ---
`n_agents` | Total number of agents simulated
`cumul_time` | Cumulative person-years of follow-up
`n_deaths` | Total number of deaths
`n_COPD` | Number of agents with COPD at end of simulation
`total_exac` | Vector of total exacerbations by severity (4 values)
`total_exac_time` | Cumulative time spent in exacerbation by severity
`total_pack_years` | Total pack-years across all agents
`total_cost` | Total discounted costs
`total_qaly` | Total discounted QALYs
`total_diagnosed_time` | Person-years with COPD diagnosis

    results <- simulate(n_agents = 50000)
    #> === EPIC Simulation Configuration ===
    #> Jurisdiction: CANADA
    #> Time horizon: 20 years
    #> Number of agents: 50,000
    #> Event recording: DISABLED
    #> =====================================
    #>
    #> Starting simulation...
    #> No active session - initializing automatically
    #> Initializing the session
    #> Working directory: /tmp/RtmpgeOOvt/Rbuild21f45248fe3d07/epicR/vignettes
    #> Running EPIC model (with custom input parameters)
    #> Record mode: record_mode_none (0)
    #> Note: No events will be recorded. Use record_mode_event (2) or record_mode_agent (1) to record events.
    #> Simulating 50000 base agents: 10% 20% 30% 40% 50%
    #> 60% 70% 80% 90% 100%
    #> Simulation completed in 1.8 seconds
    #> Collecting results...
    #> Collecting extended results...
    #> Terminating the session
    #> Done!

    # Access basic results
    basic <- results$basic
    cat("Total agents:", basic$n_agents, "\n")
    #> Total agents: 80356
    cat("Total deaths:", basic$n_deaths, "\n")
    #> Total deaths: 17356
    cat("Mild exacerbations:", basic$total_exac[1], "\n")
    #> Mild exacerbations: 9092
    cat("Moderate exacerbations:", basic$total_exac[2], "\n")
    #> Moderate exacerbations: 50432
    cat("Severe exacerbations:", basic$total_exac[3], "\n")
    #> Severe exacerbations: 5027
    cat("Very severe exacerbations:", basic$total_exac[4], "\n")
    #> Very severe exacerbations: 364
    cat("Total cost:", basic$total_cost, "\n")
    #> Total cost: 168488155
    cat("Total QALYs:", basic$total_qaly, "\n")
    #> Total QALYs: 688351.4

### Extended Output (`results$extended`)

Detailed breakdowns by time, age, sex, and disease stage. Extended results are included by default. Note: `ctime = calendar time`, `ltime = local time`

#### Population Counts by Time

Output | Dimensions | Description
--- | --- | ---
`n_alive_by_ctime_sex` | time_horizon x 2 | Alive agents by calendar time and sex
`n_alive_by_ctime_age` | time_horizon x 111 | Alive agents by calendar time and age
`n_alive_by_age_sex` | 111 x 2 | Alive agents by age and sex (total)

#### Smoking Status by Time

Output | Dimensions | Description
--- | --- | ---
`n_smoking_status_by_ctime` | time_horizon x 3 | Agents by smoking status (never/current/former)
`n_current_smoker_by_ctime_sex` | time_horizon x 2 | Current smokers by time and sex
`cumul_time_by_smoking_status` | 3 | Person-years by smoking status

#### COPD Outcomes by Time

Output | Dimensions | Description
--- | --- | ---
`n_COPD_by_ctime_sex` | time_horizon x 2 | COPD cases by time and sex
`n_COPD_by_ctime_age` | time_horizon x 111 | COPD cases by time and age
`n_COPD_by_ctime_severity` | time_horizon x 5 | COPD cases by time and GOLD stage (0-4)
`n_COPD_by_age_sex` | 111 x 2 | COPD cases by age and sex (total)
`n_inc_COPD_by_ctime_age` | time_horizon x 111 | Incident COPD cases by time and age
`cumul_non_COPD_time` | scalar | Total person-years without COPD
`cumul_time_by_ctime_GOLD` | time_horizon x 5 | Person-years by time and GOLD stage. GOLD0 = no COPD

#### Diagnosis Outcomes

Output | Dimensions | Description
--- | --- | ---
`n_Diagnosed_by_ctime_sex` | time_horizon x 2 | Diagnosed COPD cases by time and sex
`n_Diagnosed_by_ctime_severity` | time_horizon x 4 | Diagnosed cases by time and GOLD stage
`n_Overdiagnosed_by_ctime_sex` | time_horizon x 2 | False diagnoses by time and sex
`n_case_detection_by_ctime` | time_horizon x 4 | Case detection events by time and method
`n_case_detection_eligible` | scalar | Total eligible for case detection
`n_diagnosed_true_CD` | scalar | True positives from case detection
`n_agents_CD` | scalar | Agents who received case detection

#### Exacerbation Outcomes

Output | Dimensions | Description
--- | --- | ---
`n_exac_by_ctime_age` | time_horizon x 111 | Exacerbations by time and age
`n_exac_by_ctime_severity` | time_horizon x 4 | Exacerbations by time and severity
`n_exac_by_ctime_sex` | time_horizon x 2 | Exacerbations by time and sex
`n_exac_by_ctime_GOLD` | time_horizon x 4 | Exacerbations by time and GOLD stage
`n_exac_by_gold_severity` | 4 x 4 | Exacerbations by GOLD stage and severity
`n_exac_by_gold_severity_diagnosed` | 4 x 4 | Exacerbations among diagnosed patients
`n_severep_exac_by_ctime_age` | time_horizon x 111 | Severe and very severe exacerbations by time and age
`n_exac_by_ctime_severity_undiagnosed` | time_horizon x 4 | Exacerbations in undiagnosed patients
`n_exac_by_ctime_severity_diagnosed` | time_horizon x 4 | Exacerbations in diagnosed patients
`n_exac_by_ctime_severity_female` | time_horizon x 4 | Exacerbations in females by severity

#### Death Outcomes

Output | Dimensions | Description
--- | --- | ---
`n_death_by_age_sex` | 111 x 2 | Deaths by age and sex
`n_exac_death_by_ctime_age` | time_horizon x 111 | Exacerbation deaths by time and age
`n_exac_death_by_ctime_severity` | time_horizon x 4 | Exacerbation deaths by severity
`n_exac_death_by_age_sex` | 111 x 2 | Exacerbation deaths by age and sex

#### Cost and QALY Outcomes

Output | Dimensions | Description
--- | --- | ---
`annual_cost_ctime` | time_horizon | Annual costs by calendar time
`cumul_cost_ctime` | time_horizon | Cumulative costs by calendar time
`cumul_cost_gold_ctime` | time_horizon x 5 | Cumulative costs by time and GOLD stage
`cumul_qaly_ctime` | time_horizon | Cumulative QALYs by calendar time
`cumul_qaly_gold_ctime` | time_horizon x 5 | Cumulative QALYs by time and GOLD stage

#### Additional Summary Statistics

Output | Dimensions | Description
--- | --- | ---
`sum_fev1_ltime` | time_horizon | Sum of FEV1 values by local time
`sum_p_COPD_by_ctime_sex` | time_horizon x 2 | Sum of COPD probabilities by time/sex
`sum_pack_years_by_ctime_sex` | time_horizon x 2 | Sum of pack-years by time and sex
`sum_age_by_ctime_sex` | time_horizon x 2 | Sum of ages by time and sex
`sum_time_by_ctime_sex` | time_horizon x 2 | Person-time by calendar time and sex
`sum_time_by_age_sex` | 111 x 2 | Person-time by age and sex
`sum_weight_by_ctime_sex` | time_horizon x 2 | Sum of weights by time and sex

#### Symptom and GP Visit Outcomes

Output | Dimensions | Description
--- | --- | ---
`n_GPvisits_by_ctime_sex` | time_horizon x 2 | GP visits by time and sex
`n_GPvisits_by_ctime_severity` | time_horizon x 5 | GP visits by time and GOLD stage
`n_GPvisits_by_ctime_diagnosis` | time_horizon x 2 | GP visits by diagnosis status
`n_cough_by_ctime_severity` | time_horizon x 5 | Number with cough by time and GOLD
`n_phlegm_by_ctime_severity` | time_horizon x 5 | Number with phlegm by time and GOLD
`n_wheeze_by_ctime_severity` | time_horizon x 5 | Number with wheeze by time and GOLD
`n_dyspnea_by_ctime_severity` | time_horizon x 5 | Number with dyspnea by time and GOLD

#### Medication Outcomes

Output | Dimensions | Description
--- | --- | ---
`medication_time_by_class` | 5 | Person-time on each medication class
`medication_time_by_ctime_class` | time_horizon x 5 | Medication time by year and class
`n_smoking_cessation_by_ctime` | time_horizon | Smoking cessation treatments by time
`n_exac_by_medication_class` | 5 x 4 | Exacerbations by medication and severity

    results <- simulate(n_agents = 50000)
    #> === EPIC Simulation Configuration ===
    #> Jurisdiction: CANADA
    #> Time horizon: 20 years
    #> Number of agents: 50,000
    #> Event recording: DISABLED
    #> =====================================
    #>
    #> Starting simulation...
    #> No active session - initializing automatically
    #> Initializing the session
    #> Working directory: /tmp/RtmpgeOOvt/Rbuild21f45248fe3d07/epicR/vignettes
    #> Running EPIC model (with custom input parameters)
    #> Record mode: record_mode_none (0)
    #> Note: No events will be recorded. Use record_mode_event (2) or record_mode_agent (1) to record events.
    #> Simulating 50000 base agents: 10% 20% 30% 40% 50%
    #> 60% 70% 80% 90% 100%
    #> Simulation completed in 1.8 seconds
    #> Collecting results...
    #> Collecting extended results...
    #> Terminating the session
    #> Done!

    # Access extended results
    extended <- results$extended

    # Calculate COPD prevalence over time
    copd_prevalence <- rowSums(extended$n_COPD_by_ctime_sex) /
                       rowSums(extended$n_alive_by_ctime_sex)
    plot(copd_prevalence, type = "l",
         xlab = "Year", ylab = "COPD Prevalence",
         main = "COPD Prevalence Over Time")

    # Calculate annual exacerbation rates by severity
    annual_exac_rates <- extended$n_exac_by_ctime_severity /
                         rowSums(extended$n_COPD_by_ctime_sex)

    # Analyze costs by GOLD stage
    costs_by_gold <- colSums(extended$cumul_cost_gold_ctime)
    names(costs_by_gold) <- c("No COPD", "GOLD 1", "GOLD 2", "GOLD 3", "GOLD 4")
    barplot(costs_by_gold, main = "Total Costs by GOLD Stage")

## Event History (`results$events`)

For detailed agent-level analysis, you can capture the complete event history by setting `return_events = TRUE`.

Note: Event recording requires significant memory. Use with caution for large simulations.

    # Run simulation with event recording
    results <- simulate(
      n_agents = 10000,
      return_events = TRUE
    )
    #> === EPIC Simulation Configuration ===
    #> Jurisdiction: CANADA
    #> Time horizon: 20 years
    #> Number of agents: 10,000
    #> Event recording: ENABLED (record_mode = 2)
    #> Estimated memory for events: 236.6 MB
    #> =====================================
    #>
    #> Starting simulation...
    #> No active session - initializing automatically
    #> Initializing the session
    #> Working directory: /tmp/RtmpgeOOvt/Rbuild21f45248fe3d07/epicR/vignettes
    #> Running EPIC model (with custom input parameters)
    #> Record mode: record_mode_event (2)
    #> Simulating 10000 base agents: 10% 20% 30% 40% 50%
    #> 60% 70% 80% 90% 100%
    #> Simulation completed in 0.4 seconds
    #> Collecting results...
    #> Collecting extended results...
    #> Collecting event history...
    #> Terminating the session
    #> Done!

    # Access events data frame
    events <- results$events
    head(events)
    #>   id local_time female time_at_creation age_at_creation pack_years gold event
    #> 1  0          0      0                0        49.44103          0    0     0
    #> 2  0          1      0                0        49.44103          0    0     1
    #> 3  0          2      0                0        49.44103          0    0     1
    #> 4  0          3      0                0        49.44103          0    0     1
    #> 5  0          4      0                0        49.44103          0    0     1
    #> 6  0          5      0                0        49.44103          0    0     1
    #>   FEV1 FEV1_slope FEV1_acceleration pred_FEV1 smoking_status localtime_at_COPD
    #> 1    0          0                 0         0              0                 0
    #> 2    0          0                 0         0              0                 0
    #> 3    0          0                 0         0              0                 0
    #> 4    0          0                 0         0              0                 0
    #> 5    0          0                 0         0              0                 0
    #> 6    0          0                 0         0              0                 0
    #>   age_at_COPD weight_at_COPD   height followup_after_COPD FEV1_baseline
    #> 1           0              0 1.837219                   0      2.773865
    #> 2           0              0 1.837219                   0      2.773865
    #> 3           0              0 1.837219                   0      2.773865
    #> 4           0              0 1.837219                   0      2.773865
    #> 5           0              0 1.837219                   0      2.773865
    #> 6           0              0 1.837219                   0      2.773865
    #>   exac_status cough phlegm wheeze dyspnea gpvisits diagnosis medication_status
    #> 1           0     0      0      0       0        0         0                 0
    #> 2           0     0      0      0       0        1         0                 0
    #> 3           0     0      0      0       1        3         0                 0
    #> 4           0     0      0      0       0        2         0                 0
    #> 5           0     0      0      0       0        1         0                 0
    #> 6           0     0      0      1       0        2         0                 0
    #>   case_detection cumul_cost cumul_qaly time_at_diagnosis
    #> 1              0          0  0.0000000                 0
    #> 2              0          0  0.8349515                 0
    #> 3              0          0  1.6455839                 0
    #> 4              0          0  2.4326058                 0
    #> 5              0          0  3.1967046                 0
    #> 6              0          0  3.9385482                 0
    #>   exac_history_n_moderate exac_history_n_severe_plus
    #> 1                       0                          0
    #> 2                       0                          0
    #> 3                       0                          0
    #> 4                       0                          0
    #> 5                       0                          0
    #> 6                       0                          0

### Event Matrix Columns (33 columns)

Column | Description
--- | ---
`id` | Unique agent identifier
`local_time` | Time since agent creation (years)
`female` | Sex (0=male, 1=female)
`time_at_creation` | Calendar time when agent entered model
`age_at_creation` | Age when agent entered model
`pack_years` | Cumulative pack-years of smoking
`gold` | GOLD stage (0=no COPD, 1-4=GOLD stages)
`event` | Event type code (see table below)
`FEV1` | Current FEV1 value (liters)
`FEV1_slope` | FEV1 decline slope
`FEV1_acceleration` | FEV1 decline acceleration
`pred_FEV1` | Predicted FEV1 based on age/height/sex
`smoking_status` | Current smoking status (0=not smoking, 1=smoking)
`localtime_at_COPD` | Local time when COPD developed
`age_at_COPD` | Age when COPD developed
`weight_at_COPD` | Weight when COPD developed
`height` | Height (meters)
`followup_after_COPD` | Time since COPD onset
`FEV1_baseline` | FEV1 at COPD onset
`exac_status` | Current exacerbation status (0=none, 1-4=severity)
`cough` | Cough symptom present (0/1)
`phlegm` | Phlegm symptom present (0/1)
`wheeze` | Wheeze symptom present (0/1)
`dyspnea` | Dyspnea symptom present (0/1)
`gpvisits` | Annual number of GP visits
`diagnosis` | Diagnosis status (0=undiagnosed, 1=diagnosed)
`medication_status` | Medication class bitfield
`case_detection` | Case detection received (0/1)
`cumul_cost` | Cumulative cost for this agent
`cumul_qaly` | Cumulative QALYs for this agent
`time_at_diagnosis` | Local time when diagnosed
`exac_history_n_moderate` | Cumulative count of moderate exacerbations
`exac_history_n_severe_plus` | Cumulative count of severe and very severe exacerbations

### Event Type Codes

Event | Code | Description
--- | --- | ---
Start | 0 | Agent creation
Annual | 1 | Annual update (fixed time event)
Birthday | 2 | Birthday event (currently disabled)
Smoking change | 3 | Smoking status change (start or quit)
COPD incidence | 4 | New COPD diagnosis
Exacerbation | 5 | Exacerbation onset
Exacerbation end | 6 | Exacerbation resolution
Death by exacerbation | 7 | Death during exacerbation
Doctor visit | 8 | Doctor visit (not implemented)
Medication change | 9 | Medication change (not implemented)
Background death | 13 | Death from background causes
End | 14 | End of follow-up

    # Analyze events for a specific agent
    results <- simulate(n_agents = 10000, return_events = TRUE)
    #> === EPIC Simulation Configuration ===
    #> Jurisdiction: CANADA
    #> Time horizon: 20 years
    #> Number of agents: 10,000
    #> Event recording: ENABLED (record_mode = 2)
    #> Estimated memory for events: 236.6 MB
    #> =====================================
    #>
    #> Starting simulation...
    #> No active session - initializing automatically
    #> Initializing the session
    #> Working directory: /tmp/RtmpgeOOvt/Rbuild21f45248fe3d07/epicR/vignettes
    #> Running EPIC model (with custom input parameters)
    #> Record mode: record_mode_event (2)
    #> Simulating 10000 base agents: 10% 20% 30% 40% 50%
    #> 60% 70% 80% 90% 100%
    #> Simulation completed in 0.5 seconds
    #> Collecting results...
    #> Collecting extended results...
    #> Collecting event history...
    #> Terminating the session
    #> Done!
    events <- results$events

    # Get all events for agent #5
    agent_5_events <- events[events$id == 5, ]
    print(agent_5_events[, c("local_time", "event", "gold", "exac_status")])
    #>     local_time event gold exac_status
    #> 98     0.00000     0    0           0
    #> 99     1.00000     1    0           0
    #> 100    2.00000     1    0           0
    #> 101    3.00000     1    0           0
    #> 102    4.00000     1    0           0
    #> 103    5.00000     1    0           0
    #> 104    6.00000     1    0           0
    #> 105    7.00000     1    0           0
    #> 106    8.00000     1    0           0
    #> 107    9.00000     1    0           0
    #> 108   10.00000     1    0           0
    #> 109   11.00000     1    0           0
    #> 110   12.00000     1    0           0
    #> 111   12.23359     3    0           0
    #> 112   13.00000     1    0           0
    #> 113   14.00000     1    0           0
    #> 114   15.00000     1    0           0
    #> 115   16.00000     1    0           0
    #> 116   17.00000     1    0           0
    #> 117   18.00000     1    0           0
    #> 118   19.00000     1    0           0
    #> 119   20.00000    14    0           0

    # Count events by type
    event_counts <- table(events$event)
    names(event_counts) <- c("Start", "Annual", "Birthday", "Smoking",
                             "COPD", "Exac", "Exac_end", "Exac_death",
                             "Doctor", "Med_change", "", "", "",
                             "Bgd_death", "End")[as.numeric(names(event_counts)) + 1]
    print(event_counts)
    #>      Start     Annual    Smoking       COPD       Exac   Exac_end Exac_death
    #>      16071     211014       3036        936      12637      12470        141
    #>  Bgd_death        End
    #>       3266      16071

    # Find all exacerbation events
    exac_events <- events[events$event == 5, ]
    cat("Total exacerbations:", nrow(exac_events), "\n")
    #> Total exacerbations: 12637
    cat("By severity:\n")
    #> By severity:
    print(table(exac_events$exac_status))
    #>
    #>    1    2    3    4
    #> 1692 9906  961   78

## Record Modes

The `record_mode` setting controls what level of detail is captured.

Mode | Value | Description | Memory Usage
--- | --- | --- | ---
`record_mode_none` | 0 | Aggregate output only | Minimal
`record_mode_agent` | 1 | Agent-level summaries | Low
`record_mode_event` | 2 | Complete event history | High
`record_mode_some_event` | 3 | Selected event types only | Medium

    # Using settings directly
    settings <- get_default_settings()
    settings$record_mode <- 2  # Full event recording
    settings$n_base_agents <- 10000

    results <- simulate(settings = settings, return_events = TRUE)
    #> === EPIC Simulation Configuration ===
    #> Jurisdiction: CANADA
    #> Time horizon: 20 years
    #> Number of agents: 10,000
    #> Event recording: ENABLED (record_mode = 2)
    #> Estimated memory for events: 236.6 MB
    #> =====================================
    #>
    #> Starting simulation...
    #> No active session - initializing automatically
    #> Initializing the session
    #> Working directory: /tmp/RtmpgeOOvt/Rbuild21f45248fe3d07/epicR/vignettes
    #> Running EPIC model (with custom input parameters)
    #> Record mode: record_mode_event (2)
    #> Simulating 10000 base agents: 10% 20% 30% 40% 50%
    #> 60% 70% 80% 90% 100%
    #> Simulation completed in 0.4 seconds
    #> Collecting results...
    #> Collecting extended results...
    #> Collecting event history...
    #> Terminating the session
    #> Done!

    # Or simply use return_events = TRUE (automatically sets record_mode = 2)
    results <- simulate(n_agents = 10000, return_events = TRUE)
    #> === EPIC Simulation Configuration ===
    #> Jurisdiction: CANADA
    #> Time horizon: 20 years
    #> Number of agents: 10,000
    #> Event recording: ENABLED (record_mode = 2)
    #> Estimated memory for events: 236.6 MB
    #> =====================================
    #>
    #> Starting simulation...
    #> No active session - initializing automatically
    #> Initializing the session
    #> Working directory: /tmp/RtmpgeOOvt/Rbuild21f45248fe3d07/epicR/vignettes
    #> Running EPIC model (with custom input parameters)
    #> Record mode: record_mode_event (2)
    #> Simulating 10000 base agents: 10% 20% 30% 40% 50%
    #> 60% 70% 80% 90% 100%
    #> Simulation completed in 0.5 seconds
    #> Collecting results...
    #> Collecting extended results...
    #> Collecting event history...
    #> Terminating the session
    #> Done!

## Complete Example: Cost-Effectiveness Analysis

    # Baseline scenario
    input_baseline <- get_input(jurisdiction = "canada")
    results_baseline <- simulate(
      input = input_baseline$values,
      n_agents = 50000,
      seed = 12345  # For reproducibility
    )
    #> Random seed set to: 12345
    #> === EPIC Simulation Configuration ===
    #> Jurisdiction: CANADA
    #> Time horizon: 20 years
    #> Number of agents: 50,000
    #> Event recording: DISABLED
    #> =====================================
    #>
    #> Starting simulation...
    #> No active session - initializing automatically
    #> Initializing the session
    #> Working directory: /tmp/RtmpgeOOvt/Rbuild21f45248fe3d07/epicR/vignettes
    #> Running EPIC model (with custom input parameters)
    #> Record mode: record_mode_none (0)
    #> Note: No events will be recorded. Use record_mode_event (2) or record_mode_agent (1) to record events.
    #> Simulating 50000 base agents: 10% 20% 30% 40% 50%
    #> 60% 70% 80% 90% 100%
    #> Simulation completed in 1.9 seconds
    #> Collecting results...
    #> Collecting extended results...
    #> Terminating the session
    #> Done!

    # Intervention scenario: Enhanced smoking cessation
    input_intervention <- get_input(jurisdiction = "canada")
    input_intervention$values$smoking$ln_h_ces_betas[1] <-
      input_intervention$values$smoking$ln_h_ces_betas[1] + 0.5

    results_intervention <- simulate(
      input = input_intervention$values,
      n_agents = 50000,
      seed = 12345  # Same seed for comparability
    )
    #> Random seed set to: 12345
    #> === EPIC Simulation Configuration ===
    #> Jurisdiction: CANADA
    #> Time horizon: 20 years
    #> Number of agents: 50,000
    #> Event recording: DISABLED
    #> =====================================
    #>
    #> Starting simulation...
    #> No active session - initializing automatically
    #> Initializing the session
    #> Working directory: /tmp/RtmpgeOOvt/Rbuild21f45248fe3d07/epicR/vignettes
    #> Running EPIC model (with custom input parameters)
    #> Record mode: record_mode_none (0)
    #> Note: No events will be recorded. Use record_mode_event (2) or record_mode_agent (1) to record events.
    #> Simulating 50000 base agents: 10% 20% 30% 40% 50%
    #> 60% 70% 80% 90% 100%
    #> Simulation completed in 1.8 seconds
    #> Collecting results...
    #> Collecting extended results...
    #> Terminating the session
    #> Done!

    # Calculate incremental cost-effectiveness
    delta_cost <- results_intervention$basic$total_cost - results_baseline$basic$total_cost
    delta_qaly <- results_intervention$basic$total_qaly - results_baseline$basic$total_qaly
    icer <- delta_cost / delta_qaly

    cat("Baseline total cost:", results_baseline$basic$total_cost, "\n")
    #> Baseline total cost: 169165520
    cat("Intervention total cost:", results_intervention$basic$total_cost, "\n")
    #> Intervention total cost: 171719698
    cat("Baseline total QALYs:", results_baseline$basic$total_qaly, "\n")
    #> Baseline total QALYs: 688131.6
    cat("Intervention total QALYs:", results_intervention$basic$total_qaly, "\n")
    #> Intervention total QALYs: 688511.2
    cat("Incremental cost:", delta_cost, "\n")
    #> Incremental cost: 2554179
    cat("Incremental QALYs:", delta_qaly, "\n")
    #> Incremental QALYs: 379.5853
    cat("ICER:", icer, "per QALY\n")
    #> ICER: 6728.866 per QALY

## Important Notes

- Starting Age: EPIC only simulates patients starting at age 40
- Comorbidities: Cardiovascular comorbidities (MI, stroke, heart failure) are not implemented in the current version
- Memory: Event recording can require substantial memory for large simulations
- Reproducibility: Use the `seed` parameter for reproducible results
- Discounting: Costs and QALYs are discounted at the rates specified in `global_parameters`