From 86b8d44308b421d3afcb0bccaf1594ed8b0d080d Mon Sep 17 00:00:00 2001 From: jgabry Date: Wed, 31 Jul 2024 12:31:22 -0600 Subject: [PATCH] Document problems with `ppc_stat` with `stat="mean"` closes #321 --- R/ppc-test-statistics.R | 15 ++++++++++----- man/PPC-test-statistics.Rd | 11 ++++++++--- 2 files changed, 18 insertions(+), 8 deletions(-) diff --git a/R/ppc-test-statistics.R b/R/ppc-test-statistics.R index a9b6da86..11b9827b 100644 --- a/R/ppc-test-statistics.R +++ b/R/ppc-test-statistics.R @@ -1,10 +1,15 @@ #' PPC test statistics #' -#' The distribution of a (test) statistic `T(yrep)`, or a pair of (test) -#' statistics, over the simulated datasets in `yrep`, compared to the -#' observed value `T(y)` computed from the data `y`. See the -#' **Plot Descriptions** and **Details** sections, below, as -#' well as [Gabry et al. (2019)](https://github.com/jgabry/bayes-vis-paper#readme). +#' @description The distribution of a (test) statistic `T(yrep)`, or a pair of +#' (test) statistics, over the simulated datasets in `yrep`, compared to the +#' observed value `T(y)` computed from the data `y`. See the +#' **Plot Descriptions** and **Details** sections, below, as +#' well as Gabry et al. (2019). +#' +#' **NOTE:** Although the default test statistic +#' is the mean, this is unlikely to detect anything interesting in most cases. +#' In general we recommend using some other test statistic as discussed in +#' Section 5 of Gabry et al. (2019). #' #' @name PPC-test-statistics #' @aliases PPC-statistics diff --git a/man/PPC-test-statistics.Rd b/man/PPC-test-statistics.Rd index a96c3ed5..c934e4b3 100644 --- a/man/PPC-test-statistics.Rd +++ b/man/PPC-test-statistics.Rd @@ -118,11 +118,16 @@ customized using the \strong{ggplot2} package. The functions with suffix function. } \description{ -The distribution of a (test) statistic \code{T(yrep)}, or a pair of (test) -statistics, over the simulated datasets in \code{yrep}, compared to the +The distribution of a (test) statistic \code{T(yrep)}, or a pair of +(test) statistics, over the simulated datasets in \code{yrep}, compared to the observed value \code{T(y)} computed from the data \code{y}. See the \strong{Plot Descriptions} and \strong{Details} sections, below, as -well as \href{https://github.com/jgabry/bayes-vis-paper#readme}{Gabry et al. (2019)}. +well as Gabry et al. (2019). + +\strong{NOTE:} Although the default test statistic +is the mean, this is unlikely to detect anything interesting in most cases. +In general we recommend using some other test statistic as discussed in +Section 5 of Gabry et al. (2019). } \details{ For Binomial data, the plots may be more useful if