v1.1 ready

DESCRIPTION

@@ -2,7 +2,7 @@ Package: adjustr
 Encoding: UTF-8
 Type: Package
 Title: Stan Model Adjustments and Sensitivity Analyses using Importance Sampling
-Version: 0.1.0
+Version: 0.1.1
 Authors@R: person("Cory", "McCartan", email = "[email protected]",
   role = c("aut", "cre"))
 Description: Functions to help assess the sensitivity of a Bayesian model 
@@ -11,18 +11,17 @@ Description: Functions to help assess the sensitivity of a Bayesian model
     package uses Pareto-smoothed importance sampling to estimate posterior 
     quantities of interest under each specification.
 License: BSD_3_clause + file LICENSE
-Depends: R (>= 3.6.0)
+Depends: R (>= 3.6.0),
+    dplyr (>= 1.0.0)
 Imports:
-    tibble,
     tidyselect,
-    dplyr (>= 1.0.0),
     purrr,
     stringr,
     methods,
     utils,
     stats,
-    rlang,
     rstan,
+    rlang,
     ggplot2,
     loo
 Suggests:
@@ -33,6 +32,7 @@ Suggests:
     knitr,
     rmarkdown
 URL: https://corymccartan.github.io/adjustr/
+BugReports: https://github.com/CoryMcCartan/adjustr/issues
 LazyData: true
 RoxygenNote: 7.1.1
 VignetteBuilder: knitr

NEWS.md

@@ -1,3 +1,10 @@
+# adjustr 0.1.1
+
+* Improved documentation and additional references.
+
+* Fix bug in `extract_samp_stmts()` which prevented `brmsfit` objects from being used directly.
+
+
 # adjustr 0.1.0
 
 * Initial release.

R/adjust_weights.R

@@ -5,6 +5,16 @@
 #' data frame or list, compute Pareto-smoothed importance weights and attach
 #' them to the specification object, for further calculation and plotting.
 #'
+#' This function does the bulk of the sensitivity analysis work.  It operates
+#' by parsing the model code from the provided Stan object, extracting the
+#' parameters and their sampling statements.  It then uses R
+#' metaprogramming/tidy evaluation tools to flexibly evaluate the log density
+#' for each draw and each sampling statement, under the original and alternative
+#' specifications. From these, the function computes the overall importance
+#' weight for each draw and performs Pareto-smoothed importance sampling.  All
+#' of the work is performed in R, without recompiling or refitting the Stan
+#' model.
+#'
 #' @param spec An object of class \code{adjustr_spec}, probably produced by
 #'   \code{\link{make_spec}}, containing the new sampling sampling statements
 #'   to replace their counterparts in the original Stan model, and the data,
@@ -17,7 +27,7 @@
 #'   alternate specifications which deviate too much from the original
 #'   posterior, and which as a result cannot be reliably estimated using
 #'   importance sampling (i.e., if the Pareto shape parameter is larger than
-#'   0.7), have their weights discarded.
+#'   0.7), have their weights discarded—weights are set to \code{NA_real_}.
 #' @param incl_orig When \code{TRUE}, include a row for the original
 #'   model specification, with all weights equal. Can facilitate comaprison
 #'   and plotting later.
@@ -32,6 +42,12 @@
 #'   \code{\link{pull.adjustr_weighted}} method. The returned object also
 #'   includes the model sample draws, in the \code{draws} attribute.
 #'
+#' @references
+#' Vehtari, A., Simpson, D., Gelman, A., Yao, Y., & Gabry, J. (2015).
+#' Pareto smoothed importance sampling. \href{https://arxiv.org/abs/1507.02646}{arXiv preprint arXiv:1507.02646}.
+#'
+#' @seealso \code{\link{make_spec}}, \code{\link{summarize.adjustr_weighted}}, \code{\link{spec_plot}}
+#'
 #' @examples \dontrun{
 #' model_data = list(
 #'     J = 8,
@@ -52,6 +68,8 @@
 #' @export
 adjust_weights = function(spec, object, data=NULL, keep_bad=FALSE, incl_orig=TRUE) {
     # CHECK ARGUMENTS
+    if (is.null(data) & is(object, "brmsfit"))
+        data = object$data
     object = get_fit_obj(object)
     model_code = object@stanmodel@model_code
     stopifnot(is.adjustr_spec(spec))
@@ -120,9 +138,11 @@ is.adjustr_weighted = function(x) inherits(x, "adjustr_weighted")
 #' @param var A variable, as in \code{\link[dplyr]{pull}}. The default returns
 #'   the \code{.weights} column, and if there is only one row, it returns the
 #'   first element of that column
+#' @param name Ignored
+#' @param ... Ignored
 #'
 #' @export
-pull.adjustr_weighted = function(.data, var=".weights") {
+pull.adjustr_weighted = function(.data, var=".weights", name=NULL, ...) {
     var = tidyselect::vars_pull(names(.data), !!enquo(var))
     if (nrow(.data) == 1 && var == ".weights") {
         .data$.weights[[1]]
@@ -149,7 +169,8 @@ pull.adjustr_weighted = function(.data, var=".weights") {
 #' }
 #' @export
 extract_samp_stmts = function(object) {
-    model_code = get_fit_obj(object)@stanmodel@model_code
+    object = get_fit_obj(object)
+    model_code = object@stanmodel@model_code
 
     parsed = parse_model(model_code)
 

R/make_spec.R

@@ -42,6 +42,8 @@
 #' \code{\link[dplyr]{rename}}, and \code{\link[dplyr]{slice}}) are
 #' supported and operate on the underlying table of specification parameters.
 #'
+#' @seealso \code{\link{adjust_weights}}, \code{\link{summarize.adjustr_weighted}}, \code{\link{spec_plot}}
+#'
 #' @examples
 #' make_spec(eta ~ cauchy(0, 1))
 #'

R/use_weights.R

@@ -75,6 +75,8 @@ get_resampling_idxs = function(x, frac=1, replace=T) {
 #' @return An \code{adjustr_weighted} object, wth the new columns specified in
 #' \code{...} added.
 #'
+#' @seealso \code{\link{adjust_weights}}, \code{\link{spec_plot}}
+#'
 #' @examples \dontrun{
 #' model_data = list(
 #'     J = 8,
@@ -227,6 +229,8 @@ funs_env = new_environment(list(
 #' @return A \code{\link[ggplot2]{ggplot}} object which can be further
 #'   customized with the \strong{ggplot2} package.
 #'
+#' @seealso \code{\link{adjust_weights}}, \code{\link{summarize.adjustr_weighted}}
+#'
 #' @examples \dontrun{
 #' spec = make_spec(eta ~ student_t(df, 0, scale),
 #'                  df=1:10, scale=seq(2, 1, -1/9))

README.md

@@ -45,8 +45,34 @@ and [`spec_plot`](https://corymccartan.github.io/adjustr/reference/spec_plot.htm
 to examine posterior quantities of interest for each alternative specification,
 in order to assess the sensitivity of the underlying model.
 
+To illustrate, the package lets us do the following:
+```r
+extract_samp_stmts(eightschools_m)
+#> Sampling statements for model 2c8d1d8a30137533422c438f23b83428:
+#>   parameter   eta ~ std_normal()
+#>   data        y ~ normal(theta, sigma)
+
+make_spec(eta ~ student_t(0, 1, df), df=1:10) %>%
+    adjust_weights(eightschools_m) %>%
+    summarize(wasserstein(mu)) 
+#> # A tibble: 11 x 5
+#>       df .samp                     .weights      .pareto_k `wasserstein(mu)`
+#>    <int> <chr>                     <list>            <dbl>             <dbl>
+#>  1     1 eta ~ student_t(df, 0, 1) <dbl [1,000]>     1.02              0.928
+#>  2     2 eta ~ student_t(df, 0, 1) <dbl [1,000]>     1.03              0.736
+#>  3     3 eta ~ student_t(df, 0, 1) <dbl [1,000]>     0.915             0.534
+#>  4     4 eta ~ student_t(df, 0, 1) <dbl [1,000]>     0.856             0.411
+#>  5     5 eta ~ student_t(df, 0, 1) <dbl [1,000]>     0.826             0.341
+#>  6     6 eta ~ student_t(df, 0, 1) <dbl [1,000]>     0.803             0.275
+#>  7     7 eta ~ student_t(df, 0, 1) <dbl [1,000]>     0.782             0.234
+#>  8     8 eta ~ student_t(df, 0, 1) <dbl [1,000]>     0.753             0.195
+#>  9     9 eta ~ student_t(df, 0, 1) <dbl [1,000]>     0.736             0.166
+#> 10    10 eta ~ student_t(df, 0, 1) <dbl [1,000]>     0.721             0.151
+#> 11    NA <original model>          <dbl [1,000]>  -Inf                 0
+```
+
 The tutorial [vignette](https://corymccartan.github.io/adjustr/articles/eight-schools.html) 
-walks through a full sensitivity analysis for the classic 8-schools example.
+walks through a full sensitivity analysis for this 8-schools example.
 Smaller examples are also included in the package 
 [documentation](https://corymccartan.github.io/adjustr/reference/index.html). 
 
@@ -60,3 +86,9 @@ if (!require("devtools")) {
 }
 devtools::install_github("corymccartan/adjustr@*release")
 ```
+
+## References
+
+Vehtari, A., Simpson, D., Gelman, A., Yao, Y., & Gabry, J. (2015). 
+Pareto smoothed importance sampling. 
+_[arXiv preprint arXiv:1507.02646](https://arxiv.org/abs/1507.02646)_.

_pkgdown.yml

@@ -17,6 +17,8 @@ navbar:
       href: articles/index.html
     - text: "Functions"
       href: reference/index.html
+    - text: "News"
+      href: news/index.html
     - text: "Other Packages"
       menu:
         - text: "rstan"
@@ -55,12 +57,8 @@ home:
     interest under each specification. The package also provides functions to
     summarize and plot how these quantities change across specifications.
   links:
-  - text: Report a bug
-    href: https://github.com/corymccartan/adjustr/issues/
   - text: Ask a question
     href: https://discourse.mc-stan.org/
-  - text: Browse source code
-    href: https://github.com/corymccartan/adjustr/
 
 authors:
   Cory McCartan: