make_simulation_directory: Make a directory of simulations indicating which simulation...

View source: R/make_simulation_directory.R

make_simulation_directoryR Documentation

Make a directory of simulations indicating which simulation files are present in a given folder and which XML observed overlay files were associated with those simulation files

Description

The function make_simulation_directory will create a data.frame of simulations in a given project folder, the associated XML files when applicable (you'll have to provide that information with the argument existing_exp_details or else ask this function to read all the workspace files to find them), and, optionally, save that data.frame to an Excel file. It will also check whether the file names comply with USFDA and Consultancy Team standards and check whether the same simulation is saved in more than one place.

This is wicked fast.*

*Caveat: Unless you search all the workspaces for XML observed overlay data files. Then it takes about 2 seconds per simulation.

Usage

make_simulation_directory(
  project_folder = NA,
  sim_data_files = "recursive",
  existing_exp_details = NA,
  search_workspaces_for_obsfile = FALSE,
  include_possible_obsfiles = TRUE,
  obsfile_path_option = "full path",
  report_progress = "no",
  save_table = NA,
  overwrite = "ask"
)

Arguments

project_folder

location of the project folder to search. Please note that R requires forward slashes ("/") in file paths rather than the back slashes Microsoft uses. If left as NA (default), we'll assume your current working directory is the top level of your project folders.

sim_data_files

which files to include in the directory of simulations. This only applies when you don't supply anything for the argument existing_exp_details. Options are:

"recursive" (default)

all .xlsx, .db, or .wksz files in the current folder and any subfolders

NA

all .xlsx, .db, or .wksz files in the current folder

a single text string such as "dev"

include any files in the current folder or any folders below it that have that specific text

a character vector of specific file names, e.g., sim_data_files = c("abc.xlsx", "def.xlsx")

only include the files listed. We'll figure out which folder they're in.

existing_exp_details

optionally supply the output from running extractExpDetails_mult to get only the simulation files included there in your simulation directory. If you supply something here, whatever you supply for sim_data_files will be ignored. This will also be used to figure out which XML files go with which simulations.

search_workspaces_for_obsfile

TRUE or FALSE (default) for whether to search through any workspace files and check for possible XML overlay files. This runs considerably slower when set to TRUE and will take about an additional 2 seconds per simulation. If you have supplied something for 'existing_exp_details', you don't need this and we'll ignore it if you set this to TRUE.

obsfile_path_option

How would you like to see the observed overlay XML file path? Options are:

"full path" (default, "full" also works)

Show the entire path to the XML observed overlay file

"basename"

Only show the file name (the basename) of the XML overlay file and NOT any of the path. Why would you want this? Say you've moved all your XML observed overlay files from their original locations when you ran the simulations into a new folder that you'll be sharing with the client at the end of the project. This way, you can show which simulation had which XML observed overlay file without the confusion of including the original path.

"relative"

Show the path relative to the project folder

report_progress

"yes", "no" (default), or "some" for whether to report progress on reading workspaces to find observed XML overlay files. This only applies when you have set search_workspaces_for_obsfile to TRUE. Setting this to "yes" will report a message in the console for each workspace as it is read. Setting this to "some" will report a message saying when it has started and when it has finished reading workspaces, and setting this to "no" will give no progress messages.

save_table

optionally specify an Excel file name for saving your simulation directory. If you don't include the file extension ".xlsx", we'll add it.

overwrite

Should we overwrite if your Excel file already exists and already has a tab named "Simulation directory"? Options are "yes" to always overwrite, "no" to never overwrite, or "ask" (default), which means that we will ask you whether to overwrite and give you a chance to supply a different file name if the one you supplied already exists.

Value

a data.frame of simulation files and their respective file paths

Examples

# none yet

shirewoman2/Consultancy documentation built on June 1, 2025, 6:05 p.m.