Skip to contents

Add covariate to model object

addCovariate.Rd

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. Important for Occasion Covariates: When modifying an existing occasion covariate (e.g., changing option or values), you must list all structural parameters currently affected by this occasion covariate in the effect argument, even those whose effect relationship is not being changed in this specific call.

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".

  • "Yes": Apply the covariate effect using the standard method (multiplicative for LogNormal style, additive for Normal style).

  • "PlusOne": Apply the covariate effect using the "1 + effect" formulation. This is only applicable to continuous and categorical covariates where the affected structural parameter has style = "LogNormal".

  • "No": Remove the specified covariate effect from the specified structural parameter(s). The covariate itself (and its definition, e.g., fcovariate(Occ1)) remains part of the model, but the link between this covariate and the specified parameter(s) in the stparm() statement is removed. See the note for the effect argument regarding occasion covariates. Multiple options are not supported within a single call (i.e., all covariate effects listed in the effect argument for a single call must use the same option). If different options are required, use sequential calls to addCovariate.

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".

Value

Modified NlmePmlModel object

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)).

Examples

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

# 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")
)