Help for package PKPDindex

Title:

Optimal PK/PD Index Finder

Version:

0.2.0

Description:

Fits Emax models to pharmacokinetic/pharmacodynamic (PK/PD) data, estimate key parameters, and visualise model fits for multiple PK/PD indices. Methods are described in Macdougall J (2006) <doi:10.1007/0-387-33706-7_9>, Spiess AN, Neumeyer N (2010) <doi:10.1186/1471-2210-10-6>, and Burnham KP, Anderson DR (2004) <doi:10.1177/0049124104268644>.

License:

GPL (≥ 3)

Encoding:

UTF-8

RoxygenNote:

7.3.2

Depends:

R (≥ 3.5)

LazyData:

true

NeedsCompilation:

Packaged:

2025-10-06 00:31:58 UTC; najla

Author:

Najla Alabdulkarim [aut, cre], Joseph F Standing [aut]

Maintainer:

Najla Alabdulkarim <naaalabdulkarim@hotmail.com>

Repository:

CRAN

Date/Publication:

2025-10-09 07:40:07 UTC

PKPDindex: Optimal PK/PD Index Finder

Description

This function fits various Emax models to a given dataset, allowing for flexibility in model selection, initial parameter estimates, and plotting options.

Usage

PKPDindex(
  dataset,
  x_columns = NULL,
  y_column = "response",
  E0_fix,
  Emax_fix,
  EC50_init = NULL,
  maxiter = 500,
  tol = 1e-05,
  minFactor = 1e-07,
  select_mod = NULL,
  plot_results = FALSE,
  srow = FALSE,
  xlim = NULL,
  ylim = NULL,
  point_color = NULL,
  line_color = NULL,
  x_label = NULL,
  y_label = NULL,
  plot_title = NULL,
  log_scale_x = NULL,
  title_cex = 1.2,
  label_cex = 1,
  axis_cex = 1,
  detail_cex = 1
)

Arguments

dataset

A data frame containing the independent (x) and dependent (y) variables.

x_columns

A character vector specifying the x-axis variables (PK/PD indices). If NULL (default), the function attempts to detect appropriate columns from the dataset, specifically "auc_mic", "cmax_mic", and "t_mic". If these are not found, the user must specify the names manually.

"auc_mic": area under the concentration-time curve divided by the MIC.
"cmax_mic": peak drug concentration divided by the MIC.
"t_mic": time above MIC (duration the drug concentration exceeds MIC). Users should calculate these indices based on their PK data before using this function.

y_column

A character string specifying the response variable. Default name is "response".The response should be the log10-transformed change in CFU/ml (Delta log10 CFU/ml). Users can either provide a column with pre-calculated log10 CFU/ml changes, or provide raw CFU/ml counts at the initial (CFU_init) and 24-hour timepoint (CFU_24) , and the function will automatically calculate the log10 change in CFU/ml (Delta log10 CFU/ml).

E0_fix

Fixed E0 (baseline effect) value.

Emax_fix

Fixed Emax (maximum effect) value.

EC50_init

Optional numeric vector specifying initial EC50 values for each x_column. Defaults to NULL, and values are estimated automatically.

maxiter

Maximum number of iterations - Specifies the maximum number of iterations allowed for the nonlinear least squares (NLS) fitting process. Higher values may help convergence for complex models. Default maxiter = 500.

tol

Tolerance level - Defines the tolerance for convergence in the NLS algorithm. Lower values indicate stricter convergence criteria. Default tol = 1e-5.

minFactor

Minimum step factor - Determines the smallest step size used in parameter updates during the NLS fitting process, controlling the precision of optimisation. Default minFactor = 1e-7.

select_mod

Optional named list specifying preferred models for each x_column.

plot_results

Logical; if TRUE, the function generates model fit plots.

srow

Single row plotting - Logical (TRUE or FALSE). If TRUE, plots all best model fits in a single row for visual comparison.

xlim

A numeric vector of length 2 specifying x-axis limits.

ylim

A numeric vector of length 2 specifying y-axis limits.

point_color

Optional character string specifying the point colour in plots.

line_color

Optional character string specifying the line colour in plots.

x_label

Optional named list specifying custom x-axis labels.

y_label

Optional character string specifying a custom y-axis label.

plot_title

Optional character string specifying a custom plot title.

log_scale_x

Optional named list specifying whether to apply log10 scaling to x-axis for each x_column.

title_cex

Size of the plot title text. Default title_cex = 1.2.

label_cex

Size of the axis title. Default label_cex = 1.0.

axis_cex

Size of the axis labels. Default axis_cex = 1.0.

detail_cex

Size of the model detail text on the plot. Default detail_cex = 1.0.

Details

The function fits different variations of the Emax model to describe the relationship between PK/PD indices and response. The available models (m1 to m8) are defined as follows:

m1: Fixed E0 and Emax, no Hill coefficient.
m2: Fixed E0 and Emax, with Hill coefficient (gam).
m3: Fixed E0, estimated Emax, no Hill coefficient.
m4: Fixed E0, estimated Emax, with Hill coefficient.
m5: Estimated E0, fixed Emax, no Hill coefficient.
m6: Estimated E0, fixed Emax, with Hill coefficient.
m7: Estimated E0 and Emax, no Hill coefficient.
m8: Fully estimated model (E0, Emax, EC50, and gam).

Users can select specific models using the select_mod argument.

Value

A list containing:

All_Model_Results: A data frame with results from all fitted models.
Best_Models: A data frame with the best model (lowest AIC) for each PK/PD index.
Plots: A list of recorded plots (if plot_results = TRUE).

Examples

# Basic usage with default settings
 output <- PKPDindex(
  dataset = PKPDindex_data,
  E0_fix = 1.5,
  Emax_fix = 4.8
)
# Custom x and y columns and initial data
 output <- PKPDindex(
  dataset = PKPDindex_data,
  E0_fix = 1.5,
  Emax_fix = 4.8,
  x_columns = c("auc_mic","cmax_mic","t_mic"),
  y_column = "response",
  EC50_init = c(1,1,1)
)

# Generate and custom plots
 output <- PKPDindex(
  dataset = PKPDindex_data,
  E0_fix = 1.5,
  Emax_fix = 4.8,
  plot_results = TRUE,
  srow=TRUE,
  xlim = c(0, 50),
  ylim = c(-2, 10),
  point_color = "green",
  line_color = "purple",
  select_mod = list(auc_mic = "m5", t_mic = "m1"),
  x_label = list(auc_mic = "AUC/MIC", cmax_mic = "Cmax/MIC", t_mic = "Time>MIC"),
  y_label = "Log10 Change in CFU",
  plot_title = "Model Fitting Results",
  log_scale_x = list(auc_mic = TRUE, cmax_mic = TRUE,t_mic=FALSE),
  title_cex = 2,
  label_cex = 1.5,
  axis_cex = 1.4,
  detail_cex = 1.3
)

#' # To view the best models:
output$Best_Models

# To view all model results:
output$All_Model_Results

# To access a specific plot:
output$Plots[["cmax_mic"]]

PKPDindex_data

Description

Example dataset for Emax model fitting.

Usage

PKPDindex_data

Format

A data frame with 20 rows and 4 columns:

auc_mic: Area under the concentration-time curve (numeric)
cmax_mic: Maximum concentration of the drug (numeric)
t_mic: Time above minimum inhibitory concentration (numeric)
response: Observed drug response (numeric; Delta log10 CFU/ml)

Details

This dataset contains information about drug concentrations (AUC/MIC, Cmax/MIC, and Time above MIC) and their corresponding response values, used for modelling the drug's effect based on the Emax model.

Source

Generated for package example purposes.

Examples

data(PKPDindex_data)