From 80e95cd17c65544f276b343dd74c5a5961c27af4 Mon Sep 17 00:00:00 2001
From: Joe Thorley <joe@poissonconsulting.ca>
Date: Tue, 25 Aug 2026 09:40:44 +0100
Subject: [PATCH 1/3] Cite literature justifying the multinomial functions

Add @references to the four multinomial roxygen blocks: the
multinomial-Poisson identity underlying the log-likelihood and deviance
(Baker 1994; McCullagh and Nelder 1989; Forster 2010; Agresti 2013), the
standardized and deviance residual definitions (Haberman 1973; Pierce
and Schafer 1986), and the joint per-trial replicate used for posterior
predictive residuals (Gelman, Meng and Stern 1996; Johnson, Kotz and
Balakrishnan 1997).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 R/dev.R                 |  9 +++++++++
 R/log-lik.R             | 10 ++++++++++
 R/ran.R                 |  7 +++++++
 R/res.R                 | 11 +++++++++++
 man/dev_multinom.Rd     | 10 ++++++++++
 man/log_lik_multinom.Rd | 11 +++++++++++
 man/ran_multinom.Rd     |  8 ++++++++
 man/res_multinom.Rd     | 12 ++++++++++++
 8 files changed, 78 insertions(+)

diff --git a/R/dev.R b/R/dev.R
index d9fda82f..cea3d5d9 100644
--- a/R/dev.R
+++ b/R/dev.R
@@ -287,6 +287,15 @@ dev_lnorm <- function(x, meanlog = 0, sdlog = 1, res = FALSE) {
 #'
 #' @return An numeric vector of the corresponding deviances or deviance residuals.
 #' @family dev_dist
+#' @references
+#' McCullagh, P., and Nelder, J.A. 1989.
+#' Generalized Linear Models. 2nd edition. Chapman and Hall, London.
+#'
+#' Baker, S.G. 1994. The multinomial-Poisson transformation.
+#' The Statistician 43(4): 495-504. \doi{10.2307/2348134}.
+#'
+#' Agresti, A. 2013. Categorical Data Analysis. 3rd edition.
+#' John Wiley and Sons, Hoboken, New Jersey.
 #' @export
 #'
 #' @examples
diff --git a/R/log-lik.R b/R/log-lik.R
index 044a61a0..d8dccdbb 100644
--- a/R/log-lik.R
+++ b/R/log-lik.R
@@ -452,6 +452,16 @@ log_lik_lnorm <- function(x, meanlog = 0, sdlog = 1, tlower = 0, tupper = Inf) {
 #' @return An numeric vector of the corresponding log-likelihoods, one value
 #'   per row of `x`.
 #' @family log_lik_dist
+#' @references
+#' Baker, S.G. 1994. The multinomial-Poisson transformation.
+#' The Statistician 43(4): 495-504. \doi{10.2307/2348134}.
+#'
+#' McCullagh, P., and Nelder, J.A. 1989.
+#' Generalized Linear Models. 2nd edition. Chapman and Hall, London.
+#'
+#' Forster, J.J. 2010. Bayesian inference for Poisson and multinomial
+#' log-linear models. Statistical Methodology 7(3): 210-224.
+#' \doi{10.1016/j.stamet.2009.12.004}.
 #' @export
 #'
 #' @examples
diff --git a/R/ran.R b/R/ran.R
index 0d5863ce..797f6817 100644
--- a/R/ran.R
+++ b/R/ran.R
@@ -133,6 +133,13 @@ ran_lnorm <- function(n = 1, meanlog = 0, sdlog = 1) {
 #'   trial, since a trial's categories are drawn jointly.
 #' @return An integer vector of the random samples, one per row of `prob`.
 #' @family ran_dist
+#' @references
+#' Johnson, N.L., Kotz, S., and Balakrishnan, N. 1997.
+#' Discrete Multivariate Distributions. John Wiley and Sons, New York.
+#'
+#' Gelman, A., Meng, X.-L., and Stern, H. 1996. Posterior predictive
+#' assessment of model fitness via realized discrepancies.
+#' Statistica Sinica 6(4): 733-807.
 #' @export
 #'
 #' @examples
diff --git a/R/res.R b/R/res.R
index 8b9e16fe..79c0be8a 100644
--- a/R/res.R
+++ b/R/res.R
@@ -276,6 +276,17 @@ res_lnorm <- function(
 #'
 #' @return An numeric vector of the corresponding residuals.
 #' @family res_dist
+#' @references
+#' Haberman, S.J. 1973. The analysis of residuals in cross-classified
+#' tables. Biometrics 29(1): 205-220. \doi{10.2307/2529686}.
+#'
+#' Pierce, D.A., and Schafer, D.W. 1986. Residuals in generalized linear
+#' models. Journal of the American Statistical Association 81(396):
+#' 977-986. \doi{10.1080/01621459.1986.10478361}.
+#'
+#' Gelman, A., Meng, X.-L., and Stern, H. 1996. Posterior predictive
+#' assessment of model fitness via realized discrepancies.
+#' Statistica Sinica 6(4): 733-807.
 #' @export
 #'
 #' @examples
diff --git a/man/dev_multinom.Rd b/man/dev_multinom.Rd
index 57dd2172..16ce6832 100644
--- a/man/dev_multinom.Rd
+++ b/man/dev_multinom.Rd
@@ -42,6 +42,16 @@ deviance.
 \examples{
 dev_multinom(c(1, 3, 6), size = 10, prob = c(0.2, 0.3, 0.5), group = c(1, 1, 1))
 }
+\references{
+McCullagh, P., and Nelder, J.A. 1989.
+Generalized Linear Models. 2nd edition. Chapman and Hall, London.
+
+Baker, S.G. 1994. The multinomial-Poisson transformation.
+The Statistician 43(4): 495-504. \doi{10.2307/2348134}.
+
+Agresti, A. 2013. Categorical Data Analysis. 3rd edition.
+John Wiley and Sons, Hoboken, New Jersey.
+}
 \seealso{
 Other dev_dist:
 \code{\link[=dev_bern]{dev_bern()}},
diff --git a/man/log_lik_multinom.Rd b/man/log_lik_multinom.Rd
index f7b1d8f5..acf2530b 100644
--- a/man/log_lik_multinom.Rd
+++ b/man/log_lik_multinom.Rd
@@ -44,6 +44,17 @@ even share of the trial's normalizing constant, so summing over a
 \examples{
 log_lik_multinom(c(1, 3, 6), size = 10, prob = c(0.2, 0.3, 0.5), group = c(1, 1, 1))
 }
+\references{
+Baker, S.G. 1994. The multinomial-Poisson transformation.
+The Statistician 43(4): 495-504. \doi{10.2307/2348134}.
+
+McCullagh, P., and Nelder, J.A. 1989.
+Generalized Linear Models. 2nd edition. Chapman and Hall, London.
+
+Forster, J.J. 2010. Bayesian inference for Poisson and multinomial
+log-linear models. Statistical Methodology 7(3): 210-224.
+\doi{10.1016/j.stamet.2009.12.004}.
+}
 \seealso{
 Other log_lik_dist:
 \code{\link[=log_lik_bern]{log_lik_bern()}},
diff --git a/man/ran_multinom.Rd b/man/ran_multinom.Rd
index de3bcc04..436901d8 100644
--- a/man/ran_multinom.Rd
+++ b/man/ran_multinom.Rd
@@ -39,6 +39,14 @@ generated independently of one another.
 \examples{
 ran_multinom(size = 10, prob = c(0.2, 0.3, 0.5), group = c(1, 1, 1))
 }
+\references{
+Johnson, N.L., Kotz, S., and Balakrishnan, N. 1997.
+Discrete Multivariate Distributions. John Wiley and Sons, New York.
+
+Gelman, A., Meng, X.-L., and Stern, H. 1996. Posterior predictive
+assessment of model fitness via realized discrepancies.
+Statistica Sinica 6(4): 733-807.
+}
 \seealso{
 Other ran_dist:
 \code{\link[=ran_bern]{ran_bern()}},
diff --git a/man/res_multinom.Rd b/man/res_multinom.Rd
index ce90ef38..a4942467 100644
--- a/man/res_multinom.Rd
+++ b/man/res_multinom.Rd
@@ -49,6 +49,18 @@ of a \code{group} in the same call.
 \examples{
 res_multinom(c(1, 3, 6), size = 10, prob = c(0.2, 0.3, 0.5), group = c(1, 1, 1))
 }
+\references{
+Haberman, S.J. 1973. The analysis of residuals in cross-classified
+tables. Biometrics 29(1): 205-220. \doi{10.2307/2529686}.
+
+Pierce, D.A., and Schafer, D.W. 1986. Residuals in generalized linear
+models. Journal of the American Statistical Association 81(396):
+977-986. \doi{10.1080/01621459.1986.10478361}.
+
+Gelman, A., Meng, X.-L., and Stern, H. 1996. Posterior predictive
+assessment of model fitness via realized discrepancies.
+Statistica Sinica 6(4): 733-807.
+}
 \seealso{
 Other res_dist:
 \code{\link[=res_bern]{res_bern()}},

From 6e653d98669da278b0f5637fbef77b7d4b089894 Mon Sep 17 00:00:00 2001
From: Joe Thorley <joe@poissonconsulting.ca>
Date: Tue, 25 Aug 2026 09:46:36 +0100
Subject: [PATCH 2/3] Note that multinomial log-likelihood rows aren't
 pointwise

Only the sum over a `group` is exact, so document that LOO/WAIC should
treat the trial rather than the row as the leave-one-out unit, and cite
Vehtari, Gelman and Gabry 2017.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 R/log-lik.R             | 11 +++++++++++
 man/log_lik_multinom.Rd | 11 +++++++++++
 2 files changed, 22 insertions(+)

diff --git a/R/log-lik.R b/R/log-lik.R
index d8dccdbb..a01d1604 100644
--- a/R/log-lik.R
+++ b/R/log-lik.R
@@ -442,6 +442,12 @@ log_lik_lnorm <- function(x, meanlog = 0, sdlog = 1, tlower = 0, tupper = Inf) {
 #' even share of the trial's normalizing constant, so summing over a
 #' `group` recovers the trial's exact multinomial log-likelihood.
 #'
+#' The even split of the normalizing constant is a bookkeeping convention:
+#' only the sum over a `group` is exact, so an individual row's value is not
+#' a valid pointwise log-likelihood. Cross-validation and information
+#' criteria should therefore treat the trial, not the row, as the
+#' leave-one-out unit.
+#'
 #' @inheritParams params
 #' @param x A non-negative whole numeric vector of the category counts.
 #' @param prob A numeric vector of the probability of the category. Must sum
@@ -462,6 +468,11 @@ log_lik_lnorm <- function(x, meanlog = 0, sdlog = 1, tlower = 0, tupper = Inf) {
 #' Forster, J.J. 2010. Bayesian inference for Poisson and multinomial
 #' log-linear models. Statistical Methodology 7(3): 210-224.
 #' \doi{10.1016/j.stamet.2009.12.004}.
+#'
+#' Vehtari, A., Gelman, A., and Gabry, J. 2017. Practical Bayesian model
+#' evaluation using leave-one-out cross-validation and WAIC.
+#' Statistics and Computing 27(5): 1413-1432.
+#' \doi{10.1007/s11222-016-9696-3}.
 #' @export
 #'
 #' @examples
diff --git a/man/log_lik_multinom.Rd b/man/log_lik_multinom.Rd
index acf2530b..b1777840 100644
--- a/man/log_lik_multinom.Rd
+++ b/man/log_lik_multinom.Rd
@@ -40,6 +40,12 @@ uses the multinomial-as-independent-Poissons identity: each row's value
 is the Poisson log-likelihood of \code{x} given \code{mu = size * prob}, minus an
 even share of the trial's normalizing constant, so summing over a
 \code{group} recovers the trial's exact multinomial log-likelihood.
+
+The even split of the normalizing constant is a bookkeeping convention:
+only the sum over a \code{group} is exact, so an individual row's value is not
+a valid pointwise log-likelihood. Cross-validation and information
+criteria should therefore treat the trial, not the row, as the
+leave-one-out unit.
 }
 \examples{
 log_lik_multinom(c(1, 3, 6), size = 10, prob = c(0.2, 0.3, 0.5), group = c(1, 1, 1))
@@ -54,6 +60,11 @@ Generalized Linear Models. 2nd edition. Chapman and Hall, London.
 Forster, J.J. 2010. Bayesian inference for Poisson and multinomial
 log-linear models. Statistical Methodology 7(3): 210-224.
 \doi{10.1016/j.stamet.2009.12.004}.
+
+Vehtari, A., Gelman, A., and Gabry, J. 2017. Practical Bayesian model
+evaluation using leave-one-out cross-validation and WAIC.
+Statistics and Computing 27(5): 1413-1432.
+\doi{10.1007/s11222-016-9696-3}.
 }
 \seealso{
 Other log_lik_dist:

From f6a834065e035ad78e45aca83bf07b846475ed45 Mon Sep 17 00:00:00 2001
From: Joe Thorley <joe@poissonconsulting.ca>
Date: Tue, 25 Aug 2026 10:04:50 +0100
Subject: [PATCH 3/3] Point to the group sum as the valid LOO unit

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 R/log-lik.R             | 3 ++-
 man/log_lik_multinom.Rd | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/R/log-lik.R b/R/log-lik.R
index a01d1604..fd2f29cb 100644
--- a/R/log-lik.R
+++ b/R/log-lik.R
@@ -446,7 +446,8 @@ log_lik_lnorm <- function(x, meanlog = 0, sdlog = 1, tlower = 0, tupper = Inf) {
 #' only the sum over a `group` is exact, so an individual row's value is not
 #' a valid pointwise log-likelihood. Cross-validation and information
 #' criteria should therefore treat the trial, not the row, as the
-#' leave-one-out unit.
+#' leave-one-out unit, which is achieved by summing the values within each
+#' `group` to get the trial's exact log-likelihood.
 #'
 #' @inheritParams params
 #' @param x A non-negative whole numeric vector of the category counts.
diff --git a/man/log_lik_multinom.Rd b/man/log_lik_multinom.Rd
index b1777840..9bcf50ba 100644
--- a/man/log_lik_multinom.Rd
+++ b/man/log_lik_multinom.Rd
@@ -45,7 +45,8 @@ The even split of the normalizing constant is a bookkeeping convention:
 only the sum over a \code{group} is exact, so an individual row's value is not
 a valid pointwise log-likelihood. Cross-validation and information
 criteria should therefore treat the trial, not the row, as the
-leave-one-out unit.
+leave-one-out unit, which is achieved by summing the values within each
+\code{group} to get the trial's exact log-likelihood.
 }
 \examples{
 log_lik_multinom(c(1, 3, 6), size = 10, prob = c(0.2, 0.3, 0.5), group = c(1, 1, 1))