| Title: | Evaluation Platform in Chronic Obstructive Pulmonary Disease |
|---|---|
| Description: | Evaluation Platform in Chronic Obstructive Pulmonary Disease (EPIC) is a Discrete Event Simulation (DES) model that simulates health outcomes of patients with Chronic Obstructive Pulmonary Disease (COPD) based on demographics and individual-level risk factors, based on the model published in Sadatsafavi et al. (2019) <doi:10.1177/0272989X18824098>. |
| Authors: | Mohsen Sadatsafavi [aut, cph], Amin Adibi [aut, cre], Kate Johnson [aut] |
| Maintainer: | Amin Adibi <[email protected]> |
| License: | GPL-3 |
| Version: | 1.0.1 |
| Built: | 2026-05-10 08:57:42 UTC |
| Source: | https://github.com/resplab/epicr |
epicR packageEvaluation Platform in COPD (EPIC) R Package
See the README on GitHub
Maintainer: Amin Adibi [email protected]
Authors:
Mohsen Sadatsafavi [email protected] [copyright holder]
Kate Johnson [email protected]
Calculate recommended event_stack_size for a given number of agents
calc_event_stack_size(n_agents, time_horizon = 20)calc_event_stack_size(n_agents, time_horizon = 20)
n_agents |
number of agents to simulate |
time_horizon |
simulation time horizon in years (default 20) |
recommended event_stack_size
Solves stochastically for COPD incidence rate equation.
calibrate_COPD_inc( nIterations = 100, nPatients = 1e+05, time_horizon = 20, output_dir = tempdir() )calibrate_COPD_inc( nIterations = 100, nPatients = 1e+05, time_horizon = 20, output_dir = tempdir() )
nIterations |
number of iterations for the numerical solution |
nPatients |
number of simulated agents. |
time_horizon |
in years |
output_dir |
directory for output CSV files (default: tempdir()) |
regression co-efficients as files
Calibrates explicit mortality
calibrate_explicit_mortality(n_sim = 10^8)calibrate_explicit_mortality(n_sim = 10^8)
n_sim |
number of agents |
difference in mortality rates and life table
Calibrates explicit mortality by Amin
calibrate_explicit_mortality2(n_sim = 10^7)calibrate_explicit_mortality2(n_sim = 10^7)
n_sim |
number of agents |
difference in mortality rates and life table
Calibrates smoking
calibrate_smoking()calibrate_smoking()
TODO
Copy default configs to user directory
copy_configs_to_user(overwrite = FALSE)copy_configs_to_user(overwrite = FALSE)
overwrite |
Whether to overwrite existing user configs (default FALSE) |
TRUE if successful, FALSE otherwise
The epicR package now supports user-customizable configuration files. When the package is loaded for the first time, configuration files are automatically copied to a user-specific directory following CRAN policy. You can modify these files to customize model parameters for your specific region or research needs.
User configuration files are stored in a platform-specific location determined
by tools::R_user_dir("epicR", "config"). Use get_user_config_dir()
to find the exact path on your system.
get_user_config_dir: Get the path to user config directory
user_config_exists: Check if a user config exists
copy_configs_to_user: Copy default configs to user directory
reset_user_configs: Reset configs to package defaults
list_available_jurisdictions: List available config jurisdictions
validate_config: Validate a configuration file
The package automatically uses user configs if they exist. When you call
get_input(), it will:
First check for user config files in the user config directory
If found, use the user's customized configuration
If not found, fall back to package default configurations
To customize configurations for your region:
The config files are automatically copied on first package load
Edit the JSON files (e.g., 'config_canada.json', 'config_us.json')
Save your changes
The next time you use get_input(), your changes will be used
To add a new jurisdiction:
Copy an existing config file (e.g., 'config_canada.json')
Rename it to 'config_yourcountry.json'
Update the "jurisdiction" field in the JSON to match
Modify all parameters as needed for your region
Use with: get_input(jurisdiction = "yourcountry")
If you need to reset your configurations:
Reset all configs: reset_user_configs()
Reset specific jurisdiction: reset_user_configs("canada")
# Check where user configs are stored get_user_config_dir() # List available jurisdictions list_available_jurisdictions() # Validate your custom config validate_config("canada", user = TRUE) # Reset to package defaults if needed reset_user_configs("canada") # Use your custom config input <- get_input(jurisdiction = "canada")# Check where user configs are stored get_user_config_dir() # List available jurisdictions list_available_jurisdictions() # Validate your custom config validate_config("canada", user = TRUE) # Reset to package defaults if needed reset_user_configs("canada") # Use your custom config input <- get_input(jurisdiction = "canada")
Estimate memory required for simulation
estimate_memory_required(n_agents, record_mode = 0, time_horizon = 20)estimate_memory_required(n_agents, record_mode = 0, time_horizon = 20)
n_agents |
number of agents |
record_mode |
recording mode (0=none, 1=agent, 2=event, 3=some_event) |
time_horizon |
simulation time horizon in years |
estimated memory in bytes
Runs the model and exports an excel file with all output data
export_figures(nPatients = 10000)export_figures(nPatients = 10000)
nPatients |
number of agents |
an excel file with all output
Takes a named matrix and writes the R code to populate it; useful for generating input expressions from calibration results.
express_matrix(mtx)express_matrix(mtx)
mtx |
a matrix |
Invisibly returns the generated R code as a character string, also outputs via message().
Returns all events of an agent.
Returns events specific to an agent.
get_agent_events(id) get_agent_events(id)get_agent_events(id) get_agent_events(id)
id |
Agent number |
all events of agent id
dataframe consisting all events specific to agent id
Returns the size of agent struct in bytes
Get size of agent struct in bytes (from C code)
get_agent_size_bytes() get_agent_size_bytes()get_agent_size_bytes() get_agent_size_bytes()
size of agent struct in bytes
size in bytes
Returns all events.
Returns all events.
get_all_events() get_all_events()get_all_events() get_all_events()
all events
dataframe consisting all events.
Returns a matrix containing all events
get_all_events_matrix()get_all_events_matrix()
a matrix containing all events
Get available system memory (platform-specific)
get_available_memory()get_available_memory()
available memory in bytes
Exports default settings
get_default_settings()get_default_settings()
default settings
Returns errors
get_errors()get_errors()
a text with description of error messages
Returns the events stack.
get_event(i)get_event(i)
i |
number of event |
events
Returns all events of a certain type.
Returns certain events by type
get_events_by_type(event_type) get_events_by_type(event_type)get_events_by_type(event_type) get_events_by_type(event_type)
event_type |
event_type number |
all events of the type event_type
dataframe consisting all events of the type event_type
Returns a list of default model input values
get_input( age0 = 40, time_horizon = 20, discount_cost = 0, discount_qaly = 0.03, closed_cohort = 0, jurisdiction = "canada" )get_input( age0 = 40, time_horizon = 20, discount_cost = 0, discount_qaly = 0.03, closed_cohort = 0, jurisdiction = "canada" )
age0 |
Starting age in the model |
time_horizon |
Model time horizon |
discount_cost |
Discounting for cost outcomes |
discount_qaly |
Discounting for QALY outcomes |
closed_cohort |
Whether the model should run as closed_cohort, open-population by default. |
jurisdiction |
Jurisdiction for model parameters ("canada" or "us") |
A list with four components:
A nested list of model input parameter values
A nested list of help text descriptions for each parameter
A nested list of reference information for each parameter
The raw configuration object loaded from the JSON file
Recursively extracts element names from a nested list structure.
get_list_elements(ls, running_name = "")get_list_elements(ls, running_name = "")
ls |
A list to extract element names from |
running_name |
Internal parameter for recursion (default: "") |
A character vector of element names, with nested elements separated by "$" (e.g., "parent$child$grandchild").
Returns total number of events.
get_n_events()get_n_events()
number of events
Main outputs of the current run.
get_output()get_output()
number of agents, cumulative time, number of deaths, number of COPD cases, as well as exacerbation statistics and QALYs.
Extra outputs from the model
get_output_ex()get_output_ex()
Extra outputs from the model.
Returns current simulation progress.
get_progress()get_progress()
Number of agents processed so far (last_id).
Returns run time stats.
get_runtime_stats()get_runtime_stats()
agent size as well as memory and random variable fill stats.
Returns a sample output for a given year and gender.
get_sample_output(year, sex)get_sample_output(year, sex)
year |
a number |
sex |
a number, 0 for male and 1 for female |
that specific output
Returns current settings.
get_settings()get_settings()
current settings.
Returns agent Smith.
get_smith()get_smith()
agent smith.
Returns the path to the user configuration directory following
CRAN policy using tools::R_user_dir().
get_user_config_dir()get_user_config_dir()
Path to user config directory
Initializes a model. Allocates memory to the C engine.
init_session(settings = get_default_settings(), jurisdiction = "canada")init_session(settings = get_default_settings(), jurisdiction = "canada")
settings |
customized settings. |
jurisdiction |
The jurisdiction for which to load input parameters (default: "canada"). |
0 if successful.
List available config jurisdictions
list_available_jurisdictions()list_available_jurisdictions()
Character vector of available jurisdictions
Samples from a multivariate normal
mvrnormArma(n, mu, sigma)mvrnormArma(n, mu, sigma)
n |
number of samples to be taken |
mu |
the mean |
sigma |
the covariance matrix |
the multivariate normal sample
Reports COPD related stats.
report_COPD_by_ctime(n_sim = 10^6)report_COPD_by_ctime(n_sim = 10^6)
n_sim |
number of simulated agents. |
COPD-related stats
Reports exacerbation-related stats.
report_exacerbation_by_time(n_sim = 10^5)report_exacerbation_by_time(n_sim = 10^5)
n_sim |
number of simulated agents. |
exacerbation-related stats
Forces the default model_input to be reloaded on next access. Useful after modifying config files.
reset_model_input()reset_model_input()
No return value, called for side effects (clears the model input cache).
Reset user configs to package defaults
reset_user_configs(jurisdiction = NULL)reset_user_configs(jurisdiction = NULL)
jurisdiction |
Specific jurisdiction to reset, or NULL for all (default NULL) |
TRUE if successful, FALSE otherwise
Resumes running of model.
resume(max_n_agents = NULL)resume(max_n_agents = NULL)
max_n_agents |
maximum number of agents |
0 if successful.
Basic tests of model functionality. Serious issues if the test does not pass.
sanity_check()sanity_check()
tests results
Basic COPD test.
sanity_COPD()sanity_COPD()
validation test results
Sets input variables.
set_input_var(name, value)set_input_var(name, value)
name |
a string |
value |
a number |
0 if successful
Sets model settings.
set_settings_var(name, value)set_settings_var(name, value)
name |
a name |
value |
a value |
0 if successful.
This is a simplified interface that handles session management automatically and returns the results directly. Ideal for most users. Progress information is displayed including: configuration summary, a real-time progress bar showing percentage completion (10
simulate( input = NULL, settings = NULL, jurisdiction = "canada", time_horizon = NULL, n_agents = NULL, extended_results = TRUE, return_events = FALSE, seed = NULL )simulate( input = NULL, settings = NULL, jurisdiction = "canada", time_horizon = NULL, n_agents = NULL, extended_results = TRUE, return_events = FALSE, seed = NULL )
input |
customized input criteria (optional) |
settings |
customized settings (optional) |
jurisdiction |
Jurisdiction for model parameters ("canada" or "us") |
time_horizon |
Model time horizon in years (default: uses config file value) |
n_agents |
Number of agents to simulate (default: 60,000) |
extended_results |
whether to return extended results in addition to basic (default: TRUE) |
return_events |
whether to return event matrix (default: FALSE). If TRUE, automatically sets record_mode=2 |
seed |
Random seed for reproducibility (optional). If provided, ensures identical results across runs |
list with simulation results (always includes 'basic', includes 'extended' by default, optionally 'events')
# Simplest usage - includes both basic and extended results results <- simulate() print(results$basic) print(results$extended) # With custom parameters results <- simulate(jurisdiction = "us", time_horizon = 10, n_agents = 100000) # Quick test with fewer agents results <- simulate(n_agents = 10000) # Basic output only (faster, less memory) results <- simulate(extended_results = FALSE) print(results$basic) # With event history results <- simulate(return_events = TRUE) print(results$events) # Event matrix # With reproducible results results1 <- simulate(seed = 123) results2 <- simulate(seed = 123) # results1 and results2 will be identical# Simplest usage - includes both basic and extended results results <- simulate() print(results$basic) print(results$extended) # With custom parameters results <- simulate(jurisdiction = "us", time_horizon = 10, n_agents = 100000) # Quick test with fewer agents results <- simulate(n_agents = 10000) # Basic output only (faster, less memory) results <- simulate(extended_results = FALSE) print(results$basic) # With event history results <- simulate(return_events = TRUE) print(results$events) # Event matrix # With reproducible results results1 <- simulate(seed = 123) results2 <- simulate(seed = 123) # results1 and results2 will be identical
Terminates a session and releases allocated memory.
terminate_session()terminate_session()
0 if successful.
Returns results of Case Detection strategies
test_case_detection( n_sim = 10000, p_of_CD = 0.1, min_age = 40, min_pack_years = 0, only_smokers = 0, CD_method = "CDQ195" )test_case_detection( n_sim = 10000, p_of_CD = 0.1, min_age = 40, min_pack_years = 0, only_smokers = 0, CD_method = "CDQ195" )
n_sim |
number of agents |
p_of_CD |
probability of recieving case detection given that an agent meets the selection criteria |
min_age |
minimum age that can recieve case detection |
min_pack_years |
minimum pack years that can recieve case detection |
only_smokers |
set to 1 if only smokers should recieve case detection |
CD_method |
Choose one case detection method: CDQ195", "CDQ165", "FlowMeter", "FlowMeter_CDQ" |
results of case detection strategy compared to no case detection
Check if user config exists
user_config_exists(jurisdiction = "canada")user_config_exists(jurisdiction = "canada")
jurisdiction |
Jurisdiction name (e.g., "canada", "us") |
TRUE if user config exists, FALSE otherwise
Validate a config file
validate_config(jurisdiction = "canada", user = TRUE)validate_config(jurisdiction = "canada", user = TRUE)
jurisdiction |
Jurisdiction to validate |
user |
Whether to validate user config (TRUE) or package config (FALSE) |
TRUE if valid, FALSE otherwise (with warnings about issues)
This function runs validation tests for COPD model outputs. It estimates the baseline prevalence and incidence of COPD, along with sex-specific baseline COPD prevalence. Additionally, it calculates the baseline prevalence of COPD by age groups and smoking pack-years. It also estimates the coefficients for the relationships between age, pack-years, smoking status, and the prevalence of COPD.
validate_COPD(incident_COPD_k = 1, return_CI = FALSE, jurisdiction = "canada")validate_COPD(incident_COPD_k = 1, return_CI = FALSE, jurisdiction = "canada")
incident_COPD_k |
a number (default=1) by which the incidence rate of COPD will be multiplied. |
return_CI |
if TRUE, returns 95 percent confidence intervals for the "Year" coefficient |
jurisdiction |
character string specifying the jurisdiction for validation ("canada" or "us"). Default is "canada". |
For Canada: list with validation test results. For US: data frame with COPD prevalence by age group over time.
This function returns a table showing the proportion of COPD patients diagnosed over the model's runtime. It also provides a second table that breaks down the proportion of diagnosed patients by COPD severity. Additionally, the function generates a plot to visualize the distribution of diagnoses over time.
validate_diagnosis(n_sim = 10000, jurisdiction = "canada")validate_diagnosis(n_sim = 10000, jurisdiction = "canada")
n_sim |
number of agents |
jurisdiction |
character string specifying the jurisdiction ("canada" or "us"). Default is "canada" |
validation test results
This function runs validation tests for COPD exacerbation rates by GOLD stage and compares them with reference values from studies such as CanCOLD, CIHI, and Hoogendoorn. It simulates exacerbation events, and returns key metrics, including overall exacerbation rates, rates by GOLD stage, and rates in diagnosed vs. undiagnosed patients.
validate_exacerbation( base_agents = 10000, input = NULL, jurisdiction = "canada" )validate_exacerbation( base_agents = 10000, input = NULL, jurisdiction = "canada" )
base_agents |
Number of agents in the simulation. Default is 1e4. |
input |
EPIC inputs |
jurisdiction |
character string specifying the jurisdiction for validation ("canada" or "us"). Default is "canada". |
For Canada: validation test results (invisible). For US: invisible NULL (results displayed via messages and plots).
This function returns Average number of GP visits by sex, COPD severity and COPD diagnosis status along with their plots.
validate_gpvisits(n_sim = 10000, jurisdiction = "canada")validate_gpvisits(n_sim = 10000, jurisdiction = "canada")
n_sim |
number of agents |
jurisdiction |
character string specifying the jurisdiction ("canada" or "us"). Default is "canada" |
validation test results
This function evaluates FEV1 (Forced Expiratory Volume in 1 second) values and GOLD stage distributions to assess lung function in simulated patients.
validate_lung_function(jurisdiction = "canada")validate_lung_function(jurisdiction = "canada")
jurisdiction |
character string specifying the jurisdiction ("canada" or "us"). Default is "canada" |
validation test results
This function returns plots showing medication usage over time
validate_medication(n_sim = 50000, jurisdiction = "canada")validate_medication(n_sim = 50000, jurisdiction = "canada")
n_sim |
number of agents |
jurisdiction |
character string specifying the jurisdiction ("canada" or "us"). Default is "canada" |
validation test results for medication
This function returns a table and a plot of the difference between simulated and expected (life table) mortality, by sex and age.
validate_mortality( n_sim = 5e+05, bgd = 1, bgd_h = 1, manual = 1, exacerbation = 1, jurisdiction = "canada" )validate_mortality( n_sim = 5e+05, bgd = 1, bgd_h = 1, manual = 1, exacerbation = 1, jurisdiction = "canada" )
n_sim |
number of simulated agents |
bgd |
a number |
bgd_h |
a number |
manual |
a number |
exacerbation |
a number |
jurisdiction |
character string specifying the jurisdiction ("canada" or "us"). Default is "canada" |
validation test results
This function returns the proportion of non-COPD subjects overdiagnosed over model time.
validate_overdiagnosis(n_sim = 10000, jurisdiction = "canada")validate_overdiagnosis(n_sim = 10000, jurisdiction = "canada")
n_sim |
number of agents |
jurisdiction |
character string specifying the jurisdiction ("canada" or "us"). Default is "canada" |
validation test results
Returns results of validation tests for payoffs, costs and QALYs
validate_payoffs( nPatient = 1e+06, disableDiscounting = TRUE, disableExacMortality = TRUE, jurisdiction = "canada" )validate_payoffs( nPatient = 1e+06, disableDiscounting = TRUE, disableExacMortality = TRUE, jurisdiction = "canada" )
nPatient |
number of simulated patients. Default is 1e6. |
disableDiscounting |
if TRUE, discounting will be disabled for cost and QALY calculations. Default: TRUE |
disableExacMortality |
if TRUE, mortality due to exacerbations will be disabled for cost and QALY calculations. Default: TRUE |
jurisdiction |
character string specifying the jurisdiction for validation ("canada" or "us"). Default is "canada". Currently only "canada" is implemented. |
validation test results
Returns simulated vs. predicted population table and a plot
validate_population( remove_COPD = 0, incidence_k = 1, savePlots = 0, jurisdiction = "canada" )validate_population( remove_COPD = 0, incidence_k = 1, savePlots = 0, jurisdiction = "canada" )
remove_COPD |
0 or 1, indicating whether COPD-caused mortality should be removed |
incidence_k |
a number (default=1) by which the incidence rate of population will be multiplied. |
savePlots |
0 or 1, exports 300 DPI population growth and pyramid plots comparing simulated vs. predicted population |
jurisdiction |
character string specifying the jurisdiction for validation ("canada" or "us"). Default is "canada". |
For Canada: returns a table showing predicted (StatsCan) and simulated population values. For US: returns a data frame with population comparisons by age group and year.
It compares simulated smoking prevalence and trends against observed data to assess the model's accuracy.
validate_smoking(remove_COPD = 1, intercept_k = NULL, jurisdiction = "canada")validate_smoking(remove_COPD = 1, intercept_k = NULL, jurisdiction = "canada")
remove_COPD |
0 or 1. whether to remove COPD-related mortality. |
intercept_k |
a number |
jurisdiction |
character string specifying the jurisdiction for validation ("canada" or "us"). Default is "canada". |
For Canada: validation test results (invisible). For US: data frame with smoking status rates by year.
Returns the Kaplan Meier curve comparing COPD and non-COPD
validate_survival( savePlots = FALSE, base_agents = 10000, jurisdiction = "canada" )validate_survival( savePlots = FALSE, base_agents = 10000, jurisdiction = "canada" )
savePlots |
TRUE or FALSE (default), exports 300 DPI population growth and pyramid plots comparing simulated vs. predicted population |
base_agents |
Number of agents in the simulation. Default is 1e4. |
jurisdiction |
character string specifying the jurisdiction ("canada" or "us"). Default is "canada" |
validation test results
This function plots the prevalence of cough, dyspnea, phlegm and wheeze over time and by GOLD stage.
validate_symptoms(n_sim = 10000, jurisdiction = "canada")validate_symptoms(n_sim = 10000, jurisdiction = "canada")
n_sim |
number of agents |
jurisdiction |
character string specifying the jurisdiction ("canada" or "us"). Default is "canada" |
validation test results
This function runs validation tests to examine how treatment initiated at diagnosis influences exacerbation rates in COPD patients. It compares exacerbation rates between diagnosed and undiagnosed patients and assesses the impact of treatment.
validate_treatment(n_sim = 10000, jurisdiction = "canada")validate_treatment(n_sim = 10000, jurisdiction = "canada")
n_sim |
number of agents |
jurisdiction |
character string specifying the jurisdiction ("canada" or "us"). Default is "canada" |
validation test results