Updated documentation: all exported functions have now a @return tag …

…in roxygen, to describe it

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: dominanceanalysis
 Title: Dominance Analysis
-Date: 2024-02-01
+Date: 2024-02-04
 Encoding: UTF-8
 Description: Dominance analysis is a method that allows to compare the
              relative importance of predictors in multiple regression models:

R/bootAverageDominanceAnalysis.r

@@ -1,28 +1,33 @@
-#' Bootstrap average values for Dominance Analysis
+#' Bootstrap Average Values for Dominance Analysis
 #'
-#' Bootstrap average values and correspond standard errors for each predictor
-#' in the dominance analysis. Those values are used for general dominance.
+#' Bootstrap average values and corresponding standard errors for each predictor
+#' in the dominance analysis. These values are used for assessing general dominance.
 #'
-#' Use \code{summary()} to get a nice formatted \code{data.frame} object.
+#' Use \code{summary()} to obtain a nicely formatted \code{data.frame} object.
 #'
-#' @param x lm, glm or lmer model
-#' @param R number on bootstrap resamples
-#' @param constants vector of predictors to remain unchanged between models.
-#'                  i.e. vector of variables not subjected to bootstrap analysis.
-#' @param terms     vector of terms to be analyzed. By default, obtained from the model
-#' @param fit.functions list of functions which provides fit indices for model.
-#'                      See \code{fit.functions} param in \code{\link{dominanceAnalysis}}
-#'                      function.
-#' @param null.model only for linear mixed models, null model against to test the submodels.
-#'                   i.e. only random effects, without any fixed effect.
-#' @param ... Other arguments provided to lm or lmer (not implemented yet).
+#' @param x A model object, like `lm`, `glm`, or `lmer`.
+#' @param R An integer indicating the number of bootstrap resamples to be performed.
+#' @param constants A character vector specifying predictors that should remain constant in the bootstrap analysis. Default is an empty vector.
+#' @param terms An optional vector of terms (predictors) to be analyzed. If NULL, terms are obtained from the model. Default is NULL.
+#' @param fit.functions A vector of functions providing fit indices for the model. See `fit.functions` parameter in `dominanceAnalysis` function.
+#' @param null.model An optional model object specifying the null model for linear mixed models, used as a baseline for testing submodels. Default is NULL.
+#' @param ... Additional arguments passed to `dominanceAnalysis` method
+#' @return An object of class `bootAverageDominanceAnalysis` containing:
+#' -\item{boot}{The results of the bootstrap analysis in a \code{boot} object.}
+#' \item{preds}{The predictors analyzed}
+#' \item{fit.functions}{The fit functions used in the analysis}
+#' \item{R}{The number of bootstrap resamples}
+#' \item{eg}{expanded grid of predictors by fit functions}
+#' \item{terms}{The terms analyzed}
 #' @export
 #' @examples
 #' \donttest{
-#' lm.1<-lm(Employed~.,longley)
-#' da.ave.boot<-bootAverageDominanceAnalysis(lm.1,R=1000)
+#' lm.1 <- lm(Employed ~ ., longley)
+#' da.ave.boot <- bootAverageDominanceAnalysis(lm.1, R = 1000)
 #' summary(da.ave.boot)
 #' }
+#'
+#' @seealso \code{\link{dominanceAnalysis}}, \code{\link{boot}}
 
 bootAverageDominanceAnalysis<-function(x,R,constants=c(), terms = NULL, fit.functions="default",null.model=NULL, ...) {
   if (!requireNamespace("boot", quietly = TRUE)) { #nocov start

R/bootDominanceAnalysis.r

@@ -1,27 +1,38 @@
-#' Bootstrap analysis for Dominance Analysis
+#' Bootstrap Analysis for Dominance Analysis
 #'
-#' Bootstrap procedure as presented on Azen and Budescu (2003).
+#' Implements a bootstrap procedure as presented by Azen and Budescu (2003).
 #' Provides the expected level of dominance of predictor \eqn{X_i} over \eqn{X_j},
-#' as the degree to which the pattern found on sample is reproduced on the
+#' as the degree to which the pattern found in the sample is reproduced in the
 #' bootstrap samples.
-#' Use \code{summary()} to get a nice formatted data.frame
 #'
-#' @param x lm, glm or lmer model
-#' @param R number on bootstrap resamples
-#' @param constants vector of predictors to remain unchanged between models.
-#'                  i.e. vector of variables not subjected to bootstrap analysis.
-#' @param terms     vector of terms to be analyzed. By default, obtained from the model
-#' @param fit.functions list of functions which provides fit indices for model.
-#'                      See \code{fit.functions} param in \code{\link{dominanceAnalysis}}
-#'                      function.
-#' @param null.model only for linear mixed models, null model against to test the submodels.
-#'                   i.e. only random effects, without any fixed effect.
-#' @param ... Other arguments provided to lm or lmer (not implemented yet).
+#' Use \code{summary()} to obtain a nicely formatted \code{data.frame}.
+#'
+#' @param x An object of class \code{lm}, \code{glm}, or \code{lmer}.
+#' @param R The number of bootstrap resamples.
+#' @param constants A vector of predictors to remain unchanged between models,
+#'                  i.e., variables not subjected to bootstrap analysis.
+#' @param terms A vector of terms to be analyzed. By default, terms are obtained from the model.
+#' @param fit.functions A list of functions providing fit indices for the model.
+#'                      Refer to \code{fit.functions} parameter in \code{\link{dominanceAnalysis}} function.
+#' @param null.model Applicable only for linear mixed models. It refers to the null model against which to test the submodels,
+#'                   i.e., only random effects, without any fixed effects.
+#' @param ... Additional arguments provided to \code{lm} or \code{lmer} (not implemented yet).
+#' @return An object of class \code{bootDominanceAnalysis} containing:
+#'   \item{boot}{The results of the bootstrap analysis.}
+#'   \item{preds}{The predictors analyzed.}
+#'   \item{fit.functions}{The fit functions used in the analysis.}
+#'   \item{c.names}{A vector where each value represents the name of a specific dominance analysis result.
+#'                Names are prefixed with the type of dominance (complete, conditional, or general),
+#'                and the fit function used, followed by the names of the first and second predictors
+#'                involved in the comparison.}
+#'   \item{m.names}{Names of each one the predictor pairs.}
+#'   \item{terms}{The terms analyzed.}
+#'   \item{R}{The number of bootstrap resamples.}
 #' @export
 #' @examples
 #' \donttest{
-#' lm.1<-lm(Employed~.,longley)
-#' da.boot<-bootDominanceAnalysis(lm.1,R=1000)
+#' lm.1 <- lm(Employed ~ ., longley)
+#' da.boot <- bootDominanceAnalysis(lm.1, R = 1000)
 #' summary(da.boot)
 #' }
 bootDominanceAnalysis<-function(x,R,constants=c(),terms=NULL, fit.functions="default",null.model=NULL, ...) {

R/daFitFunctions.r

@@ -25,7 +25,8 @@ NULL
 #' @param original.model Original fitted model
 #' @param newdata Data used in update statement
 #' @param ... ignored
-#' @return A function described by \link{using-fit-indices} description for interface
+#' @return A function described by \link{using-fit-indices} description for interface.
+#'         You could retrieve \code{r2} index.
 #' @export
 #' @family fit indices
 #' @importFrom stats lm
@@ -54,14 +55,14 @@ da.lm.fit<-function(original.model, newdata=NULL, ...) {
 
 #' Provides fit indices for GLM models.
 #'
-#' FThese functions are only available for logistic regression models and are
+#' These functions are only available for logistic regression models and are
 #' based on the work of Azen and Traxel (2009).
 #'
 #' Check \link{daRawResults}.
 #' @param original.model Original fitted model
 #' @param newdata Data used in update statement
 #' @param ...  ignored
-#' @return A function described by \link{using-fit-indices}. You could retrieve following indices
+#' @return A function described by \link{using-fit-indices}. You could retrieve the following indices:
 #' \describe{
 #' \item{\code{r2.m}}{McFadden(1974)}
 #' \item{\code{r2.cs}}{Cox and Snell(1989). Use with caution, because don't have 1 as upper bound}
@@ -135,7 +136,7 @@ da.glm.fit<-function(original.model, newdata=NULL,...) {
 
 #' Provides fit indices for betareg models.
 #'
-#' Note that Nagelkerke and Estrella coefficients are designed for discrete dependent variables
+#' Note that the Nagelkerke and Estrella coefficients are designed for discrete dependent variables
 #' and thus cannot be used in this context. Instead, the Cox and Snell coefficient is recommended,
 #' along with the pseudo-\eqn{R^2}. It is worth noting that McFadden's index may produce
 #' negative values and should be avoided.
@@ -207,6 +208,8 @@ da.betareg.fit<-function(original.model, newdata=NULL, ...) {
 #' @param original.model Original fitted model
 #' @param newdata Data used in update statement
 #' @param ... ignored
+#' @return A function described by \link{using-fit-indices} description for interface.
+#'         You could retrieve \code{r2.n} index, corresponding to Nagelkerke method.
 #' @references
 #' \itemize{
 #' \item Nagelkerke, N. J. D. (1991). A Note on a General Definition of the Coefficient of Determination. Biometrika, 78(3), 691-692. doi:10.1093/biomet/78.3.691
@@ -243,16 +246,26 @@ da.clm.fit<-function(original.model, newdata=NULL, ...) {
 }
 
 
-#' Provides fit indices for hierarchical linear models, based on Nakagawa(2013) and Luo and Azen (2013).
+#' Provides fit indices for hierarchical linear models, based on
+#' Nakagawa et al.(2017) and Luo and Azen (2013).
 #'
 #' @param original.model Original fitted model
 #' @param null.model needed for HLM models
 #' @param newdata Data used in update statement
 #' @param ... ignored
+#' @return A function described by \link{using-fit-indices} description for interface.
+#'         By default, four indices are provided:
+#'         \item{rb.r2.1}{Amount of  Level-1 variance explained by the addition of the predictor. }
+#'         \item{rb.r2.2}{Amount of  Level-2 variance explained by the addition of the predictor.}
+#'         \item{sb.r2.1}{Proportional reduction in error of predicting scores at Level 1 }
+#'         \item{sb.r2.2}{Proportional reduction in  error of predicting cluster means at Level 2}
+#'         If \code{performance} library is available, the two following indices are also available:
+#'         \item{n.marg}{Marginal R2 coefficient based on Nakagawa et al. (2017). Considers only the variance of the fixed effects. }
+#'         \item{n.cond}{Conditional R2 coefficient based on Nakagawa et al. (2017). Takes both the fixed and random effects into account.}
 #' @references
 #' \itemize{
-#' \item Luo, W., & Azen, R. (2012). Determining Predictor Importance in Hierarchical Linear Models Using Dominance Analysis. Journal of Educational and Behavioral Statistics, 38(1), 3-31. doi:10.3102/1076998612458319
-#' \item Nakagawa, S., & Schielzeth, H. (2013). A general and simple method for obtaining R2 from generalized linear mixed-effects models. Methods in Ecology and Evolution, 4(2), 133-142. doi:10.1111/j.2041-210x.2012.00261.x
+#' \item Luo, W., & Azen, R. (2013). Determining Predictor Importance in Hierarchical Linear Models Using Dominance Analysis. Journal of Educational and Behavioral Statistics, 38(1), 3-31. doi:10.3102/1076998612458319
+#' \item Nakagawa, S., Johnson, P. C. D., and Schielzeth, H. (2017). The coefficient of determination R2 and intra-class correlation coefficient from generalized linear mixed-effects models revisited and expanded. Journal of The Royal Society Interface, 14(134), 20170213.
 #' }
 #' @family fit indices
 #' @export
@@ -299,12 +312,13 @@ da.lmerMod.fit<-function(original.model, null.model, newdata=NULL, ...) {
 
 #' Provides coefficient of determination for linear models, using covariance/correlation matrix.
 #'
-#' Uses \eqn{R^2} (coefficient of determination)
-#' See \code{\link{lmWithCov}}
+#' Uses \eqn{R^2} (coefficient of determination).
+#' See \code{\link{lmWithCov}}.
 #'
 #' @param base.cov variance/covariance matrix
 #' @param ... ignored
-#'
+#' @return A function described by \link{using-fit-indices} description for interface.
+#'         You could retrieve \code{r2} index.
 #' @family fit indices
 #' @export
 da.lmWithCov.fit<-function(base.cov, ...) {
@@ -324,8 +338,8 @@ da.lmWithCov.fit<-function(base.cov, ...) {
 #' @param ... ignored
 #' @return A list with several fit indices
 #' \describe{
-#' \item{\code{r.squared.xy}}{\eqn{R^2_{XY}}}
-#' \item{\code{p.squared.yx}}{\eqn{P^2_{YX}}}
+#' \item{\code{r.squared.xy}}{Corresponds to \eqn{R^2_{XY}}}
+#' \item{\code{p.squared.yx}}{Corresponds to \eqn{P^2_{YX}}}
 #' }
 #' See \code{\link{mlmWithCov}}
 #' @references

R/dominanceAnalysis.r

@@ -113,8 +113,10 @@ dominanceAnalysis <-
     class(z)<-c("dominanceAnalysis","list")
     z
   }
+#' Print the results of a dominanceAnalysis object
 #' @keywords internal
 #' @export
+#' @return an object of type \code{dominanceAnalysis}
 print.dominanceAnalysis<-function(x,...) {
   cat("\nDominance analysis\n")
   cat("Predictors:", paste0(x$predictors,collapse=", "),"\n")

R/lmmR2.r

@@ -1,6 +1,6 @@
 #' Calculates several measures of fit for Linear Mixed Models
 #' based on Lou and Azen (2013) text.
-#' Models could be lmer or lme models
+#' Models could be lmer or lme models.
 #' @param m.null Null model (only with random intercept effects)
 #' @param m.full Full model
 #' @return lmmR2 class
@@ -21,7 +21,7 @@ lmmR2<-function(m.null, m.full) {
 
 # Calculates coefficients of determination for different models on mer models
 #
-# Calculates the four R^2 presents on Lou and Azen (2013) text.
+# Calculates the four $R^2$ presents on Lou and Azen (2013) text.
 # Should extract the intercepts for each model
 lmmR2.mer<-function(m.null,m.full) {
   # First, I verify the group structure.
@@ -56,9 +56,10 @@ lmmR2.mer<-function(m.null,m.full) {
 
 
 
-#' Print method for  lmmR2 models summary
+#' Print method for lmmR2 object, that retrieves the summary.
 #' @param x    lmmR2 object
 #' @param ...  extra arguments for print
+#' @return an lmmR2 object
 #' @keywords internal
 
 print.lmmR2<-function(x,...) {
@@ -68,6 +69,7 @@ print.lmmR2<-function(x,...) {
 #' Print method for  lmmR2 models summary
 #' @param x    summary.lmmR2 object
 #' @param ...  unused
+#' @return a summary.lmmR2 object
 #' @keywords internal
 
 print.summary.lmmR2<-function(x, ...) {
@@ -78,12 +80,15 @@ print.summary.lmmR2<-function(x, ...) {
 	cat("Indeces:\n")
 	print(x$m2,row.names=F)
 	cat("\n")
-
+	invisible(x)
 }
 
 #' Summary for lmmR2 models
 #' @param object lmmR2 object
 #' @param ... unused
+#' @return An object of class \code{"summary.lmmR2"} containing:
+#' \item{m1}{A data frame with variance information and pseudo R-squared values}
+#' \item{m2}{A data frame with index information, meaning and values}
 #' @keywords internal
 
 summary.lmmR2<-function(object, ...) {

R/summary.bootAverageDominanceAnalysis.r

@@ -5,6 +5,10 @@
 #' @importFrom stats sd
 #' @export
 #' @keywords internal
+#' @return An object \code{summary.bootAverageDominanceAnalysis},
+#'         that containts a list of data frames containing
+#'         summary statistics for each fit index.
+
 
 summary.bootAverageDominanceAnalysis<-function(object, fit.functions=NULL, ...) {
 	bs.mean<-colMeans(object$boot$t)

R/summary.bootDominanceAnalysis.r

@@ -5,6 +5,9 @@
 #' @importFrom stats sd
 #' @export
 #' @keywords internal
+#' @return An object \code{summary.bootDominanceAnalysis}, that contains
+#'         data frames with bootstrap summary statistics for each fit index
+
 
 summary.bootDominanceAnalysis<-function(object,fit.functions=NULL,...) {
 	out<-list()
@@ -43,10 +46,11 @@ summary.bootDominanceAnalysis<-function(object,fit.functions=NULL,...) {
 	out
 }
 
-# Print a summary.bootDominanceAnalysis object
-# @param x a \code{\link{summary.bootDominanceAnalysis}} object
-# @param round.digits Number of decimal places to round results
-# @param ... further arguments passed to print method
+#' Print a summary.bootDominanceAnalysis object
+#' @param x a \code{\link{summary.bootDominanceAnalysis}} object
+#' @param round.digits Number of decimal places to round results
+#' @param ... further arguments passed to print method
+#' @return an object \code{\link{summary.bootDominanceAnalysis}}
 #' @export
 #' @keywords internal
 
@@ -60,5 +64,6 @@ print.summary.bootDominanceAnalysis<-function(x,round.digits=3,...) {
 		cat("\n")
 
 	}
+	invisible(x)
 }
 

R/summary.dominanceAnalysis.r

@@ -51,6 +51,7 @@ summary.dominanceAnalysis<-function(object, ...) {
 #' @param x a \code{\link{summary.dominanceAnalysis}} object
 #' @param round.digits Number of decimal places to round results
 #' @param ... further arguments passed to print method
+#' @return a summary.dominanceAnalysis object
 #' @keywords internal
 #' @export
 print.summary.dominanceAnalysis<-function(x, round.digits=3,...) {
@@ -70,4 +71,5 @@ print.summary.dominanceAnalysis<-function(x, round.digits=3,...) {
     }
     print(data.frame(lapply(x[[fit]]$summary.matrix,delete.na)), row.names=F, ...)
   }
+  invisible(x)
 }

README.Rmd

@@ -12,7 +12,8 @@ knitr::opts_chunk$set(
   out.width = "100%"
 )
 ```
-# dominanceanalysis
+# dominanceanalysis <img src='logo/dominance_analysis_logo.png' align="right" height="139" />
+
 
 [![codecov](https://codecov.io/gh/clbustos/dominanceAnalysis/branch/master/graph/badge.svg)](https://app.codecov.io/gh/clbustos/dominanceAnalysis)
 [![Stable version](http://www.r-pkg.org/badges/version-last-release/dominanceanalysis)](https://cran.r-project.org/package=dominanceanalysis)

README.md

@@ -1,7 +1,7 @@
 
 <!-- README.md is generated from README.Rmd. Please edit that file -->
 
-# dominanceanalysis
+# dominanceanalysis <img src='logo/dominance_analysis_logo.png' align="right" height="139" />
 
 [![codecov](https://codecov.io/gh/clbustos/dominanceAnalysis/branch/master/graph/badge.svg)](https://app.codecov.io/gh/clbustos/dominanceAnalysis)
 [![Stable

cran-comments.md

@@ -1,4 +1,31 @@
-## New version: 2.1.0
+## New version: 2.1.0, first resubmission
+
+Added \value tags to .Rd files regarding exported methods and, explaining
+the functions results in the documentation. 
+
+Missing Rd-tags that were resolved:
+      bootAverageDominanceAnalysis.Rd: \value
+      bootDominanceAnalysis.Rd: \value
+      da.clm.fit.Rd: \value
+      da.lmerMod.fit.Rd: \value
+      da.lmWithCov.fit.Rd: \value
+      print.lmmR2.Rd: \value
+      print.summary.dominanceAnalysis.Rd: \value
+      print.summary.lmmR2.Rd: \value
+      summary.bootAverageDominanceAnalysis.Rd: \value
+      summary.bootDominanceAnalysis.Rd: \value
+      summary.lmmR2.Rd: \value
+
+Local check:
+
+0 errors ✔ | 0 warnings ✔ | 0 notes ✔
+
+Check on win-builder-stable: Note regarding new submission
+
+Check on rhub Windows Server 2022, R-devel, 64 bit: same notes as first submission
+
+## First submission message from now on
+
 
 This is a minor release, to provide a version of dominanceAnalysis that complies
 with current requirements of CRAN.