MEM_Polynomial_Group_structure: Polynomial Mixed-Effects Models with Censored and...

In marie-alexandre/AUCcomparison: Statistical test - Between group comparison of AUC

Description

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

Usage

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",knotnumcrit = "AIC",
  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,
  ...
)

Arguments

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 whether B-spline curves are built with internal knot positions optimally estimated according to data (see Optimal_knot_research and @details for more details). Options are 'none' (default), 'group , 'individual', and 'both'.
knotnumcrit	an optional character variable indicating the criterion to be used for determining the number of internal knots in B-splines. See @details for more details.
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. By default, this variable fixed at 2. See @details for more details.
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. By default, this variable fixed at 2. See @details for more details.
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. By default, this variable is defined as NULL (see bs and @details 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. One can specify df_group rather than knots_group (see bs for more details). By default, this variable is defined as NULL. See @details for more details.
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. By default, this variable is defined as NULL (see bs and @details 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. By default, this variable is fixed at 2. See @details for more details.
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. By default, this variable is fixed at 2. See @details for more details.
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. If TRUE, each individual B-spline basis will be build as the corresponding group-specific B-spline basis evaluated at the individual predictor variable. By default, this variable is defined as FALSE. See @details for more details.
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. 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 and @details 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 and @details for more details).
Boundary.knots_ind	a numerical vector indicating the boundary knots for individual-specific B-spline curves. By default, this variable is defined as NULL (see bs and @details for more details).
...	Further arguments to be passed (see lmec for more details).

Details

The variable adaptive can take 4 differents values:

• 'none' (default): internal knot positions defining B-spline curves in the model are not optimally estimated according to data, whether for fixed or random effects. Knots are then defined by users.

• 'group': only internal knot positions defining B-spline curves in fixed effects are optimally estimated, even if random effects involve B-splines.

• 'individual': only internal knot positions defining B-spline curves in random effects are optimally estimated, even if fixed effects involve B-splines.

• 'both': internal knot positions defining B-spline curves for both fixed and random effects are optimally estimated.

At group level (fixed effects),

• the variables Adaptive, knotnumcrit, min_knots_group, max_knots_group, knots_group, df_group and Boundary.knots_group will be used only if the variable marginal_dyn_type has been chosen as 'spline'.

  • among them, the variables knotnumcrit, min_knots_group and max_knots_group will be used only if adaptive knots are requested (the variable Adaptive chosen as 'group' or 'both').

  • the variables knots_group, df_group and Boundary.knots_group will be used without adaptive knots.

Similarly, at individual level (random effects),

• the variables Adaptive, knotnumcrit, min_knots_ind, max_knots_ind, knots_ind, df_ind and Boundary.knots_ind will be used only if the variable ind_dyn_type has been chosen as 'spline'.

  • among them, the variables knotnumcrit, min_knots_ind and max_knots_ind will be used only if adaptive knots are requested (the variable Adaptive chosen as 'individual' or 'both').

  • the variables knots_ind, df_ind and Boundary.knots_ind will be used without adaptive knots.

• the variable same_base_group_ind can be used only if both variables marginal_dyn_type and ind_dyn_type are chosen as 'spline'.

The Mixed-Effects model describing the outcome of interest \mjteqnY_ij,g_iY_ij,g_iY_ij,g_i of the subject \mjteqniii in the group \mjteqng_ig_ig_i at the \mjteqnjjjth time point (x-axis) is given by \mjtdeqnY_ij,g_i = \gamma_0 + \sum_g=1^G 1_g_i=g\times F_g(t_ij,g) + h_i(t_ij,g_i) + \varepsilon_ij Y_ij,g_i = \gamma_0 + \sum_g=1^G 1_g_i=g\times F_g(t_ij,g) + h_i(t_ij,g_i) + \varepsilon_ij Y_ij,g_i = \gamma_0 + \sum_g=1^G 1_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 \mjteqnF_gF_gF_g and \mjteqnh_ih_ih_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 \mjteqn\beta_0^g\beta_0^g\beta_0^g is the optional group_intercept: \mjtdeqnF_g(t_ij,g) = \beta_0^g + \sum_k=1^K_g \beta^g_k f^k_g(t_ij,g)F_g(t_ij,g) = \beta_0^g + \sum_k=1^K_g \beta^g_k f^k_g(t_ij,g)F_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', \mjteqnK_gK_gK_g = degree_group and \mjteqnf^k_g(t_ij,g) = t_ij,g^kf^k_g(t_ij,g) = t_ij,g^kf^k_g(t_ij,g) = t_ij,g^k and if marginal_dyn_type is defined as 'spline', \mjteqnK_gK_gK_g = df_group (see bs for more details) and \mjteqnf^k_g(t_ij,g)f^k_g(t_ij,g)f^k_g(t_ij,g) is the \mjteqnkkkth group-specific spline basis. Similarly, the individual dynamics are described by the following functions, with \mjteqnb_0ib_0ib_0i as optional ind_intercept: \mjtdeqnh_i(t_ij,g) = b_0i + \sum_k=1^K_i b_ki \Psi_k^i(t_ij,g)h_i(t_ij,g) = b_0i + \sum_k=1^K_i b_ki \Psi_k^i(t_ij,g)h_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', \mjteqnK_iK_iK_i = degree_ind and \mjteqn\Psi_k^i(t_ij,g) = t_ij,g^k\Psi_k^i(t_ij,g) = t_ij,g^k\Psi_k^i(t_ij,g) = t_ij,g^k and if ind_dyn_type is defined as 'spline', \mjteqnK_iK_iK_i = df_ind (see bs for more details) and \mjteqn\Psi_k^i(t_ij,g)\Psi_k^i(t_ij,g)\Psi_k^i(t_ij,g) is the \mjteqnkkkth individual spline basis.

Value

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: \mjteqn\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)\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)\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.

See Also

bs, lmec, Optimal_knot_research

Examples

 # 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
colnames(data)[4] <- "y"
MEM_Pol_Group <- MEM_Polynomial_Group_structure(y=data,x=data$time,Cens=data$cens,Id=data$id) 

marie-alexandre/AUCcomparison documentation built on Dec. 21, 2021, 1:52 p.m.