R/corclus_params.R

In tessaleejohnson/corclus: Simulate Data from the Correlated Cluster Multiple Membership Model

#---------------------------------
# Param Documentation for
# All Internal Functions
#---------------------------------


#' corclus_params
#'
#' This documentation includes parameters for most functions in the
#' \code{corclus} package.
#'
#' Arguments for "self-contained" functions like
#' \code{\link{is_off_diag}}, \code{\link{pivot_longer_multicol}},
#' \code{\link{pivot_wider_multicol}}, \code{\link{plan_future}}, and
#' \code{\link{simulate_mobility}} are not included in this documentation.
#'
#' @param .clust_cov Numeric vector. The first element of the vector gives the
#' variance of all schools' predictors, z. If present, the second element gives
#' the covariance of z between schools k and k + 1. The values given in
#' \code{.clust_cov} apply to all schools (that is, similar to a Toeplitz
#' pattern). Any off-diagonal values (i.e., covariances) not specified will
#' default to 0. The main diagonal is the variance explained by the predictor.
#'
#' @param .gamma_x Numeric vector with length p (where p is the number of model
#' coefficients, including the intercept).
#'
#' @param .gamma_z Numeric scalar. The school-level effect of the
#' \code{z_predictors} on the random intercept.
#'
#' @param .id_nonmob Logical. Indicates whether non-mobile students should
#' receive a non-zero school ID for their second school. Technically, it
#' shouldn't matter if non-mobile students have a non-zero school ID (i.e., if
#' first and second schools are the same), so all ID schemes should
#' be equivalent, but it may matter for passing data to MLwiN for estimation.
#' See \code{\link[R2MLwiN]{runMLwiN}} for more information.
#'
#' @param .mean_r Numeric scalar. The mean of the person-level residual, r.
#'
#' @param .mean_x Numeric scalar. The mean of the predictor, x.
#'
#' @param .mm_id_nms A string. The prefix name of the multiple membership
#' unique ID variables.
#'
#' @param .mm_wt_nms A string. The prefix name of the multiple membership
#' weight variables.
#'
#' @param .n_sch Numeric scalar. Gives the total number of schools in the
#' dataset. The variance-covariance matrix for predictor z will have dimensions
#' \code{.n_sch x .n_sch}.
#'
#' @param .n_stu A numeric scalar. The number of students attending each
#' school. Note: this is not the total number of students in the dataset,
#' merely the number of students per school.
#'
#' @param .per_resid Numeric vector with length n (where n is the number of
#' persons in the data). Gives the person-level residual for the model.
#'
#' @param .sch_dat A matrix or dataframe. The school-level information created
#' by the \code{\link{gen_u_mmrem}} function.
#'
#' @param .sch_exp A matrix or dataframe. The school-level information created
#' by the \code{\link{gen_u_mmrem}} function and expanded by the
#' \code{\link{expand_sch_info}} function.
#'
#' @param .sch_predictor Numeric matrix or dataframe. Contains the values of
#' the school-level predictor, z, generated in \code{\link{gen_u_mmrem}}.
#'
#' @param .sch_resid Numeric matrix with dimensions n x h (where n is the number
#' of persons and h is the maximum number of schools attended by any person
#' in the dataset). The hth column of the matrix should give the residual for
#' the hth school attended by person i. As mentioned above, all students were
#' initially assigned a mobility profile that included multiple schools, then
#' only a certain proportion of those mobility profiles were retained.
#'
#' @param .sch_weight Numeric matrix with dimensions n x h (where n is the
#' number of persons and h is the maximum number of schools attended by any
#' person in the dataset). Rows should sum to 1 (that is, for each student,
#' the weights assigned to their schools attended should sum to 1). For a school
#' a student did not attend, the weight should be 0 (that is, if the maximum
#' number of schools attended was 2 and person A only attended 1 school, then
#' the weight for their "second school" should be 0, while the weight for
#' their "first school" should be 1). To simulate the data, all students were
#' initially assigned a mobility profile (meaning that all students were
#' assigned h schools to attend), and then only a certain proportion of
#' students were coded as mobile. For the students who were coded as mobile,
#' their \code{.sch_weight} matrix row should give equal weight to all schools
#' attended. For students who were coded as non-mobile, their first school
#' was given a weight of 1 and all other schools were given weights of 0.
#'
#' @param .strings A character vector. Gives the strings to be extracted by
#' \code{.capture_groups}.
#'
#' @param .u_resid_var Numeric scalar. Gives the residual variance of u0j (i.e.,
#' the variance unexplained after controlling for the school-level predictor,
#' z).
#'
#' @param .var_r Numeric scalar. The variance of the person-level residual, r.
#'
#' @param .var_x Numeric scalar. The variance of the predictor, x.
#'
#' @param .wt_vec A numeric vector with length equal to the maximum number
#' of schools attended by students in the data (in this simulation, the
#' maximum number is 2). The values in \code{.wt_vec} are used to weight
#' the effects of different schools attended on students. For this study,
#' all mobile students must have the same weights. If different weighting
#' patterns are desired, the code will need to be updated.
#'
#' @param .wt_nonmob Logical. Indicates whether non-mobile students should
#' receive the same weights as mobile students. Technically, it shouldn't
#' matter if non-mobile students are given the same weights because their
#' first and second schools are the same, so all weighting schemes should
#' be equivalent, but it may matter for passing data to MLwiN for estimation.
#' See \code{\link[R2MLwiN]{runMLwiN}} for more information.
#'
#' @param .x_predictor Numeric matrix with dimensions n x p (where n is the num
#' of persons and p is the number of coefficients, including the intercept).
#' The column of \code{.design_x} corresponding to the intercept should be a
#' column of 1s.
#'
#'
corclus_params <- function() {NULL}