# Getting Started with EPIC

## Introduction

This guide will help you get started with the Evaluation Platform in COPD (EPIC) using the epicR package. By the end of this vignette, you will be able to:

- Run a basic COPD simulation
- Understand and interpret the model outputs
- Customize inputs and settings for your analysis
- Choose between Canadian and US populations

## What is EPIC?

EPIC is a discrete-event simulation (DES) model for Chronic Obstructive Pulmonary Disease (COPD). It models the entire pathway of care including:

- Disease incidence and progression
- Diagnosis and case detection
- Exacerbations (mild, moderate, severe)
- Treatment and medication
- Healthcare resource utilization
- Mortality

The model simulates individual patients (called “agents”) with demographic and clinical characteristics. Each agent progresses through time, experiencing events like birthdays, disease onset, exacerbations, and treatment changes.

## Installation

If you haven’t already installed epicR:

    # Install from GitHub
    pak::pkg_install("resplab/epicR")

## Quick Start: Your First Simulation

### Simple Approach (Recommended)

The easiest way to run a simulation is using the `simulate()` function, which handles all session management automatically and provides progress information (configuration summary, real-time progress bar, elapsed time, and status messages):

    library(epicR)

    # Run with defaults - that's it!
    results <- simulate()

    # Access basic results
    print(results$basic)

    # Custom parameters
    results <- simulate(
      jurisdiction = "us",
      time_horizon = 10,
      n_agents = 100000
    )

    # Quick test with fewer agents (faster for testing)
    results <- simulate(n_agents = 10000)

    # By default, you get both basic and extended results
    results <- simulate()
    print(results$basic)
    print(results$extended)  # Included by default

    # Get basic output only (faster, less memory)
    results <- simulate(extended_results = FALSE)

    # Get event history (automatically sets record_mode)
    results <- simulate(return_events = TRUE)
    head(results$events)

The basic output includes:

Output | Description
--- | ---
`n_agents` | Total number of agents simulated
`cumul_time` | Total person-years of follow-up
`n_deaths` | Number of deaths
`n_COPD` | Number of agents who developed COPD
`n_exac_*` | Exacerbation counts by severity
`total_cost` | Total healthcare costs
`total_qaly` | Total quality-adjusted life years

## Choosing a Jurisdiction: Canada vs US

EPIC supports both Canadian and US populations with jurisdiction-specific parameters:

    # For Canadian population (default)
    results_canada <- simulate(jurisdiction = "canada")

    # For US population
    results_us <- simulate(jurisdiction = "us")

The jurisdictions differ in: - Population demographics - Smoking prevalence and trends - Healthcare costs - Disease incidence rates

## Customizing Your Simulation

### Understanding Inputs

Inputs control the model’s parameters. Explore them:

    inputs <- get_input()

    # Top-level structure
    names(inputs)
    # [1] "values" "help" "references"

    # Value categories
    names(inputs$values)

    # Example: global parameters
    names(inputs$values$global_parameters)
    inputs$values$global_parameters$time_horizon  # Simulation duration in years

### Common Input Modifications

The `simulate()` function provides convenient parameters for common customizations:

    # Change time horizon
    results <- simulate(time_horizon = 20)

    # Change jurisdiction and time horizon
    results <- simulate(jurisdiction = "us", time_horizon = 15)

    # For quick testing
    results <- simulate(n_agents = 10000, time_horizon = 5)

For more advanced input modifications, you can use `get_input()` to explore and modify parameters:

    # Explore available inputs
    input <- get_input()
    names(input$values)  # See categories

    # View specific parameters
    input$values$cost$exac_dcost  # Exacerbation costs by severity
    input$values$global_parameters$time_horizon

### Understanding Settings

Settings control how the model runs (not what it simulates):

    settings <- get_default_settings()
    names(settings)

Key settings:

Setting | Description | Default
--- | --- | ---
`n_base_agents` | Number of agents to simulate | 60,000
`record_mode` | Level of output detail (0=aggregate, 2=individual) | 0

### Choosing the Number of Agents

More agents = more precision but longer runtime and more memory:

    # Quick test run (10,000 agents)
    results <- simulate(n_agents = 1e4)

    # Standard run (60,000 agents - default)
    results <- simulate()

    # Production run (1,000,000 agents)
    results <- simulate(n_agents = 1e6)

    # Check memory requirements before running large simulations
    estimate_memory_required(n_agents = 1e6, record_mode = 0, time_horizon = 20)

## Getting Detailed Results

### Extended Output

For more detailed results by year and demographics:

    # By default, you get both basic and extended results
    results <- simulate()

    # Access basic results
    print(results$basic)

    # Access detailed output tables
    names(results$extended)

### Individual Patient Data

To collect event-level data for each agent, use `return_events = TRUE`:

    # Get event history (automatically sets record_mode = 2)
    # Keep n_agents small due to memory requirements
    results <- simulate(
      n_agents = 1e4,
      time_horizon = 5,
      return_events = TRUE
    )

    # Access events data frame
    head(results$events)

    # Get everything including events
    results <- simulate(
      n_agents = 1e4,
      extended_results = TRUE,  # TRUE by default
      return_events = TRUE
    )
    # Returns: results$basic, results$extended, results$events

Warning: Recording individual events requires substantial memory. Start with a small number of agents.

### Event Types

Each event in the individual data has a numeric code:

Event | Code
--- | ---
Start | 0
Annual | 1
Birthday | 2
Smoking change | 3
COPD incidence | 4
Exacerbation | 5
Exacerbation end | 6
Death by exacerbation | 7
Doctor visit | 8
Medication change | 9
Background death | 13
End | 14

## Open vs Closed Cohort

By default, EPIC is an open population model that captures population dynamics (births, deaths, immigration, emigration). For a closed cohort analysis (fixed initial population, no new entries):

    # Run closed cohort analysis
    results <- simulate(closed_cohort = TRUE)

    # Combine with other parameters
    results <- simulate(
      closed_cohort = TRUE,
      jurisdiction = "us",
      time_horizon = 10,
      n_agents = 50000
    )

## Comparing Scenarios

A common use case is comparing interventions. The `simulate()` function makes this straightforward:

    # Baseline scenario
    results_baseline <- simulate(
      jurisdiction = "canada",
      time_horizon = 20,
      n_agents = 100000
    )

    # Intervention scenario (e.g., different time horizon or jurisdiction)
    results_intervention <- simulate(
      jurisdiction = "us",
      time_horizon = 20,
      n_agents = 100000
    )

    # Compare outcomes
    cost_diff <- results_intervention$basic$total_cost -
      results_baseline$basic$total_cost
    qaly_diff <- results_intervention$basic$total_qaly -
      results_baseline$basic$total_qaly
    icer <- cost_diff / qaly_diff

For more complex scenarios requiring custom input modifications, see the “Advanced Usage” section below.

## Advanced Usage

For advanced users who need fine-grained control over input parameters:

### Custom Input Modifications

For complex input modifications not covered by `simulate()` parameters:

    # Get and modify inputs
    input <- get_input()

    # Modify specific parameters
    input$values$global_parameters$time_horizon <- 5
    input$values$agent$p_female <- 0.55

    # Run with custom inputs
    results <- simulate(input = input$values)

### Running Multiple Simulations

To run multiple simulations with different parameters:

    # Simulation 1
    results1 <- simulate(n_agents = 50000, time_horizon = 10, seed = 123)

    # Simulation 2 with different parameters
    results2 <- simulate(n_agents = 50000, time_horizon = 20, seed = 123)

    # Compare results
    comparison <- data.frame(
      time_horizon = c(10, 20),
      n_deaths = c(results1$basic$n_deaths, results2$basic$n_deaths)
    )

### Error Handling

The `simulate()` function includes automatic error handling and cleanup. For additional safety:

    results <- tryCatch({
      simulate(n_agents = 50000)
    }, error = function(e) {
      message("Simulation failed: ", e$message)
      NULL
    })

## Troubleshooting

### Memory Errors

If you get memory allocation errors: 1. Reduce the number of agents: `simulate(n_agents = 10000)` 2. Don’t request event history unless needed (omit `return_events`) 3. Check available memory with `estimate_memory_required()`

### Session Issues

The `simulate()` function handles session management automatically and includes error handling.

## Next Steps

- Model Background: See `vignette("BackgroundEPIC")` for model structure details
- Calibration: See `vignette("Calibrate_COPD_Prevalence")` for calibration methods
- Validation: Explore the `validate_*()` functions for model validation
- US Model: See `vignette("Calibrate_Smoking")` for US-specific calibration

## References

Sadatsafavi M, et al. (2019). Development and Validation of the Evaluation Platform in COPD (EPIC): A Population-Based Outcomes Model of COPD for Canada. Medical Decision Making. doi:10.1177/0272989X18824098