From e46a5de4f06e43a361528a412795b97c26ab8596 Mon Sep 17 00:00:00 2001 From: Indrajeet Patil Date: Sat, 20 Apr 2024 13:53:51 +0200 Subject: [PATCH] Use Markdown syntax in roxygen docs cf. https://github.com/easystats/easystats/issues/187 --- R/bayesfactor_parameters.R | 55 ++++++++++++++--------------- R/effective_sample.R | 14 +++++--- R/equivalence_test.R | 29 +++++++++------- R/mediation.R | 7 ++-- R/sexit.R | 65 +++++++++++++++++++---------------- R/weighted_posteriors.R | 12 +++---- man/bayesfactor_parameters.Rd | 6 ++-- man/bayesfactor_restricted.Rd | 6 ++-- man/effective_sample.Rd | 7 +++- man/equivalence_test.Rd | 8 ++++- man/mediation.Rd | 1 - man/sexit.Rd | 33 ++++++++++-------- man/si.Rd | 6 ++-- man/weighted_posteriors.Rd | 4 +-- 14 files changed, 142 insertions(+), 111 deletions(-) diff --git a/R/bayesfactor_parameters.R b/R/bayesfactor_parameters.R index 4e22b1663..6e1b2e832 100644 --- a/R/bayesfactor_parameters.R +++ b/R/bayesfactor_parameters.R @@ -86,25 +86,22 @@ #' See example below.) #' \cr\cr #' It is important to provide the correct `prior` for meaningful results. -#' \itemize{ -#' \item When `posterior` is a numerical vector, `prior` should also be a numerical vector. -#' \item When `posterior` is a `data.frame`, `prior` should also be a `data.frame`, with matching column order. -#' \item When `posterior` is a `stanreg`, `brmsfit` or other supported Bayesian model: \itemize{ -#' \item `prior` can be set to `NULL`, in which case prior samples are drawn internally. -#' \item `prior` can also be a model equivalent to `posterior` but with samples from -#' the priors *only*. See [unupdate()]. -#' \item **Note:** When `posterior` is a `brmsfit_multiple` model, `prior` **must** be provided. -#' } -#' \item When `posterior` is an `emmGrid` / `emm_list` object: \itemize{ -#' \item `prior` should also be an `emmGrid` / `emm_list` object equivalent to `posterior` but -#' created with a model of priors samples *only*. See [unupdate()]. -#' \item `prior` can also be the original (posterior) *model*. If so, the function will try to -#' update the `emmGrid` / `emm_list` to use the [unupdate()]d prior-model. -#' (*This cannot be done for `brmsfit` models.*) -#' \item **Note**: When the `emmGrid` has undergone any transformations (`"log"`, `"response"`, etc.), -#' or `regrid`ing, then `prior` must be an `emmGrid` object, as stated above. -#' } -#' } +#' +#' - When `posterior` is a numerical vector, `prior` should also be a numerical vector. +#' - When `posterior` is a `data.frame`, `prior` should also be a `data.frame`, with matching column order. +#' - When `posterior` is a `stanreg`, `brmsfit` or other supported Bayesian model: +#' - `prior` can be set to `NULL`, in which case prior samples are drawn internally. +#' - `prior` can also be a model equivalent to `posterior` but with samples from +#' the priors *only*. See [unupdate()]. +#' - **Note:** When `posterior` is a `brmsfit_multiple` model, `prior` **must** be provided. +#' - When `posterior` is an `emmGrid` / `emm_list` object: +#' - `prior` should also be an `emmGrid` / `emm_list` object equivalent to `posterior` but +#' created with a model of priors samples *only*. See [unupdate()]. +#' - `prior` can also be the original (posterior) *model*. If so, the function will try to +#' update the `emmGrid` / `emm_list` to use the [unupdate()]d prior-model. +#' (*This cannot be done for `brmsfit` models.*) +#' - **Note**: When the `emmGrid` has undergone any transformations (`"log"`, `"response"`, etc.), +#' or `regrid`ing, then `prior` must be an `emmGrid` object, as stated above. #' #' @section Interpreting Bayes Factors: #' A Bayes factor greater than 1 can be interpreted as evidence against the @@ -161,26 +158,30 @@ #' } #' #' @references -#' \itemize{ -#' \item Wagenmakers, E. J., Lodewyckx, T., Kuriyal, H., and Grasman, R. (2010). +#' +#' - Wagenmakers, E. J., Lodewyckx, T., Kuriyal, H., and Grasman, R. (2010). #' Bayesian hypothesis testing for psychologists: A tutorial on the #' Savage-Dickey method. Cognitive psychology, 60(3), 158-189. -#' \item Heck, D. W. (2019). A caveat on the Savage–Dickey density ratio: The +#' +#' - Heck, D. W. (2019). A caveat on the Savage–Dickey density ratio: The #' case of computing Bayes factors for regression parameters. British Journal of #' Mathematical and Statistical Psychology, 72(2), 316-333. -#' \item Morey, R. D., & Wagenmakers, E. J. (2014). Simple relation between +#' +#' - Morey, R. D., & Wagenmakers, E. J. (2014). Simple relation between #' Bayesian order-restricted and point-null hypothesis tests. Statistics & #' Probability Letters, 92, 121-124. -#' \item Morey, R. D., & Rouder, J. N. (2011). Bayes factor approaches for +#' +#' - Morey, R. D., & Rouder, J. N. (2011). Bayes factor approaches for #' testing interval null hypotheses. Psychological methods, 16(4), 406. -#' \item Liao, J. G., Midya, V., & Berg, A. (2020). Connecting and contrasting +#' +#' - Liao, J. G., Midya, V., & Berg, A. (2020). Connecting and contrasting #' the Bayes factor and a modified ROPE procedure for testing interval null #' hypotheses. The American Statistician, 1-19. -#' \item Wetzels, R., Matzke, D., Lee, M. D., Rouder, J. N., Iverson, G. J., and +#' +#' - Wetzels, R., Matzke, D., Lee, M. D., Rouder, J. N., Iverson, G. J., and #' Wagenmakers, E.-J. (2011). Statistical Evidence in Experimental Psychology: #' An Empirical Comparison Using 855 t Tests. Perspectives on Psychological #' Science, 6(3), 291–298. \doi{10.1177/1745691611406923} -#' } #' #' @author Mattan S. Ben-Shachar #' diff --git a/R/effective_sample.R b/R/effective_sample.R index 454146a26..fa81bd5d5 100644 --- a/R/effective_sample.R +++ b/R/effective_sample.R @@ -8,12 +8,16 @@ #' #' @return A data frame with two columns: Parameter name and effective sample size (ESS). #' -#' @details **Effective Sample (ESS)** should be as large as possible, altough for most applications, an effective sample size greater than 1,000 is sufficient for stable estimates (Bürkner, 2017). The ESS corresponds to the number of independent samples with the same estimation power as the N autocorrelated samples. It is is a measure of \dQuote{how much independent information there is in autocorrelated chains} (*Kruschke 2015, p182-3*). +#' @details **Effective Sample (ESS)** should be as large as possible, altough +#' for most applications, an effective sample size greater than 1,000 is +#' sufficient for stable estimates (Bürkner, 2017). The ESS corresponds to the +#' number of independent samples with the same estimation power as the N +#' autocorrelated samples. It is is a measure of \dQuote{how much independent +#' information there is in autocorrelated chains} (*Kruschke 2015, p182-3*). #' -#' @references \itemize{ -#' \item Kruschke, J. (2014). Doing Bayesian data analysis: A tutorial with R, JAGS, and Stan. Academic Press. -#' \item Bürkner, P. C. (2017). brms: An R package for Bayesian multilevel models using Stan. Journal of Statistical Software, 80(1), 1-28 -#' } +#' @references +#' - Kruschke, J. (2014). Doing Bayesian data analysis: A tutorial with R, JAGS, and Stan. Academic Press. +#' - Bürkner, P. C. (2017). brms: An R package for Bayesian multilevel models using Stan. Journal of Statistical Software, 80(1), 1-28 #' #' @examplesIf require("rstanarm") #' \donttest{ diff --git a/R/equivalence_test.R b/R/equivalence_test.R index 5d4a9226b..99c19e433 100644 --- a/R/equivalence_test.R +++ b/R/equivalence_test.R @@ -3,13 +3,17 @@ #' Perform a **Test for Practical Equivalence** for Bayesian and frequentist models. #' #' Documentation is accessible for: -#' \itemize{ -#' \item [Bayesian models](https://easystats.github.io/bayestestR/reference/equivalence_test.html) -#' \item [Frequentist models](https://easystats.github.io/parameters/reference/equivalence_test.lm.html) -#' } #' -#' For Bayesian models, the **Test for Practical Equivalence** is based on the *"HDI+ROPE decision rule"* (\cite{Kruschke, 2014, 2018}) to check whether parameter values should be accepted or rejected against an explicitly formulated "null hypothesis" (i.e., a ROPE). In other words, it checks the percentage of the `89%` [HDI][hdi] that is the null region (the ROPE). If this percentage is sufficiently low, the null hypothesis is rejected. If this percentage is sufficiently high, the null hypothesis is accepted. +#' - [Bayesian models](https://easystats.github.io/bayestestR/reference/equivalence_test.html) +#' - [Frequentist models](https://easystats.github.io/parameters/reference/equivalence_test.lm.html) #' +#' For Bayesian models, the **Test for Practical Equivalence** is based on the +#' *"HDI+ROPE decision rule"* (\cite{Kruschke, 2014, 2018}) to check whether +#' parameter values should be accepted or rejected against an explicitly +#' formulated "null hypothesis" (i.e., a ROPE). In other words, it checks the +#' percentage of the `89%` [HDI][hdi] that is the null region (the ROPE). If +#' this percentage is sufficiently low, the null hypothesis is rejected. If this +#' percentage is sufficiently high, the null hypothesis is accepted. #' #' @inheritParams rope #' @@ -54,14 +58,13 @@ #' - Piironen, J., & Vehtari, A. (2017). Comparison of Bayesian predictive methods for model selection. Statistics and Computing, 27(3), 711–735. \doi{10.1007/s11222-016-9649-y} #' #' @return A data frame with following columns: -#' \itemize{ -#' \item `Parameter` The model parameter(s), if `x` is a model-object. If `x` is a vector, this column is missing. -#' \item `CI` The probability of the HDI. -#' \item `ROPE_low`, `ROPE_high` The limits of the ROPE. These values are identical for all parameters. -#' \item `ROPE_Percentage` The proportion of the HDI that lies inside the ROPE. -#' \item `ROPE_Equivalence` The "test result", as character. Either "rejected", "accepted" or "undecided". -#' \item `HDI_low` , `HDI_high` The lower and upper HDI limits for the parameters. -#' } +#' +#' - `Parameter` The model parameter(s), if `x` is a model-object. If `x` is a vector, this column is missing. +#' - `CI` The probability of the HDI. +#' - `ROPE_low`, `ROPE_high` The limits of the ROPE. These values are identical for all parameters. +#' - `ROPE_Percentage` The proportion of the HDI that lies inside the ROPE. +#' - `ROPE_Equivalence` The "test result", as character. Either "rejected", "accepted" or "undecided". +#' - `HDI_low` , `HDI_high` The lower and upper HDI limits for the parameters. #' #' @note There is a `print()`-method with a `digits`-argument to control #' the amount of digits in the output, and there is a diff --git a/R/mediation.R b/R/mediation.R index ba939cabe..c8b664265 100644 --- a/R/mediation.R +++ b/R/mediation.R @@ -62,15 +62,14 @@ #' different \pkg{bayestestR} package. #' #' @references -#' \itemize{ -#' \item Imai, K., Keele, L. and Tingley, D. (2010) A General Approach to Causal +#' +#' - Imai, K., Keele, L. and Tingley, D. (2010) A General Approach to Causal #' Mediation Analysis, Psychological Methods, Vol. 15, No. 4 (December), pp. #' 309-334. #' -#' \item Tingley, D., Yamamoto, T., Hirose, K., Imai, K. and Keele, L. (2014). +#' - Tingley, D., Yamamoto, T., Hirose, K., Imai, K. and Keele, L. (2014). #' mediation: R package for Causal Mediation Analysis, Journal of Statistical #' Software, Vol. 59, No. 5, pp. 1-38. -#' } #' #' @seealso The \pkg{mediation} package for a causal mediation analysis in #' the frequentist framework. diff --git a/R/sexit.R b/R/sexit.R index e2f1516f0..1adebdf19 100644 --- a/R/sexit.R +++ b/R/sexit.R @@ -1,30 +1,35 @@ #' Sequential Effect eXistence and sIgnificance Testing (SEXIT) #' +#' @description +#' #' The SEXIT is a new framework to describe Bayesian effects, guiding which #' indices to use. Accordingly, the `sexit()` function returns the minimal (and #' optimal) required information to describe models' parameters under a Bayesian #' framework. It includes the following indices: -#' \itemize{ -#' \item{Centrality: the median of the posterior distribution. In +#' +#' - Centrality: the median of the posterior distribution. In #' probabilistic terms, there is `50%` of probability that the effect is higher -#' and lower. See [`point_estimate()`][point_estimate].} -#' \item{Uncertainty: the `95%` Highest Density Interval (HDI). In +#' and lower. See [`point_estimate()`][point_estimate]. +#' +#' - Uncertainty: the `95%` Highest Density Interval (HDI). In #' probabilistic terms, there is `95%` of probability that the effect is -#' within this confidence interval. See [`ci()`][ci].} -#' \item{Existence: The probability of direction allows to quantify the +#' within this confidence interval. See [`ci()`][ci]. +#' +#' - Existence: The probability of direction allows to quantify the #' certainty by which an effect is positive or negative. It is a critical #' index to show that an effect of some manipulation is not harmful (for #' instance in clinical studies) or to assess the direction of a link. See -#' [`p_direction()`][p_direction].} -#' \item{Significance: Once existence is demonstrated with high certainty, we +#' [`p_direction()`][p_direction]. +#' +#' - Significance: Once existence is demonstrated with high certainty, we #' can assess whether the effect is of sufficient size to be considered as #' significant (i.e., not negligible). This is a useful index to determine #' which effects are actually important and worthy of discussion in a given -#' process. See [`p_significance()`][p_significance].} -#' \item{Size: Finally, this index gives an idea about the strength of an +#' process. See [`p_significance()`][p_significance]. +#' +#' - Size: Finally, this index gives an idea about the strength of an #' effect. However, beware, as studies have shown that a big effect size can -#' be also suggestive of low statistical power (see details section).} -#' } +#' be also suggestive of low statistical power (see details section). #' #' @inheritParams p_direction #' @inheritParams hdi @@ -77,29 +82,31 @@ #' option, and might not be adapted to your case. Thus, they are to be handled #' with care, and the chosen thresholds should always be explicitly reported #' and justified. -#' \itemize{ -#' \item For **linear models (lm)**, this can be generalised to \ifelse{html}{\out{0.05 * SDy}}{\eqn{[0.05*SD_{y}]}} and \ifelse{html}{\out{0.3 * SDy}}{\eqn{[0.3*SD_{y}]}} for significant and large effects, respectively. -#' \item For **logistic models**, the parameters expressed in log odds ratio can be converted to standardized difference through the formula \ifelse{html}{\out{π/√(3)}}{\eqn{\pi/\sqrt{3}}}, resulting a threshold of `0.09` and `0.54`. -#' \item For other models with **binary outcome**, it is strongly recommended to manually specify the rope argument. Currently, the same default is applied that for logistic models. -#' \item For models from **count data**, the residual variance is used. This is a rather experimental threshold and is probably often similar to `0.05` and `0.3`, but should be used with care! -#' \item For **t-tests**, the standard deviation of the response is used, similarly to linear models (see above). -#' \item For **correlations**,`0.05` and `0.3` are used. -#' \item For all other models, `0.05` and `0.3` are used, but it is strongly advised to specify it manually. -#' } +#' +#' - For **linear models (lm)**, this can be generalised to \ifelse{html}{\out{0.05 * SDy}}{\eqn{[0.05*SD_{y}]}} and \ifelse{html}{\out{0.3 * SDy}}{\eqn{[0.3*SD_{y}]}} for significant and large effects, respectively. +#' - For **logistic models**, the parameters expressed in log odds ratio can be converted to standardized difference through the formula \ifelse{html}{\out{π/√(3)}}{\eqn{\pi/\sqrt{3}}}, resulting a threshold of `0.09` and `0.54`. +#' - For other models with **binary outcome**, it is strongly recommended to manually specify the rope argument. Currently, the same default is applied that for logistic models. +#' - For models from **count data**, the residual variance is used. This is a rather experimental threshold and is probably often similar to `0.05` and `0.3`, but should be used with care! +#' - For **t-tests**, the standard deviation of the response is used, similarly to linear models (see above). +#' - For **correlations**,`0.05` and `0.3` are used. +#' - For all other models, `0.05` and `0.3` are used, but it is strongly advised to specify it manually. #' } +#' #' \subsection{Examples}{ #' The three values for existence, significance and size provide a useful description of the posterior distribution of the effects. Some possible scenarios include: -#' \itemize{ -#' \item{The probability of existence is low, but the probability of being large is high: it suggests that the posterior is very wide (covering large territories on both side of 0). The statistical power might be too low, which should warrant any confident conclusion.} -#' \item{The probability of existence and significance is high, but the probability of being large is very small: it suggests that the effect is, with high confidence, not large (the posterior is mostly contained between the significance and the large thresholds).} -#' \item{The 3 indices are very low: this suggests that the effect is null with high confidence (the posterior is closely centred around 0).}}} +#' +#' - The probability of existence is low, but the probability of being large is high: it suggests that the posterior is very wide (covering large territories on both side of 0). The statistical power might be too low, which should warrant any confident conclusion. +#' - The probability of existence and significance is high, but the probability of being large is very small: it suggests that the effect is, with high confidence, not large (the posterior is mostly contained between the significance and the large thresholds). +#' - The 3 indices are very low: this suggests that the effect is null with high confidence (the posterior is closely centred around 0). +#' } #' #' @return A dataframe and text as attribute. #' -#' @references \itemize{ -#' \item{Makowski, D., Ben-Shachar, M. S., & Lüdecke, D. (2019). bayestestR: Describing Effects and their Uncertainty, Existence and Significance within the Bayesian Framework. Journal of Open Source Software, 4(40), 1541. \doi{10.21105/joss.01541}} -#' \item{Makowski D, Ben-Shachar MS, Chen SHA, Lüdecke D (2019) Indices of Effect Existence and Significance in the Bayesian Framework. Frontiers in Psychology 2019;10:2767. \doi{10.3389/fpsyg.2019.02767}} -#' } +#' @references +#' +#' - Makowski, D., Ben-Shachar, M. S., & Lüdecke, D. (2019). bayestestR: Describing Effects and their Uncertainty, Existence and Significance within the Bayesian Framework. Journal of Open Source Software, 4(40), 1541. \doi{10.21105/joss.01541} +#' +#' - Makowski D, Ben-Shachar MS, Chen SHA, Lüdecke D (2019) Indices of Effect Existence and Significance in the Bayesian Framework. Frontiers in Psychology 2019;10:2767. \doi{10.3389/fpsyg.2019.02767} #' #' @examples #' \donttest{ diff --git a/R/weighted_posteriors.R b/R/weighted_posteriors.R index d9f8a9c1b..230c2771b 100644 --- a/R/weighted_posteriors.R +++ b/R/weighted_posteriors.R @@ -108,23 +108,23 @@ #' hdi(wp[1:5]) # between, but closer to pred_m1 #' } #' } +#' #' @references -#' \itemize{ -#' \item Clyde, M., Desimone, H., & Parmigiani, G. (1996). Prediction via +#' +#' - Clyde, M., Desimone, H., & Parmigiani, G. (1996). Prediction via #' orthogonalized model mixing. Journal of the American Statistical #' Association, 91(435), 1197-1208. #' -#' \item Hinne, M., Gronau, Q. F., van den Bergh, D., and Wagenmakers, E. +#' - Hinne, M., Gronau, Q. F., van den Bergh, D., and Wagenmakers, E. #' (2019, March 25). A conceptual introduction to Bayesian Model Averaging. #' \doi{10.31234/osf.io/wgb64} #' -#' \item Rouder, J. N., Haaf, J. M., & Vandekerckhove, J. (2018). Bayesian +#' - Rouder, J. N., Haaf, J. M., & Vandekerckhove, J. (2018). Bayesian #' inference for psychology, part IV: Parameter estimation and Bayes factors. #' Psychonomic bulletin & review, 25(1), 102-113. #' -#' \item van den Bergh, D., Haaf, J. M., Ly, A., Rouder, J. N., & Wagenmakers, +#' - van den Bergh, D., Haaf, J. M., Ly, A., Rouder, J. N., & Wagenmakers, #' E. J. (2019). A cautionary note on estimating effect size. -#' } #' #' @export weighted_posteriors <- function(..., prior_odds = NULL, missing = 0, verbose = TRUE) { diff --git a/man/bayesfactor_parameters.Rd b/man/bayesfactor_parameters.Rd index ecb576b72..f44a6652c 100644 --- a/man/bayesfactor_parameters.Rd +++ b/man/bayesfactor_parameters.Rd @@ -232,13 +232,15 @@ It is important to provide the correct \code{prior} for meaningful results. \itemize{ \item When \code{posterior} is a numerical vector, \code{prior} should also be a numerical vector. \item When \code{posterior} is a \code{data.frame}, \code{prior} should also be a \code{data.frame}, with matching column order. -\item When \code{posterior} is a \code{stanreg}, \code{brmsfit} or other supported Bayesian model: \itemize{ +\item When \code{posterior} is a \code{stanreg}, \code{brmsfit} or other supported Bayesian model: +\itemize{ \item \code{prior} can be set to \code{NULL}, in which case prior samples are drawn internally. \item \code{prior} can also be a model equivalent to \code{posterior} but with samples from the priors \emph{only}. See \code{\link[=unupdate]{unupdate()}}. \item \strong{Note:} When \code{posterior} is a \code{brmsfit_multiple} model, \code{prior} \strong{must} be provided. } -\item When \code{posterior} is an \code{emmGrid} / \code{emm_list} object: \itemize{ +\item When \code{posterior} is an \code{emmGrid} / \code{emm_list} object: +\itemize{ \item \code{prior} should also be an \code{emmGrid} / \code{emm_list} object equivalent to \code{posterior} but created with a model of priors samples \emph{only}. See \code{\link[=unupdate]{unupdate()}}. \item \code{prior} can also be the original (posterior) \emph{model}. If so, the function will try to diff --git a/man/bayesfactor_restricted.Rd b/man/bayesfactor_restricted.Rd index 45d211fe7..cf73c6fc8 100644 --- a/man/bayesfactor_restricted.Rd +++ b/man/bayesfactor_restricted.Rd @@ -123,13 +123,15 @@ It is important to provide the correct \code{prior} for meaningful results. \itemize{ \item When \code{posterior} is a numerical vector, \code{prior} should also be a numerical vector. \item When \code{posterior} is a \code{data.frame}, \code{prior} should also be a \code{data.frame}, with matching column order. -\item When \code{posterior} is a \code{stanreg}, \code{brmsfit} or other supported Bayesian model: \itemize{ +\item When \code{posterior} is a \code{stanreg}, \code{brmsfit} or other supported Bayesian model: +\itemize{ \item \code{prior} can be set to \code{NULL}, in which case prior samples are drawn internally. \item \code{prior} can also be a model equivalent to \code{posterior} but with samples from the priors \emph{only}. See \code{\link[=unupdate]{unupdate()}}. \item \strong{Note:} When \code{posterior} is a \code{brmsfit_multiple} model, \code{prior} \strong{must} be provided. } -\item When \code{posterior} is an \code{emmGrid} / \code{emm_list} object: \itemize{ +\item When \code{posterior} is an \code{emmGrid} / \code{emm_list} object: +\itemize{ \item \code{prior} should also be an \code{emmGrid} / \code{emm_list} object equivalent to \code{posterior} but created with a model of priors samples \emph{only}. See \code{\link[=unupdate]{unupdate()}}. \item \code{prior} can also be the original (posterior) \emph{model}. If so, the function will try to diff --git a/man/effective_sample.Rd b/man/effective_sample.Rd index d0de21129..50c8aac01 100644 --- a/man/effective_sample.Rd +++ b/man/effective_sample.Rd @@ -50,7 +50,12 @@ A data frame with two columns: Parameter name and effective sample size (ESS). This function returns the effective sample size (ESS). } \details{ -\strong{Effective Sample (ESS)} should be as large as possible, altough for most applications, an effective sample size greater than 1,000 is sufficient for stable estimates (Bürkner, 2017). The ESS corresponds to the number of independent samples with the same estimation power as the N autocorrelated samples. It is is a measure of \dQuote{how much independent information there is in autocorrelated chains} (\emph{Kruschke 2015, p182-3}). +\strong{Effective Sample (ESS)} should be as large as possible, altough +for most applications, an effective sample size greater than 1,000 is +sufficient for stable estimates (Bürkner, 2017). The ESS corresponds to the +number of independent samples with the same estimation power as the N +autocorrelated samples. It is is a measure of \dQuote{how much independent +information there is in autocorrelated chains} (\emph{Kruschke 2015, p182-3}). } \examples{ \dontshow{if (require("rstanarm")) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} diff --git a/man/equivalence_test.Rd b/man/equivalence_test.Rd index 249162a02..8f7b44326 100644 --- a/man/equivalence_test.Rd +++ b/man/equivalence_test.Rd @@ -91,7 +91,13 @@ Documentation is accessible for: \item \href{https://easystats.github.io/parameters/reference/equivalence_test.lm.html}{Frequentist models} } -For Bayesian models, the \strong{Test for Practical Equivalence} is based on the \emph{"HDI+ROPE decision rule"} (\cite{Kruschke, 2014, 2018}) to check whether parameter values should be accepted or rejected against an explicitly formulated "null hypothesis" (i.e., a ROPE). In other words, it checks the percentage of the \verb{89\%} \link[=hdi]{HDI} that is the null region (the ROPE). If this percentage is sufficiently low, the null hypothesis is rejected. If this percentage is sufficiently high, the null hypothesis is accepted. +For Bayesian models, the \strong{Test for Practical Equivalence} is based on the +\emph{"HDI+ROPE decision rule"} (\cite{Kruschke, 2014, 2018}) to check whether +parameter values should be accepted or rejected against an explicitly +formulated "null hypothesis" (i.e., a ROPE). In other words, it checks the +percentage of the \verb{89\%} \link[=hdi]{HDI} that is the null region (the ROPE). If +this percentage is sufficiently low, the null hypothesis is rejected. If this +percentage is sufficiently high, the null hypothesis is accepted. Using the \link[=rope]{ROPE} and the \link[=hdi]{HDI}, \cite{Kruschke (2018)} suggests using the percentage of the \verb{95\%} (or \verb{89\%}, considered more stable) diff --git a/man/mediation.Rd b/man/mediation.Rd index c3cca5e0d..51dc3d778 100644 --- a/man/mediation.Rd +++ b/man/mediation.Rd @@ -151,7 +151,6 @@ mediation(m3, centrality = "mean", ci = 0.95) \item Imai, K., Keele, L. and Tingley, D. (2010) A General Approach to Causal Mediation Analysis, Psychological Methods, Vol. 15, No. 4 (December), pp. 309-334. - \item Tingley, D., Yamamoto, T., Hirose, K., Imai, K. and Keele, L. (2014). mediation: R package for Causal Mediation Analysis, Journal of Statistical Software, Vol. 59, No. 5, pp. 1-38. diff --git a/man/sexit.Rd b/man/sexit.Rd index a8218f53c..2c8c58475 100644 --- a/man/sexit.Rd +++ b/man/sexit.Rd @@ -28,25 +28,25 @@ indices to use. Accordingly, the \code{sexit()} function returns the minimal (an optimal) required information to describe models' parameters under a Bayesian framework. It includes the following indices: \itemize{ -\item{Centrality: the median of the posterior distribution. In +\item Centrality: the median of the posterior distribution. In probabilistic terms, there is \verb{50\%} of probability that the effect is higher -and lower. See \code{\link[=point_estimate]{point_estimate()}}.} -\item{Uncertainty: the \verb{95\%} Highest Density Interval (HDI). In +and lower. See \code{\link[=point_estimate]{point_estimate()}}. +\item Uncertainty: the \verb{95\%} Highest Density Interval (HDI). In probabilistic terms, there is \verb{95\%} of probability that the effect is -within this confidence interval. See \code{\link[=ci]{ci()}}.} -\item{Existence: The probability of direction allows to quantify the +within this confidence interval. See \code{\link[=ci]{ci()}}. +\item Existence: The probability of direction allows to quantify the certainty by which an effect is positive or negative. It is a critical index to show that an effect of some manipulation is not harmful (for instance in clinical studies) or to assess the direction of a link. See -\code{\link[=p_direction]{p_direction()}}.} -\item{Significance: Once existence is demonstrated with high certainty, we +\code{\link[=p_direction]{p_direction()}}. +\item Significance: Once existence is demonstrated with high certainty, we can assess whether the effect is of sufficient size to be considered as significant (i.e., not negligible). This is a useful index to determine which effects are actually important and worthy of discussion in a given -process. See \code{\link[=p_significance]{p_significance()}}.} -\item{Size: Finally, this index gives an idea about the strength of an +process. See \code{\link[=p_significance]{p_significance()}}. +\item Size: Finally, this index gives an idea about the strength of an effect. However, beware, as studies have shown that a big effect size can -be also suggestive of low statistical power (see details section).} +be also suggestive of low statistical power (see details section). } } \details{ @@ -103,12 +103,15 @@ and justified. \item For all other models, \code{0.05} and \code{0.3} are used, but it is strongly advised to specify it manually. } } + \subsection{Examples}{ The three values for existence, significance and size provide a useful description of the posterior distribution of the effects. Some possible scenarios include: \itemize{ -\item{The probability of existence is low, but the probability of being large is high: it suggests that the posterior is very wide (covering large territories on both side of 0). The statistical power might be too low, which should warrant any confident conclusion.} -\item{The probability of existence and significance is high, but the probability of being large is very small: it suggests that the effect is, with high confidence, not large (the posterior is mostly contained between the significance and the large thresholds).} -\item{The 3 indices are very low: this suggests that the effect is null with high confidence (the posterior is closely centred around 0).}}} +\item The probability of existence is low, but the probability of being large is high: it suggests that the posterior is very wide (covering large territories on both side of 0). The statistical power might be too low, which should warrant any confident conclusion. +\item The probability of existence and significance is high, but the probability of being large is very small: it suggests that the effect is, with high confidence, not large (the posterior is mostly contained between the significance and the large thresholds). +\item The 3 indices are very low: this suggests that the effect is null with high confidence (the posterior is closely centred around 0). +} +} } \examples{ \donttest{ @@ -135,7 +138,7 @@ if (require("rstanarm")) { } \references{ \itemize{ -\item{Makowski, D., Ben-Shachar, M. S., & Lüdecke, D. (2019). bayestestR: Describing Effects and their Uncertainty, Existence and Significance within the Bayesian Framework. Journal of Open Source Software, 4(40), 1541. \doi{10.21105/joss.01541}} -\item{Makowski D, Ben-Shachar MS, Chen SHA, Lüdecke D (2019) Indices of Effect Existence and Significance in the Bayesian Framework. Frontiers in Psychology 2019;10:2767. \doi{10.3389/fpsyg.2019.02767}} +\item Makowski, D., Ben-Shachar, M. S., & Lüdecke, D. (2019). bayestestR: Describing Effects and their Uncertainty, Existence and Significance within the Bayesian Framework. Journal of Open Source Software, 4(40), 1541. \doi{10.21105/joss.01541} +\item Makowski D, Ben-Shachar MS, Chen SHA, Lüdecke D (2019) Indices of Effect Existence and Significance in the Bayesian Framework. Frontiers in Psychology 2019;10:2767. \doi{10.3389/fpsyg.2019.02767} } } diff --git a/man/si.Rd b/man/si.Rd index 5fea658df..c6f769240 100644 --- a/man/si.Rd +++ b/man/si.Rd @@ -154,13 +154,15 @@ It is important to provide the correct \code{prior} for meaningful results. \itemize{ \item When \code{posterior} is a numerical vector, \code{prior} should also be a numerical vector. \item When \code{posterior} is a \code{data.frame}, \code{prior} should also be a \code{data.frame}, with matching column order. -\item When \code{posterior} is a \code{stanreg}, \code{brmsfit} or other supported Bayesian model: \itemize{ +\item When \code{posterior} is a \code{stanreg}, \code{brmsfit} or other supported Bayesian model: +\itemize{ \item \code{prior} can be set to \code{NULL}, in which case prior samples are drawn internally. \item \code{prior} can also be a model equivalent to \code{posterior} but with samples from the priors \emph{only}. See \code{\link[=unupdate]{unupdate()}}. \item \strong{Note:} When \code{posterior} is a \code{brmsfit_multiple} model, \code{prior} \strong{must} be provided. } -\item When \code{posterior} is an \code{emmGrid} / \code{emm_list} object: \itemize{ +\item When \code{posterior} is an \code{emmGrid} / \code{emm_list} object: +\itemize{ \item \code{prior} should also be an \code{emmGrid} / \code{emm_list} object equivalent to \code{posterior} but created with a model of priors samples \emph{only}. See \code{\link[=unupdate]{unupdate()}}. \item \code{prior} can also be the original (posterior) \emph{model}. If so, the function will try to diff --git a/man/weighted_posteriors.Rd b/man/weighted_posteriors.Rd index 77d154fc9..c5a60bc54 100644 --- a/man/weighted_posteriors.Rd +++ b/man/weighted_posteriors.Rd @@ -177,21 +177,19 @@ if (require("rstanarm") && interactive()) { hdi(wp[1:5]) # between, but closer to pred_m1 } } + } \references{ \itemize{ \item Clyde, M., Desimone, H., & Parmigiani, G. (1996). Prediction via orthogonalized model mixing. Journal of the American Statistical Association, 91(435), 1197-1208. - \item Hinne, M., Gronau, Q. F., van den Bergh, D., and Wagenmakers, E. (2019, March 25). A conceptual introduction to Bayesian Model Averaging. \doi{10.31234/osf.io/wgb64} - \item Rouder, J. N., Haaf, J. M., & Vandekerckhove, J. (2018). Bayesian inference for psychology, part IV: Parameter estimation and Bayes factors. Psychonomic bulletin & review, 25(1), 102-113. - \item van den Bergh, D., Haaf, J. M., Ly, A., Rouder, J. N., & Wagenmakers, E. J. (2019). A cautionary note on estimating effect size. }