Expand on returned value

#227

Author: mattansb

R/adjust.R

@@ -1,13 +1,29 @@
 #' Adjust data for the effect of other variable(s)
 #'
-#' This function can be used to adjust the data for the effect of other variables present in the dataset. It is based on an underlying fitting of regressions models, allowing for quite some flexibility, such as including factors as random effects in mixed models (multilevel partialization), continuous variables as smooth terms in general additive models (non-linear partialization) and/or fitting these models under a Bayesian framework. The values returned by this function are the residuals of the regression models. Note that a regular correlation between two "adjusted" variables is equivalent to the partial correlation between them.
+#' This function can be used to adjust the data for the effect of other
+#' variables present in the dataset. It is based on an underlying fitting of
+#' regressions models, allowing for quite some flexibility, such as including
+#' factors as random effects in mixed models (multilevel partialization),
+#' continuous variables as smooth terms in general additive models (non-linear
+#' partialization) and/or fitting these models under a Bayesian framework. The
+#' values returned by this function are the residuals of the regression models.
+#' Note that a regular correlation between two "adjusted" variables is
+#' equivalent to the partial correlation between them.
 #'
 #' @param data A dataframe.
-#' @param effect Character vector of column names to be adjusted for (regressed out). If `NULL` (the default), all variables will be selected.
+#' @param effect Character vector of column names to be adjusted for (regressed
+#'   out). If `NULL` (the default), all variables will be selected.
 #' @inheritParams standardize
-#' @param multilevel If `TRUE`, the factors are included as random factors. Else, if `FALSE` (default), they are included as fixed effects in the simple regression model.
-#' @param additive If `TRUE`, continuous variables as included as smooth terms in additive models. The goal is to regress-out potential non-linear effects.
-#' @param bayesian If `TRUE`, the models are fitted under the Bayesian framework using `rstanarm`.
+#' @param multilevel If `TRUE`, the factors are included as random factors.
+#'   Else, if `FALSE` (default), they are included as fixed effects in the
+#'   simple regression model.
+#' @param additive If `TRUE`, continuous variables as included as smooth terms
+#'   in additive models. The goal is to regress-out potential non-linear
+#'   effects.
+#' @param bayesian If `TRUE`, the models are fitted under the Bayesian framework
+#'   using `rstanarm`.
+#'
+#' @return A data frame comparable to `data`, with adjusted variables.
 #'
 #' @examples
 #' adjust(iris, effect = "Species", select = "Sepal.Length")

R/cohens_d.R

@@ -40,7 +40,8 @@
 #' tail-probabilities, and then convert these `ncp`s to the corresponding effect
 #' sizes.
 #'
-#' @return A data frame with the effect size(s) and confidence interval(s).
+#' @return A data frame with the effect size ( `Cohens_d`, `Hedges_g`,
+#'   `Glass_delta`) and their CIs (`CI_low` and `CI_high`).
 #'
 #' @seealso [d_to_common_language()] [sd_pooled()]
 #' @family effect size indices

R/convert_OR_to_RR.R

@@ -4,6 +4,8 @@
 #' @param p0 Baseline risk
 #' @inheritParams oddsratio_to_d
 #'
+#' @return Converted index.
+#'
 #' @family convert between effect sizes
 #'
 #' @examples

R/convert_chisq.R

@@ -11,7 +11,8 @@
 #' @param adjust Should the effect size be bias-corrected? Defaults to `FALSE`.
 #' @param ... Arguments passed to or from other methods.
 #'
-#' @return A data frame with the effect size(s) between 0-1, and confidence interval(s).
+#' @return A data frame with the effect size(s) between 0-1, and confidence
+#'   interval(s). See [cramers_v()].
 #'
 #' @details These functions use the following formulae:
 #' \cr

R/convert_d_to_common_language.R

@@ -10,6 +10,8 @@
 #' \cr\cr
 #' \deqn{Pr(superiority) = \Phi(d/\sqrt{2})}
 #'
+#' @return A list of `Cohen's U3`, `Overlap`, `Probability of superiority`.
+#'
 #' @note
 #' These calculations assume that the populations have equal variance and are
 #' normally distributed.

R/convert_odds_to_probs.R

@@ -9,6 +9,8 @@
 #' from transformation.
 #' @param ... Arguments passed to or from other methods.
 #'
+#' @return Converted index.
+#'
 #' @seealso [stats::plogis()]
 #' @family convert between effect sizes
 #'

R/convert_tF_to_pve.R

@@ -15,9 +15,12 @@
 #' @inheritParams chisq_to_phi
 #' @param ... Arguments passed to or from other methods.
 #'
-#' @return A data frame with the effect size(s) between 0-1, and confidence interval(s) (Note that for \eqn{\omega_p^2} and \eqn{\epsilon_p^2}
-#' it is possible to compute a negative number; even though this doesn't make any practical sense,
-#' it is recommended to report the negative number and not a 0).
+#' @return A data frame with the effect size(s) between 0-1 (`Eta2_partial`,
+#'   `Epsilon2_partial`, `Omega2_partial`, `Cohens_f_partial` or
+#'   `Cohens_f2_partial`), and their CIs (`CI_low` and `CI_high`). (Note that
+#'   for \eqn{\omega_p^2} and \eqn{\epsilon_p^2} it is possible to compute a
+#'   negative number; even though this doesn't make any practical sense, it is
+#'   recommended to report the negative number and not a 0).
 #'
 #' @details These functions use the following formulae:
 #' \cr

R/convert_tFz_to_r.R

@@ -2,22 +2,27 @@
 
 #' Convert test statistics (t, z, F) to effect sizes of differences (Cohen's d) or association (**partial** r)
 #'
-#' These functions are convenience functions to convert t, z and F test statistics to Cohen's d and
-#' **partial** r. These are useful in cases where the data required to compute these are not easily
-#' available or their computation is not straightforward (e.g., in liner mixed models, contrasts, etc.).
+#' These functions are convenience functions to convert t, z and F test
+#' statistics to Cohen's d and **partial** r. These are useful in cases where
+#' the data required to compute these are not easily available or their
+#' computation is not straightforward (e.g., in liner mixed models, contrasts,
+#' etc.).
 #' \cr
 #' See [Effect Size from Test Statistics vignette.](https://easystats.github.io/effectsize/articles/from_test_statistics.html)
 #'
 #' @param t,f,z The t, the F or the z statistics.
-#' @param df,df_error Degrees of freedom of numerator or of the error estimate (i.e., the residuals).
+#' @param df,df_error Degrees of freedom of numerator or of the error estimate
+#'   (i.e., the residuals).
 #' @param n The number of observations (the sample size).
-#' @param paired Should the estimate accout for the t-value being testing the difference between dependant means?
+#' @param paired Should the estimate accout for the t-value being testing the
+#'   difference between dependant means?
 #' @param pooled Deprecated. Use `paired`.
 #' @inheritParams chisq_to_phi
 #' @param ... Arguments passed to or from other methods.
 #'
 #'
-#' @return A data frame with the effect size(s) between 0-1, and confidence interval(s)
+#' @return A data frame with the effect size(s)(`r` or `d`), and their CIs
+#'   (`CI_low` and `CI_high`).
 #'
 #'
 #' @details These functions use the following formulae to approximate *r* and *d*:

R/effectsize.R

@@ -24,6 +24,9 @@
 #' **For statistical models it is recommended to directly use the listed
 #' functions, for the full range of options they provide.**
 #'
+#' @return A data frame with the effect size (depending on input) and and its
+#'   CIs (`CI_low` and `CI_high`).
+#'
 #' @family effect size indices
 #'
 #' @examples

R/equivalence_test.R

@@ -35,7 +35,7 @@ bayestestR::equivalence_test
 #'
 #' @seealso For more details, see [bayestestR::equivalence_test()].
 #'
-#' @return A data frame.
+#' @return A data frame with the results of the equivalence test.
 #'
 #' @references
 #' - Campbell, H., & Gustafson, P. (2018). Conditional equivalence testing: An alternative remedy for publication bias. PLOS ONE, 13(4), e0195145. https://doi.org/10.1371/journal.pone.0195145

R/eta_squared.R

@@ -24,7 +24,9 @@
 #' @param ... For Bayesian models, passed to `ss_function`. Otherwise ignored.
 #'
 #' @return
-#' A data frame with the effect size(s) and confidence interval(s).
+#' A data frame with the effect size(s) between 0-1 (`Eta2`, `Epsilon2`,
+#' `Omega2`, `Cohens_f` or `Cohens_f2`, possibly with the `partial` or
+#' `generalized` suffix), and their CIs (`CI_low` and `CI_high`).
 #' \cr\cr
 #' For `eta_squared_posterior()`, a data frame containing the ppd of the Eta
 #' squared for each fixed effect, which can then be passed to
@@ -58,6 +60,10 @@
 #' Though Omega is the more popular choice (Albers \& Lakens, 2018), Epsilon is
 #' analogous to adjusted R2 (Allen, 2017, p. 382), and has been found to be less
 #' biased (Carroll & Nordholm, 1975).
+#' \cr\cr
+#' (Note that for \eqn{\omega_p^2} and \eqn{\epsilon_p^2} it is possible to
+#' compute a negative number; even though this doesn't make any practical sense,
+#' it is recommended to report the negative number and not a 0.)
 #'
 #' ## Cohen's f
 #' Cohen's f can take on values between zero, when the population means are all

R/normalize.R

@@ -25,6 +25,7 @@
 #' @family transform utilities
 #'
 #' @return A normalized object.
+#'
 #' @export
 normalize <- function(x, ...) {
   UseMethod("normalize")

R/ranktransform.R

@@ -14,6 +14,7 @@
 #' ranktransform(c(0, 1, 5, -5, -2), sign = TRUE)
 #'
 #' head(ranktransform(iris))
+#'
 #' @return A rank-transformed object.
 #'
 #' @family transform utilities

R/standardize_info.R

@@ -6,6 +6,11 @@
 #' @param include_pseudo (For (G)LMMs) Should Pseudo-standardized information be included?
 #' @param ... Arguments passed to or from other methods.
 #'
+#' @return A data frame with information on each parameter (see
+#'   [parameters::parameters_type]), and various standardization coefficients
+#'   for the post-hoc methods (see [standardize_parameters()]) for the predictor
+#'   and the response.
+#'
 #' @family standardize
 #'
 #' @examples

R/standardize_parameters.R

@@ -80,10 +80,14 @@
 #' coefficients (e.g., in a binomial model: the exponent of the standardized
 #' parameter is the OR of a change of 1 SD in the predictor, etc.)
 #'
-#' @return A data frame with the standardized parameters and their CIs.
+#' @return A data frame with the standardized parameters (`Std_*`, depending on
+#'   the model type) and their CIs (`CI_low` and `CI_high`). Where applicable,
+#'   standard errors (SEs) are returned as an attribute (`attr(x,
+#'   "standard_error")`).
 #'
 #' @family standardize
 #' @family effect size indices
+#' @seealso [standardize_info()]
 #'
 #' @examples
 #' library(effectsize)
@@ -125,10 +129,6 @@
 #' }
 #' }
 #'
-#' @seealso [standardize_info()]
-#'
-#' @return Standardized parameters table.
-#'
 #' @references
 #' - Hoffman, L. (2015). Longitudinal analysis: Modeling within-person fluctuation and change. Routledge.
 #' - Neter, J., Wasserman, W., & Kutner, M. H. (1989). Applied linear regression models.

R/xtab.R

@@ -43,7 +43,9 @@
 #' @inheritSection cohens_d Confidence Intervals
 #' @inheritSection chisq_to_phi CI Contains Zero
 #'
-#' @return A data frame with the effect size(s), and confidence interval(s).
+#' @return A data frame with the effect size (`Cramers_v`, `phi` (possibly with
+#'   the suffix `_adjusted`), `Odds_ratio`, `Risk_ratio` (possibly with the
+#'   prefix `log_`), or `Cohens_g`) and its CIs (`CI_low` and `CI_high`).
 #'
 #' @seealso [chisq_to_phi()] for details regarding estimation and CIs.
 #' @family effect size indices