inductFit: Fit induction data to calculate EC50, Emax, and/or slope

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

Fit induction data to calculate EC50, Emax, and/or slope

Description

inductFit fits induction data – either activity or mRNA expression – to one or all of four models for calculating Indmax or Emax, EC50, and, when appropriate, a slope. Two important notes:

• With the exception of the sigmoidal 3-parameter model, the fitted parameter describing maximal induction is Emax and not Indmax, the parameter used in the Simcyp Simulator. Note that Indmax = Emax + 1.

• If you're familiar with Howie's R script for fitting induction data ("Induction_fit_script_ver2.r"), one way in which this function differs is that the default setting includes no upper or lower bounds for parameter estimates. This means that, if sufficient data to describe the curve do not exist, the function will fail to deliver any fitted parameters, which is meant to be a benefit but could be an annoyance depending on your perspective. If you would like this function to behave more like Howie's script, please look at the help file for the arguments bounds_Emax, bounds_EC50, and bounds_slope.

For detailed instructions and examples, please see the SharePoint file "Simcyp PBPKConsult R Files - Simcyp PBPKConsult R Files/SimcypConsultancy function examples and instructions/Fitting induction data/Fitting-induction-data.docx". (Sorry, we are unable to include a link to it here.)

Usage

inductFit(
  DF,
  conc_column = Concentration_uM,
  fold_change_column = FoldInduction,
  donor_column = DonorID,
  fitByDonor = TRUE,
  model = "all",
  graph_mean_of_fits = FALSE,
  measurement = "mRNA",
  enzyme = "CYP3A4",
  drug = NA,
  weights = "1/y^2",
  bounds_Emax = NA,
  bounds_EC50 = NA,
  bounds_slope = NA,
  bounds_gamma = NA,
  omit = NA,
  color_set = "default",
  y_axis_limits = NA,
  y_axis_label = NA,
  hline_foldinduct1 = FALSE,
  vert_line = NA,
  Imaxu_line = NA,
  rounding = NA,
  include_fit_stats = TRUE,
  graph_title = NA,
  graph_title_size = 14,
  save_graph = NA,
  save_table = NA,
  page_orientation = "portrait",
  fig_height = 5,
  fig_width = 5.5,
  save_output = NA
)

Arguments

DF	the data.frame containing induction data with a column for the drug concentration, a column for the fold induction observed, and, if you want to fit the data by individual, a column for the donor ID. For an example, please run view(IndData).
conc_column	the name of the column within DF that contains concentration data. This should be unquoted.
fold_change_column	the name of the column within DF that contains fold-change data, e.g., mRNA measurements or activity. This should be unquoted.
donor_column	the name of the column within DF that contains the donor IDs, unquoted
fitByDonor	TRUE (default) or FALSE for whether to fit the data by individual donor
model	which model(s) you would like to use. The four model options are: "Emax" the Emax model. This assumes a hyperbolic shape to the interaction when inducer concentration is plotted on the x axis and fold induction is plotted on the y. fold induction = 1 + (Emax * I)/(EC50 + I) where I is the inducer concentration, and Emax (the maximum induction), and EC50 (the inducer concentration at 1/2 Emax) are the fitted parameters. "EmaxSlope" the Emax model with the addition of a slope n fold induction = 1 + Emax * I^n / (EC50^n + I^n) "slope" slope only: fold induction = 1 + I * n "Sig3Param" Sigmoidal 3-parameter model (often used by Xenotech): fold induction = Indmax / (1 + exp( -(I - IndC50)/n )) SPECIAL NOTE: The sigmoidal 3-parameter model is the only model that determines Indmax instead of Emax! "all" (default) All 4 models will be fitted to the data.
graph_mean_of_fits	TRUE or FALSE (default) for whether to graph a line representing the mean of all donors' fitted parameters. Please note that this is NOT line showing the model fitted to the mean data; instead, this is the mean of all the donors individually fitted parameters. This only applies when fitByDonor = TRUE. If graph_mean_of_fits = FALSE, graph will show a line for each donor's fitted parameters.
measurement	the type of measurement used. Options are "mRNA" or "activity". This only affects the y axis labels on the output graph(s).
enzyme	the enzyme involved. Default is "CYP3A4" but can be set to NA to leave as unspecified. This only affects the figure and table headings and captions in the Word document output.
drug	the drug used in the incubations. Default is NA to leave this unspecified, but supplying a value will include the drug name in the x-axis label on the graphs as well as the figure and table headings and captions in the Word document output.
weights	weighting scheme to use for the regression. User may supply a numeric vector of weights to use or choose from "none", "1/x", "1/x^2", "1/y" or "1/y^2" (default). Be careful that you don't have any infinite values or this will fail!
bounds_Emax	lower and upper boundaries for fitting Indmax or Emax, specified as a vector of numbers, e.g., c(1, 20); default is no boundaries. If you only want to specify an upper limit, set the first number to -Inf and the second number to that value. If you only want to specify a lower limit, set the first number to that value and the second number to Inf.
bounds_EC50	lower and upper boundaries for fitting IndC50 or EC50, specified as a vector of numbers, e.g., c(1, 20); default is no boundaries. If you only want to specify an upper limit, set the first number to -Inf and the second number to that value. If you only want to specify a lower limit, set the first number to that value and the second number to Inf.
bounds_slope	lower and upper boundaries for fitting the slope, specified as a vector of numbers, e.g., c(1, 20); default is no boundaries. If you only want to specify an upper limit, set the first number to -Inf and the second number to that value. If you only want to specify a lower limit, set the first number to that value and the second number to Inf.
bounds_gamma	lower and upper boundaries for fitting the Hill coefficient gamma, specified as a vector of numbers, e.g., c(1, 20); default is no boundaries. If you only want to specify an upper limit, set the first number to -Inf and the second number to that value. If you only want to specify a lower limit, set the first number to that value and the second number to Inf.
omit	An index of which, if any, samples to omit from regression(s). These samples will be depicted as open circles in the graph but will not be included in the regression. An example of acceptable input where, say, you want to omit samples where the concentration was greater than 100 uM but still want to see those points on the graph(s): omit = which(DF$Concentration > 100)
color_set	the set of colors to use. Options: "default" a set of colors from Cynthia Brewer et al. from Penn State that are friendly to those with red-green colorblindness. The first three colors are green, orange, and purple. This can also be referred to as "Brewer set 2". "Brewer set 1" colors selected from the Brewer palette "set 1". The first three colors are red, blue, and green. "ggplot2 default" the default set of colors used in ggplot2 graphs (ggplot2 is an R package for graphing.) "rainbow" colors selected from a rainbow palette. The default palette is limited to something like 6 colors, so if you have more than that, that's when this palette is most useful. It's not very useful when you only need a couple of colors. "blue-green" a set of blues fading into greens. This palette can be especially useful if you are comparing a systematic change in some continuous variable – for example, increasing dose or predicting how a change in intrinsic solubility will affect concentration-time profiles – because the direction of the trend will be clear. "blues" a set of blues fading light blue to dark blue. Like "blue-green", this palette can be especially useful if you are comparing a systematic change in some continuous variable. "Tableau" uses the standard Tableau palette; requires the "ggthemes" package "viridis" from the eponymous package by Simon Garnier and ranges colors from purple to blue to green to yellow in a manner that is "printer-friendly, perceptually uniform and easy to read by those with colorblindness", according to the package author
y_axis_limits	optionally set the Y axis limits, e.g., c(1, 5). If left as NA, the Y axis limits will be automatically selected. (Reminder: Numeric data should not be in quotes.)
y_axis_label	optionally supply a character vector or an expression to use for the y axis label
hline_foldinduct1	TRUE or FALSE (default) on whether to include a dotted red line where the fold induction = 1.
vert_line	optionally include a vertical dotted red line at some concentration. Use a numeric value for the concentration you want or leave as NA (default) for no vertical line.
Imaxu_line	optionally specify a value for 30*Imax,u (see p. 5 USFDA Guidance (2020) "In Vitro Drug Interaction Studies - Cytochrome P450 Enzyme and Transporter Mediated Drug Interactions") and this will create red dotted line that goes down from the top of the graph at that concentration and then across to the y axis at the 2-fold change level. Points within that upper left corner are a potential concern for induction. Use a numeric value for the concentration you want or leave as NA (default) for no line.
rounding	option for what rounding to perform, if any. Options are: NA or "Consultancy" All output will be rounded according to Simcyp Consultancy Team standards: to three significant figures when the value is < 100 or to the ones place if the value is >= 100. Please see the function round_consultancy, which does the rounding here. "none" No rounding will be performed. "significant X" where "X" is a number Output will be rounded to X significant figures. rounding = "signif X" also works fine. "round X" where "X" is a number Output will be rounded to X digits "Consultancy" round according to the Simcyp Consultancy report template: 3 significant figures if less than 100 and otherwise, round to the nearest integer "Word only" Output saved to Word file will be rounded using the function round_consultancy, but nothing will be rounded in the csv file if you supply a file name for save_table or in the output R object. This can be useful when you want to have nicely rounded and formatted output in a Word file while keeping all the decimal places elsewhere
include_fit_stats	TRUE (default) or FALSE for whether to include statistics describing the goodness of fit: the standard error (SE), the p value, and the Akaike information criterion (AIC). These values come from the nonlinear regression of the various models to the data.
graph_title	optionally specify a title that will be centered across your graph or set of graphs
graph_title_size	the font size for the graph title if it's included; default is 14. This also determines the font size of the graph labels.
save_graph	optionally save the output graph by supplying a file name in quotes here, e.g., "My induction graph.png". If you leave off ".png", it will be saved as a png file, but if you specify a different file extension, it will be saved as that file format. Acceptable extensions are "eps", "ps", "jpeg", "jpg", "tiff", "png", "bmp", or "svg". Do not include any slashes, dollar signs, or periods in the file name. If you only want to save the table of fitted parameters, please use the argument save_table. If you want to save a Word document with all the results, please use the argument save_output.
save_table	optionally save the table of fitted parameters by supplying a file name in quotes here, e.g., "My fitted induction parameters.csv". Saving as an xlsx file is also supported. Do not include any slashes, dollar signs, or periods in the file name. If you only want to save the graphs, please use the argument save_graph. If you want to save a Word document with all the results, please use the argument save_output.
page_orientation	set the page orientation for the Word file output to "portrait" (default) or "landscape"
fig_height	figure height in inches; default is 5
fig_width	figure width in inches; default is 5.5
save_output	optionally save a) the equations used for fitting, b) the fitted parameters, and c) the graphs by supplying a file name in quotes here, e.g., "My induction results.docx". Do not include any slashes, dollar signs, or periods in the file name. If you only want to save the graphs, please use the argument save_graph. If you only want to save the table of fitted parameters, please use the argument save_table.

Value

Returns a list of

Fit

the fitted parameters

Fit_means

the mean fitted parameters for all donors

Graph

a graph or set of graphs of the data with the fitted parameters depicted as lines

Curve

a data.frame of numeric data used to graph the fitted parameters in case you'd like to plot the fitted parameters in some other way

Examples

# IndData is a data.frame of example induction data included with the package.

inductFit(IndData, model = "Emax")$Graph
inductFit(IndData %>% rename(Conc_uM = Concentration_uM),
          conc_column = Conc_uM, model = "EmaxSlope")$Graph
inductFit(IndData, model = "slope")$Graph
inductFit(IndData, model = "Sig3Param")

inductFit(IndData, model = "EmaxSlope", measurement = "activity")

MyFit <- inductFit(IndData, model = "all")
MyFit$Graph; MyFit$Fit

MyFit <- inductFit(IndData, model = "Sig3Param", fitByDonor = TRUE, donor_column = DonorID)
MyFit$Fit; MyFit$Fit_means; MyFit$Graph

MyFit <- inductFit(IndData, model = "all", fitByDonor = TRUE, donor_column = DonorID)
MyFit$Fit; MyFit$Fit_means; MyFit$Graph

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