facts_engines {rfacts}

Engine-specific trial simulation functions

Description

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.

Usage

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.

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()).

Value

Nothing.

See Also

run_engine(), get_facts_file_example(), get_facts_engine(), run_facts(), run_flfll().

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)
}