Simulate trials — simulate

This is the key user-facing function for simulating trials.

Usage

simulate_trials(scenario, ...)

# S3 method for hrqolr_scenario
simulate_trials(
  scenario,
  n_trials = 100,
  n_patients_ground_truth = 1000,
  n_example_trajectories_per_arm = 50,
  test_fun = welch_t_test,
  include_trial_results = FALSE,
  verbose = TRUE,
  n_digits = 2,
  valid_hrqol_range = c(-0.757, 1),
  alpha = 0.05,
  max_batch_size = NULL,
  seed = NULL,
  ...
)

Arguments

scenario: object of class 'hrqolr_scenario', the output of setup_scenario
...: passed on to methods
n_trials: single integer, the number of trials to simulate in total
n_patients_ground_truth: single integer, how many patients (per arm) to use when estimating the ground truth
n_example_trajectories_per_arm: single integer, the number of example trajectories to include in the returned object
test_fun: function used to compare estimates. The default is welch_t_test (built into hrqolr). Note that the function should handle the number of arms provided. See Details below.
include_trial_results: single logical, indicates whether trial-level results are kept. Default is FALSE because the resulting object may be very large if many trials are simulated.
verbose: single logical, should the function give progress timestamped updates? Default: TRUE
n_digits: single integer, the number of decimal places of in the first HRQoL values of patients. More digits will yield greater precision but also cause longer run-times.
valid_hrqol_range: two-element numeric vector, the lower and upper bounds of valid HRQoL values. The default (c(-0.757, 1.0)) corresponds to the Danish EQ-5D-5L index values.
alpha: single numerical value in [0, 1], the desired type 1 error rate used when comparing HRQoL in the arms.
max_batch_size: single integer, the maximum number of patients to process in each batch. The default is to use run one batch (i.e. no upper limit).
seed: single integer, optional seed for reproducible pseudo-random number generation. Defaults to a deterministic value based on the arguments given (ensuring reproducibility by default).

Value

An object of class hrqolr_results, which is a specialised list with six elements:

summary_stats contains summary statistics for each arm
comparisons contains comparisons against the ground truth and performance metrics
args is a list with all arguments
trial_results contains trial-level results, if include_trial_results = TRUE
example_trajectories contains example trajectories is n_example_trajectories_per_arm is greater than 0
resource_use documents approximate run-time, peak memory use and maximum cache size. This information can be helpful for orchestration if several (hundreds or thousands) scenarios are simulated in parallel on e.g. high-performance computing systems

Details

test_fun

hrqolr comes with three built-in test functions: welch_t_test and bootstrap_estimates work with two-armed trials, games_howell_test with three-arm trials. If you use case so requires, you can specify your own test_fun. It must accept five arguments:

vals is a vector all outcome values
grps is a vector with the same length as vals with grouping indices
arms is the unique values in the grps vector
na_replacement is the value to put in place of NA's (which would be patients for whom no outcome values are available because they have died before follow-up started)
alpha the significance level specified when calling simulate_trials()

--and it must return a list with six elements:

comparator string, the name of comparator arm in the comparison
target string, the name of target arm in the comparison
est numeric, the point estimate
p_value numeric
ci_lo numeric, lower bound of the confidence interval
ci_hi numeric, upper bound of the confidence interval

References

Jensen CE et al. (20219). The Danish EQ-5D-5L Value Set: A Hybrid Model Using cTTO and DCE Data. Appl Health Econ Health Policy 19, 579–591 (https://doi.org/10.1007/s40258-021-00639-3)