Use Markdown syntax in roxygen docs

cf. easystats/easystats#187

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
 #'

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{

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

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.

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 * SD<sub>y</sub>}}{\eqn{[0.05*SD_{y}]}} and \ifelse{html}{\out{0.3 * SD<sub>y</sub>}}{\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{&pi;/&radic;(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 * SD<sub>y</sub>}}{\eqn{[0.05*SD_{y}]}} and \ifelse{html}{\out{0.3 * SD<sub>y</sub>}}{\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{&pi;/&radic;(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{

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) {