MEM_Polynomial_Group_structure: Polynomial Mixed-Effects Models with Censored and...
In marie-alexandre/AUCtest: Statistical test - Between group comparison of AUC

Description Usage Arguments Details Value See Also Examples

View source: R/MEM_Polynomial_Group_structure.R

\loadmathjax

This function fits a mixed-effects model (MEM) to potentially censored data structured by group when marginal and individual dynamics are described either by polynomials or B-spline curves.

MEM_Polynomial_Group_structure(
  y,
  x = NULL,
  Group = NULL,
  Id = NULL,
  Cens = NULL,
  marginal_dyn_type = "polynomial",
  ind_dyn_type = "polynomial",
  global_intercept = TRUE,
  group_intercept = FALSE,
  degree_group = 3,
  Adaptive = "none",
  min_knots_group = 2,
  max_knots_group = 2,
  knots_group = NULL,
  df_group = NULL,
  Boundary.knots_group = NULL,
  ind_intercept = FALSE,
  degree_ind = 3,
  min_knots_ind = 2,
  max_knots_ind = 2,
  same_base_group_ind = FALSE,
  knots_ind = NULL,
  df_ind = NULL,
  Boundary.knots_ind = NULL,
  ...
)

`y`	observed responses described either as a data frame containing at least a column named 'y' and possibly the columns 'x', 'Group', 'Id' and 'Cens' (among others), or as a vector of numerical values.
`x`	a numerical vector representing the x-axis coordinates corresponding to the observed responses (e.g. time of observations) which can be defined is `y` is a vector or a data frame without `x` column. By default, this variable is defined as NULL.
`Group`	a vector of group indicator for each observed responses which can be defined if `y` is a vector or a data frame without `Group` column. If this variable is defined as NULL (default) and y does not contain group information, all observed data are assumed to belong to the same group.
`Id`	a vector of individual ID for each observed responses which can be defined if `y` is a vector or a data frame without 'Id' column. By default, this variable is defined as NULL.
`Cens`	a vector of censoring indicator (if `y` >= ytrue, then `Cens` == 1). If this variable is defined as NULL (default) and `y` does not contain 'Cens' column, observed data are assumed as uncensored.
`marginal_dyn_type`	a character variable indicating the type of marginal dynamics. Options are 'polynomial' (default) and 'spline'.
`ind_dyn_type`	a character variable indicating the type of individual dynamics (random effects). Options are 'polynomial' (default) or 'spline'.
`global_intercept`	a logical scalar. If TRUE (default) a global intercept (no group-specific) is included in the marginal dynamics.
`group_intercept`	a logical scalar (same option for all groups) or vector. For each group, if TRUE, a group-specific intercept is included in the marginal dynamics. By default, this variable is defined as FALSE
`degree_group`	an integer scalar (same option for all groups) or vector. The variable indicates for each group either the degree of polynomial functions or spline curves describing marginal dynamics. By default, the variable is fixed at 3.
`Adaptive`	an optional character variable that can be used when `marginal_dyn_type` or `ind_dyn_type` are chosen as 'spline'. Corresponding B-spline curves are then build with internal knot positions optimally estimated according to data (see Optimal_knot_research for more details). Options are 'none' (default), 'group , 'individual', and 'both'.
`min_knots_group`	an optional integer scalar indicating the minimum number of internal knots to consider in the research of optimal knots for marginal dynamics. This variable is used only if `marginal_dyn_type` is chosen as 'spline' and `Adaptive` chosen as 'group' or 'both'. By default, this variable fixed at 2.
`max_knots_group`	an optional integer scalar indicating the maximum number of internal knots to consider in the research of optimal knots for marginal dynamics. This variable is used only if `marginal_dyn_type` is chosen as 'spline' and `Adaptive` chosen as 'group' or 'both'. By default, this variable fixed at 2.
`knots_group`	a numerical vector (same option for all groups) or a list of either numerical vectors or NULL (one for each group) indicating the internal knots for group-specific B-spline curves. This variable will be used only if `marginal_dyn_type` has been chosen as 'spline', without adaptive knots. By default, this variable is defined as NULL(see bs for more details).
`df_group`	an integer scalar (same option for all groups) or vector indicating the degrees of freedom to consider to build marginal B-spline curves. This variable will be used only if `marginal_dyn_type` has been chosen as 'spline', without adaptive knots. One can specify `df_group` rather than `knots_group` (see bs for more details). By default, this variable is defined as NULL.
`Boundary.knots_group`	a numerical vector (same option for all groups) or a list of either numerical vectors or NULL (one for each group) indicating the boundary knots for group-specific B-spline curves. This variable will be used only if `marginal_dyn_type` has been chosen as 'spline', without adaptive knots. By default, this variable is defined as NULL (see bs for more details).
`ind_intercept`	a logical scalar. If TRUE, an intercept is included in the individual dynamics (random effects). By default, this variable is defined as FALSE.
`degree_ind`	an integer scalar indicating either the degree of the polynomial functions or the B-spline curves describing individual dynamics. By default, this variable is fixed at 2.
`min_knots_ind`	an optional interger scalar indicating the minimum number of internal knots to consider in the research of optimal knots for individual dynamics. This variable is used only if `ind_dyn_type` is chosen as 'spline' and `Adaptive` chosen as 'individual' or 'both'. By default, this variable is fixed at 2
`max_knots_ind`	an optional interger scalar indicating the maximum number of internal knots to consider in the research of optimal knots for individual dynamics. This variable is used only if `ind_dyn_type` is chosen as 'spline' and `Adaptive` chosen as 'individual' or 'both'. By default, this variable is fixed at 2
`same_base_group_ind`	an optional logical scalar indicating whether or not the same B-spline basis must be considered in group-specific and individual dynamics. This variable is used only if `marginal_dyn_type` and `ind_dyn_type` are chosen as 'spline'. If TRUE, each individual B-spline basis will be build as the corresponding group-specific B-spline basis evaluted at the individual predictor variable. By default, this variable is defined as FALSE.
`knots_ind`	a numerical vector (same option for all individuals) or a list of numerical values or NULL indicating the internal knots for individual-specific B-spline curves. This variable will be used only if `ind_dyn_type` has been chosen as 'spline', without adaptive knots. If this variable is defined as a list, internal knots can either be defined individually (one vector or NULL for each Id value), equivalent for each individual belong to the same group (one vector or NULL for each Group), or equivalent for each individual (one vector or NULL). By default, this variable is defined as NULL(see bs for more details).
`df_ind`	an integer scalar (same option for all individuals) or vector indicating the degrees of freedom to consier to build individual B-splines curves. This variable can be choosen different for each individual or equivalent for each individual belonging to the same group (one value for each group). By default, this variable is defined as NULL(see bs for more details).
`Boundary.knots_ind`	a numerical vector indicating the boundary knots for individual-specific B-spline curves. This variable will be used only if `ind_dyn_type` has been chosen as 'spline', without adaptive knots. By default, this variable is defined as NULL (see bs for more details).
`...`	Further arguments to be passed (see lmec for more details).

The Mixed-Effects model describing the outcome of interest \mjseqnY_ij,g_i of the subject \mjseqni in the group \mjseqng_i at the \mjseqnjth time point (x-axis) is given by \mjsdeqnY_ij,g_i = \gamma_0+ \sum_g=1^G \mathbb1_[g_i=g] \times F_g(t_ij,g) + h_i(t_ij,g_i) + \varepsilon_ij where \mjseqn\gamma_0 is the global (non group-specific) intercept and the functions \mjseqnF_g and \mjseqnh_i are the non-linear smooth functions describing respectively the marginal group-specific dynamics and the individual dynamics (random effects). Through this function, the group-specific functions are defined as following, where \mjseqn\beta_0^g is the optional group_intercept: \mjsdeqnF_g(t_ij,g) = \beta_0^g + \sum_k=1^K_g \beta^g_k f^k_g(t_ij,g) If marginal_dyn_type is defined as 'polynomial', \mjseqnK_g = degree_group and \mjseqnf^k_g(t_ij,g) = t_ij,g^k and if marginal_dyn_type is defined as 'spline', \mjseqnK_g = df_group (see bs for more details) and \mjseqnf^k_g(t_ij,g) is the \mjseqnkth group-specific spline basis. Similarly, the indvidual dynamics are described by the following functions, with \mjseqnb_0i as optional ind_intercept: \mjsdeqnh_i(t_ij,g) = b_0i + \sum_k=1^K_i b_ki \Psi_k^i(t_ij,g) If ind_dyn_type is defined as 'polynomial', \mjseqnK_i = degree_ind and \mjseqn\Psi_k^i(t_ij,g) = t_ij,g^k and if ind_dyn_type is defined as 'spline', \mjseqnK_i = df_ind (see bs for more details) and \mjseqn\Psi_k^i(t_ij,g) is the \mjseqnkth individual spline basis.

A list containing:

`Model_estimation`	a list containing the results of the model estimation provided by the function lmec. In this list, the vector of fixed parameters called `beta`, the parameters are returned in the following order: \mjseqn\beta = (\gamma_0,\beta_0^1, \cdots, \beta_K_1^1,\cdots,\beta_0^g,\cdots,\beta_K_g^g,\cdots,\beta_0^G,\cdots,\beta_K_G^G).
`Model_features`	a list of 3 elements:
	1. `Groups` - a vector indicating the names of the groups involved in the model
	2. `Marginal.dyn.feature` - a list summarizing the features of the marginal dynamics defined in the model (through input arguments):
	`dynamic.type` - a character scalar indicating the chosen type of marginal dynamics `intercept` - a logical vector summarizing choices about global and group-specific intercepts (Number of groups + 1 values) For 'polynomial' marginal dynamics: `polynomial.degree` - an integer vector indicating the degree of polynomial functions For 'spline' marginal dynamics: `spline.degree` - an integer vector indicating the degree of B-spline curves `adaptive.splines` - a logical scalar indicating whether or not adaptive internal knots have been considered `knots` - a list of group-specific internal knots used to build B-spline basis. If the degrees of freedom were equals to the spline degrees, then NULL `df` - a numerical vector of group-specific degrees of freedom used to build B-spline basis. `boundary.knots` - a list of group-specific boundary knots used to build B-spline basis.
	3. `Individual.dyn.feature` - a list summarizing the features of the individual dynamics defined in the model (through input arguments)
	`dynamic.type` - a character scalar indicating the chosen type of individual dynamics `intercept` - a logical scalar indicating whether a random intercept was included in the model For 'polynomial' individual dynamics: `polynomial.degree` - an integer scalar indicating the degree of polynomial functions For 'spline' marginal dynamics: `spline.degree` - an integer scalar indicating the degree of B-spline curves `adaptive.splines` - a logical scalar indicating whether or not adaptive internal knots have been considered `knots` - a data frame of individually estimated internal knots (if `Adaptive` chosen as 'individual' or 'both'), or a list of chosen individual internal knots `df` - a numerical vector of individual degrees of freedom `boundary.knots` - a numerical vector of individual boundary knots

bs, lmec, Optimal_knot_research

# Download of data
data("HIV_Simu_Dataset_Delta01_cens")
data <- HIV_Simu_Dataset_Delta01_cens

# Change factors in character vectors
data$id <- as.character(data$id) ; data$Group <- as.character(data$Group)

# We call the function considering the variable 'y' as a vector (we need to specify the groups )
MEM_Pol_Group <- MEM_Polynomial_Group_structure(y=data$VL,x=data$time,Group=data$Group,Id=data$id,Cens=data$cens)

# We call the function considering the variable 'y' as a  data frame (the column 'VL' in data has to be rename)
colnames(data)[4] <- "y"
MEM_Pol_Group <- MEM_Polynomial_Group_structure(y=data,x=data$time,Cens=data$cens,Id=data$id)