+
+
+
+Amrhein, V., Korner-Nievergelt, F., & Roth, T. (2017). The earth is flat
+( *p* \> 0.05): Significance thresholds and the crisis of unreplicable
+research. *PeerJ*, *5*, e3544.
+
+
+
+
+
+Greenland, S., Rafi, Z., Matthews, R., & Higgs, M. (2022). *To Aid
+Scientific Inference, Emphasize Unconditional Compatibility Descriptions
+of Statistics*. Retrieved from
+
+
+
+
+
+Lakens, D. (2024). *Improving Your Statistical Inferences*.
+
+
+
+
+
+
+Lakens, D., Scheel, A. M., & Isager, P. M. (2018). Equivalence testing
+for psychological research: A tutorial. *Advances in Methods and
+Practices in Psychological Science*, *1*(2), 259–269.
+
+
+
+
+
+
+Makowski, D., Ben-Shachar, M. S., Chen, S. H. A., & Lüdecke, D. (2019).
+Indices of Effect Existence and Significance in the Bayesian Framework.
+*Frontiers in Psychology*, *10*, 2767.
+
+
+
+
+
+
+Rafi, Z., & Greenland, S. (2020). Semantic and cognitive tools to aid
+statistical science: Replace confidence and significance by
+compatibility and surprise. *BMC Medical Research Methodology*, *20*(1),
+244.
+
+
+
+
+
+Schweder, T. (2018). Confidence is epistemic probability for empirical
+science. *Journal of Statistical Planning and Inference*, *195*,
+116–125.
+
+
+
+
+
+Schweder, T., & Hjort, N. L. (2003). Frequentist Analogues of Priors and
+Posteriors. In B. Stigum (Ed.), *Econometrics and the Philosophy of
+Economics: Theory-Data Confrontations in Economics* (pp. 285–217).
+Retrieved from
+
+
+
+
+
+Vos, P., & Holbert, D. (2022). Frequentist statistical inference without
+repeated sampling. *Synthese*, *200*(2), 89.
+
+
+
+
+
}}\preformatted{# simulate full normal distribution
+out <- bayestestR::distribution_normal(10000, 0, 0.5)
+# range of "full" distribution
+range(out)
+# range of 95\% CI
+round(quantile(out, probs = c(0.025, 0.975)), 2)
+}\if{html}{\out{
}}
+
+This ensures that the SGPV always refers to the general compatible parameter
+space of coefficients, independent from the confidence interval chosen for
+testing practical equivalence. Therefore, the SGPV of the \emph{full interval} is
+similar to the ROPE coverage of Bayesian equivalence tests, see following
+code:
+
+\if{html}{\out{}}\preformatted{library(bayestestR)
+library(brms)
+m <- lm(mpg ~ gear + wt + cyl + hp, data = mtcars)
+m2 <- brm(mpg ~ gear + wt + cyl + hp, data = mtcars)
+# SGPV for frequentist models
+equivalence_test(m)
+# similar to ROPE coverage of Bayesian models
+equivalence_test(m2)
+# similar to ROPE coverage of simulated draws / bootstrap samples
+equivalence_test(simulate_model(m))
+}\if{html}{\out{
}}
}
\subsection{ROPE range}{
@@ -158,13 +226,73 @@ for further information.
There is also a \href{https://easystats.github.io/see/articles/parameters.html}{\code{plot()}-method}
implemented in the \href{https://easystats.github.io/see/}{\strong{see}-package}.
}
+\section{Statistical inference - how to quantify evidence}{
+
+There is no standardized approach to drawing conclusions based on the
+available data and statistical models. A frequently chosen but also much
+criticized approach is to evaluate results based on their statistical
+significance (\emph{Amrhein et al. 2017}).
+
+A more sophisticated way would be to test whether estimated effects exceed
+the "smallest effect size of interest", to avoid even the smallest effects
+being considered relevant simply because they are statistically significant,
+but clinically or practically irrelevant (\emph{Lakens et al. 2018, Lakens 2024}).
+
+A rather unconventional approach, which is nevertheless advocated by various
+authors, is to interpret results from classical regression models either in
+terms of probabilities, similar to the usual approach in Bayesian statistics
+(\emph{Schweder 2018; Schweder and Hjort 2003; Vos 2022}) or in terms of relative
+measure of "evidence" or "compatibility" with the data (\emph{Greenland et al. 2022;
+Rafi and Greenland 2020}), which nevertheless comes close to a probabilistic
+interpretation.
+
+A more detailed discussion of this topic is found in the documentation of
+\code{\link[=p_function]{p_function()}}.
+
+The \strong{parameters} package provides several options or functions to aid
+statistical inference. These are, for example:
+\itemize{
+\item \code{\link[=equivalence_test.lm]{equivalence_test()}}, to compute the (conditional)
+equivalence test for frequentist models
+\item \code{\link[=p_significance.lm]{p_significance()}}, to compute the probability of
+\emph{practical significance}, which can be conceptualized as a unidirectional
+equivalence test
+\item \code{\link[=p_function]{p_function()}}, or \emph{consonance function}, to compute p-values and
+compatibility (confidence) intervals for statistical models
+\item the \code{pd} argument (setting \code{pd = TRUE}) in \code{model_parameters()} includes
+a column with the \emph{probability of direction}, i.e. the probability that a
+parameter is strictly positive or negative. See \code{\link[bayestestR:p_direction]{bayestestR::p_direction()}}
+for details. If plotting is desired, the \code{\link[=p_direction.lm]{p_direction()}}
+function can be used, together with \code{plot()}.
+\item the \code{s_value} argument (setting \code{s_value = TRUE}) in \code{model_parameters()}
+replaces the p-values with their related \emph{S}-values (\emph{Rafi and Greenland 2020})
+\item finally, it is possible to generate distributions of model coefficients by
+generating bootstrap-samples (setting \code{bootstrap = TRUE}) or simulating
+draws from model coefficients using \code{\link[=simulate_model]{simulate_model()}}. These samples
+can then be treated as "posterior samples" and used in many functions from
+the \strong{bayestestR} package.
+}
+
+Most of the above shown options or functions derive from methods originally
+implemented for Bayesian models (\emph{Makowski et al. 2019}). However, assuming
+that model assumptions are met (which means, the model fits well to the data,
+the correct model is chosen that reflects the data generating process
+(distributional model family) etc.), it seems appropriate to interpret
+results from classical frequentist models in a "Bayesian way" (more details:
+documentation in \code{\link[=p_function]{p_function()}}).
+}
+
\examples{
+\dontshow{if (requireNamespace("sandwich")) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
data(qol_cancer)
model <- lm(QoL ~ time + age + education, data = qol_cancer)
# default rule
equivalence_test(model)
+# using heteroscedasticity-robust standard errors
+equivalence_test(model, vcov = "HC3")
+
# conditional equivalence test
equivalence_test(model, rule = "cet")
@@ -173,9 +301,13 @@ if (require("see", quietly = TRUE)) {
result <- equivalence_test(model)
plot(result)
}
+\dontshow{\}) # examplesIf}
}
\references{
\itemize{
+\item Amrhein, V., Korner-Nievergelt, F., and Roth, T. (2017). The earth is
+flat (p > 0.05): Significance thresholds and the crisis of unreplicable
+research. PeerJ, 5, e3544. \doi{10.7717/peerj.3544}
\item Blume, J. D., D'Agostino McGowan, L., Dupont, W. D., & Greevy, R. A.
(2018). Second-generation p-values: Improved rigor, reproducibility, &
transparency in statistical analyses. PLOS ONE, 13(3), e0188299.
@@ -183,6 +315,9 @@ https://doi.org/10.1371/journal.pone.0188299
\item Campbell, H., & Gustafson, P. (2018). Conditional equivalence
testing: An alternative remedy for publication bias. PLOS ONE, 13(4),
e0195145. doi: 10.1371/journal.pone.0195145
+\item Greenland S, Rafi Z, Matthews R, Higgs M. To Aid Scientific Inference,
+Emphasize Unconditional Compatibility Descriptions of Statistics. (2022)
+https://arxiv.org/abs/1909.08583v7 (Accessed November 10, 2022)
\item Kruschke, J. K. (2014). Doing Bayesian data analysis: A tutorial with
R, JAGS, and Stan. Academic Press
\item Kruschke, J. K. (2018). Rejecting or accepting parameter values in
@@ -191,15 +326,37 @@ Science, 1(2), 270-280. doi: 10.1177/2515245918771304
\item Lakens, D. (2017). Equivalence Tests: A Practical Primer for t Tests,
Correlations, and Meta-Analyses. Social Psychological and Personality
Science, 8(4), 355–362. doi: 10.1177/1948550617697177
-\item Lakens, D., & Delacre, M. (2020). Equivalence Testing and the Second
+\item Lakens, D. (2024). Improving Your Statistical Inferences (Version v1.5.1).
+Retrieved from https://lakens.github.io/statistical_inferences/.
+\doi{10.5281/ZENODO.6409077}
+\item Lakens, D., and Delacre, M. (2020). Equivalence Testing and the Second
Generation P-Value. Meta-Psychology, 4.
https://doi.org/10.15626/MP.2018.933
+\item Lakens, D., Scheel, A. M., and Isager, P. M. (2018). Equivalence Testing
+for Psychological Research: A Tutorial. Advances in Methods and Practices
+in Psychological Science, 1(2), 259–269. \doi{10.1177/2515245918770963}
+\item Makowski, D., Ben-Shachar, M. S., Chen, S. H. A., and Lüdecke, D. (2019).
+Indices of Effect Existence and Significance in the Bayesian Framework.
+Frontiers in Psychology, 10, 2767. \doi{10.3389/fpsyg.2019.02767}
\item Pernet, C. (2017). Null hypothesis significance testing: A guide to
commonly misunderstood concepts and recommendations for good practice.
F1000Research, 4, 621. doi: 10.12688/f1000research.6963.5
+\item Rafi Z, Greenland S. Semantic and cognitive tools to aid statistical
+science: replace confidence and significance by compatibility and surprise.
+BMC Medical Research Methodology (2020) 20:244.
+\item Schweder T. Confidence is epistemic probability for empirical science.
+Journal of Statistical Planning and Inference (2018) 195:116–125.
+\doi{10.1016/j.jspi.2017.09.016}
+\item Schweder T, Hjort NL. Frequentist analogues of priors and posteriors.
+In Stigum, B. (ed.), Econometrics and the Philosophy of Economics: Theory
+Data Confrontation in Economics, pp. 285-217. Princeton University Press,
+Princeton, NJ, 2003
+\item Vos P, Holbert D. Frequentist statistical inference without repeated sampling.
+Synthese 200, 89 (2022). \doi{10.1007/s11229-022-03560-x}
}
}
\seealso{
-For more details, see \code{\link[bayestestR:equivalence_test]{bayestestR::equivalence_test()}}.
-Further readings can be found in the references.
+For more details, see \code{\link[bayestestR:equivalence_test]{bayestestR::equivalence_test()}}. Further
+readings can be found in the references. See also \code{\link[=p_significance]{p_significance()}} for
+a unidirectional equivalence test.
}
diff --git a/man/format_parameters.Rd b/man/format_parameters.Rd
index 05a5dc25f..08f65b89d 100644
--- a/man/format_parameters.Rd
+++ b/man/format_parameters.Rd
@@ -28,7 +28,7 @@ to make them more human-readable.
Note that the \emph{interpretation} of interaction terms depends on many
characteristics of the model. The number of parameters, and overall
-performance of the model, can differ \emph{or not} between \code{a * b}
+performance of the model, can differ \emph{or not} between \code{a * b},
\code{a : b}, and \code{a / b}, suggesting that sometimes interaction terms
give different parameterizations of the same model, but other times it gives
completely different models (depending on \code{a} or \code{b} being factors
diff --git a/man/model_parameters.BFBayesFactor.Rd b/man/model_parameters.BFBayesFactor.Rd
index 328e25f3d..9b67ccb4f 100644
--- a/man/model_parameters.BFBayesFactor.Rd
+++ b/man/model_parameters.BFBayesFactor.Rd
@@ -14,11 +14,9 @@
rope_range = "default",
rope_ci = 0.95,
priors = TRUE,
- effectsize_type = NULL,
+ es_type = NULL,
include_proportions = FALSE,
verbose = TRUE,
- cohens_d = NULL,
- cramers_v = NULL,
...
)
}
@@ -51,16 +49,17 @@ For each "test", the corresponding \pkg{bayestestR} function is called
(e.g. \code{\link[bayestestR:rope]{rope()}} or \code{\link[bayestestR:p_direction]{p_direction()}}) and its results
included in the summary output.}
-\item{rope_range}{ROPE's lower and higher bounds. Should be a list of two
-values (e.g., \code{c(-0.1, 0.1)}) or \code{"default"}. If \code{"default"},
-the bounds are set to \code{x +- 0.1*SD(response)}.}
+\item{rope_range}{ROPE's lower and higher bounds. Should be a vector of two
+values (e.g., \code{c(-0.1, 0.1)}), \code{"default"} or a list of numeric vectors of
+the same length as numbers of parameters. If \code{"default"}, the bounds are
+set to \code{x +- 0.1*SD(response)}.}
\item{rope_ci}{The Credible Interval (CI) probability, corresponding to the
proportion of HDI, to use for the percentage in ROPE.}
\item{priors}{Add the prior used for each parameter.}
-\item{effectsize_type}{The effect size of interest. Not that possibly not all
+\item{es_type}{The effect size of interest. Not that possibly not all
effect sizes are applicable to the model object. See 'Details'. For Anova
models, can also be a character vector with multiple effect size names.}
@@ -71,8 +70,6 @@ information is often redundant.}
\item{verbose}{Toggle off warnings.}
-\item{cohens_d, cramers_v}{Deprecated. Please use \code{effectsize_type}.}
-
\item{...}{Additional arguments to be passed to or from methods.}
}
\value{
@@ -97,22 +94,26 @@ the \emph{g} parameters; See the \emph{Bayes Factors for ANOVAs} paper
}
}
\examples{
+\dontshow{if (require("BayesFactor")) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
\donttest{
-if (require("BayesFactor")) {
- # Bayesian t-test
- model <- ttestBF(x = rnorm(100, 1, 1))
- model_parameters(model)
- model_parameters(model, cohens_d = TRUE, ci = .9)
+# Bayesian t-test
+model <- BayesFactor::ttestBF(x = rnorm(100, 1, 1))
+model_parameters(model)
+model_parameters(model, es_type = "cohens_d", ci = 0.9)
- # Bayesian contingency table analysis
- data(raceDolls)
- bf <- contingencyTableBF(raceDolls, sampleType = "indepMulti", fixedMargin = "cols")
- model_parameters(bf,
- centrality = "mean",
- dispersion = TRUE,
- verbose = FALSE,
- effectsize_type = "cramers_v"
- )
-}
+# Bayesian contingency table analysis
+data(raceDolls)
+bf <- BayesFactor::contingencyTableBF(
+ raceDolls,
+ sampleType = "indepMulti",
+ fixedMargin = "cols"
+)
+model_parameters(bf,
+ centrality = "mean",
+ dispersion = TRUE,
+ verbose = FALSE,
+ es_type = "cramers_v"
+)
}
+\dontshow{\}) # examplesIf}
}
diff --git a/man/model_parameters.Rd b/man/model_parameters.Rd
index d124d2cc9..c3e5dc2f1 100644
--- a/man/model_parameters.Rd
+++ b/man/model_parameters.Rd
@@ -99,7 +99,7 @@ models). This method is particularly recommended for complex models that
include interactions or transformations (e.g., polynomial or spline terms).
The \code{robust} (default to \code{FALSE}) argument enables a robust standardization
of data, i.e., based on the \code{median} and \code{MAD} instead of the \code{mean} and
-\code{SD}. \strong{See \code{\link[=standardize]{standardize()}} for more details.}
+\code{SD}. \strong{See \code{\link[datawizard:standardize]{datawizard::standardize()}} for more details.}
\strong{Note} that \code{standardize_parameters(method = "refit")} may not return
the same results as fitting a model on data that has been standardized with
\code{standardize()}; \code{standardize_parameters()} used the data used by the model
@@ -321,11 +321,67 @@ p-values are based on the probability of direction (\code{\link[bayestestR:p_dir
which is converted into a p-value using \code{\link[bayestestR:pd_to_p]{bayestestR::pd_to_p()}}.
}
+\section{Statistical inference - how to quantify evidence}{
+
+There is no standardized approach to drawing conclusions based on the
+available data and statistical models. A frequently chosen but also much
+criticized approach is to evaluate results based on their statistical
+significance (\emph{Amrhein et al. 2017}).
+
+A more sophisticated way would be to test whether estimated effects exceed
+the "smallest effect size of interest", to avoid even the smallest effects
+being considered relevant simply because they are statistically significant,
+but clinically or practically irrelevant (\emph{Lakens et al. 2018, Lakens 2024}).
+
+A rather unconventional approach, which is nevertheless advocated by various
+authors, is to interpret results from classical regression models either in
+terms of probabilities, similar to the usual approach in Bayesian statistics
+(\emph{Schweder 2018; Schweder and Hjort 2003; Vos 2022}) or in terms of relative
+measure of "evidence" or "compatibility" with the data (\emph{Greenland et al. 2022;
+Rafi and Greenland 2020}), which nevertheless comes close to a probabilistic
+interpretation.
+
+A more detailed discussion of this topic is found in the documentation of
+\code{\link[=p_function]{p_function()}}.
+
+The \strong{parameters} package provides several options or functions to aid
+statistical inference. These are, for example:
+\itemize{
+\item \code{\link[=equivalence_test.lm]{equivalence_test()}}, to compute the (conditional)
+equivalence test for frequentist models
+\item \code{\link[=p_significance.lm]{p_significance()}}, to compute the probability of
+\emph{practical significance}, which can be conceptualized as a unidirectional
+equivalence test
+\item \code{\link[=p_function]{p_function()}}, or \emph{consonance function}, to compute p-values and
+compatibility (confidence) intervals for statistical models
+\item the \code{pd} argument (setting \code{pd = TRUE}) in \code{model_parameters()} includes
+a column with the \emph{probability of direction}, i.e. the probability that a
+parameter is strictly positive or negative. See \code{\link[bayestestR:p_direction]{bayestestR::p_direction()}}
+for details. If plotting is desired, the \code{\link[=p_direction.lm]{p_direction()}}
+function can be used, together with \code{plot()}.
+\item the \code{s_value} argument (setting \code{s_value = TRUE}) in \code{model_parameters()}
+replaces the p-values with their related \emph{S}-values (\emph{Rafi and Greenland 2020})
+\item finally, it is possible to generate distributions of model coefficients by
+generating bootstrap-samples (setting \code{bootstrap = TRUE}) or simulating
+draws from model coefficients using \code{\link[=simulate_model]{simulate_model()}}. These samples
+can then be treated as "posterior samples" and used in many functions from
+the \strong{bayestestR} package.
+}
+
+Most of the above shown options or functions derive from methods originally
+implemented for Bayesian models (\emph{Makowski et al. 2019}). However, assuming
+that model assumptions are met (which means, the model fits well to the data,
+the correct model is chosen that reflects the data generating process
+(distributional model family) etc.), it seems appropriate to interpret
+results from classical frequentist models in a "Bayesian way" (more details:
+documentation in \code{\link[=p_function]{p_function()}}).
+}
+
\section{Interpretation of Interaction Terms}{
Note that the \emph{interpretation} of interaction terms depends on many
characteristics of the model. The number of parameters, and overall
-performance of the model, can differ \emph{or not} between \code{a * b}
+performance of the model, can differ \emph{or not} between \code{a * b},
\code{a : b}, and \code{a / b}, suggesting that sometimes interaction terms
give different parameterizations of the same model, but other times it gives
completely different models (depending on \code{a} or \code{b} being factors
@@ -346,12 +402,12 @@ warnings for the different functions in the \strong{parameters} package. However
some messages providing additional information can be displayed or suppressed
using \code{options()}:
\itemize{
-\item \code{parameters_summary}: \code{options(parameters_summary = TRUE)} will override the
-\code{summary} argument in \code{model_parameters()} and always show the model summary
-for non-mixed models.
-\item \code{parameters_mixed_summary}: \code{options(parameters_mixed_summary = TRUE)} will
-override the \code{summary} argument in \code{model_parameters()} for mixed models, and
-will then always show the model summary.
+\item \code{parameters_info}: \code{options(parameters_info = TRUE)} will override the
+\code{include_info} argument in \code{model_parameters()} and always show the model
+summary for non-mixed models.
+\item \code{parameters_mixed_info}: \code{options(parameters_mixed_info = TRUE)} will
+override the \code{include_info} argument in \code{model_parameters()} for mixed
+models, and will then always show the model summary.
\item \code{parameters_cimethod}: \code{options(parameters_cimethod = TRUE)} will show the
additional information about the approximation method used to calculate
confidence intervals and p-values. Set to \code{FALSE} to hide this message when
@@ -377,18 +433,45 @@ options.
\item \code{easystats_html_engine}: \code{options(easystats_html_engine = "gt")} will set
the default HTML engine for tables to \code{gt}, i.e. the \emph{gt} package is used to
create HTML tables. If set to \code{tt}, the \emph{tinytable} package is used.
+\item \code{insight_use_symbols}: \code{options(insight_use_symbols = TRUE)} will try to
+print unicode-chars for symbols as column names, wherever possible (e.g.,
+\ifelse{html}{\out{ω}}{\eqn{\omega}} instead of \code{Omega}).
}
}
\references{
\itemize{
+\item Amrhein, V., Korner-Nievergelt, F., and Roth, T. (2017). The earth is
+flat (p > 0.05): Significance thresholds and the crisis of unreplicable
+research. PeerJ, 5, e3544. \doi{10.7717/peerj.3544}
+\item Greenland S, Rafi Z, Matthews R, Higgs M. To Aid Scientific Inference,
+Emphasize Unconditional Compatibility Descriptions of Statistics. (2022)
+https://arxiv.org/abs/1909.08583v7 (Accessed November 10, 2022)
\item Hoffman, L. (2015). Longitudinal analysis: Modeling within-person
fluctuation and change. Routledge.
-\item Neter, J., Wasserman, W., & Kutner, M. H. (1989). Applied linear
+\item Lakens, D. (2024). Improving Your Statistical Inferences (Version v1.5.1).
+Retrieved from https://lakens.github.io/statistical_inferences/.
+\doi{10.5281/ZENODO.6409077}
+\item Lakens, D., Scheel, A. M., and Isager, P. M. (2018). Equivalence Testing
+for Psychological Research: A Tutorial. Advances in Methods and Practices
+in Psychological Science, 1(2), 259–269. \doi{10.1177/2515245918770963}
+\item Makowski, D., Ben-Shachar, M. S., Chen, S. H. A., and Lüdecke, D. (2019).
+Indices of Effect Existence and Significance in the Bayesian Framework.
+Frontiers in Psychology, 10, 2767. \doi{10.3389/fpsyg.2019.02767}
+\item Neter, J., Wasserman, W., and Kutner, M. H. (1989). Applied linear
regression models.
\item Rafi Z, Greenland S. Semantic and cognitive tools to aid statistical
science: replace confidence and significance by compatibility and surprise.
BMC Medical Research Methodology (2020) 20:244.
+\item Schweder T. Confidence is epistemic probability for empirical science.
+Journal of Statistical Planning and Inference (2018) 195:116–125.
+\doi{10.1016/j.jspi.2017.09.016}
+\item Schweder T, Hjort NL. Frequentist analogues of priors and posteriors.
+In Stigum, B. (ed.), Econometrics and the Philosophy of Economics: Theory
+Data Confrontation in Economics, pp. 285-217. Princeton University Press,
+Princeton, NJ, 2003
+\item Vos P, Holbert D. Frequentist statistical inference without repeated sampling.
+Synthese 200, 89 (2022). \doi{10.1007/s11229-022-03560-x}
}
}
\seealso{
diff --git a/man/model_parameters.aov.Rd b/man/model_parameters.aov.Rd
index 0b769fb43..bd24bb816 100644
--- a/man/model_parameters.aov.Rd
+++ b/man/model_parameters.aov.Rd
@@ -13,20 +13,17 @@
alternative = NULL,
test = NULL,
power = FALSE,
- effectsize_type = NULL,
+ es_type = NULL,
keep = NULL,
drop = NULL,
table_wide = FALSE,
verbose = TRUE,
- omega_squared = NULL,
- eta_squared = NULL,
- epsilon_squared = NULL,
...
)
\method{model_parameters}{afex_aov}(
model,
- effectsize_type = NULL,
+ es_type = NULL,
df_error = NULL,
type = NULL,
keep = NULL,
@@ -50,7 +47,7 @@ for ANOVA-tables from mixed models. See 'Examples'. (Ignored for
\code{afex_aov}.)}
\item{ci}{Confidence Interval (CI) level for effect sizes specified in
-\code{effectsize_type}. The default, \code{NULL}, will compute no confidence
+\code{es_type}. The default, \code{NULL}, will compute no confidence
intervals. \code{ci} should be a scalar between 0 and 1.}
\item{alternative}{A character string specifying the alternative hypothesis;
@@ -67,7 +64,7 @@ the multivariate test (that is also given by the \code{print}-method). If
\item{power}{Logical, if \code{TRUE}, adds a column with power for each
parameter.}
-\item{effectsize_type}{The effect size of interest. Not that possibly not all
+\item{es_type}{The effect size of interest. Not that possibly not all
effect sizes are applicable to the model object. See 'Details'. For Anova
models, can also be a character vector with multiple effect size names.}
@@ -99,8 +96,6 @@ be in the same row. Default: \code{FALSE}.}
\item{verbose}{Toggle warnings and messages.}
-\item{omega_squared, eta_squared, epsilon_squared}{Deprecated. Please use \code{effectsize_type}.}
-
\item{...}{Arguments passed to \code{\link[effectsize:effectsize]{effectsize::effectsize()}}. For example,
to calculate \emph{partial} effect sizes types, use \code{partial = TRUE}. For objects
of class \code{htest} or \code{BFBayesFactor}, \code{adjust = TRUE} can be used to return
@@ -166,13 +161,13 @@ df$Sepal.Big <- ifelse(df$Sepal.Width >= 3, "Yes", "No")
model <- aov(Sepal.Length ~ Sepal.Big, data = df)
model_parameters(model)
-model_parameters(model, effectsize_type = c("omega", "eta"), ci = 0.9)
+model_parameters(model, es_type = c("omega", "eta"), ci = 0.9)
model <- anova(lm(Sepal.Length ~ Sepal.Big, data = df))
model_parameters(model)
model_parameters(
model,
- effectsize_type = c("omega", "eta", "epsilon"),
+ es_type = c("omega", "eta", "epsilon"),
alternative = "greater"
)
@@ -192,7 +187,7 @@ model_parameters(model)
# parameters table including effect sizes
model_parameters(
model,
- effectsize_type = "eta",
+ es_type = "eta",
ci = 0.9,
df_error = dof_satterthwaite(mm)[2:3]
)
diff --git a/man/model_parameters.averaging.Rd b/man/model_parameters.averaging.Rd
index e15a8983d..c9c8cbdd1 100644
--- a/man/model_parameters.averaging.Rd
+++ b/man/model_parameters.averaging.Rd
@@ -30,6 +30,7 @@
exponentiate = FALSE,
p_adjust = NULL,
summary = getOption("parameters_summary", FALSE),
+ include_info = getOption("parameters_info", FALSE),
keep = NULL,
drop = NULL,
verbose = TRUE,
@@ -43,6 +44,7 @@
exponentiate = FALSE,
p_adjust = NULL,
summary = getOption("parameters_summary", FALSE),
+ include_info = getOption("parameters_info", FALSE),
keep = NULL,
drop = NULL,
verbose = TRUE,
@@ -59,6 +61,7 @@
exponentiate = FALSE,
p_adjust = NULL,
summary = getOption("parameters_summary", FALSE),
+ include_info = getOption("parameters_info", FALSE),
keep = NULL,
drop = NULL,
verbose = TRUE,
@@ -174,6 +177,7 @@
exponentiate = FALSE,
p_adjust = NULL,
summary = getOption("parameters_summary", FALSE),
+ include_info = getOption("parameters_info", FALSE),
keep = NULL,
drop = NULL,
verbose = TRUE,
@@ -190,6 +194,7 @@
exponentiate = FALSE,
p_adjust = NULL,
summary = getOption("parameters_summary", FALSE),
+ include_info = getOption("parameters_info", FALSE),
keep = NULL,
drop = NULL,
verbose = TRUE,
@@ -250,7 +255,9 @@ possible adjustment methods are \code{"tukey"}, \code{"scheffe"},
\code{"sidak"} and \code{"none"} to explicitly disable adjustment for
\code{emmGrid} objects (from \strong{emmeans}).}
-\item{summary}{Logical, if \code{TRUE}, prints summary information about the
+\item{summary}{Deprecated, please use \code{info} instead.}
+
+\item{include_info}{Logical, if \code{TRUE}, prints summary information about the
model (model formula, number of observations, residual standard deviation
and more).}
@@ -279,8 +286,19 @@ names.}
\item{verbose}{Toggle warnings and messages.}
\item{...}{Arguments passed to or from other methods. For instance, when
-\code{bootstrap = TRUE}, arguments like \code{type} or \code{parallel} are
-passed down to \code{bootstrap_model()}.}
+\code{bootstrap = TRUE}, arguments like \code{type} or \code{parallel} are passed down to
+\code{bootstrap_model()}. Further non-documented arguments are \code{digits},
+\code{p_digits}, \code{ci_digits} and \code{footer_digits} to set the number of digits for
+the output. If \code{s_value = TRUE}, the p-value will be replaced by the
+S-value in the output (cf. \emph{Rafi and Greenland 2020}). \code{pd} adds an
+additional column with the \emph{probability of direction} (see
+\code{\link[bayestestR:p_direction]{bayestestR::p_direction()}} for details). \code{groups} can be used to group
+coefficients. It will be passed to the print-method, or can directly be
+used in \code{print()}, see documentation in \code{\link[=print.parameters_model]{print.parameters_model()}}.
+Furthermore, see 'Examples' for this function. For developers, whose
+interest mainly is to get a "tidy" data frame of model summaries, it is
+recommended to set \code{pretty_names = FALSE} to speed up computation of the
+summary table.}
\item{include_studies}{Logical, if \code{TRUE} (default), includes parameters
for all studies. Else, only parameters for overall-effects are shown.}
diff --git a/man/model_parameters.cgam.Rd b/man/model_parameters.cgam.Rd
index 90a5ff164..c2a4afa4b 100644
--- a/man/model_parameters.cgam.Rd
+++ b/man/model_parameters.cgam.Rd
@@ -34,7 +34,7 @@
\method{model_parameters}{Gam}(
model,
- effectsize_type = NULL,
+ es_type = NULL,
df_error = NULL,
type = NULL,
table_wide = FALSE,
@@ -140,10 +140,21 @@ names.}
\item{verbose}{Toggle warnings and messages.}
\item{...}{Arguments passed to or from other methods. For instance, when
-\code{bootstrap = TRUE}, arguments like \code{type} or \code{parallel} are
-passed down to \code{bootstrap_model()}.}
-
-\item{effectsize_type}{The effect size of interest. Not that possibly not all
+\code{bootstrap = TRUE}, arguments like \code{type} or \code{parallel} are passed down to
+\code{bootstrap_model()}. Further non-documented arguments are \code{digits},
+\code{p_digits}, \code{ci_digits} and \code{footer_digits} to set the number of digits for
+the output. If \code{s_value = TRUE}, the p-value will be replaced by the
+S-value in the output (cf. \emph{Rafi and Greenland 2020}). \code{pd} adds an
+additional column with the \emph{probability of direction} (see
+\code{\link[bayestestR:p_direction]{bayestestR::p_direction()}} for details). \code{groups} can be used to group
+coefficients. It will be passed to the print-method, or can directly be
+used in \code{print()}, see documentation in \code{\link[=print.parameters_model]{print.parameters_model()}}.
+Furthermore, see 'Examples' for this function. For developers, whose
+interest mainly is to get a "tidy" data frame of model summaries, it is
+recommended to set \code{pretty_names = FALSE} to speed up computation of the
+summary table.}
+
+\item{es_type}{The effect size of interest. Not that possibly not all
effect sizes are applicable to the model object. See 'Details'. For Anova
models, can also be a character vector with multiple effect size names.}
diff --git a/man/model_parameters.default.Rd b/man/model_parameters.default.Rd
index 2a2ccec29..132dc2d5d 100644
--- a/man/model_parameters.default.Rd
+++ b/man/model_parameters.default.Rd
@@ -17,12 +17,13 @@
standardize = NULL,
exponentiate = FALSE,
p_adjust = NULL,
+ vcov = NULL,
+ vcov_args = NULL,
summary = getOption("parameters_summary", FALSE),
+ include_info = getOption("parameters_info", FALSE),
keep = NULL,
drop = NULL,
verbose = TRUE,
- vcov = NULL,
- vcov_args = NULL,
...
)
@@ -35,11 +36,12 @@
standardize = NULL,
exponentiate = FALSE,
p_adjust = NULL,
+ vcov = NULL,
+ vcov_args = NULL,
summary = getOption("parameters_summary", FALSE),
+ include_info = getOption("parameters_info", FALSE),
keep = NULL,
drop = NULL,
- vcov = NULL,
- vcov_args = NULL,
verbose = TRUE,
...
)
@@ -53,12 +55,13 @@
standardize = NULL,
exponentiate = FALSE,
p_adjust = NULL,
+ vcov = NULL,
+ vcov_args = NULL,
summary = getOption("parameters_summary", FALSE),
+ include_info = getOption("parameters_info", FALSE),
keep = NULL,
drop = NULL,
verbose = TRUE,
- vcov = NULL,
- vcov_args = NULL,
...
)
@@ -122,7 +125,34 @@ possible adjustment methods are \code{"tukey"}, \code{"scheffe"},
\code{"sidak"} and \code{"none"} to explicitly disable adjustment for
\code{emmGrid} objects (from \strong{emmeans}).}
-\item{summary}{Logical, if \code{TRUE}, prints summary information about the
+\item{vcov}{Variance-covariance matrix used to compute uncertainty estimates
+(e.g., for robust standard errors). This argument accepts a covariance matrix,
+a function which returns a covariance matrix, or a string which identifies
+the function to be used to compute the covariance matrix.
+\itemize{
+\item A covariance matrix
+\item A function which returns a covariance matrix (e.g., \code{stats::vcov()})
+\item A string which indicates the kind of uncertainty estimates to return.
+\itemize{
+\item Heteroskedasticity-consistent: \code{"vcovHC"}, \code{"HC"}, \code{"HC0"}, \code{"HC1"},
+\code{"HC2"}, \code{"HC3"}, \code{"HC4"}, \code{"HC4m"}, \code{"HC5"}. See \code{?sandwich::vcovHC}.
+\item Cluster-robust: \code{"vcovCR"}, \code{"CR0"}, \code{"CR1"}, \code{"CR1p"}, \code{"CR1S"},
+\code{"CR2"}, \code{"CR3"}. See \code{?clubSandwich::vcovCR}.
+\item Bootstrap: \code{"vcovBS"}, \code{"xy"}, \code{"residual"}, \code{"wild"}, \code{"mammen"},
+\code{"webb"}. See \code{?sandwich::vcovBS}.
+\item Other \code{sandwich} package functions: \code{"vcovHAC"}, \code{"vcovPC"}, \code{"vcovCL"},
+\code{"vcovPL"}.
+}
+}}
+
+\item{vcov_args}{List of arguments to be passed to the function identified by
+the \code{vcov} argument. This function is typically supplied by the \strong{sandwich}
+or \strong{clubSandwich} packages. Please refer to their documentation (e.g.,
+\code{?sandwich::vcovHAC}) to see the list of available arguments.}
+
+\item{summary}{Deprecated, please use \code{info} instead.}
+
+\item{include_info}{Logical, if \code{TRUE}, prints summary information about the
model (model formula, number of observations, residual standard deviation
and more).}
@@ -150,40 +180,27 @@ names.}
\item{verbose}{Toggle warnings and messages.}
-\item{vcov}{Variance-covariance matrix used to compute uncertainty estimates
-(e.g., for robust standard errors). This argument accepts a covariance matrix,
-a function which returns a covariance matrix, or a string which identifies
-the function to be used to compute the covariance matrix.
-\itemize{
-\item A covariance matrix
-\item A function which returns a covariance matrix (e.g., \code{stats::vcov()})
-\item A string which indicates the kind of uncertainty estimates to return.
-\itemize{
-\item Heteroskedasticity-consistent: \code{"vcovHC"}, \code{"HC"}, \code{"HC0"}, \code{"HC1"},
-\code{"HC2"}, \code{"HC3"}, \code{"HC4"}, \code{"HC4m"}, \code{"HC5"}. See \code{?sandwich::vcovHC}.
-\item Cluster-robust: \code{"vcovCR"}, \code{"CR0"}, \code{"CR1"}, \code{"CR1p"}, \code{"CR1S"}, \code{"CR2"},
-\code{"CR3"}. See \code{?clubSandwich::vcovCR}.
-\item Bootstrap: \code{"vcovBS"}, \code{"xy"}, \code{"residual"}, \code{"wild"}, \code{"mammen"}, \code{"webb"}.
-See \code{?sandwich::vcovBS}.
-\item Other \code{sandwich} package functions: \code{"vcovHAC"}, \code{"vcovPC"}, \code{"vcovCL"}, \code{"vcovPL"}.
-}
-}}
-
-\item{vcov_args}{List of arguments to be passed to the function identified by
-the \code{vcov} argument. This function is typically supplied by the \strong{sandwich}
-or \strong{clubSandwich} packages. Please refer to their documentation (e.g.,
-\code{?sandwich::vcovHAC}) to see the list of available arguments.}
-
\item{...}{Arguments passed to or from other methods. For instance, when
-\code{bootstrap = TRUE}, arguments like \code{type} or \code{parallel} are
-passed down to \code{bootstrap_model()}.}
+\code{bootstrap = TRUE}, arguments like \code{type} or \code{parallel} are passed down to
+\code{bootstrap_model()}. Further non-documented arguments are \code{digits},
+\code{p_digits}, \code{ci_digits} and \code{footer_digits} to set the number of digits for
+the output. If \code{s_value = TRUE}, the p-value will be replaced by the
+S-value in the output (cf. \emph{Rafi and Greenland 2020}). \code{pd} adds an
+additional column with the \emph{probability of direction} (see
+\code{\link[bayestestR:p_direction]{bayestestR::p_direction()}} for details). \code{groups} can be used to group
+coefficients. It will be passed to the print-method, or can directly be
+used in \code{print()}, see documentation in \code{\link[=print.parameters_model]{print.parameters_model()}}.
+Furthermore, see 'Examples' for this function. For developers, whose
+interest mainly is to get a "tidy" data frame of model summaries, it is
+recommended to set \code{pretty_names = FALSE} to speed up computation of the
+summary table.}
}
\value{
A data frame of indices related to the model's parameters.
}
\description{
-Extract and compute indices and measures to describe parameters of (general)
-linear models (GLMs).
+Extract and compute indices and measures to describe parameters
+of (generalized) linear models (GLMs).
}
\section{Confidence intervals and approximation of degrees of freedom}{
@@ -375,6 +392,11 @@ model_parameters(model,
# different p-value style in output
model_parameters(model, p_digits = 5)
model_parameters(model, digits = 3, ci_digits = 4, p_digits = "scientific")
+
+# report S-value or probability of direction for parameters
+model_parameters(model, s_value = TRUE)
+model_parameters(model, pd = TRUE)
+
\donttest{
# logistic regression model
model <- glm(vs ~ wt + cyl, data = mtcars, family = "binomial")
@@ -395,6 +417,6 @@ model_parameters(model)
\dontshow{\}) # examplesIf}
}
\seealso{
-\code{\link[insight:standardize_names]{insight::standardize_names()}} to
-rename columns into a consistent, standardized naming scheme.
+\code{\link[insight:standardize_names]{insight::standardize_names()}} to rename columns into a
+consistent, standardized naming scheme.
}
diff --git a/man/model_parameters.glht.Rd b/man/model_parameters.glht.Rd
index 9ac52abde..b71244fd3 100644
--- a/man/model_parameters.glht.Rd
+++ b/man/model_parameters.glht.Rd
@@ -58,8 +58,19 @@ names.}
\item{verbose}{Toggle warnings and messages.}
\item{...}{Arguments passed to or from other methods. For instance, when
-\code{bootstrap = TRUE}, arguments like \code{type} or \code{parallel} are
-passed down to \code{bootstrap_model()}.}
+\code{bootstrap = TRUE}, arguments like \code{type} or \code{parallel} are passed down to
+\code{bootstrap_model()}. Further non-documented arguments are \code{digits},
+\code{p_digits}, \code{ci_digits} and \code{footer_digits} to set the number of digits for
+the output. If \code{s_value = TRUE}, the p-value will be replaced by the
+S-value in the output (cf. \emph{Rafi and Greenland 2020}). \code{pd} adds an
+additional column with the \emph{probability of direction} (see
+\code{\link[bayestestR:p_direction]{bayestestR::p_direction()}} for details). \code{groups} can be used to group
+coefficients. It will be passed to the print-method, or can directly be
+used in \code{print()}, see documentation in \code{\link[=print.parameters_model]{print.parameters_model()}}.
+Furthermore, see 'Examples' for this function. For developers, whose
+interest mainly is to get a "tidy" data frame of model summaries, it is
+recommended to set \code{pretty_names = FALSE} to speed up computation of the
+summary table.}
}
\value{
A data frame of indices related to the model's parameters.
diff --git a/man/model_parameters.htest.Rd b/man/model_parameters.htest.Rd
index f58bba0b3..3d83e29c7 100644
--- a/man/model_parameters.htest.Rd
+++ b/man/model_parameters.htest.Rd
@@ -10,19 +10,8 @@
ci = 0.95,
alternative = NULL,
bootstrap = FALSE,
- effectsize_type = NULL,
+ es_type = NULL,
verbose = TRUE,
- cramers_v = NULL,
- phi = NULL,
- standardized_d = NULL,
- hedges_g = NULL,
- omega_squared = NULL,
- eta_squared = NULL,
- epsilon_squared = NULL,
- cohens_g = NULL,
- rank_biserial = NULL,
- rank_epsilon_squared = NULL,
- kendalls_w = NULL,
...
)
@@ -50,17 +39,26 @@ the \href{https://easystats.github.io/effectsize/}{effectsize_CIs vignette}.}
\item{bootstrap}{Should estimates be bootstrapped?}
-\item{effectsize_type}{The effect size of interest. Not that possibly not all
+\item{es_type}{The effect size of interest. Not that possibly not all
effect sizes are applicable to the model object. See 'Details'. For Anova
models, can also be a character vector with multiple effect size names.}
\item{verbose}{Toggle warnings and messages.}
-\item{cramers_v, phi, cohens_g, standardized_d, hedges_g, omega_squared, eta_squared, epsilon_squared, rank_biserial, rank_epsilon_squared, kendalls_w}{Deprecated. Please use \code{effectsize_type}.}
-
\item{...}{Arguments passed to or from other methods. For instance, when
-\code{bootstrap = TRUE}, arguments like \code{type} or \code{parallel} are
-passed down to \code{bootstrap_model()}.}
+\code{bootstrap = TRUE}, arguments like \code{type} or \code{parallel} are passed down to
+\code{bootstrap_model()}. Further non-documented arguments are \code{digits},
+\code{p_digits}, \code{ci_digits} and \code{footer_digits} to set the number of digits for
+the output. If \code{s_value = TRUE}, the p-value will be replaced by the
+S-value in the output (cf. \emph{Rafi and Greenland 2020}). \code{pd} adds an
+additional column with the \emph{probability of direction} (see
+\code{\link[bayestestR:p_direction]{bayestestR::p_direction()}} for details). \code{groups} can be used to group
+coefficients. It will be passed to the print-method, or can directly be
+used in \code{print()}, see documentation in \code{\link[=print.parameters_model]{print.parameters_model()}}.
+Furthermore, see 'Examples' for this function. For developers, whose
+interest mainly is to get a "tidy" data frame of model summaries, it is
+recommended to set \code{pretty_names = FALSE} to speed up computation of the
+summary table.}
\item{ci_method}{Method for computing degrees of freedom for
confidence intervals (CI) and the related p-values. Allowed are following
@@ -137,13 +135,13 @@ model <- cor.test(mtcars$mpg, mtcars$cyl, method = "pearson")
model_parameters(model)
model <- t.test(iris$Sepal.Width, iris$Sepal.Length)
-model_parameters(model, effectsize_type = "hedges_g")
+model_parameters(model, es_type = "hedges_g")
model <- t.test(mtcars$mpg ~ mtcars$vs)
-model_parameters(model, effectsize_type = "hedges_g")
+model_parameters(model, es_type = "hedges_g")
model <- t.test(iris$Sepal.Width, mu = 1)
-model_parameters(model, effectsize_type = "cohens_d")
+model_parameters(model, es_type = "cohens_d")
data(airquality)
airquality$Month <- factor(airquality$Month, labels = month.abb[5:9])
@@ -156,6 +154,6 @@ model <- suppressWarnings(pairwise.prop.test(smokers, patients))
model_parameters(model)
model <- suppressWarnings(chisq.test(table(mtcars$am, mtcars$cyl)))
-model_parameters(model, effectsize_type = "cramers_v")
+model_parameters(model, es_type = "cramers_v")
}
diff --git a/man/model_parameters.merMod.Rd b/man/model_parameters.merMod.Rd
index 8b1b8e75c..a5c99f91e 100644
--- a/man/model_parameters.merMod.Rd
+++ b/man/model_parameters.merMod.Rd
@@ -47,10 +47,11 @@
p_adjust = NULL,
wb_component = TRUE,
summary = getOption("parameters_mixed_summary", FALSE),
+ include_info = getOption("parameters_mixed_info", FALSE),
+ include_sigma = FALSE,
keep = NULL,
drop = NULL,
verbose = TRUE,
- include_sigma = FALSE,
...
)
@@ -66,14 +67,15 @@
group_level = FALSE,
exponentiate = FALSE,
p_adjust = NULL,
+ vcov = NULL,
+ vcov_args = NULL,
wb_component = TRUE,
summary = getOption("parameters_mixed_summary", FALSE),
+ include_info = getOption("parameters_mixed_info", FALSE),
+ include_sigma = FALSE,
keep = NULL,
drop = NULL,
verbose = TRUE,
- include_sigma = FALSE,
- vcov = NULL,
- vcov_args = NULL,
...
)
@@ -92,10 +94,11 @@
p_adjust = NULL,
wb_component = TRUE,
summary = getOption("parameters_mixed_summary", FALSE),
+ include_info = getOption("parameters_mixed_info", FALSE),
+ include_sigma = FALSE,
keep = NULL,
drop = NULL,
verbose = TRUE,
- include_sigma = FALSE,
...
)
@@ -114,10 +117,11 @@
p_adjust = NULL,
wb_component = TRUE,
summary = getOption("parameters_mixed_summary", FALSE),
+ include_info = getOption("parameters_mixed_info", FALSE),
+ include_sigma = FALSE,
keep = NULL,
drop = NULL,
verbose = TRUE,
- include_sigma = FALSE,
...
)
@@ -133,14 +137,15 @@
group_level = FALSE,
exponentiate = FALSE,
p_adjust = NULL,
+ vcov = NULL,
+ vcov_args = NULL,
wb_component = TRUE,
summary = getOption("parameters_mixed_summary", FALSE),
+ include_info = getOption("parameters_mixed_info", FALSE),
+ include_sigma = FALSE,
keep = NULL,
drop = NULL,
verbose = TRUE,
- include_sigma = FALSE,
- vcov = NULL,
- vcov_args = NULL,
...
)
@@ -154,6 +159,7 @@
exponentiate = FALSE,
p_adjust = NULL,
summary = getOption("parameters_summary", FALSE),
+ include_info = getOption("parameters_info", FALSE),
keep = NULL,
drop = NULL,
verbose = TRUE,
@@ -289,8 +295,19 @@ names.}
\item{verbose}{Toggle warnings and messages.}
\item{...}{Arguments passed to or from other methods. For instance, when
-\code{bootstrap = TRUE}, arguments like \code{type} or \code{parallel} are
-passed down to \code{bootstrap_model()}.}
+\code{bootstrap = TRUE}, arguments like \code{type} or \code{parallel} are passed down to
+\code{bootstrap_model()}. Further non-documented arguments are \code{digits},
+\code{p_digits}, \code{ci_digits} and \code{footer_digits} to set the number of digits for
+the output. If \code{s_value = TRUE}, the p-value will be replaced by the
+S-value in the output (cf. \emph{Rafi and Greenland 2020}). \code{pd} adds an
+additional column with the \emph{probability of direction} (see
+\code{\link[bayestestR:p_direction]{bayestestR::p_direction()}} for details). \code{groups} can be used to group
+coefficients. It will be passed to the print-method, or can directly be
+used in \code{print()}, see documentation in \code{\link[=print.parameters_model]{print.parameters_model()}}.
+Furthermore, see 'Examples' in \code{\link[=model_parameters.default]{model_parameters.default()}}. For
+developers, whose interest mainly is to get a "tidy" data frame of model
+summaries, it is recommended to set \code{pretty_names = FALSE} to speed up
+computation of the summary table.}
\item{component}{Should all parameters, parameters for the conditional model,
for the zero-inflation part of the model, or the dispersion model be returned?
@@ -305,7 +322,9 @@ between-effects, and cross-level interactions. By default, the
\code{Component} column indicates, which parameters belong to the
conditional or zero-inflation component of the model.}
-\item{summary}{Logical, if \code{TRUE}, prints summary information about the
+\item{summary}{Deprecated, please use \code{info} instead.}
+
+\item{include_info}{Logical, if \code{TRUE}, prints summary information about the
model (model formula, number of observations, residual standard deviation
and more).}
@@ -320,11 +339,12 @@ the function to be used to compute the covariance matrix.
\itemize{
\item Heteroskedasticity-consistent: \code{"vcovHC"}, \code{"HC"}, \code{"HC0"}, \code{"HC1"},
\code{"HC2"}, \code{"HC3"}, \code{"HC4"}, \code{"HC4m"}, \code{"HC5"}. See \code{?sandwich::vcovHC}.
-\item Cluster-robust: \code{"vcovCR"}, \code{"CR0"}, \code{"CR1"}, \code{"CR1p"}, \code{"CR1S"}, \code{"CR2"},
-\code{"CR3"}. See \code{?clubSandwich::vcovCR}.
-\item Bootstrap: \code{"vcovBS"}, \code{"xy"}, \code{"residual"}, \code{"wild"}, \code{"mammen"}, \code{"webb"}.
-See \code{?sandwich::vcovBS}.
-\item Other \code{sandwich} package functions: \code{"vcovHAC"}, \code{"vcovPC"}, \code{"vcovCL"}, \code{"vcovPL"}.
+\item Cluster-robust: \code{"vcovCR"}, \code{"CR0"}, \code{"CR1"}, \code{"CR1p"}, \code{"CR1S"},
+\code{"CR2"}, \code{"CR3"}. See \code{?clubSandwich::vcovCR}.
+\item Bootstrap: \code{"vcovBS"}, \code{"xy"}, \code{"residual"}, \code{"wild"}, \code{"mammen"},
+\code{"webb"}. See \code{?sandwich::vcovBS}.
+\item Other \code{sandwich} package functions: \code{"vcovHAC"}, \code{"vcovPC"}, \code{"vcovCL"},
+\code{"vcovPL"}.
}
}}
diff --git a/man/model_parameters.mira.Rd b/man/model_parameters.mira.Rd
index 323886aa8..5b379f152 100644
--- a/man/model_parameters.mira.Rd
+++ b/man/model_parameters.mira.Rd
@@ -87,38 +87,32 @@ similar to \code{summary(mice::pool())}, i.e. it generates the pooled summary
of multiple imputed repeated regression analyses.
}
\examples{
+\dontshow{if (require("mice", quietly = TRUE) && require("gee", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
library(parameters)
-if (require("mice", quietly = TRUE)) {
- data(nhanes2)
- imp <- mice(nhanes2)
- fit <- with(data = imp, exp = lm(bmi ~ age + hyp + chl))
- model_parameters(fit)
-}
+data(nhanes2, package = "mice")
+imp <- mice::mice(nhanes2)
+fit <- with(data = imp, exp = lm(bmi ~ age + hyp + chl))
+model_parameters(fit)
\donttest{
# model_parameters() also works for models that have no "tidy"-method in mice
-if (require("mice", quietly = TRUE) && require("gee", quietly = TRUE)) {
- data(warpbreaks)
- set.seed(1234)
- warpbreaks$tension[sample(1:nrow(warpbreaks), size = 10)] <- NA
- imp <- mice(warpbreaks)
- fit <- with(data = imp, expr = gee(breaks ~ tension, id = wool))
+data(warpbreaks)
+set.seed(1234)
+warpbreaks$tension[sample(1:nrow(warpbreaks), size = 10)] <- NA
+imp <- mice::mice(warpbreaks)
+fit <- with(data = imp, expr = gee::gee(breaks ~ tension, id = wool))
- # does not work:
- # summary(pool(fit))
+# does not work:
+# summary(mice::pool(fit))
- model_parameters(fit)
-}
+model_parameters(fit)
}
-
-
# and it works with pooled results
-if (require("mice")) {
- data("nhanes2")
- imp <- mice(nhanes2)
- fit <- with(data = imp, exp = lm(bmi ~ age + hyp + chl))
- pooled <- pool(fit)
+data("nhanes2", package = "mice")
+imp <- mice::mice(nhanes2)
+fit <- with(data = imp, exp = lm(bmi ~ age + hyp + chl))
+pooled <- mice::pool(fit)
- model_parameters(pooled)
-}
+model_parameters(pooled)
+\dontshow{\}) # examplesIf}
}
diff --git a/man/model_parameters.mlm.Rd b/man/model_parameters.mlm.Rd
index fb6e86490..54d2ee308 100644
--- a/man/model_parameters.mlm.Rd
+++ b/man/model_parameters.mlm.Rd
@@ -35,6 +35,7 @@
exponentiate = FALSE,
p_adjust = NULL,
summary = getOption("parameters_summary", FALSE),
+ include_info = getOption("parameters_info", FALSE),
keep = NULL,
drop = NULL,
verbose = TRUE,
@@ -67,6 +68,7 @@
exponentiate = FALSE,
p_adjust = NULL,
summary = getOption("parameters_summary", FALSE),
+ include_info = getOption("parameters_info", FALSE),
keep = NULL,
drop = NULL,
verbose = TRUE,
@@ -152,10 +154,23 @@ names.}
\item{verbose}{Toggle warnings and messages.}
\item{...}{Arguments passed to or from other methods. For instance, when
-\code{bootstrap = TRUE}, arguments like \code{type} or \code{parallel} are
-passed down to \code{bootstrap_model()}.}
-
-\item{summary}{Logical, if \code{TRUE}, prints summary information about the
+\code{bootstrap = TRUE}, arguments like \code{type} or \code{parallel} are passed down to
+\code{bootstrap_model()}. Further non-documented arguments are \code{digits},
+\code{p_digits}, \code{ci_digits} and \code{footer_digits} to set the number of digits for
+the output. If \code{s_value = TRUE}, the p-value will be replaced by the
+S-value in the output (cf. \emph{Rafi and Greenland 2020}). \code{pd} adds an
+additional column with the \emph{probability of direction} (see
+\code{\link[bayestestR:p_direction]{bayestestR::p_direction()}} for details). \code{groups} can be used to group
+coefficients. It will be passed to the print-method, or can directly be
+used in \code{print()}, see documentation in \code{\link[=print.parameters_model]{print.parameters_model()}}.
+Furthermore, see 'Examples' for this function. For developers, whose
+interest mainly is to get a "tidy" data frame of model summaries, it is
+recommended to set \code{pretty_names = FALSE} to speed up computation of the
+summary table.}
+
+\item{summary}{Deprecated, please use \code{info} instead.}
+
+\item{include_info}{Logical, if \code{TRUE}, prints summary information about the
model (model formula, number of observations, residual standard deviation
and more).}
@@ -170,11 +185,12 @@ the function to be used to compute the covariance matrix.
\itemize{
\item Heteroskedasticity-consistent: \code{"vcovHC"}, \code{"HC"}, \code{"HC0"}, \code{"HC1"},
\code{"HC2"}, \code{"HC3"}, \code{"HC4"}, \code{"HC4m"}, \code{"HC5"}. See \code{?sandwich::vcovHC}.
-\item Cluster-robust: \code{"vcovCR"}, \code{"CR0"}, \code{"CR1"}, \code{"CR1p"}, \code{"CR1S"}, \code{"CR2"},
-\code{"CR3"}. See \code{?clubSandwich::vcovCR}.
-\item Bootstrap: \code{"vcovBS"}, \code{"xy"}, \code{"residual"}, \code{"wild"}, \code{"mammen"}, \code{"webb"}.
-See \code{?sandwich::vcovBS}.
-\item Other \code{sandwich} package functions: \code{"vcovHAC"}, \code{"vcovPC"}, \code{"vcovCL"}, \code{"vcovPL"}.
+\item Cluster-robust: \code{"vcovCR"}, \code{"CR0"}, \code{"CR1"}, \code{"CR1p"}, \code{"CR1S"},
+\code{"CR2"}, \code{"CR3"}. See \code{?clubSandwich::vcovCR}.
+\item Bootstrap: \code{"vcovBS"}, \code{"xy"}, \code{"residual"}, \code{"wild"}, \code{"mammen"},
+\code{"webb"}. See \code{?sandwich::vcovBS}.
+\item Other \code{sandwich} package functions: \code{"vcovHAC"}, \code{"vcovPC"}, \code{"vcovCL"},
+\code{"vcovPL"}.
}
}}
diff --git a/man/model_parameters.rma.Rd b/man/model_parameters.rma.Rd
index 2d12431d8..e58a6844f 100644
--- a/man/model_parameters.rma.Rd
+++ b/man/model_parameters.rma.Rd
@@ -88,8 +88,19 @@ names.}
\item{verbose}{Toggle warnings and messages.}
\item{...}{Arguments passed to or from other methods. For instance, when
-\code{bootstrap = TRUE}, arguments like \code{type} or \code{parallel} are
-passed down to \code{bootstrap_model()}.}
+\code{bootstrap = TRUE}, arguments like \code{type} or \code{parallel} are passed down to
+\code{bootstrap_model()}. Further non-documented arguments are \code{digits},
+\code{p_digits}, \code{ci_digits} and \code{footer_digits} to set the number of digits for
+the output. If \code{s_value = TRUE}, the p-value will be replaced by the
+S-value in the output (cf. \emph{Rafi and Greenland 2020}). \code{pd} adds an
+additional column with the \emph{probability of direction} (see
+\code{\link[bayestestR:p_direction]{bayestestR::p_direction()}} for details). \code{groups} can be used to group
+coefficients. It will be passed to the print-method, or can directly be
+used in \code{print()}, see documentation in \code{\link[=print.parameters_model]{print.parameters_model()}}.
+Furthermore, see 'Examples' for this function. For developers, whose
+interest mainly is to get a "tidy" data frame of model summaries, it is
+recommended to set \code{pretty_names = FALSE} to speed up computation of the
+summary table.}
}
\value{
A data frame of indices related to the model's parameters.
diff --git a/man/model_parameters.stanreg.Rd b/man/model_parameters.stanreg.Rd
index 3980d2292..57095a54b 100644
--- a/man/model_parameters.stanreg.Rd
+++ b/man/model_parameters.stanreg.Rd
@@ -27,7 +27,13 @@
...
)
-\method{model_parameters}{data.frame}(model, as_draws = FALSE, verbose = TRUE, ...)
+\method{model_parameters}{data.frame}(
+ model,
+ as_draws = FALSE,
+ exponentiate = FALSE,
+ verbose = TRUE,
+ ...
+)
\method{model_parameters}{brmsfit}(
model,
@@ -61,6 +67,7 @@
test = "pd",
rope_range = "default",
rope_ci = 0.95,
+ exponentiate = FALSE,
keep = NULL,
drop = NULL,
verbose = TRUE,
@@ -124,9 +131,10 @@ For each "test", the corresponding \pkg{bayestestR} function is called
(e.g. \code{\link[bayestestR:rope]{rope()}} or \code{\link[bayestestR:p_direction]{p_direction()}}) and its results
included in the summary output.}
-\item{rope_range}{ROPE's lower and higher bounds. Should be a list of two
-values (e.g., \code{c(-0.1, 0.1)}) or \code{"default"}. If \code{"default"},
-the bounds are set to \code{x +- 0.1*SD(response)}.}
+\item{rope_range}{ROPE's lower and higher bounds. Should be a vector of two
+values (e.g., \code{c(-0.1, 0.1)}), \code{"default"} or a list of numeric vectors of
+the same length as numbers of parameters. If \code{"default"}, the bounds are
+set to \code{x +- 0.1*SD(response)}.}
\item{rope_ci}{The Credible Interval (CI) probability, corresponding to the
proportion of HDI, to use for the percentage in ROPE.}
@@ -171,6 +179,19 @@ the data frame is treated as posterior samples and handled similar to
Bayesian models. All arguments in \code{...} are passed to
\code{model_parameters.draws()}.}
+\item{exponentiate}{Logical, indicating whether or not to exponentiate the
+coefficients (and related confidence intervals). This is typical for
+logistic regression, or more generally speaking, for models with log or
+logit links. It is also recommended to use \code{exponentiate = TRUE} for models
+with log-transformed response values. \strong{Note:} Delta-method standard
+errors are also computed (by multiplying the standard errors by the
+transformed coefficients). This is to mimic behaviour of other software
+packages, such as Stata, but these standard errors poorly estimate
+uncertainty for the transformed coefficient. The transformed confidence
+interval more clearly captures this uncertainty. For \code{compare_parameters()},
+\code{exponentiate = "nongaussian"} will only exponentiate coefficients from
+non-Gaussian families.}
+
\item{effects}{Should results for fixed effects, random effects or both be
returned? Only applies to mixed models. May be abbreviated.}
@@ -188,19 +209,6 @@ argument - but no auxiliary parameters). For \code{component = "distributional"}
(or \code{"auxiliary"}), components like \code{sigma}, \code{dispersion}, or \code{beta}
(and other auxiliary parameters) are returned.}
-\item{exponentiate}{Logical, indicating whether or not to exponentiate the
-coefficients (and related confidence intervals). This is typical for
-logistic regression, or more generally speaking, for models with log or
-logit links. It is also recommended to use \code{exponentiate = TRUE} for models
-with log-transformed response values. \strong{Note:} Delta-method standard
-errors are also computed (by multiplying the standard errors by the
-transformed coefficients). This is to mimic behaviour of other software
-packages, such as Stata, but these standard errors poorly estimate
-uncertainty for the transformed coefficient. The transformed confidence
-interval more clearly captures this uncertainty. For \code{compare_parameters()},
-\code{exponentiate = "nongaussian"} will only exponentiate coefficients from
-non-Gaussian families.}
-
\item{standardize}{The method used for standardizing the parameters. Can be
\code{NULL} (default; no standardization), \code{"refit"} (for re-fitting the model
on standardized data) or one of \code{"basic"}, \code{"posthoc"}, \code{"smart"},
diff --git a/man/model_parameters.zcpglm.Rd b/man/model_parameters.zcpglm.Rd
index c277b50c3..c9d67ae9d 100644
--- a/man/model_parameters.zcpglm.Rd
+++ b/man/model_parameters.zcpglm.Rd
@@ -14,9 +14,10 @@
standardize = NULL,
exponentiate = FALSE,
p_adjust = NULL,
+ summary = getOption("parameters_summary", FALSE),
+ include_info = getOption("parameters_info", FALSE),
keep = NULL,
drop = NULL,
- summary = getOption("parameters_summary", FALSE),
verbose = TRUE,
...
)
@@ -88,6 +89,12 @@ possible adjustment methods are \code{"tukey"}, \code{"scheffe"},
\code{"sidak"} and \code{"none"} to explicitly disable adjustment for
\code{emmGrid} objects (from \strong{emmeans}).}
+\item{summary}{Deprecated, please use \code{info} instead.}
+
+\item{include_info}{Logical, if \code{TRUE}, prints summary information about the
+model (model formula, number of observations, residual standard deviation
+and more).}
+
\item{keep}{Character containing a regular expression pattern that
describes the parameters that should be included (for \code{keep}) or excluded
(for \code{drop}) in the returned data frame. \code{keep} may also be a
@@ -110,15 +117,22 @@ names.}
\item{drop}{See \code{keep}.}
-\item{summary}{Logical, if \code{TRUE}, prints summary information about the
-model (model formula, number of observations, residual standard deviation
-and more).}
-
\item{verbose}{Toggle warnings and messages.}
\item{...}{Arguments passed to or from other methods. For instance, when
-\code{bootstrap = TRUE}, arguments like \code{type} or \code{parallel} are
-passed down to \code{bootstrap_model()}.}
+\code{bootstrap = TRUE}, arguments like \code{type} or \code{parallel} are passed down to
+\code{bootstrap_model()}. Further non-documented arguments are \code{digits},
+\code{p_digits}, \code{ci_digits} and \code{footer_digits} to set the number of digits for
+the output. If \code{s_value = TRUE}, the p-value will be replaced by the
+S-value in the output (cf. \emph{Rafi and Greenland 2020}). \code{pd} adds an
+additional column with the \emph{probability of direction} (see
+\code{\link[bayestestR:p_direction]{bayestestR::p_direction()}} for details). \code{groups} can be used to group
+coefficients. It will be passed to the print-method, or can directly be
+used in \code{print()}, see documentation in \code{\link[=print.parameters_model]{print.parameters_model()}}.
+Furthermore, see 'Examples' for this function. For developers, whose
+interest mainly is to get a "tidy" data frame of model summaries, it is
+recommended to set \code{pretty_names = FALSE} to speed up computation of the
+summary table.}
}
\value{
A data frame of indices related to the model's parameters.
diff --git a/man/n_clusters.Rd b/man/n_clusters.Rd
index 444d06ad7..13b385a05 100644
--- a/man/n_clusters.Rd
+++ b/man/n_clusters.Rd
@@ -94,8 +94,19 @@ as \code{method}).}
\item{n_max}{Maximal number of clusters to test.}
\item{...}{Arguments passed to or from other methods. For instance, when
-\code{bootstrap = TRUE}, arguments like \code{type} or \code{parallel} are
-passed down to \code{bootstrap_model()}.}
+\code{bootstrap = TRUE}, arguments like \code{type} or \code{parallel} are passed down to
+\code{bootstrap_model()}. Further non-documented arguments are \code{digits},
+\code{p_digits}, \code{ci_digits} and \code{footer_digits} to set the number of digits for
+the output. If \code{s_value = TRUE}, the p-value will be replaced by the
+S-value in the output (cf. \emph{Rafi and Greenland 2020}). \code{pd} adds an
+additional column with the \emph{probability of direction} (see
+\code{\link[bayestestR:p_direction]{bayestestR::p_direction()}} for details). \code{groups} can be used to group
+coefficients. It will be passed to the print-method, or can directly be
+used in \code{print()}, see documentation in \code{\link[=print.parameters_model]{print.parameters_model()}}.
+Furthermore, see 'Examples' for this function. For developers, whose
+interest mainly is to get a "tidy" data frame of model summaries, it is
+recommended to set \code{pretty_names = FALSE} to speed up computation of the
+summary table.}
\item{clustering_function, gap_method}{Other arguments passed to other
functions. \code{clustering_function} is used by \code{fviz_nbclust()} and
diff --git a/man/p_direction.lm.Rd b/man/p_direction.lm.Rd
new file mode 100644
index 000000000..e7e74d8e7
--- /dev/null
+++ b/man/p_direction.lm.Rd
@@ -0,0 +1,240 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/p_direction.R
+\name{p_direction.lm}
+\alias{p_direction.lm}
+\title{Probability of Direction (pd)}
+\usage{
+\method{p_direction}{lm}(
+ x,
+ ci = 0.95,
+ method = "direct",
+ null = 0,
+ vcov = NULL,
+ vcov_args = NULL,
+ ...
+)
+}
+\arguments{
+\item{x}{A statistical model.}
+
+\item{ci}{Confidence Interval (CI) level. Default to \code{0.95} (\verb{95\%}).}
+
+\item{method}{Can be \code{"direct"} or one of methods of \code{\link[bayestestR:estimate_density]{estimate_density()}},
+such as \code{"kernel"}, \code{"logspline"} or \code{"KernSmooth"}. See details.}
+
+\item{null}{The value considered as a "null" effect. Traditionally 0, but
+could also be 1 in the case of ratios of change (OR, IRR, ...).}
+
+\item{vcov}{Variance-covariance matrix used to compute uncertainty estimates
+(e.g., for robust standard errors). This argument accepts a covariance matrix,
+a function which returns a covariance matrix, or a string which identifies
+the function to be used to compute the covariance matrix.
+\itemize{
+\item A covariance matrix
+\item A function which returns a covariance matrix (e.g., \code{stats::vcov()})
+\item A string which indicates the kind of uncertainty estimates to return.
+\itemize{
+\item Heteroskedasticity-consistent: \code{"vcovHC"}, \code{"HC"}, \code{"HC0"}, \code{"HC1"},
+\code{"HC2"}, \code{"HC3"}, \code{"HC4"}, \code{"HC4m"}, \code{"HC5"}. See \code{?sandwich::vcovHC}.
+\item Cluster-robust: \code{"vcovCR"}, \code{"CR0"}, \code{"CR1"}, \code{"CR1p"}, \code{"CR1S"},
+\code{"CR2"}, \code{"CR3"}. See \code{?clubSandwich::vcovCR}.
+\item Bootstrap: \code{"vcovBS"}, \code{"xy"}, \code{"residual"}, \code{"wild"}, \code{"mammen"},
+\code{"webb"}. See \code{?sandwich::vcovBS}.
+\item Other \code{sandwich} package functions: \code{"vcovHAC"}, \code{"vcovPC"}, \code{"vcovCL"},
+\code{"vcovPL"}.
+}
+}}
+
+\item{vcov_args}{List of arguments to be passed to the function identified by
+the \code{vcov} argument. This function is typically supplied by the \strong{sandwich}
+or \strong{clubSandwich} packages. Please refer to their documentation (e.g.,
+\code{?sandwich::vcovHAC}) to see the list of available arguments.}
+
+\item{...}{Arguments passed to other methods, e.g. \code{ci()}. Arguments like
+\code{vcov} or \code{vcov_args} can be used to compute confidence intervals using a
+specific variance-covariance matrix for the standard errors.}
+}
+\value{
+A data frame.
+}
+\description{
+Compute the \strong{Probability of Direction} (\emph{pd}, also known as
+the Maximum Probability of Effect - \emph{MPE}). This can be interpreted as the
+probability that a parameter (described by its full confidence, or
+"compatibility" interval) is strictly positive or negative (whichever is the
+most probable). Although differently expressed, this index is fairly similar
+(i.e., is strongly correlated) to the frequentist \emph{p-value} (see 'Details').
+}
+\section{What is the \emph{pd}?}{
+
+
+
+The Probability of Direction (pd) is an index of effect existence, representing
+the certainty with which an effect goes in a particular direction (i.e., is
+positive or negative / has a sign), typically ranging from 0.5 to 1 (but see
+next section for cases where it can range between 0 and 1). Beyond
+its simplicity of interpretation, understanding and computation, this index
+also presents other interesting properties:
+\itemize{
+\item Like other posterior-based indices, \emph{pd} is solely based on the posterior
+distributions and does not require any additional information from the data
+or the model (e.g., such as priors, as in the case of Bayes factors).
+\item It is robust to the scale of both the response variable and the predictors.
+\item It is strongly correlated with the frequentist p-value, and can thus
+be used to draw parallels and give some reference to readers non-familiar
+with Bayesian statistics (Makowski et al., 2019).
+}
+
+}
+
+\section{Relationship with the p-value}{
+
+
+
+In most cases, it seems that the \emph{pd} has a direct correspondence with the
+frequentist one-sided \emph{p}-value through the formula (for two-sided \emph{p}):
+\ifelse{html}{\out{p = 2 * (1 - p}}\preformatted{# simulate full normal distribution
+out <- bayestestR::distribution_normal(10000, 0, 0.5)
+# range of "full" distribution
+range(out)
+# range of 95\% CI
+round(quantile(out, probs = c(0.025, 0.975)), 2)
+}\if{html}{\out{
}}
+
+This ensures that the practical significance always refers to the general
+compatible parameter space of coefficients. Therefore, the \emph{full interval} is
+similar to a Bayesian posterior distribution of an equivalent Bayesian model,
+see following code:
+
+\if{html}{\out{}}\preformatted{library(bayestestR)
+library(brms)
+m <- lm(mpg ~ gear + wt + cyl + hp, data = mtcars)
+m2 <- brm(mpg ~ gear + wt + cyl + hp, data = mtcars)
+# probability of significance (ps) for frequentist model
+p_significance(m)
+# similar to ps of Bayesian models
+p_significance(m2)
+# similar to ps of simulated draws / bootstrap samples
+p_significance(simulate_model(m))
+}\if{html}{\out{
}}
+}
+\note{
+There is also a \href{https://easystats.github.io/see/articles/bayestestR.html}{\code{plot()}-method}
+implemented in the \href{https://easystats.github.io/see/}{\strong{see}-package}.
+}
+\section{Statistical inference - how to quantify evidence}{
+
+There is no standardized approach to drawing conclusions based on the
+available data and statistical models. A frequently chosen but also much
+criticized approach is to evaluate results based on their statistical
+significance (\emph{Amrhein et al. 2017}).
+
+A more sophisticated way would be to test whether estimated effects exceed
+the "smallest effect size of interest", to avoid even the smallest effects
+being considered relevant simply because they are statistically significant,
+but clinically or practically irrelevant (\emph{Lakens et al. 2018, Lakens 2024}).
+
+A rather unconventional approach, which is nevertheless advocated by various
+authors, is to interpret results from classical regression models either in
+terms of probabilities, similar to the usual approach in Bayesian statistics
+(\emph{Schweder 2018; Schweder and Hjort 2003; Vos 2022}) or in terms of relative
+measure of "evidence" or "compatibility" with the data (\emph{Greenland et al. 2022;
+Rafi and Greenland 2020}), which nevertheless comes close to a probabilistic
+interpretation.
+
+A more detailed discussion of this topic is found in the documentation of
+\code{\link[=p_function]{p_function()}}.
+
+The \strong{parameters} package provides several options or functions to aid
+statistical inference. These are, for example:
+\itemize{
+\item \code{\link[=equivalence_test.lm]{equivalence_test()}}, to compute the (conditional)
+equivalence test for frequentist models
+\item \code{\link[=p_significance.lm]{p_significance()}}, to compute the probability of
+\emph{practical significance}, which can be conceptualized as a unidirectional
+equivalence test
+\item \code{\link[=p_function]{p_function()}}, or \emph{consonance function}, to compute p-values and
+compatibility (confidence) intervals for statistical models
+\item the \code{pd} argument (setting \code{pd = TRUE}) in \code{model_parameters()} includes
+a column with the \emph{probability of direction}, i.e. the probability that a
+parameter is strictly positive or negative. See \code{\link[bayestestR:p_direction]{bayestestR::p_direction()}}
+for details. If plotting is desired, the \code{\link[=p_direction.lm]{p_direction()}}
+function can be used, together with \code{plot()}.
+\item the \code{s_value} argument (setting \code{s_value = TRUE}) in \code{model_parameters()}
+replaces the p-values with their related \emph{S}-values (\emph{Rafi and Greenland 2020})
+\item finally, it is possible to generate distributions of model coefficients by
+generating bootstrap-samples (setting \code{bootstrap = TRUE}) or simulating
+draws from model coefficients using \code{\link[=simulate_model]{simulate_model()}}. These samples
+can then be treated as "posterior samples" and used in many functions from
+the \strong{bayestestR} package.
+}
+
+Most of the above shown options or functions derive from methods originally
+implemented for Bayesian models (\emph{Makowski et al. 2019}). However, assuming
+that model assumptions are met (which means, the model fits well to the data,
+the correct model is chosen that reflects the data generating process
+(distributional model family) etc.), it seems appropriate to interpret
+results from classical frequentist models in a "Bayesian way" (more details:
+documentation in \code{\link[=p_function]{p_function()}}).
+}
+
+\examples{
+\dontshow{if (requireNamespace("bayestestR") && packageVersion("bayestestR") > "0.14.0" && requireNamespace("sandwich")) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
+data(qol_cancer)
+model <- lm(QoL ~ time + age + education, data = qol_cancer)
+
+p_significance(model)
+p_significance(model, threshold = c(-0.5, 1.5))
+
+# based on heteroscedasticity-robust standard errors
+p_significance(model, vcov = "HC3")
+
+if (require("see", quietly = TRUE)) {
+ result <- p_significance(model)
+ plot(result)
+}
+\dontshow{\}) # examplesIf}
+}
+\references{
+\itemize{
+\item Amrhein, V., Korner-Nievergelt, F., and Roth, T. (2017). The earth is
+flat (p > 0.05): Significance thresholds and the crisis of unreplicable
+research. PeerJ, 5, e3544. \doi{10.7717/peerj.3544}
+\item Greenland S, Rafi Z, Matthews R, Higgs M. To Aid Scientific Inference,
+Emphasize Unconditional Compatibility Descriptions of Statistics. (2022)
+https://arxiv.org/abs/1909.08583v7 (Accessed November 10, 2022)
+\item Lakens, D. (2024). Improving Your Statistical Inferences (Version v1.5.1).
+Retrieved from https://lakens.github.io/statistical_inferences/.
+\doi{10.5281/ZENODO.6409077}
+\item Lakens, D., Scheel, A. M., and Isager, P. M. (2018). Equivalence Testing
+for Psychological Research: A Tutorial. Advances in Methods and Practices
+in Psychological Science, 1(2), 259–269. \doi{10.1177/2515245918770963}
+\item Makowski, D., Ben-Shachar, M. S., Chen, S. H. A., and Lüdecke, D. (2019).
+Indices of Effect Existence and Significance in the Bayesian Framework.
+Frontiers in Psychology, 10, 2767. \doi{10.3389/fpsyg.2019.02767}
+\item Rafi Z, Greenland S. Semantic and cognitive tools to aid statistical
+science: replace confidence and significance by compatibility and surprise.
+BMC Medical Research Methodology (2020) 20:244.
+\item Schweder T. Confidence is epistemic probability for empirical science.
+Journal of Statistical Planning and Inference (2018) 195:116–125.
+\doi{10.1016/j.jspi.2017.09.016}
+\item Schweder T, Hjort NL. Frequentist analogues of priors and posteriors.
+In Stigum, B. (ed.), Econometrics and the Philosophy of Economics: Theory
+Data Confrontation in Economics, pp. 285-217. Princeton University Press,
+Princeton, NJ, 2003
+\item Vos P, Holbert D. Frequentist statistical inference without repeated sampling.
+Synthese 200, 89 (2022). \doi{10.1007/s11229-022-03560-x}
+}
+}
+\seealso{
+For more details, see \code{\link[bayestestR:p_significance]{bayestestR::p_significance()}}. See also
+\code{\link[=equivalence_test]{equivalence_test()}}, \code{\link[=p_function]{p_function()}} and \code{\link[bayestestR:p_direction]{bayestestR::p_direction()}}
+for functions related to checking effect existence and significance.
+}
diff --git a/man/p_value.Rd b/man/p_value.Rd
index 9797e389f..d49b0390b 100644
--- a/man/p_value.Rd
+++ b/man/p_value.Rd
@@ -28,10 +28,9 @@ p_value(model, ...)
\item{dof}{Number of degrees of freedom to be used when calculating
confidence intervals. If \code{NULL} (default), the degrees of freedom are
-retrieved by calling \code{\link[=degrees_of_freedom]{degrees_of_freedom()}} with
-approximation method defined in \code{method}. If not \code{NULL}, use this argument
-to override the default degrees of freedom used to compute confidence
-intervals.}
+retrieved by calling \code{\link[insight:get_df]{insight::get_df()}} with approximation method
+defined in \code{method}. If not \code{NULL}, use this argument to override the
+default degrees of freedom used to compute confidence intervals.}
\item{method}{Method for computing degrees of freedom for
confidence intervals (CI) and the related p-values. Allowed are following
@@ -57,11 +56,12 @@ the function to be used to compute the covariance matrix.
\itemize{
\item Heteroskedasticity-consistent: \code{"vcovHC"}, \code{"HC"}, \code{"HC0"}, \code{"HC1"},
\code{"HC2"}, \code{"HC3"}, \code{"HC4"}, \code{"HC4m"}, \code{"HC5"}. See \code{?sandwich::vcovHC}.
-\item Cluster-robust: \code{"vcovCR"}, \code{"CR0"}, \code{"CR1"}, \code{"CR1p"}, \code{"CR1S"}, \code{"CR2"},
-\code{"CR3"}. See \code{?clubSandwich::vcovCR}.
-\item Bootstrap: \code{"vcovBS"}, \code{"xy"}, \code{"residual"}, \code{"wild"}, \code{"mammen"}, \code{"webb"}.
-See \code{?sandwich::vcovBS}.
-\item Other \code{sandwich} package functions: \code{"vcovHAC"}, \code{"vcovPC"}, \code{"vcovCL"}, \code{"vcovPL"}.
+\item Cluster-robust: \code{"vcovCR"}, \code{"CR0"}, \code{"CR1"}, \code{"CR1p"}, \code{"CR1S"},
+\code{"CR2"}, \code{"CR3"}. See \code{?clubSandwich::vcovCR}.
+\item Bootstrap: \code{"vcovBS"}, \code{"xy"}, \code{"residual"}, \code{"wild"}, \code{"mammen"},
+\code{"webb"}. See \code{?sandwich::vcovBS}.
+\item Other \code{sandwich} package functions: \code{"vcovHAC"}, \code{"vcovPC"}, \code{"vcovCL"},
+\code{"vcovPL"}.
}
}}
diff --git a/man/p_value_betwithin.Rd b/man/p_value_betwithin.Rd
index 17d814646..9f2c7069d 100644
--- a/man/p_value_betwithin.Rd
+++ b/man/p_value_betwithin.Rd
@@ -18,7 +18,10 @@ p_value_betwithin(model, dof = NULL, ...)
\item{ci}{Confidence Interval (CI) level. Default to \code{0.95} (\verb{95\%}).}
-\item{...}{Additional arguments}
+\item{...}{Additional arguments passed down to the underlying functions.
+E.g., arguments like \code{vcov} or \code{vcov_args} can be used to compute confidence
+intervals using a specific variance-covariance matrix for the standard
+errors.}
\item{dof}{Degrees of Freedom.}
}
diff --git a/man/p_value_ml1.Rd b/man/p_value_ml1.Rd
index 0fb9229f6..c272fe8d9 100644
--- a/man/p_value_ml1.Rd
+++ b/man/p_value_ml1.Rd
@@ -17,7 +17,10 @@ p_value_ml1(model, dof = NULL, ...)
\item{ci}{Confidence Interval (CI) level. Default to \code{0.95} (\verb{95\%}).}
-\item{...}{Additional arguments}
+\item{...}{Additional arguments passed down to the underlying functions.
+E.g., arguments like \code{vcov} or \code{vcov_args} can be used to compute confidence
+intervals using a specific variance-covariance matrix for the standard
+errors.}
\item{dof}{Degrees of Freedom.}
}
diff --git a/man/p_value_satterthwaite.Rd b/man/p_value_satterthwaite.Rd
index 5ac41192c..ebe3586b3 100644
--- a/man/p_value_satterthwaite.Rd
+++ b/man/p_value_satterthwaite.Rd
@@ -21,7 +21,10 @@ se_satterthwaite(model)
\item{ci}{Confidence Interval (CI) level. Default to \code{0.95} (\verb{95\%}).}
-\item{...}{Additional arguments}
+\item{...}{Additional arguments passed down to the underlying functions.
+E.g., arguments like \code{vcov} or \code{vcov_args} can be used to compute confidence
+intervals using a specific variance-covariance matrix for the standard
+errors.}
\item{dof}{Degrees of Freedom.}
}
diff --git a/man/parameters-package.Rd b/man/parameters-package.Rd
index ab8407b4f..b4e466b2c 100644
--- a/man/parameters-package.Rd
+++ b/man/parameters-package.Rd
@@ -32,25 +32,25 @@ Useful links:
}
\author{
-\strong{Maintainer}: Daniel Lüdecke \email{d.luedecke@uke.de} (\href{https://orcid.org/0000-0002-8895-3206}{ORCID}) (@strengejacke)
+\strong{Maintainer}: Daniel Lüdecke \email{d.luedecke@uke.de} (\href{https://orcid.org/0000-0002-8895-3206}{ORCID})
Authors:
\itemize{
- \item Dominique Makowski \email{dom.makowski@gmail.com} (\href{https://orcid.org/0000-0001-5375-9967}{ORCID}) (@Dom_Makowski)
+ \item Dominique Makowski \email{dom.makowski@gmail.com} (\href{https://orcid.org/0000-0001-5375-9967}{ORCID})
\item Mattan S. Ben-Shachar \email{matanshm@post.bgu.ac.il} (\href{https://orcid.org/0000-0002-4287-4801}{ORCID})
- \item Indrajeet Patil \email{patilindrajeet.science@gmail.com} (\href{https://orcid.org/0000-0003-1995-6531}{ORCID}) (@patilindrajeets)
+ \item Indrajeet Patil \email{patilindrajeet.science@gmail.com} (\href{https://orcid.org/0000-0003-1995-6531}{ORCID})
\item Søren Højsgaard \email{sorenh@math.aau.dk}
- \item Brenton M. Wiernik \email{brenton@wiernik.org} (\href{https://orcid.org/0000-0001-9560-6336}{ORCID}) (@bmwiernik)
+ \item Brenton M. Wiernik \email{brenton@wiernik.org} (\href{https://orcid.org/0000-0001-9560-6336}{ORCID})
}
Other contributors:
\itemize{
\item Zen J. Lau \email{zenjuen.lau@ntu.edu.sg} [contributor]
- \item Vincent Arel-Bundock \email{vincent.arel-bundock@umontreal.ca} (\href{https://orcid.org/0000-0003-1995-6531}{ORCID}) (@vincentab) [contributor]
- \item Jeffrey Girard \email{me@jmgirard.com} (\href{https://orcid.org/0000-0002-7359-3746}{ORCID}) (@jeffreymgirard) [contributor]
+ \item Vincent Arel-Bundock \email{vincent.arel-bundock@umontreal.ca} (\href{https://orcid.org/0000-0003-2042-7063}{ORCID}) [contributor]
+ \item Jeffrey Girard \email{me@jmgirard.com} (\href{https://orcid.org/0000-0002-7359-3746}{ORCID}) [contributor]
\item Christina Maimone \email{christina.maimone@northwestern.edu} [reviewer]
\item Niels Ohlsen (@Niels_Bremen) [reviewer]
- \item Douglas Ezra Morrison \email{dmorrison01@ucla.edu} (\href{https://orcid.org/0000-0002-7195-830X}{ORCID}) (@demstats1) [contributor]
+ \item Douglas Ezra Morrison \email{dmorrison01@ucla.edu} (\href{https://orcid.org/0000-0002-7195-830X}{ORCID}) [contributor]
\item Joseph Luchman \email{jluchman@gmail.com} (\href{https://orcid.org/0000-0002-8886-9717}{ORCID}) [contributor]
}
diff --git a/man/pool_parameters.Rd b/man/pool_parameters.Rd
index d677cd968..6b02889b0 100644
--- a/man/pool_parameters.Rd
+++ b/man/pool_parameters.Rd
@@ -8,7 +8,7 @@ pool_parameters(
x,
exponentiate = FALSE,
effects = "fixed",
- component = "conditional",
+ component = "all",
verbose = TRUE,
...
)
@@ -64,12 +64,10 @@ small samples (\emph{Barnard and Rubin, 1999}).
}
\note{
Models with multiple components, (for instance, models with zero-inflation,
-where predictors appear in the count and zero-inflation part) may fail in
-case of identical names for coefficients in the different model components,
-since the coefficient table is grouped by coefficient names for pooling. In
-such cases, coefficients of count and zero-inflation model parts would be
-combined. Therefore, the \code{component} argument defaults to
-\code{"conditional"} to avoid this.
+where predictors appear in the count and zero-inflation part, or models with
+dispersion component) may fail in rare situations. In this case, compute
+the pooled parameters for components separately, using the \code{component}
+argument.
Some model objects do not return standard errors (e.g. objects of class
\code{htest}). For these models, no pooled confidence intervals nor p-values
diff --git a/man/principal_components.Rd b/man/principal_components.Rd
index c0a644356..d851baa0c 100644
--- a/man/principal_components.Rd
+++ b/man/principal_components.Rd
@@ -106,7 +106,11 @@ frame.}
with missing values from the original data, hence the number of rows of
predicted data and original data is equal.}
-\item{digits, labels}{Arguments for \code{print()}.}
+\item{digits}{Argument for \code{print()}, indicates the number of digits
+(rounding) to be used.}
+
+\item{labels}{Argument for \code{print()}, character vector of same length as
+columns in \code{x}. If provided, adds an additional column with the labels.}
}
\value{
A data frame of loadings.
@@ -220,6 +224,17 @@ principal_components(mtcars[, 1:7], n = "all", threshold = 0.2)
# Automated number of components
principal_components(mtcars[, 1:4], n = "auto")
+# labels can be useful if variable names are not self-explanatory
+print(
+ principal_components(mtcars[, 1:4], n = "auto"),
+ labels = c(
+ "Miles/(US) gallon",
+ "Number of cylinders",
+ "Displacement (cu.in.)",
+ "Gross horsepower"
+ )
+)
+
# Sparse PCA
principal_components(mtcars[, 1:7], n = 4, sparse = TRUE)
principal_components(mtcars[, 1:7], n = 4, sparse = "robust")
diff --git a/man/print.compare_parameters.Rd b/man/print.compare_parameters.Rd
new file mode 100644
index 000000000..d74c26307
--- /dev/null
+++ b/man/print.compare_parameters.Rd
@@ -0,0 +1,268 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/format.R, R/print.compare_parameters.R,
+% R/print_html.R, R/print_md.R
+\name{format.compare_parameters}
+\alias{format.compare_parameters}
+\alias{print.compare_parameters}
+\alias{print_html.compare_parameters}
+\alias{print_md.compare_parameters}
+\title{Print comparisons of model parameters}
+\usage{
+\method{format}{compare_parameters}(
+ x,
+ split_components = TRUE,
+ select = NULL,
+ digits = 2,
+ ci_digits = digits,
+ p_digits = 3,
+ ci_width = NULL,
+ ci_brackets = NULL,
+ zap_small = FALSE,
+ format = NULL,
+ groups = NULL,
+ engine = NULL,
+ ...
+)
+
+\method{print}{compare_parameters}(
+ x,
+ split_components = TRUE,
+ caption = NULL,
+ subtitle = NULL,
+ footer = NULL,
+ digits = 2,
+ ci_digits = digits,
+ p_digits = 3,
+ zap_small = FALSE,
+ groups = NULL,
+ column_width = NULL,
+ ci_brackets = c("(", ")"),
+ select = NULL,
+ ...
+)
+
+\method{print_html}{compare_parameters}(
+ x,
+ caption = NULL,
+ subtitle = NULL,
+ footer = NULL,
+ digits = 2,
+ ci_digits = digits,
+ p_digits = 3,
+ zap_small = FALSE,
+ groups = NULL,
+ select = NULL,
+ ci_brackets = c("(", ")"),
+ font_size = "100\%",
+ line_padding = 4,
+ column_labels = NULL,
+ engine = "gt",
+ ...
+)
+
+\method{print_md}{compare_parameters}(
+ x,
+ digits = 2,
+ ci_digits = digits,
+ p_digits = 3,
+ caption = NULL,
+ subtitle = NULL,
+ footer = NULL,
+ select = NULL,
+ split_components = TRUE,
+ ci_brackets = c("(", ")"),
+ zap_small = FALSE,
+ groups = NULL,
+ engine = "tt",
+ ...
+)
+}
+\arguments{
+\item{x}{An object returned by \code{\link[=compare_parameters]{compare_parameters()}}.}
+
+\item{split_components}{Logical, if \code{TRUE} (default), For models with
+multiple components (zero-inflation, smooth terms, ...), each component is
+printed in a separate table. If \code{FALSE}, model parameters are printed
+in a single table and a \code{Component} column is added to the output.}
+
+\item{select}{Determines which columns and and which layout columns are
+printed. There are three options for this argument:
+\enumerate{
+\item Selecting columns by name or index
+\cr
+\code{select} can be a character vector (or numeric index) of column names that
+should be printed. There are two pre-defined options for selecting columns:
+\code{select = "minimal"} prints coefficients, confidence intervals and p-values,
+while \code{select = "short"} prints coefficients, standard errors and p-values.
+\item A string expression with layout pattern
+\cr
+\code{select} is a string with "tokens" enclosed in braces. These tokens will
+be replaced by their associated columns, where the selected columns will
+be collapsed into one column. However, it is possible to create multiple
+columns as well. Following tokens are replaced by the related coefficients
+or statistics: \code{{estimate}}, \code{{se}}, \code{{ci}} (or \code{{ci_low}} and \code{{ci_high}}),
+\code{{p}} and \code{{stars}}. The token \code{{ci}} will be replaced by \verb{\{ci_low\}, \{ci_high\}}.
+Furthermore, a \code{|} separates values into new cells/columns. If
+\code{format = "html"}, a \verb{