extractConcTime: Extract concentration-time data from a simulator output Excel...

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

Extract concentration-time data from a simulator output Excel file

Description

Extracts concentration-time data from simulator output Excel files and, optionally, a separately specified observed data file, and puts all data into a single, tidy data.frame. There are some nuances to how it deals with observed data; please see the details at the bottom of this help file. Not all substrate metabolites, inhibitors, or inhibitor metabolites are available in all tissues. If it's not present in your Excel output, we can't extract it here. For detailed instructions and examples, please see the SharePoint file "Simcyp PBPKConsult R Files - Simcyp PBPKConsult R Files/SimcypConsultancy function examples and instructions/Concentration-time plots 1 - one sim at a time/Concentration-time-plot-examples-1.docx". (Sorry, we are unable to include a link to it here.)

Usage

extractConcTime(
  sim_data_file,
  obs_data_file = NA,
  tissue = "plasma",
  compoundToExtract = "substrate",
  returnAggregateOrIndiv = "both",
  adjust_obs_time = FALSE,
  existing_exp_details = NA,
  fromMultFunction = FALSE
)

Arguments

sim_data_file	name of the Excel file containing the simulated concentration-time data, in quotes; must be an output file from the Simcyp simulator
obs_data_file	name of the Excel file containing the observed concentration-time data for the substrate or metabolite you're extracting, in quotes. If the observed data you want to plot were already included in the Excel output from the simulator, leave this as NA. Otherwise, this is the file that it is ready to be converted to an XML file, not the file that contains only the digitized time and concentration data.
tissue	From which tissue should the desired concentrations be extracted? Default is plasma for typical plasma concentration-time data. Other options are "blood" or any tissues included in "Sheet Options", "Tissues" in the simulator. All possible options: First-order absorption models "plasma", "blood", "unbound blood", "unbound plasma", "additional organ", "adipose", "bone", "brain", "feto-placenta", "gut tissue", "heart", "kidney", "liver", "lung", "muscle", "pancreas", "peripheral blood", "peripheral plasma", "peripheral unbound blood", "peripheral unbound plasma", "portal vein blood", "portal vein plasma", "portal vein unbound blood", "portal vein unbound plasma", "skin", or "spleen". ADAM-models "stomach", "duodenum", "jejunum I", "jejunum II", "jejunum III" (only applies to rodents), "jejunum IV" (only applies to rodents), "ileum I", "ileum II", "ileum III", "ileum IV", "colon", "faeces", "gut tissue", "cumulative absorption", "cumulative fraction released", or "cumulative dissolution". ADC simulations NOT YET SET UP. If you need this, please contact Laura Shireman. Not case sensitive.
compoundToExtract	For which compound do you want to extract concentration-time data? Options are: "substrate" (default), "primary metabolite 1", "primary metabolite 2", "secondary metabolite", "inhibitor 1" – this can be an inducer, inhibitor, activator, or suppresesor, but it's labeled as "Inhibitor 1" in the simulator, "inhibitor 2" for the 2nd inhibitor listed in the simulation, "inhibitor 1 metabolite" for the primary metabolite of inhibitor 1 "conjugated protein" for DAR1-DARmax for an antibody-drug conjugate; observed data with DV listed as "Conjugated Protein Plasma Total" will match these simulated data, "total protein" for DAR0-DARmax for an ADC; observed data with DV listed as "Total Protein Conjugate Plasma Total" will match these simulated data, "released payload" for the released drug from an ADC, which shows up as primary metabolite 1 in Simulator output files. Note: If your compound is a therapeutic protein or ADC, we haven't tested this very thoroughly, so please be extra careful to check that you're getting the correct data.
returnAggregateOrIndiv	Return aggregate and/or individual simulated concentration-time data? Options are "aggregate", "individual", or "both" (default). Aggregated data are not calculated here but are pulled from the simulator output rows labeled as "Population Statistics".
adjust_obs_time	TRUE or FALSE (default) for whether to adjust the time listed in the observed data file to match the last dose administered. This only applies to multiple-dosing regimens. If TRUE, the graph will show the observed data overlaid with the simulated data such that the dose in the observed data was administered at the same time as the last dose in the simulated data. If FALSE, the observed data will start at whatever times are listed in the Excel file.
existing_exp_details	If you have already run extractExpDetails_mult or extractExpDetails to get all the details from the "Input Sheet" (e.g., when you ran extractExpDetails you said exp_details = "Input Sheet" or exp_details = "all"), you can save some processing time by supplying that object here, unquoted. If left as NA, this function will run extractExpDetails behind the scenes to figure out some information about your experimental set up.
fromMultFunction	INTERNAL USE ONLY. TRUE or FALSE on whether this is being called on by extractConcTime_mult.

Details

A note on observed data: When observed data are included in a simulator output file, because the simulator output does not explicitly say whether those observed data were in the presence of an inhibitor or perpetrator, this function cannot tell the difference and will thus assume all observed data included in the simulator output were for the substrate in the absence of any perpetrator. It will further assume that the compound – substrate or inhibitor 1 or primary metabolite 1 or whatever – is the same as compoundToExtract. If compoundToExtract was an inhibitor or inhibitor metabolite, the observed data from the simulator output will NOT be pulled since it is unlikely to be inhibitor concentrations.

For best results, we recommend supplying an observed data file here, which contains more information, to make sure the data are what you're expecting.

Value

A data.frame of concentration-time data with the following columns:

Compound

the compound whose concentration is listed; this matches whatever you named your substrate or inhibitor in the simulator

CompoundID

the generic name of the compound: "substrate", "inhibitor 1", "primary metabolite 1", etc.

Inhibitor (as applicable)

the inhibitor(s) or perpetrator(s) of interest; this matches whatever you named "Inhibitor 1", "Inhibitor 2", or "Inhibitor 1 metabolite" in the simulator and will be a concatenation of all the perpetrators present

Tissue

the tissue

Individual

the individual for the given profile, which will be a number for a simulated individual or will be "obs" or "obs+inhibitor" for observed data, "mean" for the mean data, "geomean" for the geometric mean data, or "per5" or "per95" for the 5th and 95th percentile data.

Trial

the trial number for that set of simulations or "obs", "mean", etc. for the observed or aggregate data

Simulated

TRUE or FALSE for whether the data were simulated

Time

the time since the first dose

Conc

concentration of the compound listed

Time_units

units used for time

Conc_units

units used for concentrations

,

Tissue_subtype

the subtype of tissue, which only applies in special situations, mainly ADAM-model tissues and brain-compartment tissues. Examples of ADAM-model tissues you can get: "undissolved compound", "free compound in lumen", "Heff", "absorption rate", "unreleased compound in faeces", "dissolved compound", "luminal CLint", "cumulative fraction of compound dissolved", "cumulative fraction of compound released", "cumulative fraction of compound absorbed". Examples of brain-compartment tissues you can get: "cranial CSF", "total brain", "spinal CSF", "Kp,uu,brain". This column was formerly named "subsection_ADAM" but now includes non-ADAM-model tissues.

Dose_num

the dose number

Dose_int

the dosing interval. This will be NA for custom-dosing regimens.

File

the simulator output Excel file that was used as the source for these data

Examples

extractConcTime(sim_data_file = "../Example simulator output MD.xlsx")

extractConcTime(sim_data_file = "../Example simulator output MD.xlsx",
                returnAggregateOrIndiv = "individual")

extractConcTime(sim_data_file = "../Example simulator output MD.xlsx",
                obs_data_file = "../fig1-242-06-001-MD - for XML conversion.xlsx")

extractConcTime(sim_data_file = "../Example simulator output MD + inhibitor.xlsx",
                returnAggregateOrIndiv = c("aggregate", "individual"))

extractConcTime(sim_data_file = "../Example simulator output MD + inhibitor.xlsx",
                obs_data_file = "../fig1-242-06-001-MD - for XML conversion.xlsx",
                returnAggregateOrIndiv = c("aggregate", "individual"))

extractConcTime(sim_data_file = "../Example simulator output MD + inhibitor.xlsx",
                tissue = "lung")

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