extractExpDetails_mult: Extract experimental details for multiple files at once

In shirewoman2/Consultancy: Standardized tools for using R within the Simcyp Consultancy Team

Extract experimental details for multiple files at once

Description

extractExpDetails_mult takes a character vector of Simcyp Simulator output files – or all the Excel files in the current directory if no files are specified – and collects experimental details for the simulations into a single table. It optionally saves that table to a csv or Excel file. For detailed instructions and examples, please see the SharePoint file "Simcyp PBPKConsult R Files - Simcyp PBPKConsult R Files/SimcypConsultancy function examples and instructions/Checking simulation experimental details/Checking-simulation-experimental-details.docx". (Sorry, we are unable to include a link to it here.)

Usage

extractExpDetails_mult(
  sim_data_files = NA,
  exp_details = "all",
  existing_exp_details = NA,
  overwrite = FALSE,
  ...
)

Arguments

sim_data_files	a character vector of simulator output files, each in quotes and encapsulated with c(...), NA to extract experimental details for all the Excel files in the current folder, or "recursive" to extract experimental details for all the Excel files in the current folder and all subfolders. Example of acceptable input: sim_data_files = c("sim1.xlsx", "sim2.xlsx"). If some of your Excel files are not regular simulator output, e.g. they are sensitivity analyses or a file where you were doing some calculations, those files will be skipped. A note: There are just a few items that we will attempt to extract from the matching workspace file; for that information, we will look for a workspace file that is named identically to the Excel file except for the file extension. It will ignore the date/time stamp that the autorunner adds as long as that stamp is in a format like this: "myfile - 2023-10-31 07-23-15.xlsx".
exp_details	experimental details you want to extract from the simulator output files using the function extractExpDetails. Options are "Summary tab" Extract details only from the "Summary tab" "Input Sheet" Extract details only from the "Input Sheet" tab "population tab" Extract details about the population used (data come from the tab with the same name as the population simulated) "Simcyp inputs" Extract all the details that you normally fill out on the "Simcyp inputs (and QC)" tab of a compound data sheet plus trial design information "workspace" Extract a limited set of details directly from the Simcyp Simulator workspace files. The set of possible details may be viewed by entering view(AllWorkspaceDetails) in the console. This only works when each workspace file name perfectly matches its corresponding Excel results file name and is located in the same folder. Otherwise, this step in the data extraction will be skipped. "all" Extract all possible parameters (default). This is the slowest option in terms of processing time because it must read multiple Excel tabs. Note: While information about custom dosing regimens can be extracted by the function extractExpDetails, that information cannot easily be made to fit with the rest of the output for extractExpDetails_mult. That's because each simulator file and compound with a custom-dosing regimen will have its own data.frame with the time, time units, dose number, dose amount, dose units, and dose route. For that reason, custom-dosing information will largely be ignored here.
existing_exp_details	(optional) a data.frame that contains previously extracted experimental details. If this object does exist, it should NOT be in quotes, e.g. existing_exp_details = MyDeets. Because we can see scenarios where you might want to extract some experimental details and then run more simulations for comparisons, this function will add data to that data.frame. It will not overwrite existing data unless overwrite is set to TRUE.
overwrite	TRUE or FALSE (default) on whether to re-extract the experimental details from output files that are already included in existing_exp_details. Since pulling data from Excel files is slow, by default, this will not overwrite existing data and instead will only add data from any Excel files that aren't already included. A situation where you might want to set this to TRUE would be when you have changed input parameters for simulations and re-run them OR when you have extracted only some of the possible experimental details and you now would like more experimental details from each simulator output file.

Value

Returns a data.frame of experimental details for simulator files

Examples

extractExpDetails_mult(
    sim_data_files =
        c("Example simulator output - SD MDZ + MD RTV.xlsx",
          "Example simulator output - MDZ + metabolites.xlsx",
          "Example simulator output - met1 met2 sec met1 inhib1.xlsx",
          "Example simulator output - met1 met2 sec met1.xlsx"),
    exp_details = "all")
 

shirewoman2/Consultancy documentation built on Feb. 18, 2025, 10 p.m.