cleanup docs

R/stan_esf.R

@@ -73,23 +73,15 @@
 #'
 #' Eigenvector spatial filtering (ESF) is a method for spatial regression analysis. ESF is extensively covered in Griffith et al. (2019). This function implements the methodology introduced in Donegan et al. (2020), which uses Piironen and Vehtari's (2017) regularized horseshoe prior.
 #'
-#' ESF decomposes spatial autocorrelation into a linear combination of various patterns, typically at different scales (such as local, regional, and global trends). By adding a spatial filter to a regression model, these spatial autocorrelation patterns are shifted from the residuals to the spatial filter. ESF models take the spectral decomposition of a transformed spatial connectivity matrix, \eqn{C}. The resulting eigenvectors, \eqn{E}, are mutually orthogonal and uncorrelated map patterns. The spatial filter equals \eqn{E \beta_{E}} where \eqn{\beta_{E}} is a vector of coefficients.
+#'  By adding a spatial filter to a regression model, spatial autocorrelation patterns are shifted from the residuals to the spatial filter. ESF models take the spectral decomposition of a transformed spatial connectivity matrix, \eqn{C}. The resulting eigenvectors, \eqn{E}, are mutually orthogonal and uncorrelated map patterns (at various scales, 'local' to 'regional' to 'global'). The spatial filter equals \eqn{E \beta_{E}} where \eqn{\beta_{E}} is a vector of coefficients.
 #'
 #' ESF decomposes the data into a global mean, \eqn{\alpha}, global patterns contributed by covariates \eqn{X \beta}, spatial trends \eqn{E \beta_{E}}, and residual variation. Thus, for `family=gaussian()`,
 #' 
 #' \deqn{
 #' y \sim Gauss(\alpha + X * \beta + E \beta_{E}, \sigma).
 #'}
 #' 
-#' An ESF component can be incorporated into the linear predictor of any generalized linear model. For example, a spatial Poisson model for rare disease incidence may be specified as follows:
-#' 
-#' \deqn{y \sim Poisson(e^{O + \mu})}
-#' \deqn{\mu = \alpha + E \beta_{E} + A }
-#' \deqn{ A \sim Guass(0, \tau) }
-#' \deqn{ \tau \sim student(20, 0, 2) }
-#' \deqn{ \beta_{E} \sim horseshoe(.) }
-#' 
-#' The form of this model is similar to the BYM model (see \link[geostan]{stan_icar}), in the sense that it contains a spatially structured trend term (\eqn{E \beta_{E}}) and an unstructured ('random effects') term (\eqn{A}).
+#' An ESF component can be incorporated into the linear predictor of any generalized linear model. For example, using `stan_esf` with `family = poisson()` and adding a 'random effects' term for each spatial unit (via the `re` argument) will produce a model that resembles the BYM model (combining spatially structured and spatially-unstructured components). 
 #' 
 #' The \link[geostan]{spatial.geostan_fit} method will return \eqn{E \beta_{E}}.
 #'
@@ -99,7 +91,7 @@
 #'
 #' ## Additional functionality
 #'
-#' The CAR models can also incorporate spatially-lagged covariates, measurement/sampling error in covariates (particularly when using small area survey estimates as covariates), missing outcome data, and censored outcomes (such as arise when a disease surveillance system suppresses data for privacy reasons). For details on these options, please see the Details section in the documentation for \link[geostan]{stan_glm}.
+#' The ESF models can also incorporate spatially-lagged covariates, measurement/sampling error in covariates (particularly when using small area survey estimates as covariates), missing outcome data, and censored outcomes (such as arise when a disease surveillance system suppresses data for privacy reasons). For details on these options, please see the Details section in the documentation for \link[geostan]{stan_glm}.
 #' 
 #' @return An object of class class \code{geostan_fit} (a list) containing: 
 #' \describe{
@@ -139,7 +131,7 @@
 #' Piironen, J and A. Vehtari (2017). Sparsity information and regularization in the horseshoe and other shrinkage priors. In *Electronic Journal of Statistics*, 11(2):5018-5051.
 #' 
 #' @examples
-#' \donttest{
+#'\donttest{
 #' data(sentencing)
 #' # spatial weights matrix with binary coding scheme
 #' C <- shape2mat(sentencing, style = "B", quiet = TRUE)

R/stan_glm.R

@@ -67,24 +67,6 @@
 #'
 #' Fit a generalized linear model using the R formula interface. Default prior distributions are designed to be weakly informative relative to the data. Much of the functionality intended for spatial models, such as the ability to add spatially lagged covariates and observational error models, are also available in \code{stan_glm}. All of \code{geostan}'s spatial models build on top of the same Stan code used in \code{stan_glm}.
 #'
-#' ### Poisson models and disease mapping
-#' 
-#' In spatial statistics, Poisson models are often used to calculate incidence rates (mortality rates, or disease incidence rates) for administrative areas like counties or census tracts. If \eqn{y} are counts of cases, and \eqn{P} are populations at risk, then the crude rates are \eqn{y/P}. The purpose is to model risk \eqn{\eta} for which crude rates are a (noisy) indicator. Our analysis should also respect the fact that the amount of information contained in the observations \eqn{y/P} increases with \eqn{P}. Hierarchical Poisson models are often used to incorporate all of this information.
-#'
-#' For the Poisson model, \eqn{y} is specified as the outcome and the log of the population at risk `log(P)` needs to be provided as an offset term. For such a case, disease incidence across the collection of areas could be modeled as:
-#'
-#' \deqn{y \sim Poisson(e^{log(P) + \eta})}
-#' \deqn{ \eta = \alpha + A}
-#' \deqn{ A \sim Gauss(0, \tau)}
-#' \deqn{\tau \sim Student(20, 0, 2)}
-#' where \eqn{\alpha} is the mean log-risk (incidence rate) and \eqn{A} is a vector of (so-called) random effects, which enable partial pooling of information across observations. Covariates can be added to the model for the log-rates, such that \eqn{\eta = \alpha + X \beta + A}.
-#'
-#' Note that the denominator for the rates is specified as a log-offset to provide a consistent, formula-line interface to the model. Using the log-offest (as above) is equivalent to the following:
-#' \deqn{
-#' y \sim Poisson(P * e^{\eta})
-#' }
-#' where \eqn{P} is still the population at risk and it is multiplied by \eqn{e^{\eta}}, the incidence rate (risk). 
-#'
 #' ### Spatially lagged covariates (SLX)
 #' 
 #' The `slx` argument is a convenience function for including SLX terms. For example, 
@@ -219,6 +201,10 @@
 #'                 quiet = TRUE)
 #'
 #' print(fit2)
+#'
+#' # example prior for two covariates
+#' pl <- list(beta = normal(c(0, 0),
+#'                          c(1, 1))
 #' 
 #' ##
 #' ## Poisson model for count data
@@ -247,17 +233,20 @@
 #'
 #' # summary of results with MCMC diagnostics
 #' print(fit.pois)
-#' 
+#'
+#' \donttest{
 #' # MCMC diagnostics plot: Rhat values should all by very near 1
 #' rstan::stan_rhat(fit.pois$stanfit)
 #' 
+#' 
 #' # effective sample size for all parameters and generated quantities
 #' # (including residuals, predicted values, etc.)
 #' rstan::stan_ess(fit.pois$stanfit)
 #' 
 #' # or for a particular parameter
 #' rstan::stan_ess(fit.pois$stanfit, "alpha_re")
-#'
+#' }
+#' 
 #' ##
 #' ## Visualize the posterior predictive distribution
 #' ##

R/stan_icar.R

@@ -161,7 +161,7 @@
 #' ```
 #' ## Additional functionality
 #'
-#' The CAR models can also incorporate spatially-lagged covariates, measurement/sampling error in covariates (particularly when using small area survey estimates as covariates), missing outcome data, and censored outcomes (such as arise when a disease surveillance system suppresses data for privacy reasons). For details on these options, please see the Details section in the documentation for \link[geostan]{stan_glm}.
+#' The ICAR models can also incorporate spatially-lagged covariates, measurement/sampling error in covariates (particularly when using small area survey estimates as covariates), missing outcome data, and censored outcomes (such as arise when a disease surveillance system suppresses data for privacy reasons). For details on these options, please see the Details section in the documentation for \link[geostan]{stan_glm}.
 #' 
 #' @return An object of class class \code{geostan_fit} (a list) containing: 
 #' \describe{
@@ -221,30 +221,6 @@
 #' library(rstan)
 #' rstan::stan_ess(fit.bym$stanfit)
 #' rstan::stan_rhat(fit.bym$stanfit)
-#' 
-#' # calculate log-standardized incidence ratios 
-#' # (observed/exected case counts)
-#' library(ggplot2)
-#' library(sf)
-#' 
-#' f <- fitted(fit.bym, rates = FALSE)$mean
-#' SSR <- f / sentencing$expected_sents
-#' log.SSR <- log( SSR, base = 2)
-#'
-#' ggplot(sentencing) +
-#'   geom_sf(aes(fill = log.SSR)) +
-#'   scale_fill_gradient2(
-#'    low = "navy",
-#'    high = "darkred"
-#'   ) +
-#'   labs(title = "Log-standardized incidence ratios",
-#'        subtitle = "log( Fitted/Expected), base 2") +
-#'   theme_void() +
-#'   theme(
-#'    legend.position = "bottom",
-#'    legend.key.height = unit(0.35, "cm"),
-#'    legend.key.width = unit(1.5, "cm")
-#'   )
 #' }
 #' @export
 #' @md