facts_results {rfacts}

Read trial simulation results

Description

These functions read trial simulation results. The results were computed by FACTS (via run_facts() or run_engine() or one of the engine functions such as run_engine_contin()) and are stored in CSV files. Different functions read different types of output. The functions are named according to the CSV files they read. For example, read_patients() reads all files named patients00001.csv, patients00002.csv, etc. The most important functions are read_patients() and read_weeks(). The ⁠read_s1*()⁠, ⁠read_s2*()⁠, and ⁠read_master*()⁠ functions are for staged designs. The read_csv_special() function allows you to supply a custom file name prefix such as "patients", but be warned: not every kind of CSV output file is tested in rfacts.

Usage

read_patients(csv_files)

read_weeks(csv_files)

read_mcmc(csv_files)

read_s1_mcmc(csv_files)

read_s1_weeks(csv_files)

read_s1_patients(csv_files)

read_s2_patients(csv_files)

read_s2_weeks(csv_files)

read_s2_mcmc(csv_files)

read_master_mcmc(csv_files)

read_master_patients(csv_files)

read_master_weeks(csv_files)

read_cohorts(csv_files)

read_simulations(csv_files)

read_csv_special(csv_files, prefix, numbered = TRUE)

Arguments

csv_files

Character vector of file paths. Either the directories containing the trial simulation results or the actual CSV file files themselves.

prefix

Character, name of the prefix for read_csv_special(). read_weeks(x) is equivalent to read_csv_special(x, prefix = "weeks"). Be careful: not all kinds of CSV output are tested. We can only guarantee the file types with special functions will be read correctly, e.g. read_patients() and read_weeks().

numbered

Logical. If TRUE, only read the numbered files like patients00001.csv, weeks00017.csv, etc. If FALSE, only list the non-numbered files like simulations.csv and simulations_freq_locf.csv. Avoid summary.csv files. They are not reliable on Linux.

Value

A data frame of trial simulation data. Each ⁠read_*()⁠ function returns different information, but all the ⁠read_*()⁠ functions support the following columns:

• facts_file: character, the base name of the FACTS file.

• facts_scenario: character, the name of the simulation scenario from FACTS. Usually, this factors in the virtual subject response (VSR) profile, accrual profile (how fast do patients enroll?) and dropout profile (how fast do they drop out?).

• facts_sim: integer, numeric index of the CSV file name. For example, the facts_sim of patients00012.csv is 12. In trial execution mode, all these indices are 00000, so facts_id is much safer than facts_sim for packetized trial execution mode.

• facts_id: character, random unique id of each CSV file being read. Different for every call to read_patients() etc. Safer than facts_sim for aggregation over simulations.

• facts_output: character, type of output is in the data frame: "patients" for patients files, "weeks" for weeks files, "mcmc" for MCMC files, etc. These names adhere to established conventions in FACTS.

• facts_csv: character, full path to the original CSV files where FACTS stored the simulation output. Required for overwrite_csv_files().

• facts_header: a character vector of ⁠\n⁠-delimited CSV file headers. Required for overwrite_csv_files().

See Also

get_facts_file_example(), run_facts(), run_flfll(), run_engine()

Examples

# Can only run if system dependencies are configured:
if (file.exists(Sys.getenv("RFACTS_PATHS"))) {
facts_file <- get_facts_file_example("contin.facts")
out <- run_facts(
  facts_file,
  n_sims = 4,
  verbose = FALSE
)
# What results files do we have?
head(get_csv_files(out))
# Read all the "patients*.csv" files with `read_patients(out)`.
# For each scenario, we have files named
# patients00001.csv, patients00002.csv, patients00003.csv,
# and patients00004.csv.
read_patients(out)
}