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..fd2f29cb 100644 --- a/R/log-lik.R +++ b/R/log-lik.R @@ -442,6 +442,13 @@ 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, 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. #' @param prob A numeric vector of the probability of the category. Must sum @@ -452,6 +459,21 @@ 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}. +#' +#' 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/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..9bcf50ba 100644 --- a/man/log_lik_multinom.Rd +++ b/man/log_lik_multinom.Rd @@ -40,10 +40,33 @@ 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, 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)) } +\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}. + +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: \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()}},