addCovariate: Add covariate to model object

In Certara.RsNLME: Pharmacometric Modeling

Add covariate to model object

Description

Add a continuous, categorical, or occasion covariate to model object and set covariate effect on structural parameters.

Usage

addCovariate(
  .Object,
  covariate,
  effect = NULL,
  type = c("Continuous", "Categorical", "Occasion"),
  direction = c("Forward", "Interpolate", "Backward"),
  option = c("Yes", "PlusOne", "No"),
  center = NULL,
  centerValue = NULL,
  levels = NULL,
  labels = NULL,
  isDiagonal = TRUE,
  values = NULL,
  isPositive = TRUE
)

Arguments

.Object	Model object
covariate	Name of covariate. If the involved model has columns mapped (i.e. model with columnMap = TRUE) use named character if the name of the covariate is different from the corresponding column in the input dataset, for example, covariate = c(BW = "BodyWeight"), where BW denotes the name of the covariate, and "BodyWeight" is the name of the corresponding column in the input dataset.
effect	Name of structural parameter(s) on which the covariate has an effect. Specify effect as character or character vector if the covariate has an effect on multiple structural parameters.
type	Type of covariate. Options are "Continuous", "Categorical", "Occasion".
direction	Direction of missing values propagation (if no covariate value is given). Options are "Forward", "Interpolate", "Backward", where "Interpolate" is only applicable to type = "Continuous".
option	Options are "Yes", "PlusOne", or "No", where option = "No" will remove the covariate effect from the specified structural parameter(s), but retain the covariate in the model. Note: option = "PlusOne" is only applicable to continuous and categorical covariates in the case where structural parameters have style = "LogNormal". Multiple options are not supported (i.e. all covariate effects in the call are supposed to have the same option. If different options are required for different covariate effects, sequential calls of current method could be done.
center	Centering method. Options are "Mean", "Median", "Value" or "None". Only applicable to covariate type = "Continuous". Must include argument centerValue if center = "Value".
centerValue	Value used to center covariate. Only applicable if argument center = "Value" and type = "Continuous".
levels	Unique values of categorical or occasion covariate. Only applicable to covariate type = "Categorical" or type = "Occasion".
labels	Label names (in the same order as levels) for unique levels of categorical or occasion covariate in data. Only applicable to covariate type = "Categorical" or type = "Occasion" where its corresponding column in the input dataset has character type.
isDiagonal	Set to FALSE if inter-occasion covariance matrix is not diagonal matrix. Only applicable to covariate type = "Occasion".
values	Initial values for the diagonal elements of the inter-occasion covariance matrix (if isDiagonal = TRUE) or initial values for the lower triangular elements (including diagonal elements) of inter-occasion covariance matrix (if isDiagonal = FALSE) in a row-wise order. Only applicable for covariate type = "Occasion".
isPositive	Set to FALSE if covariate contains negative values. Only applicable to covariate type = "Continuous".

Details

The following relationships are applicable for covariates:

• direction = "Forward" is equivalent to PML code 'fcovariate(CovName)';

• direction = "Backward" is equivalent to PML code 'covariate(CovName)';

• direction = "Interpolate" is equivalent to PML code 'interpolate(CovName)'.

  If the structural parameter has style = "LogNormal", the options are reflected in PML code as follows:

• option = "Yes" is equivalent to stparm(V = tvV * wt^dVdwt * exp(dVdsex1*(sex==1)) * exp(nV));

• ⁠option = "PlusOne⁠ is equivalent to stparm(V = tvV * (1+wt*dVdwt) * (1+dVdsex1*(sex==1)) * exp(nV)).

Value

Modified NlmePmlModel object

Examples

model <- pkmodel(
  numCompartments = 2,
  data = pkData,
  ID = "Subject",
  Time = "Act_Time",
  A1 = "Amount",
  CObs = "Conc"
)

# Add Gender covariate of type categorical
model <- addCovariate(model,
  covariate = "Gender",
  type = "Categorical",
  effect = c("V2", "Cl2"),
  levels = c(0, 1),
  labels = c("Female", "Male")
)

# Add BodyWeight covariate of type continuous
model <- addCovariate(model,
  covariate = "BodyWeight",
  type = "Continuous",
  direction = "Backward",
  center = "Mean",
  effect = c("V", "Cl")
)

Certara.RsNLME documentation built on April 3, 2025, 11:04 p.m.