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.

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

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