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

  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



Model object


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.


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 of covariate. Options are "Continuous", "Categorical", "Occasion".


Direction of missing values propagation (if no covariate value is given). Options are "Forward", "Interpolate", "Backward", where "Interpolate" is only applicable to type = "Continuous".


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.


Centering method. Options are "Mean", "Median", "Value" or "None". Only applicable to covariate type = "Continuous". Must include argument centerValue if center = "Value".


Value used to center covariate. Only applicable if argument center = "Value" and type = "Continuous".


Unique values of categorical or occasion covariate. Only applicable to covariate type = "Categorical" or type = "Occasion".


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.


Set to FALSE if inter-occasion covariance matrix is not diagonal matrix. Only applicable to covariate type = "Occasion".


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


Set to FALSE if covariate contains negative values. Only applicable to covariate type = "Continuous".


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


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