Merge pull request #190 from LCBC-UiO/ropensci-documentation

Ropensci documentation

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: galamm
 Title: Generalized Additive Latent and Mixed Models
-Version: 0.2.1
+Version: 0.2.1.9000
 Authors@R: c(
     person(given = "Øystein",
            family = "Sørensen",

NAMESPACE

@@ -17,6 +17,7 @@ S3method(plot,galamm)
 S3method(plot_smooth,galamm)
 S3method(predict,galamm)
 S3method(print,VarCorr.galamm)
+S3method(print,galamm)
 S3method(print,summary.galamm)
 S3method(ranef,galamm)
 S3method(residuals,galamm)
@@ -31,6 +32,7 @@ export(galamm)
 export(galamm_control)
 export(plot_smooth)
 export(ranef)
+export(response)
 export(s)
 export(sl)
 export(t2)

R/anova.galamm.R

@@ -2,9 +2,11 @@
 #'
 #' @srrstats {G1.4} Function documented with roxygen2.
 #' @srrstats {G2.1a} Expected data types provided for all inputs.
+#' @srrstats {RE4.11} Goodness-of-fit and other statistics associated such as
+#'   effect sizes with model coefficients.
 #'
-#' @description
-#' Anova function for comparing different GALAMMs fitted on the same data.
+#' @description Anova function for comparing different GALAMMs fitted on the
+#' same data.
 #'
 #' @param object An object of class \code{galamm} returned from
 #'   \code{\link{galamm}}.
@@ -111,6 +113,7 @@ anova.galamm <- function(object, ...) {
 #'
 #' @srrstats {G1.4} Function documented with roxygen2.
 #' @srrstats {G2.1a} Expected data types provided for all inputs.
+#' @srrstats {RE4.5} Numbers of observations submitted to model (via nobs())
 #'
 #' @param object An object of class \code{galamm} returned from
 #'   \code{\link{galamm}}.

R/coef.R

@@ -2,6 +2,7 @@
 #'
 #' @srrstats {G1.4} Function documented with roxygen2.
 #' @srrstats {G2.1a} Expected data types provided for all inputs.
+#' @srrstats {RE4.2} Model coefficients (via coef() / coefficients())
 #'
 #' @description
 #' Currently, this function only returns the fixed effects.

R/confint.R

@@ -5,6 +5,7 @@
 #' @srrstats {G2.3,G2.3b} Arguments parm and method are case sensitive, as stated in
 #'   their documentation.
 #' @srrstats {G2.1a} Expected data types provided for all inputs.
+#' @srrstats {RE4.3} Confidence intervals on those coefficients (via confint())
 #'
 #' @param object An object of class \code{galamm} returned from
 #'   \code{\link{galamm}}.

R/data.R

@@ -126,7 +126,7 @@
 #' Simulated dataset mimicking the measurement of abilities in three cognitive
 #' domains. The latent traits (cognitive ability in a given domain) are based on
 #' the functions in \code{mgcv::gamSim}
-#' \insertCite{woodGeneralizedAdditiveModels2017a}{galamm}, and depend on the
+#' \insertCite{woodGeneralizedAdditiveModels2017}{galamm}, and depend on the
 #' explanatory variable x.
 #'
 #' @srrstats {G5.1} Dataset used to test package is exported.

R/fitted.galamm.R

@@ -2,6 +2,8 @@
 #'
 #' @srrstats {G1.4} Function documented with roxygen2.
 #' @srrstats {G2.1a} Expected data types provided for all inputs.
+#' @srrstats {RE4.9} Modelled values of response variables.
+#'
 #' @description
 #' Extracts fitted values from a model including random effects.
 #'

R/formula.R

@@ -1,6 +1,7 @@
 #' @title Extract formula from fitted galamm object
 #'
 #' @srrstats {G1.4} Function documented with roxygen2.
+#' @srrstats {RE4.4} The specification of the model, generally as a formula (via formula())
 #' @param x Object of class \code{galamm} returned from \code{\link{galamm}}.
 #' @param ... Optional arguments passed on to other methods. Currently not used.
 #'

R/galamm.R

@@ -4,7 +4,7 @@
 #'   (GALAMMs), as described in
 #'   \insertCite{sorensenLongitudinalModelingAgeDependent2023;textual}{galamm}.
 #'   The building blocks of these models are generalized additive mixed models
-#'   (GAMMs) \insertCite{woodGeneralizedAdditiveModels2017a}{galamm}, of which
+#'   (GAMMs) \insertCite{woodGeneralizedAdditiveModels2017}{galamm}, of which
 #'   generalized linear mixed models
 #'   \insertCite{breslowApproximateInferenceGeneralized1993,harvilleMaximumLikelihoodApproaches1977,hendersonBestLinearUnbiased1975,lairdRandomEffectsModelsLongitudinal1982}{galamm}
 #'   are special cases. GALAMMs extend upon GAMMs by allowing factor structures,
@@ -38,13 +38,14 @@
 #' @srrstats {G2.2} Assertions on the lengths of arguments are implemented in
 #'   galamm.
 #' @srrstats {G2.3,G2.3a} match.arg() used on "na.action" argument.
-#' @srrstats {G2.3,G2.3b} Arguments "family", "load.var", "factor", and the elements
-#'   of the "start" argument are case sensitive. This is stated in the
+#' @srrstats {G2.3,G2.3b} Arguments "family", "load.var", "factor", and the
+#'   elements of the "start" argument are case sensitive. This is stated in the
 #'   documentation below.
-#' @srrstats {G2.4,G2.4a} Internally, objects family_mapping, weights_mapping and
-#'   lambda_mapping_X are explicitly converted to integer using as.integer().
-#' @srrstats {G2.4,G2.4b} as.numeric() used multiple places throughout the code for
-#'   explicitly converting to continuous.
+#' @srrstats {G2.4,G2.4a} Internally, objects family_mapping, weights_mapping
+#'   and lambda_mapping_X are explicitly converted to integer using
+#'   as.integer().
+#' @srrstats {G2.4,G2.4b} as.numeric() used multiple places throughout the code
+#'   for explicitly converting to continuous.
 #' @srrstats {G2.6} If \code{lambda} is provided as a vector, it will be
 #'   converted to a matrix with a single column, and a message will be printed.
 #' @srrstats {G2.7} Both \code{tibble}s and \code{data.table}s are accepted in
@@ -65,35 +66,75 @@
 #' @srrstats {G2.16} \code{NaN}, \code{Inf}, or \code{-Inf} in \code{data}
 #'   causes an error. The same happens with such values in \code{lambda}.
 #' @srrstats {G5.2} All errors and warnings are tested.
-#' @srrstats {G5.2a} Every message produced within R code by stop(),
-#'   warning(), or message(), is unique.
-#' @srrstats {G5.2b} All stop(), warning(), and message() calls are tested,
-#'   as can be seen in the CodeCov report on GitHub.
+#' @srrstats {G5.2a} Every message produced within R code by stop(), warning(),
+#'   or message(), is unique.
+#' @srrstats {G5.2b} All stop(), warning(), and message() calls are tested, as
+#'   can be seen in the CodeCov report on GitHub.
 #' @srrstats {G5.3} Tests have explicit expectations about return objects.
-#' @srrstats {G5.4a} These are new methods, but they have been used in the
-#'   paper Sørensen, Fjell, and Walhovd (2023), in which extensive simulation
-#'   studies confirmed the correctness of the implementation. Furthermore, the
-#'   simulated datasets, which are documented in "R/data.R" and exported, have
-#'   known ground truth and we confirm in the vignettes that the obtained
-#'   estimates are close to the true values.
+#' @srrstats {G5.4a} These are new methods, but they have been used in the paper
+#'   Sørensen, Fjell, and Walhovd (2023), in which extensive simulation studies
+#'   confirmed the correctness of the implementation. Furthermore, the simulated
+#'   datasets, which are documented in "R/data.R" and exported, have known
+#'   ground truth and we confirm in the vignettes that the obtained estimates
+#'   are close to the true values.
 #' @srrstats {G5.4b} Wherever there is overlapping functionality, results from
 #'   galamm() have been confirmed to be identical to those of lme4::lmer() for
-#'   linear mixed models, to those of lme4::glmer() for generalized linear
-#'   mixed models with binomial or Poisson responses, to those of
-#'   nlme::lme() for linear mixed models with heteroscedastic residuals, and
-#'   to those of PLmixed::PLmixed() for linear mixed models with factor
-#'   structures and generalized linear mixed models with factor structures.
-#' @srrstats {G5.5} Random seed is set when simulating data, but the
-#'   algorithms are determinstic, and hence don't depend on random numbers.
-#' @srrstats {G5.6} Implemented in the tests, both through data simulated
-#'   for this package, and through simulated data from PLmixed and lme4.
+#'   linear mixed models, to those of lme4::glmer() for generalized linear mixed
+#'   models with binomial or Poisson responses, to those of nlme::lme() for
+#'   linear mixed models with heteroscedastic residuals, and to those of
+#'   PLmixed::PLmixed() for linear mixed models with factor structures and
+#'   generalized linear mixed models with factor structures.
+#' @srrstats {G5.5} Random seed is set when simulating data, but the algorithms
+#'   are determinstic, and hence don't depend on random numbers.
+#' @srrstats {G5.6} Implemented in the tests, both through data simulated for
+#'   this package, and through simulated data from PLmixed and lme4.
 #' @srrstats {G5.6a} Tolerance in testthat() set to relatively high values,
 #'   since the outcome is platform dependent.
 #'
+#' @srrstats {RE1.0} The models can be fitted via a formula interface.
+#' @srrstats {RE1.1} The package vignettes describe all the mathematics behind
+#'   how the formula object is converted to a matrix representation.
+#' @srrstats {RE1.2} The documentation for the data argument below specifies
+#'   that a data.frame is expected.
+#' @srrstats {RE1.3} Argument factor below contains names of the latent
+#'   variables, and these are passed onto the summary and other output
+#'   functions.
+#' @srrstats {RE1.3a} This requirement does not seem relevant, as there is not
+#'   otherwise relevant information which is not transferred.
+#' @srrstats {RE1.4} Distributional assumptions with regard to input data are
+#'   documented through the family option below.
+#' @srrstats {RE2.0} Requirements to input data are strict, but no particular
+#'   transformations are performed.
+#' @srrstats {RE2.1} Satisfied through the na.action argument to galamm().
+#' @srrstats {RE2.2} This requirement seems very hard to satisfy in the context
+#'   for multilevel latent variable models, since random effects are an integral
+#'   part of the fit.
+#' @srrstats {RE2.3} Centering and offseting is possible.
+#' @srrstats {RE2.4} Preprocessing routines are part of galamm() function.
+#' @srrstats {RE2.4a} Rank-deficient design matrix leads to an error.
+#' @srrstats {RE2.4b} Obtained through the model.matrix() formula, which by
+#'   defaults drops the right-hand side variable and gives a warning.
+#' @srrstats {RE4.0} A model object of class galamm is returned, and all its
+#'   components are documented here.
+#' @srrstats {RE4.1} Generating a model object with no data seems hard for this
+#'   type of model. Instead, when a dataframe with zero rows is provided, an
+#'   error message is generated.
+#' @srrstats {RE4.7} Not applicable; algorithm is deterministic.
+#' @srrstats {RE4.12,RE4.13} Not applicable.
+#' @srrstats {RE4.14} Natural part of the confidence bands for fitted smooth
+#'   functions, which typically are very wide outside of the domain of the
+#'   training data.
+#' @srrstats {RE14.5} It is well documented in the literature that confidence
+#'   bands for smooth terms are very wide outside of the data domain. Some
+#'   tendency of this can be seen in Figure 2 of the Psychometrika paper by
+#'   Sørensen, Fjell, and Walhovd (2023) which describes the algorithms
+#'   implemented in this package.
+#' @srrstats {RE5.0} Documented in vignette on computational scaling.
+#'
 #'
 #' @param formula A formula specifying the model. Smooth terms are defined in
 #'   the style of the \code{mgcv} and \code{gamm4} packages, see
-#'   \insertCite{woodGeneralizedAdditiveModels2017a}{galamm} for an
+#'   \insertCite{woodGeneralizedAdditiveModels2017}{galamm} for an
 #'   introduction. Random effects are specified using \code{lme4} syntax, which
 #'   is described in detail in
 #'   \insertCite{batesFittingLinearMixedEffects2015}{galamm}. Factor loadings

R/galamm_control.R

@@ -8,6 +8,11 @@
 #' @srrstats {G2.3,G2.3b} Argument "method" is case sensitive, as documented
 #'   below.
 #'
+#' @srrstats {RE3.0,RE3.1,RE3.2,RE3.3} All of these requirements are satisfied
+#'   by this function, which its output is given as an argument to the
+#'   galamm_control argument in galamm(). In addition, there is a special
+#'   vignette on optimization which goes further into the details.
+#'
 #' @param optim_control List containing optimization parameters. If \code{method
 #'   = "L-BFGS-B"} it is passed on to \code{stats::optim}'s \code{control}
 #'   argument and if \code{method = "Nelder-Mead"}, it is passed on to

R/gamm4-functions.R

@@ -18,7 +18,7 @@
 #'
 #' @references \insertRef{woodStraightforwardIntermediateRank2013}{galamm}
 #'
-#' \insertRef{woodGeneralizedAdditiveModels2017a}{galamm}
+#' \insertRef{woodGeneralizedAdditiveModels2017}{galamm}
 #'
 #'
 gamm4.setup <- function(formula, pterms, mf) {
@@ -110,7 +110,7 @@ gamm4.setup <- function(formula, pterms, mf) {
 #' @references
 #' \insertRef{woodStraightforwardIntermediateRank2013}{galamm}
 #'
-#' \insertRef{woodGeneralizedAdditiveModels2017a}{galamm}
+#' \insertRef{woodGeneralizedAdditiveModels2017}{galamm}
 #'
 #' @srrstats {G1.4a} Internal function documented.
 #'
@@ -191,7 +191,12 @@ gamm4 <- function(fixed, random = NULL, data) {
   }
 
   lme4.formula <- stats::as.formula(lme4.formula)
-  b <- lme4::lFormula(lme4.formula, data = mf, REML = FALSE)
+  b <- lme4::lFormula(
+    formula = lme4.formula,
+    data = mf,
+    REML = FALSE,
+    control = lme4::lmerControl(check.rankX = "stop.deficient")
+    )
 
   tn <- names(b$reTrms$cnms)
   ind <- seq_along(tn)

R/mgcv-functions.R

@@ -17,7 +17,7 @@
 #' @seealso [gamm4.setup()] and [gamm4()].
 #'
 #' @references
-#' \insertRef{woodGeneralizedAdditiveModels2017a}{galamm}
+#' \insertRef{woodGeneralizedAdditiveModels2017}{galamm}
 #'
 gam.setup <- function(formula, pterms, mf) {
   m <- length(formula$smooth.spec)
@@ -261,7 +261,7 @@ gam.setup <- function(formula, pterms, mf) {
 #' @srrstats {G2.4,G2.4d} explicit conversion to factor via `as.factor()`
 #'
 #' @references
-#' \insertRef{woodGeneralizedAdditiveModels2017a}{galamm}
+#' \insertRef{woodGeneralizedAdditiveModels2017}{galamm}
 
 variable.summary <- function(pf, dl, n) {
   v.n <- length(dl)
@@ -322,7 +322,7 @@ variable.summary <- function(pf, dl, n) {
 #' @srrstats {G1.4a} Internal function documented.
 #'
 #' @references
-#' \insertRef{woodGeneralizedAdditiveModels2017a}{galamm}
+#' \insertRef{woodGeneralizedAdditiveModels2017}{galamm}
 #'
 gam.side <- function(sm, Xp, tol = .Machine$double.eps^.5) {
   m <- length(sm)
@@ -359,7 +359,7 @@ gam.side <- function(sm, Xp, tol = .Machine$double.eps^.5) {
 #' @srrstats {G1.4a} Internal function documented.
 #'
 #' @references
-#' \insertRef{woodGeneralizedAdditiveModels2017a}{galamm}
+#' \insertRef{woodGeneralizedAdditiveModels2017}{galamm}
 #'
 interpret.gam0 <- function(gf) {
   p.env <- environment(gf)

R/plot.galamm.R

@@ -8,6 +8,8 @@
 #'
 #' @srrstats {G1.4} Function documented with roxygen2.
 #' @srrstats {G2.1a} Expected data types provided for all inputs.
+#' @srrstats {RE6.0,RE6.2} Default plot method.
+#' @srrstats {RE6.1,RE6.3} Not applicable.
 #'
 #' @seealso [residuals.galamm()] for extracting residuals and [plot()] for the
 #'   generic function.

R/plot_smooth.R

@@ -10,7 +10,7 @@ plot_smooth <- function(object, ...) {
 #' @description
 #' Plots smooth terms of a fitted \code{galamm} object. This function is a thin
 #' wrapper around \code{mgcv::plot.gam}
-#' \insertCite{woodGeneralizedAdditiveModels2017a}{galamm}.
+#' \insertCite{woodGeneralizedAdditiveModels2017}{galamm}.
 #'
 #' @aliases plot_smooth plot_smooth.galamm
 #' @export plot_smooth

R/predict.galamm.R

@@ -4,6 +4,8 @@
 #' @srrstats {G2.1a} Expected data types provided for all inputs.
 #' @srrstats {G2.3,G2.3a} match.arg() used on "type" argument.
 #' @srrstats {G2.3,G2.3b} Argument "type" is case sensitive, which is documented.
+#' @srrstats {RE4.16} Submitting new groups yields population level prediction,
+#'   which is the correct prediction for new groups in these models.
 #'
 #' @description Predictions are given at the population level, i.e., with random
 #'   effects set to zero. For fitted models including random effects, see

R/residuals.galamm.R

@@ -5,6 +5,9 @@
 #' @srrstats {G2.3,G2.3b} Argument type is case sensitive, as stated in their
 #'   documentation.
 #' @srrstats {G2.1a} Expected data types provided for all inputs.
+#' @srrstats {RE4.10} Model Residuals, including sufficient documentation to
+#'   enable interpretation of residuals, and to enable users to submit residuals
+#'   to their own tests.
 #'
 #' @param object An object of class \code{galamm} returned from
 #'   \code{\link{galamm}}.

R/response.R

@@ -0,0 +1,34 @@
+#' @title Extract response values
+#'
+#' @srrstats {G1.4} Function documented with roxygen2.
+#' @srrstats {G2.1a} Expected data types provided for all inputs.
+#' @srrstats {RE4.8} Response variables, and associated "metadata" where
+#'   applicable.
+#'
+#' @description Extracts response values from a model.
+#'
+#' @param object An object of class \code{galamm} returned from
+#'   \code{\link{galamm}}.
+#' @param ... Optional arguments passed on to other methods. Currently not used.
+#'
+#'
+#' @return A numerical vector with fit response values for each row in the input
+#'   data.
+#' @export
+#'
+#' @family details of model fit
+#'
+#' @examples
+#' # Linear mixed model with heteroscedastic residuals
+#' mod <- galamm(
+#'   formula = y ~ x + (1 | id),
+#'   weights = ~ (1 | item),
+#'   data = hsced
+#' )
+#'
+#' # Plot response versus fitted values
+#' plot(fitted(mod), response(mod))
+#'
+response <- function(object, ...) {
+  object$model$response
+}

R/smooths.R

@@ -48,7 +48,7 @@ NULL
 #'
 #' \insertRef{woodThinPlateRegression2003}{galamm}
 #'
-#' \insertRef{woodGeneralizedAdditiveModels2017a}{galamm}
+#' \insertRef{woodGeneralizedAdditiveModels2017}{galamm}
 #'
 #' @examples
 #' # Linear mixed model with factor structures
@@ -120,7 +120,7 @@ sl <- function(..., factor = NULL) {
 #'
 #' \insertRef{woodThinPlateRegression2003}{galamm}
 #'
-#' \insertRef{woodGeneralizedAdditiveModels2017a}{galamm}
+#' \insertRef{woodGeneralizedAdditiveModels2017}{galamm}
 #'
 #' @examples
 #' # Linear mixed model with factor structures