Engine-specific trial simulation functions

These functions are the inner functions called by run_engine(). In this help file, only the most common engine functions are listed. To identify the appropriate engine function for your FACTS file, call get_facts_engine().

run_engine_aipf_contin(): Enrichment continuous.
run_engine_aipf_dichot(): Enrichment dichotomous.
run_engine_aipf_tte(): Enrichment time to event.
run_engine_contin(): Core continuous.
run_engine_crm(): continual reassessment method (CRM).
run_engine_dichot(): Core dichotomous.
run_engine_multep(): Multiple endpoint.
run_engine_tte(): Time to event.

run_engine_aipf_contin(
  param_files,
  n_sims = 1L,
  mode = c("", "r"),
  seed = NULL,
  analysis_data = NULL,
  analysis_mode = NULL,
  current_week = NULL,
  execdata = NULL,
  final = NULL,
  interim = NULL,
  mcmc_num = NULL,
  verbose = FALSE,
  version = NULL
)

run_engine_aipf_dichot(
  param_files,
  n_sims = 1L,
  mode = c("", "r"),
  seed = NULL,
  analysis_data = NULL,
  analysis_mode = NULL,
  current_week = NULL,
  execdata = NULL,
  final = NULL,
  interim = NULL,
  mcmc_num = NULL,
  verbose = FALSE,
  version = NULL
)

run_engine_aipf_tte(
  param_files,
  n_sims = 1L,
  mode = c("", "r"),
  seed = NULL,
  analysis_data = NULL,
  analysis_mode = NULL,
  current_week = NULL,
  execdata = NULL,
  final = NULL,
  interim = NULL,
  mcmc_num = NULL,
  verbose = FALSE,
  version = NULL
)

run_engine_contin(
  param_files,
  n_sims = 1L,
  mode = c("s", "r", "p"),
  seed = NULL,
  analysis_data = NULL,
  analysis_mode = NULL,
  arm_selection = NULL,
  armsdropped = NULL,
  complete_data_analysis = NULL,
  current_week = NULL,
  execdata = NULL,
  final = NULL,
  fsimdata = NULL,
  fsimexp = NULL,
  fsimparam = NULL,
  interim = NULL,
  keepfiles = NULL,
  mcmc_num = NULL,
  noadapt = NULL,
  s2_aux_paramfile = NULL,
  stage = NULL,
  verbose = FALSE,
  version = NULL
)

run_engine_crm(
  param_files,
  n_sims = 1L,
  mode = c("s", ""),
  directory = ".",
  allocator = NULL,
  charting_info = NULL,
  estimator = NULL,
  force_cohort = NULL,
  reduced_priority = NULL,
  version = NULL,
  verbose = FALSE
)

run_engine_dichot(
  param_files,
  n_sims = 1L,
  mode = c("s", "r", "p"),
  seed = NULL,
  analysis_data = NULL,
  analysis_mode = NULL,
  arm_selection = NULL,
  armsdropped = NULL,
  complete_data_analysis = NULL,
  current_week = NULL,
  execdata = NULL,
  final = NULL,
  fsimdata = NULL,
  fsimexp = NULL,
  fsimparam = NULL,
  interim = NULL,
  keepfiles = NULL,
  mcmc_num = NULL,
  noadapt = NULL,
  s2_aux_paramfile = NULL,
  stage = NULL,
  verbose = FALSE,
  version = NULL
)

run_engine_multep(
  param_files,
  n_sims = 1L,
  mode = c("s", "r", "p"),
  seed = NULL,
  analysis_data = NULL,
  analysis_mode = NULL,
  arm_selection = NULL,
  armsdropped = NULL,
  complete_data_analysis = NULL,
  current_week = NULL,
  execdata = NULL,
  final = NULL,
  fsimdata = NULL,
  fsimexp = NULL,
  fsimparam = NULL,
  interim = NULL,
  keepfiles = NULL,
  mcmc_num = NULL,
  noadapt = NULL,
  s2_aux_paramfile = NULL,
  stage = NULL,
  verbose = FALSE,
  version = NULL
)

run_engine_tte(
  param_files,
  n_sims = 1L,
  mode = c("s", "r", "p"),
  seed = NULL,
  analysis_data = NULL,
  analysis_mode = NULL,
  arm_selection = NULL,
  armsdropped = NULL,
  complete_data_analysis = NULL,
  current_week = NULL,
  execdata = NULL,
  final = NULL,
  fsimdata = NULL,
  fsimexp = NULL,
  fsimparam = NULL,
  interim = NULL,
  keepfiles = NULL,
  mcmc_num = NULL,
  noadapt = NULL,
  s2_aux_paramfile = NULL,
  stage = NULL,
  verbose = FALSE,
  version = NULL
)

Arguments

param_files: Character vector of file paths or the output of prep_param_files(). If a character vector, the elements can be directories containing *.param files or the paths to the *.param files themselves. Such a directory is returned by run_flfll().
n_sims: Positive integer, number of simulations per param file.
mode: Character scalar: "s" for simulation mode in non-enrichment designs, "" for simulation mode in enrichment designs, "r" for execution mode, and "p" for prediction mode. For the CRM engine, mode needs to be "s" or "".
seed: Positive integer, random number generator seed for the actual trial simulations. Use this seed argument instead of flfll_seed (run_facts(), run_flfll()) to control pseudo-randomness in the actual trial simulations. flfll_seed only controls how the *.param files are generated.
analysis_data: Character, analysis mode patient data file name.
analysis_mode: Logical, whether to activate analysis mode.
current_week: Numeric, current time in weeks.
execdata: Character, name of the execution mode patient file.
final: Logical, whether to do the final analysis. For execution mode only.
interim: Integer, interim number.
mcmc_num: Integer, MCMC file number. For analysis mode only.
verbose: Logical, whether to print progress information to the R console.
version: Character scalar, version of FACTS corresponding to the FACTS file. Get by calling get_facts_version() on your FACTS file. See possible versions with get_facts_versions(). Do not supply version to run_engine(). run_engine() detects the version automatically from the FACTS file and passes it to the appropriate engine function.
arm_selection: Logical, whether to activate arm selection.
armsdropped: Character, a comma-separated collection of integers indicating dropped arms.
complete_data_analysis: Logical, whether to do a complete data analysis.
fsimdata: Character, prediction mode patient data file name.
fsimexp: Logical. For expert use only.
fsimparam: Character, name of the prediction mode *.param file.
keepfiles: Logical, whether to deactivate cleanup of extraneous staged design files.
noadapt: Logical, whether to deactivate adaptive actions in prediction mode.
s2_aux_paramfile: Character, name of the stage 2 execution auxiliary *.param file.
stage: Integer, trial design stage. For staged designs only.
directory: Character, working directory. CRM only.
allocator: Logical, allocator/execution/recommender mode. CRM only.
charting_info: Logical, unused.
estimator: Logical, use estimator. CRM only.
force_cohort: Logical, whether to force small cohort run-in to end. CRM only.
reduced_priority: Logical, whether to run at reduced priority. CRM only.

Value

Nothing.

Details

If you need to repeatedly invoke an engine, as with most trial execution mode workflows, these engine functions may be slow on their own. To avoid the most severe sources of slowness, consider running prep_param_files() and then passing the result to one of the individual engine functions (such as run_engine_contin()).

Examples

facts_file <- get_facts_file_example("contin.facts")
# Can only run if system dependencies are configured:
if (file.exists(Sys.getenv("RFACTS_PATHS"))) {
out <- run_flfll(facts_file, verbose = FALSE) # Generate param files.
# Identify which engine you need.
get_facts_engine(facts_file)
# Run the sims with the engine function or `run_engine()`.
run_engine_contin(out, n_sims = 1, verbose = FALSE, version = "6.2.5")
read_patients(out)
}

Arguments

Value

Details

See also

Examples