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.
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)Character vector of file paths. Either the directories containing the trial simulation results or the actual CSV file files themselves.
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().
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.
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().
# 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)
}