Polish documentation and vignettes

Author: mthulin

DESCRIPTION

@@ -8,7 +8,8 @@ Authors@R: c(
     person("Hadley", "Wickham", email = "[email protected]", role = c("aut", "ctb"), comment = c(ORCID = "0000-0003-4757-117X")),
     person("Niladri Roy", "Chowdhury", email = "[email protected]", role = c("aut", "ctb")),
     person("Di", "Cook", email = "[email protected]", role = c("aut", "cre"), comment = c(ORCID = "0000-0002-3813-7155")),
-    person("Heike", "Hofmann", email = "[email protected]", role = c("aut", "ctb"), comment = c(ORCID = "0000-0001-6216-5183"))
+    person("Heike", "Hofmann", email = "[email protected]", role = c("aut", "ctb"), comment = c(ORCID = "0000-0001-6216-5183")),
+    person("Måns", "Thulin", email = "[email protected]", role = c("aut", "ctb"))
   )
 Maintainer: Di Cook <[email protected]>
 License: GPL (>= 2)

R/method-model.r

@@ -9,7 +9,7 @@
 #'   'rotate', 'perm', 'pboot' and 'boot' are defined by \code{\link{resid_rotate}},
 #'   \code{\link{resid_perm}}, \code{\link{resid_pboot}} and \code{\link{resid_boot}}
 #'   respectively
-#' @param additional whether to compute additional meaures: standardized
+#' @param additional whether to compute additional measures: standardized
 #'   residuals and leverage
 #' @param ... other arguments passed onto \code{method}.
 #' @return a function that given \code{data} generates a null data set.

R/quick_plots.R

@@ -7,7 +7,7 @@
 #' descriptions of these plots.
 #' In the lineup protocol the plot of the real data is embedded amongst a field of
 #' plots of data generated to be consistent with some null hypothesis.
-#' If the observe can pick the real data as different from the others, this
+#' If the observer can pick the real data as different from the others, this
 #' lends weight to the statistical significance of the structure in the plot.
 #' The protocol is described in Buja et al. (2009).
 #'
@@ -25,9 +25,11 @@
 #'    and high leverage, which are likely to have a strong influence on
 #'    the model fit.
 #'
-#' Generate n - 1 null datasets and randomly position the true data.  If you
-#' pick the real data as being noticeably different, then you have formally
-#' established that it is different to with p-value 1/n.
+#' 19 null datasets are plotted together the the true data (randomly
+#' positioned). If you pick the real data as being noticeably different, then
+#' you have formally established that it is different to with p-value 0.05.
+#' Run the \code{decrypt} message printed in the R Console to see which
+#' plot represents the true data.
 #'
 #' If the null hypothesis in the type 1 plot is violated, consider using
 #' a different model. If the null hypotheses in the type 2 or 3 plots
@@ -127,13 +129,16 @@ lineup_residuals <- function(model, type = 1, method = "rotate", color_points =
 #' \code{dist} argument.
 #' In the lineup protocol the plot of the real data is embedded amongst a field of
 #' plots of data generated to be consistent with some null hypothesis.
-#' If the observe can pick the real data as different from the others, this
+#' If the observer can pick the real data as different from the others, this
 #' lends weight to the statistical significance of the structure in the plot.
 #' The protocol is described in Buja et al. (2009).
 #'
-#' @details #' Generate n - 1 null datasets and randomly position the true data.  If you
-#' pick the real data as being noticeably different, then you have formally
-#' established that it is different to with p-value 1/n.
+#' @details 19 null datasets are plotted together the the true data (randomly
+#' positioned)  If you pick the real data as being noticeably different, then
+#' you have formally established that it is different to with p-value 0.05.
+#'
+#' Run the \code{decrypt} message printed in the R Console to see which
+#' plot represents the true data.
 #'
 #' @param data a data frame.
 #' @param variable the name of the variable that should be plotted.
@@ -209,13 +214,16 @@ lineup_histograms <- function(data, variable, dist = NULL, params = NULL, color_
 #' data follows the distribution specified by the \code{dist} argument.
 #' In the lineup protocol the plot of the real data is embedded amongst a field of
 #' plots of data generated to be consistent with some null hypothesis.
-#' If the observe can pick the real data as different from the others, this
+#' If the observer can pick the real data as different from the others, this
 #' lends weight to the statistical significance of the structure in the plot.
 #' The protocol is described in Buja et al. (2009).
 #'
-#' @details Generate n - 1 null datasets and randomly position the true data.  If you
-#' pick the real data as being noticeably different, then you have formally
-#' established that it is different to with p-value 1/n.
+#' @details 19 null datasets are plotted together the the true data (randomly
+#' positioned)  If you pick the real data as being noticeably different, then
+#' you have formally established that it is different to with p-value 0.05.
+#'
+#' Run the \code{decrypt} message printed in the R Console to see which
+#' plot represents the true data.
 #'
 #' @param data a data frame.
 #' @param variable the name of the variable that should be plotted.

man/lineup_histograms.Rd

@@ -63,7 +63,7 @@ lineup_histograms(tips, "total_bill", dist = "gamma")
 ### Specifying distribution parameters
 In some cases, we need (or want) to specify the entire distribution, and not just the family. We then provide the distribution parameters, using the standard format for the distribution (i.e. the same used by `r*`, `d*`, `p*`, and `q*` functions, where `*` is the distribution name).
 
-Let's say that we want to test whether a dataset comes from a uniform $U(0,1)$ distribution. First, we generate two example variables. `x1` is $U(0,1)$, but `x2` is not.
+As an example, let's say that we want to test whether a dataset comes from a uniform $U(0,1)$ distribution. First, we generate two example variables. `x1` is $U(0,1)$, but `x2` is not.
 
 ```{r message=FALSE}
 example_data <- data.frame(x1 = runif(100, 0, 1),
@@ -84,9 +84,9 @@ lineup_histograms(example_data, "x2", dist = "uniform", params = list(min = 0, m
 
 
 ## Using Q-Q plots
-An alternative to histograms is to use quantile-quantile plots, in which the theoretical quantiles of the distribution are compared to the empirical quantiles from the data. Under the null hypothesis, the points should lie along the reference line. However, some deviations in the tails are usually expected. A lineup plot is useful to see how much points can deviate from the reference line under the null hypothesis.
+An alternative to histograms is to use quantile-quantile plots, in which the theoretical quantiles of the distribution are compared to the empirical quantiles from the (standardized) data. Under the null hypothesis, the points should lie along the reference line. However, some deviations in the tails are usually expected. A lineup plot is useful to see how much points can deviate from the reference line under the null hypothesis.
 
-To create a Q-Q lineup plot, use `lineup_qq`:
+To create a Q-Q lineup plot using the normal distribution as the null distribution, use `lineup_qq` as follows:
 
 ```{r message=FALSE}
 lineup_qq(tips, "total_bill", dist = "normal")

man/lineup_qq.Rd

@@ -31,7 +31,7 @@ x <- lm(tip ~ total_bill, data = tips)
 
 The `lineup_residuals` function can now be used to generate four types of residual lineup plots.
 
-The first residual plot shows the residuals versus the fitted values. It is used to test the hypothesis that the response variable is a linear combination of the predictors:
+The first residual plot shows the residuals versus the fitted values. It is used to test the hypothesis that the response variable is a linear combination of the predictors. If you can spot the true data in the plot, you can formally reject the null hypothesis with p-value 0.05 (Buja et al., 2009; Li et al., 2024). After running the code below, run the `decrypt` message (e.g. `decrypt("XSKz 5xQx Vd Z3jVQV3d ww")`) printed in the R Console to see which dataset is the true data.
 
 ```{r message=FALSE}
 lineup_residuals(x, type = 1)
@@ -74,4 +74,6 @@ References
 
 Buja, A., Cook, D., Hofmann, H., Lawrence, M., Lee, E.-K., Swayne, D. F, Wickham, H. (2009) Statistical Inference for Exploratory Data Analysis and Model Diagnostics, Royal Society Philosophical Transactions A, 367:4361--4383, DOI: 10.1098/rsta.2009.0120.
 
+Li, W., Cook, D., Tanaka, E., & VanderPlas, S. (2024). A plot is worth a thousand tests: Assessing residual diagnostics with the lineup protocol. Journal of Computational and Graphical Statistics, 1-19.
+
 Thulin, M. (2024) _Modern Statistics with R_. Boca Raton: CRC Press. ISBN 9781032512440. [https://www.modernstatisticswithr.com/](https://www.modernstatisticswithr.com/)