diff --git a/_pkgdown.yml b/_pkgdown.yml index d69e9638..5de22c84 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -65,6 +65,11 @@ articles: An overview of a new datatype introduced by posterior contents: - rvar + - title: "Pareto-khat diagnostics" + desc: > + An overview of diagnostics related to Pareto-smoothed importance sampling + contents: + - pareto_diagnostics reference: - title: "Overview" @@ -93,6 +98,7 @@ reference: - order_draws - split_chains - subset_draws + - draws-index - rename_variables - repair_draws - resample_draws @@ -108,14 +114,13 @@ reference: - starts_with("ess") - starts_with("rhat") - starts_with("mcse") + - starts_with("pareto") + - starts_with("ps") - quantile2 - rstar - entropy - dissent - modal_category - - pareto_diags - - pareto_khat - - pareto_smooth - title: "Functionality specific to the rvar datatype" desc: > The `draws_rvar` format (a structured list of `rvar` objects) has the same diff --git a/docs/404.html b/docs/404.html index ce26ebe5..2ef5e33d 100644 --- a/docs/404.html +++ b/docs/404.html @@ -39,7 +39,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/CONTRIBUTING.html b/docs/CONTRIBUTING.html new file mode 100644 index 00000000..7aa0bbb2 --- /dev/null +++ b/docs/CONTRIBUTING.html @@ -0,0 +1,162 @@ + +Contributing to posterior • posterior + + +
+
+ + + +
+
+
+

Contributing to posterior

+
+ +
+ +

This outlines how to propose a change to posterior and is based on similar instructions for tidyverse packages, including the contributing guidelines generated by usethis::use_tidy_contributing().

+
+

Fixing typos

+

You can fix typos, spelling mistakes, or grammatical errors in the documentation directly using the GitHub web interface, as long as the changes are made in the source file. This generally means you’ll need to edit roxygen2 comments in an .R, not a .Rd file. You can find the .R file that generates the .Rd by reading the comment in the first line.

+
+
+

Bigger changes

+

If you want to make a bigger change, it’s a good idea to first file an issue and make sure someone from the team agrees that it’s needed. If you’ve found a bug, please file an issue that illustrates the bug with a minimal reproducible example (see e.g. the tidyverse reprex instructions). The tidyverse guide on how to create a great issue has more advice.

+
+

Pull request process

+

If you are new to creating pull requests here are some tips. Using the functions from the usethis package is not required but can be helpful if this process is new to you.

+

  • Fork the package and clone onto your computer. If you haven’t done this before, we recommend using usethis::create_from_github("stan-dev/posterior", fork = TRUE).

    • +

  • Install all development dependencies with devtools::install_dev_deps(), and then make sure the package passes R CMD check by running devtools::check(). If R CMD check doesn’t pass cleanly, it’s a good idea to ask for help before continuing.

    • +

  • Create a Git branch for your pull request (PR). We recommend using usethis::pr_init("brief-description-of-change").

    • +

  • Make your changes, commit to git, and then create a PR by running usethis::pr_push(), and following the prompts in your browser. The title of your PR should briefly describe the change. The body of your PR should contain Fixes #issue-number.

    • +

  • For user-facing changes, add a bullet to the top of NEWS.md (i.e. just below the first header). Follow the style already used in NEWS.md.

    • +
+
+

Code style

+

  • New code should attempt to follow the style used in the package. When in doubt follow the tidyverse style guide.

    • +

  • We use roxygen2, with Markdown syntax, for documentation.

    • +

  • We use testthat for unit tests. Contributions with test cases included are easier to accept.

    • +
+
+
+

Code of Conduct

+

Please note that the posterior project follows the Stan project’s Code of Conduct. By contributing to this project you agree to abide by its terms.

+
+
+ +
+ + + +
+ + + +
+ + + + + + + + diff --git a/docs/LICENSE-text.html b/docs/LICENSE-text.html index e083d1f9..48fcc6c0 100644 --- a/docs/LICENSE-text.html +++ b/docs/LICENSE-text.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/LICENSE.html b/docs/LICENSE.html index 7c805c8b..51c126c0 100644 --- a/docs/LICENSE.html +++ b/docs/LICENSE.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/articles/index.html b/docs/articles/index.html index 755597ae..6a0de3d2 100644 --- a/docs/articles/index.html +++ b/docs/articles/index.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 @@ -115,6 +115,13 @@

rvar: The Random Variable Datatype

rvar: The Random Variable Datatype
+
+

Pareto-khat diagnostics

+

An overview of diagnostics related to Pareto-smoothed importance sampling

+ +
Pareto-khat diagnostics
+
+
diff --git a/docs/articles/pareto_diagnostics.html b/docs/articles/pareto_diagnostics.html new file mode 100644 index 00000000..2ca44cdb --- /dev/null +++ b/docs/articles/pareto_diagnostics.html @@ -0,0 +1,471 @@ + + + + + + + +Pareto-khat diagnostics • posterior + + + + + + + + + + + + + + + + + + + +
+
+ + + + +
+
+
+

Pareto-khat diagnostics

+

Aki +Vehtari

+ + + Source: vignettes/pareto_diagnostics.Rmd + + +
+ + + +
+

Introduction +

+

The paper

+
    +
  • Aki Vehtari, Daniel Simpson, Andrew Gelman, Yuling Yao, and Jonah +Gabry (2024). Pareto smoothed importance sampling. Journal of +Machine Learning Research, 25(72):1-58.
    • +
+

presents Pareto smoothed importance sampling, but also Pareto-\(\hat{k}\) diagnostic that can be used when +estimating any expectation based on finite sample. This vignette +illustrates the use of these diagnostics. The individual diagnostic +functions are pareto_khat(), pareto_min_ss(), +pareto_convergence_rate() and +pareto_khat_threshold(). The function +pareto_diags() will return all of these.

+

Additionally, the pareto_smooth() function can be used +to transform draws by smoothing the tail(s). ## Example

+ +
## This is posterior version 1.6.0
+
## 
+## Attaching package: 'posterior'
+
## The following objects are masked from 'package:stats':
+## 
+##     mad, sd, var
+
## The following objects are masked from 'package:base':
+## 
+##     %in%, match
+ +
## 
+## Attaching package: 'dplyr'
+
## The following objects are masked from 'package:stats':
+## 
+##     filter, lag
+
## The following objects are masked from 'package:base':
+## 
+##     intersect, setdiff, setequal, union
+
+options(pillar.neg = FALSE, pillar.subtle=FALSE, pillar.sigfig=2)
+
+

Simulated data +

+

Generate xn a simulated MCMC sample with 4 chains each +with 1000 iterations using AR process with marginal normal(0,1)

+
+N <- 1000
+phi <- 0.3
+set.seed(6534)
+dr <- array(data=replicate(4,as.numeric(arima.sim(n = N,
+                                                list(ar = c(phi)),
+                                                sd = sqrt((1-phi^2))))),
+         dim=c(N,4,1)) %>%
+  as_draws_df() %>%
+  set_variables('xn')
+

Transform xn via cdf-inverse-cdf so that we have +variables that have marginally distributions \(t_3\), \(t_{2.5}\), \(t_2\), \(t_{1.5}\), and \(t_1\). These all have thick tails. In +addition \(t_2\), \(t_{1.5}\), and \(t_1\) have infinite variance, and \(t_1\) (aka Cauchy) has infinite mean.

+
+drt <- dr %>%
+  mutate_variables(xt3=qt(pnorm(xn), df=3),
+                   xt2_5=qt(pnorm(xn), df=2.5),
+                   xt2=qt(pnorm(xn), df=2),
+                   xt1_5=qt(pnorm(xn), df=1.5),
+                   xt1=qt(pnorm(xn), df=1))
+
+
+

MCMC convergence diagnostics +

+

We examine the draws with the default +summarise_draws().

+ +
## # A tibble: 6 × 10
+##   variable  mean  median    sd   mad    q5   q95  rhat ess_bulk ess_tail
+##   <chr>    <dbl>   <dbl> <dbl> <dbl> <dbl> <dbl> <dbl>    <dbl>    <dbl>
+## 1 xn       0.010 0.00094  0.99  0.99  -1.6   1.6   1.0    2284.    3189.
+## 2 xt3      0.025 0.0010   1.6   1.1   -2.3   2.3   1.0    2284.    3189.
+## 3 xt2_5    0.031 0.0010   2.0   1.1   -2.5   2.5   1.0    2284.    3189.
+## 4 xt2      0.046 0.0011   2.9   1.2   -2.8   2.9   1.0    2284.    3189.
+## 5 xt1_5    0.092 0.0011   7.6   1.3   -3.5   3.6   1.0    2284.    3189.
+## 6 xt1      0.33  0.0012  93.    1.5   -5.8   6.1   1.0    2284.    3189.
+

All the usual convergence diagnostics \(\widehat{R}\), Bulk-ESS, and Tail-ESS look +good, which is fine as they have been designed to work also with +infinite variance (Vehtari et al., 2020).

+

If these variables would present variables of interest for which we +would like to estimate means, we would be also interested in Monte Carlo +standard error (MCSE, see case study How +many iterations to run and how many digits to report).

+
+drt %>%
+  summarise_draws(mean, sd, mcse_mean, ess_bulk, ess_basic)
+
## # A tibble: 6 × 6
+##   variable  mean    sd mcse_mean ess_bulk ess_basic
+##   <chr>    <dbl> <dbl>     <dbl>    <dbl>     <dbl>
+## 1 xn       0.010  0.99     0.021    2284.     2280.
+## 2 xt3      0.025  1.6      0.033    2284.     2452.
+## 3 xt2_5    0.031  2.0      0.039    2284.     2584.
+## 4 xt2      0.046  2.9      0.054    2284.     2903.
+## 5 xt1_5    0.092  7.6      0.13     2284.     3553.
+## 6 xt1      0.33  93.       1.5      2284.     3976.
+

Here MCSE for mean is based on standard deviation and Basic-ESS, but +these assume finite variance. We did sample also from distributions with +infinite variance, but given a finite sample size, the empirical +variance estimates are always finite, and thus we get overoptimistic +MCSE.

+
+
+
+

Pareto-\(\hat{k}\) +

+

To diagnose whether our variables of interest may have infinite +variance and even infinite mean, we can use Pareto-\(\hat{k}\) diagnostic.

+
+drt %>%
+  summarise_draws(mean, sd, mcse_mean, ess_basic, pareto_khat)
+
## # A tibble: 6 × 6
+##   variable  mean    sd mcse_mean ess_basic pareto_khat
+##   <chr>    <dbl> <dbl>     <dbl>     <dbl>       <dbl>
+## 1 xn       0.010  0.99     0.021     2280.      -0.072
+## 2 xt3      0.025  1.6      0.033     2452.       0.33 
+## 3 xt2_5    0.031  2.0      0.039     2584.       0.41 
+## 4 xt2      0.046  2.9      0.054     2903.       0.52 
+## 5 xt1_5    0.092  7.6      0.13      3553.       0.69 
+## 6 xt1      0.33  93.       1.5       3976.       1.0
+

\(\hat{k} \leq 0\) indicates that +all moments exist, and the inverse of positive \(\hat{k}\) tells estimate for the number of +finite (fractional) moments. Thus, \(\hat{k}\geq 1/2\) indicates infinite +variance, and \(\hat{k}\geq 1\) +indicates infinite mean. Sometimes very thick distribution tails may +affect also sampling, but assuming sampling did go well, and we would be +interested only in quantiles, infinite variance and mean are not a +problem. But if we are interested in mean, then we need to care about +the number of (fractional) moments. Here we see \(\hat{k} \geq 1/2\) for \(t_2\), \(t_{1.5}\), and \(t_{1}\), and we should not trust their +mcse_mean values. Without trustworthy MCSE estimate we +don’t have good estimate of how accurate the mean estimate is. +Furthermore, as \(\hat{k} \geq 1\) for +\(t_{1}\), the mean is not finite and +the mean estimate is not valid.

+
+
+

Pareto smoothing +

+

If we really do need those mean estimates, we can improve +trustworthiness by Pareto smoothing, which replaces extreme tail draws +with expected ordered statistics of Pareto distribution fitted to the +tails of the distribution. Pareto smoothed mean estimate (computed using +Pareto smoothed draws) has finite variance with a cost of some bias +which we know when it is negligible. As a thumb rule when \(\hat{k}<0.7\), the bias is +negligible.

+

We do Pareto smoothing for all the variables.

+
+drts <- drt %>% 
+  mutate_variables(xt3_s=pareto_smooth(xt3),
+                   xt2_5_s=pareto_smooth(xt2_5),
+                   xt2_s=pareto_smooth(xt2),
+                   xt1_5_s=pareto_smooth(xt1_5),
+                   xt1_s=pareto_smooth(xt1)) %>%
+  subset_draws(variable="_s", regex=TRUE)
+
## Pareto k-hat = 0.32.
+
## Pareto k-hat = 0.4.
+
## Pareto k-hat = 0.51.
+
## Pareto k-hat = 0.68.
+
## Pareto k-hat = 1.02. Mean does not exist, making empirical mean estimate of the draws not applicable.
+

Now the mcse_mean values are more trustworthy when \(\hat{k} < 0.7\). When \(\hat{k}>0.7\) both bias and variance +grow so fast that Pareto smoothing rarely helps (see more details in the +paper).

+
+drts %>%
+  summarise_draws(mean, mcse_mean, ess_basic, pareto_khat)
+
## # A tibble: 5 × 5
+##   variable  mean mcse_mean ess_basic pareto_khat
+##   <chr>    <dbl>     <dbl>     <dbl>       <dbl>
+## 1 xt3_s    0.026     0.033     2438.        0.33
+## 2 xt2_5_s  0.033     0.038     2536.        0.40
+## 3 xt2_s    0.052     0.051     2763.        0.50
+## 4 xt1_5_s  0.12      0.10      3293.        0.67
+## 5 xt1_s    0.97      0.80      3903.        0.98
+
+
+

Minimum sample size required +

+

The bias and variance depend on the sample size, and we can use +additional diagnostic min_ss which tells the minimum sample +size needed so that mcse_mean can be trusted.

+
+drt %>%
+  summarise_draws(mean, mcse_mean, ess_basic,
+                  pareto_khat, min_ss=pareto_min_ss)
+
## # A tibble: 6 × 6
+##   variable  mean mcse_mean ess_basic pareto_khat min_ss
+##   <chr>    <dbl>     <dbl>     <dbl>       <dbl>  <dbl>
+## 1 xn       0.010     0.021     2280.      -0.072    10 
+## 2 xt3      0.025     0.033     2452.       0.33     31.
+## 3 xt2_5    0.031     0.039     2584.       0.41     48.
+## 4 xt2      0.046     0.054     2903.       0.52    116.
+## 5 xt1_5    0.092     0.13      3553.       0.69   1735.
+## 6 xt1      0.33      1.5       3976.       1.0     Inf
+

Here required min_ss is smaller than +ess_basic for all except \(t_1\), for which there is no hope.

+
+
+

Convergence rate +

+

Given finite variance, the central limit theorem states that to halve +MCSE we need four times bigger sample size. With Pareto smoothing, we +can go further, but the convergence rate decreases when \(\hat{k}\) increases.

+
+drt %>%
+  summarise_draws(mean, mcse_mean, ess_basic,
+                  pareto_khat, min_ss=pareto_min_ss,
+                  conv_rate=pareto_convergence_rate)
+
## # A tibble: 6 × 7
+##   variable  mean mcse_mean ess_basic pareto_khat min_ss conv_rate
+##   <chr>    <dbl>     <dbl>     <dbl>       <dbl>  <dbl>     <dbl>
+## 1 xn       0.010     0.021     2280.      -0.072    10       1   
+## 2 xt3      0.025     0.033     2452.       0.33     31.      0.98
+## 3 xt2_5    0.031     0.039     2584.       0.41     48.      0.95
+## 4 xt2      0.046     0.054     2903.       0.52    116.      0.86
+## 5 xt1_5    0.092     0.13      3553.       0.69   1735.      0.60
+## 6 xt1      0.33      1.5       3976.       1.0     Inf       0
+

We see that with \(t_2\), \(t_{1.5}\), and \(t_1\) we need \(4^{1/0.86}\approx 5\), \(4^{1/0.60}\approx 10\), and \(4^{1/0}\approx \infty\) times bigger sample +sizes to halve MCSE for mean.

+
+
+

Pareto-\(\hat{k}\)-threshold +

+

The final Pareto diagnostic, \(\hat{k}\)-threshold, is useful for smaller +sample sizes. Here we select only 100 iterations per chain to get total +of 400 draws.

+
+drt %>%
+  subset_draws(iteration=1:100) %>%
+  summarise_draws(mean, mcse_mean, ess_basic,
+                  pareto_khat, min_ss=pareto_min_ss,
+                  khat_thres=pareto_khat_threshold,
+                  conv_rate=pareto_convergence_rate)
+
## # A tibble: 6 × 8
+##   variable   mean mcse_mean ess_basic pareto_khat min_ss khat_thres conv_rate
+##   <chr>     <dbl>     <dbl>     <dbl>       <dbl>  <dbl>      <dbl>     <dbl>
+## 1 xn        0.038     0.066      244.      -0.012 1  e 1       0.62      1   
+## 2 xt3       0.054     0.11       237.       0.32  3.0e 1       0.62      0.96
+## 3 xt2_5     0.057     0.13       237.       0.38  4.2e 1       0.62      0.93
+## 4 xt2       0.063     0.17       243.       0.48  8.3e 1       0.62      0.86
+## 5 xt1_5     0.061     0.31       271.       0.64  5.6e 2       0.62      0.66
+## 6 xt1      -0.26      1.6        344.       0.95  2.2e18       0.62      0.11
+

With only 400 draws, we can trust the Pareto smoothed result only +when \(\hat{k}<0.62\). For \(t_{1.5}\) \(\hat{k}\approx 0.64\), and +min_ss reveals we would probably need more than 560 draws +to be on the safe side.

+
+
+

Pareto diagnostics +

+

We can get all these diagnostics with pareto_diags(), +and it’s easy to use it also for derived quantities.

+
+drt %>%
+  mutate_variables(xt2_5_sq=xt2_5^2) %>%
+  subset_draws(variable="xt2_5_sq") %>%
+  summarise_draws(mean, mcse_mean,
+                  pareto_diags)
+
## # A tibble: 1 × 7
+##   variable  mean mcse_mean  khat min_ss khat_threshold convergence_rate
+##   <chr>    <dbl>     <dbl> <dbl>  <dbl>          <dbl>            <dbl>
+## 1 xt2_5_sq   3.9      0.56  0.67  1124.           0.72             0.63
+
+
+

Discussion +

+

All these diagnostics are presented in Section 3 and summarized in +Table 1 in PSIS paper (Vehtari et al., 2024).

+

If you don’t need to estimate means of thick tailed distributions, +and there are no sampling issues due to thick tails, then you don’t need +to check existence of finite variance, and thus there is no need to +check Pareto-\(\hat{k}\) for all the +parameters and derived quantities.

+

It is possible that the distribution has finite variance, but +pre-asymptotically given a finite sample size the behavior can be +similar to infinite variance. Thus the diagnostic is useful even in +cases where theory guarantees finite variance.

+
+
+

Reference +

+

Vehtari, A., Simpson, D., Gelman, A., Yao, Y., & Gabry, J. +(2024). Pareto smoothed importance sampling. Journal of Machine +Learning Research, 25(72):1-58.

+

Vehtari A., Gelman A., Simpson D., Carpenter B., & Bürkner P. C. +(2020). Rank-normalization, folding, and localization: An improved Rhat +for assessing convergence of MCMC. Bayesian Analysis, +16(2):667-718.

+
+
+ + + +
+ + + + +
+ + + + + + + + diff --git a/docs/articles/posterior.html b/docs/articles/posterior.html index 98f7283a..d1c0163c 100644 --- a/docs/articles/posterior.html +++ b/docs/articles/posterior.html @@ -40,7 +40,7 @@ posterior - 1.5.0 + 1.6.0 @@ -175,7 +175,7 @@

Example 
 library("posterior")
-
## This is posterior version 1.5.0
+
## This is posterior version 1.6.0
## 
 ## Attaching package: 'posterior'
## The following objects are masked from 'package:stats':
@@ -339,17 +339,17 @@ 
Example: create draws_matrix
 print(x)
## # A draws_matrix: 10 iterations, 1 chains, and 5 variables
 ##     variable
-## draw     V1    V2    V3    V4     V5
-##   1   0.123 -0.27 -0.59  0.60 -1.789
-##   2   0.353  0.24 -0.12  0.92  0.013
-##   3  -0.316 -0.60 -0.21  0.81 -1.121
-##   4   0.755 -1.38 -0.63 -0.17 -1.363
-##   5   0.042  0.88  0.66  0.28 -0.469
-##   6  -0.210  0.31  0.93 -0.80 -1.809
-##   7   0.135  0.63  0.81 -0.55 -2.086
-##   8  -0.615  0.18 -0.10 -0.34  0.790
-##   9  -0.372  0.13 -2.56 -1.22  1.520
-##   10 -0.354  0.33  0.60  0.79  0.153
+## draw V1 V2 V3 V4 V5 +## 1 -1.14 -1.386 0.54 -0.83 0.700 +## 2 -1.52 2.124 -0.35 0.64 1.078 +## 3 -2.01 -1.062 0.40 0.94 -0.071 +## 4 0.31 -0.032 1.69 0.55 -0.071 +## 5 -0.63 -1.580 0.83 0.69 -0.870 +## 6 0.12 0.687 1.76 -0.25 -0.448 +## 7 -0.25 0.278 0.79 0.68 2.251 +## 8 0.98 0.932 -1.02 0.45 2.170 +## 9 -0.30 -0.384 -0.12 1.34 0.434 +## 10 -0.38 -0.872 -2.81 -0.36 -0.379

Because the matrix was converted to a draws_matrix, all of the methods for working with draws objects described in subsequent sections of this vignette will now be available.

@@ -369,17 +369,17 @@

Example: create draws print(x) 
## # A draws_matrix: 50 iterations, 1 chains, and 2 variables
 ##     variable
-## draw   alpha  beta
-##   1  -0.7025 -0.72
-##   2   0.0350  0.44
-##   3  -0.5237 -2.36
-##   4   0.0415 -0.23
-##   5  -0.0051  1.01
-##   6  -0.2882 -1.28
-##   7  -1.5631 -0.11
-##   8  -0.4261  0.37
-##   9  -1.5636  1.00
-##   10 -0.2385 -1.28
+## draw  alpha   beta
+##   1  -0.044 -0.885
+##   2  -1.048  1.247
+##   3   0.983  0.725
+##   4   1.390  1.201
+##   5  -1.002 -0.693
+##   6   0.247 -1.470
+##   7   1.265 -0.074
+##   8   0.113 -0.132
+##   9  -0.094  0.310
+##   10 -0.794 -0.014
 ## # ... with 40 more draws

Analogous functions exist for the other draws formats and are used similarly.

@@ -491,7 +491,7 @@

Renaming
 # mu is a scalar, theta is a vector
 x <- rename_variables(eight_schools_df, mean = mu, alpha = theta)
-variables(x)
+variables(x) 
##  [1] "mean"     "tau"      "alpha[1]" "alpha[2]" "alpha[3]" "alpha[4]"
 ##  [7] "alpha[5]" "alpha[6]" "alpha[7]" "alpha[8]"

In the call to rename_variables() above, mu @@ -501,7 +501,7 @@

Renamingalpha:

 x <- rename_variables(x, a1 = `alpha[1]`)
-variables(x)
+variables(x) 
##  [1] "mean"     "tau"      "a1"       "alpha[2]" "alpha[3]" "alpha[4]"
 ##  [7] "alpha[5]" "alpha[6]" "alpha[7]" "alpha[8]"
@@ -524,12 +524,12 @@

Bindingprint(x4) 
## # A draws_matrix: 5 iterations, 1 chains, and 3 variables
 ##     variable
-## draw alpha  beta theta
-##    1 -0.83 -2.78 0.073
-##    2 -0.37  3.17 0.053
-##    3  0.21 -0.48 0.110
-##    4  0.31 -0.65 0.534
-##    5 -0.24 -1.51 0.694
+## draw alpha beta theta +## 1 0.793 -0.073 0.22 +## 2 0.483 0.267 0.19 +## 3 0.331 0.238 6.60 +## 4 -0.837 1.301 0.47 +## 5 0.066 0.722 1.33

Because x1 and x2 have the same variables, we can bind them along the 'draw' dimension to create a single draws_matrix with more draws:

@@ -538,17 +538,17 @@

Bindingprint(x5) 
## # A draws_matrix: 10 iterations, 1 chains, and 2 variables
 ##     variable
-## draw alpha  beta
-##   1  -0.83 -2.78
-##   2  -0.37  3.17
-##   3   0.21 -0.48
-##   4   0.31 -0.65
-##   5  -0.24 -1.51
-##   6  -0.92  0.29
-##   7   1.09  0.51
-##   8  -0.15 -1.99
-##   9  -2.01 -0.63
-##   10  1.80  0.27
+## draw alpha beta +## 1 0.793 -0.073 +## 2 0.483 0.267 +## 3 0.331 0.238 +## 4 -0.837 1.301 +## 5 0.066 0.722 +## 6 1.374 1.284 +## 7 -0.061 -0.212 +## 8 -0.386 -0.052 +## 9 -1.356 0.061 +## 10 0.627 -0.815

As with all posterior methods, bind_draws() can be used with all draws formats and depending on the format different dimensions are available to bind on. For example, we can bind @@ -661,16 +661,16 @@

Using custom functions## # A tibble: 10 × 2 ## variable weighted_mean ## <chr> <dbl> -## 1 mu 4.00 -## 2 tau 4.09 -## 3 theta[1] 6.56 -## 4 theta[2] 4.95 -## 5 theta[3] 2.98 -## 6 theta[4] 4.72 -## 7 theta[5] 3.15 -## 8 theta[6] 3.59 -## 9 theta[7] 6.06 -## 10 theta[8] 4.45 +## 1 mu 4.13 +## 2 tau 4.07 +## 3 theta[1] 6.93 +## 4 theta[2] 5.54 +## 5 theta[3] 3.35 +## 6 theta[4] 5.03 +## 7 theta[5] 3.23 +## 8 theta[6] 3.52 +## 9 theta[7] 6.59 +## 10 theta[8] 4.58

Specifying functions using lambda-like syntax @@ -804,12 +804,13 @@

Other methods for working

References

-

Gelman A., Carlin J. B., Stern H. S., David B. Dunson D. B., Aki -Vehtari A., & Rubin D. B. (2013). Bayesian Data Analysis, Third +

Gelman A., Carlin J. B., Stern H. S., David B. Dunson D. B., Vehtari, +A., & Rubin D. B. (2013). Bayesian Data Analysis, Third Edition. Chapman and Hall/CRC.

Vehtari A., Gelman A., Simpson D., Carpenter B., & Bürkner P. C. (2020). Rank-normalization, folding, and localization: An improved Rhat -for assessing convergence of MCMC. Bayesian Analysis.

+for assessing convergence of MCMC. Bayesian Analysis, +16(2):667-718.

diff --git a/docs/articles/rvar.html b/docs/articles/rvar.html index 50b7d7a0..483772a1 100644 --- a/docs/articles/rvar.html +++ b/docs/articles/rvar.html @@ -40,7 +40,7 @@ posterior - 1.5.0 + 1.6.0 @@ -134,7 +134,7 @@

rvar: The Random Variable Datatype

Matthew Kay

-

2023-11-10

+

2024-07-05

Source: vignettes/rvar.Rmd @@ -156,7 +156,7 @@

Introductiondistributional package, to be able to be used inside data.frame()s and -tibble()s, and to be used with distribution visualizations +tibble()s, and to be used with distribution visualizations in the ggdist package.

@@ -342,12 +342,12 @@

The draws_rvars datatypemu and Sigma:

 +variables(post) 
## [1] "mu"    "Sigma"

But converted to a draws_list(), it contains one variable for each combination of the dimensions of its variables:

+variables(as_draws_list(post)) 
##  [1] "mu[1]"      "mu[2]"      "mu[3]"      "Sigma[1,1]" "Sigma[2,1]"
 ##  [6] "Sigma[3,1]" "Sigma[1,2]" "Sigma[2,2]" "Sigma[3,2]" "Sigma[1,3]"
 ## [11] "Sigma[2,3]" "Sigma[3,3]"
@@ -370,9 +370,12 @@

Math with rvars## rvar<100,4>[3] mean ± sd: ## [1] 1.1 ± 0.11 1.1 ± 0.20 1.2 ± 0.31

Matrix multiplication is also implemented (using a tensor product -under the hood). Because the normal matrix multiplication operator in R -(%*%) cannot be properly implemented for S3 datatypes, -rvar uses %**% instead. A trivial example:

+under the hood). In R < 4.3, the normal matrix multiplication +operator (%*%) cannot be properly implemented for S3 +datatypes, so rvar uses %**% instead. In R ≥ +4.3, which does support matrix multiplication for S3 datatypes, you can +use %*% to matrix-multiply rvars.

+

A trivial example:

 
## rvar<100,4>[3,3] mean ± sd:
@@ -420,7 +423,8 @@ 
Math with rvars
 
 Matrix multiplication
-%**%
+
+%**%, %*% (R ≥ 4.3 only)
 
 
 Basic functions
@@ -935,9 +939,10 @@ 
Subsetting rvars by
 ## [1] 4 ± 2

The resulting mixture looks like this:

-library(ggplot2)
-
-ggplot() + ggdist::stat_slab(aes(xdist = mixture))
+library(ggplot2) +
## Warning: package 'ggplot2' was built under R version 4.2.3
+
+ggplot() + ggdist::stat_slab(aes(xdist = mixture))

See vignette("slabinterval", package = "ggdist") for more examples of visualizing distribution-type objects, including @@ -953,7 +958,7 @@

Conditionals using rvar_ifelse()yes where test == TRUE and draws from no where test == FALSE.

Thus, we can create the mixture as follows:

-
+
 x = rvar_ifelse(i == 1, component[[1]], component[[2]])
 x

 
## rvar<4000>[1] mean ± sd:
@@ -972,7 +977,7 @@ 
Selecting diffe
 rvar whose values are either 1 or
 2 within each draw, you can use it as an index directly on
 component to create the mixture:

-
+
 x = component[[i]]
 x

 
## rvar<4000>[1] mean ± sd:
@@ -993,7 +998,7 @@ 
Applying functions over rvar
 its first dimension, which may be necessary for compatibility with some
 functions (like purrr:map()).

 
For example, given this multidimensional rvar…

-
+
 set.seed(3456)
 x <- rvar_rng(rnorm, 24, mean = 1:24)
 dim(x) <- c(2,3,4)
@@ -1024,7 +1029,7 @@ 
Applying functions over rvar
 ## [2,] 20 ± 1.00  22 ± 1.00  24 ± 1.00

 
… you can apply functions along the margins using
 apply() (here, a silly example):

-
+
 apply(x, c(1,2), length)

 
##      [,1] [,2] [,3]
 ## [1,]    4    4    4
@@ -1040,12 +1045,12 @@ 
Applying functions over rvar
 
For example, you can use rvar_apply() with
 rvar_mean() to compute the distributions of means along one
 margin of an array:

-
+
 rvar_apply(x, 1, rvar_mean)

 
## rvar<4000>[2] mean ± sd:
 ## [1] 12 ± 0.29  13 ± 0.29

 
Or along multiple dimensions:

-
+
 rvar_apply(x, c(2,3), rvar_mean)

 
## rvar<4000>[3,4] mean ± sd:
 ##      [,1]         [,2]         [,3]         [,4]        
@@ -1068,7 +1073,7 @@ 
Looping over draws and 
 base-R plots of individual draws (for ggplot2-based
 plotting of rvars, see the next section and the ggdist package). For
 example, it can be used to construct a parallel coordinates plot:

-
+
 eight_schools <- as_draws_rvars(example_draws())
 
 plot(1, type = "n",
@@ -1097,8 +1102,8 @@ 
Looping over draws and 
 
Using rvars in data frames and in ggplot2
 

 
rvars can be used as columns in
-data.frame() or tibble() objects:

-
+data.frame() or tibble() objects:

+
 df <- data.frame(group = c("a","b","c","d"), mu)
 df

 
##   group       mu
@@ -1113,11 +1118,12 @@ 
Using rvars in d
 stat_... family of geometries in the ggdist package, such as
 stat_halfeye(), stat_lineribbon(), and
 stat_dotsinterval(). For example:

-
+
+
## Warning: package 'ggdist' was built under R version 4.2.3

+
+ggplot(df) +
   stat_halfeye(aes(y = group, xdist = mu))

 

 
See vignette("slabinterval", package = "ggdist") or
diff --git a/docs/articles/rvar_files/figure-html/data_frame_plot-1.png b/docs/articles/rvar_files/figure-html/data_frame_plot-1.png
index 4cf02c0b..30e22dfe 100644
Binary files a/docs/articles/rvar_files/figure-html/data_frame_plot-1.png and b/docs/articles/rvar_files/figure-html/data_frame_plot-1.png differ
diff --git a/docs/articles/rvar_files/figure-html/mixture-1.png b/docs/articles/rvar_files/figure-html/mixture-1.png
index a63f63ad..add78e0e 100644
Binary files a/docs/articles/rvar_files/figure-html/mixture-1.png and b/docs/articles/rvar_files/figure-html/mixture-1.png differ
diff --git a/docs/authors.html b/docs/authors.html
index f3e2af9b..acb26f56 100644
--- a/docs/authors.html
+++ b/docs/authors.html
@@ -17,7 +17,7 @@
       
       
         posterior
-        1.5.0
+        1.6.0
       
     

 
@@ -139,6 +139,10 @@ 
Authors

           
Jacob Socolar. Contributor. 
           

         
+        
  • 
+          
    Noa Kallioinen. Contributor. 
+          
    
+        
    • 
       
    
     
    
     
    
@@ -148,15 +152,15 @@ 
    Citation
    
     
    
 
 
-    
    Bürkner P, Gabry J, Kay M, Vehtari A (2023).
+    
    Bürkner P, Gabry J, Kay M, Vehtari A (2024).
 “posterior: Tools for Working with Posterior Distributions.”
-R package version 1.5.0, https://mc-stan.org/posterior/. 
+R package version 1.6.0, https://mc-stan.org/posterior/. 
 
    
     
    @Misc{,
   title = {posterior: Tools for Working with Posterior Distributions},
   author = {Paul-Christian Bürkner and Jonah Gabry and Matthew Kay and Aki Vehtari},
-  year = {2023},
-  note = {R package version 1.5.0},
+  year = {2024},
+  note = {R package version 1.6.0},
   url = {https://mc-stan.org/posterior/},
 }
    
     
    Vehtari A, Gelman A, Simpson D, Carpenter B, Bürkner P (2021).
diff --git a/docs/index.html b/docs/index.html
index c457eb22..714c5c83 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -50,7 +50,7 @@
       
       
         posterior
-        1.5.0
+        1.6.0
       
     
    
 
@@ -328,7 +328,7 @@ 
    Mutating and renaming draws
     x <- rename_variables(eight_schools_df, mean = mu, alpha = theta)
-variables(x)
+variables(x)
 #>  [1] "mean"     "tau"      "alpha[1]" "alpha[2]" "alpha[3]" "alpha[4]" "alpha[5]"
 #>  [8] "alpha[6]" "alpha[7]" "alpha[8]"
    
 
    As with all posterior methods, mutate_variables and rename_variables can be used with all draws formats.
    
@@ -409,7 +409,7 @@ 
    Converting from regu
 
     x <- array(data=rnorm(200), dim=c(10, 2, 5))
 x <- as_draws_matrix(x)
-variables(x) <-  paste0("V", 1:5)
+variables(x) <-  paste0("V", 1:5)
 print(x)
 #> # A draws_matrix: 10 iterations, 2 chains, and 5 variables
 #>     variable
@@ -506,6 +506,12 @@ 
    License
    
 
 
    
 
+
    
+
    Community
    
+
+
    
 
 
    
 
    Citation
    
diff --git a/docs/news/index.html b/docs/news/index.html
index 9d738f3f..d94aa8a1 100644
--- a/docs/news/index.html
+++ b/docs/news/index.html
@@ -17,7 +17,7 @@
       
       
         posterior
-        1.5.0
+        1.6.0
       
     
    
 
@@ -102,6 +102,23 @@ 
    Changelog 
    
       Source: NEWS.md
     
    
 
+    
    
+
    posterior 1.6.02024-07-03
    
+
    
+
    Enhancements
    
+
    • Add exclude option to subset_draws(), which can be used to exclude the matched selection.
      • 
+
    • Add are_log_weights option to pareto_smooth(), which is necessary for correct Pareto smoothing computation if the input vector consists of log weights.
      • 
+
    • Add pareto_smooth option to weight_draws(), to Pareto smooth weights before adding to a draws object.
      • 
+
    • Add individual Pareto diagnostic functions (pareto_khat(), pareto_khat_threshold(), pareto_min_ss(), pareto_convergence_rate())
      • 
+
    • 
+thin_draws() now automatically thins draws based on ESS by default, and non-integer thinning is possible.
      • 
+
    • Matrix multiplication of rvars can now be done with the base matrix multiplication operator (%*%) instead of %**% in R >= 4.3.
      • 
+
    • 
+variables(), variables<-(), set_variables(), and nvariables() now support a with_indices argument, which determines whether variable names are retrieved/set with ("x[1]", "x[2]" …) or without ("x") indices (#208).
      • 
+
    • Add extract_variable_array() function to extract variables with indices into arrays of iterations x chains x any remaining dimensions (#340).
      • 
+
    • For types that support factor variables (draws_df, draws_list, and draws_rvars), extract_variable() and extract_variable_matrix() can now return factors.
      • 
+
    
+
    
     
    
 
    posterior 1.5.02023-10-31
    
 
    
diff --git a/docs/pkgdown.yml b/docs/pkgdown.yml
index 8ad1e3a7..ef76ad77 100644
--- a/docs/pkgdown.yml
+++ b/docs/pkgdown.yml
@@ -1,10 +1,11 @@
-pandoc: 3.1.1
+pandoc: 3.1.11
 pkgdown: 2.0.7
 pkgdown_sha: ~
 articles:
+  pareto_diagnostics: pareto_diagnostics.html
   posterior: posterior.html
   rvar: rvar.html
-last_built: 2023-11-10T09:53Z
+last_built: 2024-07-05T08:44Z
 urls:
   reference: https://mc-stan.org/posterior/reference
   article: https://mc-stan.org/posterior/articles
diff --git a/docs/pull_request_template.html b/docs/pull_request_template.html
index 4bc6c54d..d7bc28be 100644
--- a/docs/pull_request_template.html
+++ b/docs/pull_request_template.html
@@ -17,7 +17,7 @@
       
       
         posterior
-        1.5.0
+        1.6.0
       
     
    
 
diff --git a/docs/reference/as_rvar.html b/docs/reference/as_rvar.html
index e0cce8e9..b5fe7754 100644
--- a/docs/reference/as_rvar.html
+++ b/docs/reference/as_rvar.html
@@ -17,7 +17,7 @@
       
       
         posterior
-        1.5.0
+        1.6.0
       
     
    
 
diff --git a/docs/reference/as_rvar_factor.html b/docs/reference/as_rvar_factor.html
index 31187484..417130e0 100644
--- a/docs/reference/as_rvar_factor.html
+++ b/docs/reference/as_rvar_factor.html
@@ -17,7 +17,7 @@
       
       
         posterior
-        1.5.0
+        1.6.0
       
     
    
 
diff --git a/docs/reference/autocorrelation.html b/docs/reference/autocorrelation.html
index 46947ec1..dac6b794 100644
--- a/docs/reference/autocorrelation.html
+++ b/docs/reference/autocorrelation.html
@@ -19,7 +19,7 @@
       
       
         posterior
-        1.5.0
+        1.6.0
       
     
    
 
diff --git a/docs/reference/autocovariance.html b/docs/reference/autocovariance.html
index 3faaf667..76e996eb 100644
--- a/docs/reference/autocovariance.html
+++ b/docs/reference/autocovariance.html
@@ -19,7 +19,7 @@
       
       
         posterior
-        1.5.0
+        1.6.0
       
     
    
 
diff --git a/docs/reference/bind_draws.html b/docs/reference/bind_draws.html
index 0d7a9cc1..937411cc 100644
--- a/docs/reference/bind_draws.html
+++ b/docs/reference/bind_draws.html
@@ -17,7 +17,7 @@
       
       
         posterior
-        1.5.0
+        1.6.0
       
     
    
 
@@ -165,7 +165,7 @@ 
    Examples
    
 
 x4 <- draws_matrix(theta = rexp(5))
 x5 <- bind_draws(x1, x4, along = "variable")
-variables(x5)
+variables(x5)
 #> [1] "alpha" "beta"  "theta"
 
 
    
diff --git a/docs/reference/chol.rvar.html b/docs/reference/chol.rvar.html
index 0ec7c5fd..7c17b693 100644
--- a/docs/reference/chol.rvar.html
+++ b/docs/reference/chol.rvar.html
@@ -17,7 +17,7 @@
       
       
         posterior
-        1.5.0
+        1.6.0
       
     
    
 
diff --git a/docs/reference/diag-rvar-method.html b/docs/reference/diag-rvar-method.html
index a7d4690a..467cd5b3 100644
--- a/docs/reference/diag-rvar-method.html
+++ b/docs/reference/diag-rvar-method.html
@@ -18,7 +18,7 @@
       
       
         posterior
-        1.5.0
+        1.6.0
    diff --git a/docs/reference/diagnostics.html b/docs/reference/diagnostics.html index 186cec0c..6c5404e6 100644 --- a/docs/reference/diagnostics.html +++ b/docs/reference/diagnostics.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 @@ -117,7 +117,7 @@

    Value

    Details

    -
    FunctionDescription
    ess_basic()Basic version of effective sample size
    ess_bulk()Bulk effective sample size
    ess_tail()Tail effective sample size
    ess_quantile()Effective sample sizes for quantiles
    ess_sd()Effective sample sizes for standard deviations
    mcse_mean()Monte Carlo standard error for the mean
    mcse_quantile()Monte Carlo standard error for quantiles
    mcse_sd()Monte Carlo standard error for standard deviations
    rhat_basic()Basic version of Rhat
    rhat()Improved, rank-based version of Rhat
    rhat_nested()Rhat for use with many short chains
    rstar()R* diagnostic
    +
    FunctionDescription
    ess_basic()Basic version of effective sample size
    ess_bulk()Bulk effective sample size
    ess_tail()Tail effective sample size
    ess_quantile()Effective sample sizes for quantiles
    ess_sd()Effective sample sizes for standard deviations
    mcse_mean()Monte Carlo standard error for the mean
    mcse_quantile()Monte Carlo standard error for quantiles
    mcse_sd()Monte Carlo standard error for standard deviations
    pareto_khat()Pareto khat diagnostic for tail(s)
    pareto_diags()Additional diagnostics related to Pareto khat
    rhat_basic()Basic version of Rhat
    rhat()Improved, rank-based version of Rhat
    rhat_nested()Rhat for use with many short chains
    rstar()R* diagnostic
    diff --git a/docs/reference/draws-index.html b/docs/reference/draws-index.html index 004fadd1..3658f418 100644 --- a/docs/reference/draws-index.html +++ b/docs/reference/draws-index.html @@ -1,5 +1,5 @@ -Index draws objects — draws-index • posteriorIndex draws objects — draws-index • posterior @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 @@ -104,22 +104,16 @@

    Index draws objects

    -

    Index variables, iterations, chains, and draws.

    +

    Index iterations, chains, and draws of draws objects.

    - 
    variables(x, ...)
-
-variables(x) <- value
-
-iteration_ids(x)
+    
    iteration_ids(x)
 
 chain_ids(x)
 
 draw_ids(x)
 
-nvariables(x, ...)
-
 niterations(x)
 
 nchains(x)
@@ -133,23 +127,11 @@ 
    Arguments
    
 
    (draws) A draws object or another R object for which the method
 is defined.
    
 
-
-
    ...
    
-
    Arguments passed to individual methods (if applicable).
    
-
-
-
    value
    
-
    (character vector) For variables(x) <- value, the new variable
-names to use.
    
-
 
    
     
    
     
    Value
    
     
 
-
    For variables(), a character vector.
    
-
-
 
    For iteration_ids(), chain_ids(), and draw_ids(), an integer vector.
    
 
 
@@ -157,27 +139,21 @@ 
    Value
    
     
    
     
    
     
    Details
    
-    
    The methods variables(), iteration_ids(), chain_ids(), and draw_ids() return
-vectors of all variables, iterations, chains, and draws, respectively. In
-contrast, the methods nvariables(), niterations(), nchains(), and
+    
    The methods iteration_ids(), chain_ids(), and draw_ids() return
+vectors of all iterations, chains, and draws, respectively. In
+contrast, the methods niterations(), nchains(), and
 ndraws() return the number of variables, iterations, chains, and draws,
 respectively.
    
-
    variables(x) <- value allows you to modify the vector of variable names,
-similar to how names(x) <- value works for vectors and lists. For renaming
-specific variables, set_variables() works equivalently, but is more intuitive when using the pipe operator. rename_variables() may offer a more convenient approach.
    
+    
    
+    
    
+    
    See also
    
+    
    variables, rename_variables
    
     
    
 
     
    
     
    Examples
    
     
    x <- example_draws()
 
-variables(x)
-#>  [1] "mu"       "tau"      "theta[1]" "theta[2]" "theta[3]" "theta[4]"
-#>  [7] "theta[5]" "theta[6]" "theta[7]" "theta[8]"
-nvariables(x)
-#> [1] 10
-variables(x) <- letters[1:nvariables(x)]
-
 iteration_ids(x)
 #>   [1]   1   2   3   4   5   6   7   8   9  10  11  12  13  14  15  16  17  18
 #>  [19]  19  20  21  22  23  24  25  26  27  28  29  30  31  32  33  34  35  36
diff --git a/docs/reference/draws.html b/docs/reference/draws.html
index 74a4b3b7..9bd04ab8 100644
--- a/docs/reference/draws.html
+++ b/docs/reference/draws.html
@@ -18,7 +18,7 @@
       
       
         posterior
-        1.5.0
+        1.6.0
       
     
    
 
diff --git a/docs/reference/draws_array.html b/docs/reference/draws_array.html
index 29dc038a..44e66e6d 100644
--- a/docs/reference/draws_array.html
+++ b/docs/reference/draws_array.html
@@ -21,7 +21,7 @@
       
       
         posterior
-        1.5.0
+        1.6.0
       
     
    
 
@@ -179,11 +179,11 @@ 
    Details
    
     
    
     
    See also
    
     
    Other formats: 
+draws,
 draws_df(),
 draws_list(),
 draws_matrix(),
-draws_rvars(),
-draws
    
+draws_rvars()
    diff --git a/docs/reference/draws_df.html b/docs/reference/draws_df.html index 19f52749..cee18fa3 100644 --- a/docs/reference/draws_df.html +++ b/docs/reference/draws_df.html @@ -21,7 +21,7 @@ posterior - 1.5.0 + 1.6.0
    @@ -189,11 +189,11 @@

    Details

    See also

    Other formats: +draws, draws_array(), draws_list(), draws_matrix(), -draws_rvars(), -draws

    +draws_rvars()

    diff --git a/docs/reference/draws_list.html b/docs/reference/draws_list.html index 3e8c53b4..b94afc4e 100644 --- a/docs/reference/draws_list.html +++ b/docs/reference/draws_list.html @@ -21,7 +21,7 @@ posterior - 1.5.0 + 1.6.0
    @@ -181,11 +181,11 @@

    Details

    See also

    Other formats: +draws, draws_array(), draws_df(), draws_matrix(), -draws_rvars(), -draws

    +draws_rvars()

    diff --git a/docs/reference/draws_matrix.html b/docs/reference/draws_matrix.html index 8b79b02f..8ebdabfe 100644 --- a/docs/reference/draws_matrix.html +++ b/docs/reference/draws_matrix.html @@ -21,7 +21,7 @@ posterior - 1.5.0 + 1.6.0
    @@ -179,11 +179,11 @@

    Details

    See also

    Other formats: +draws, draws_array(), draws_df(), draws_list(), -draws_rvars(), -draws

    +draws_rvars()

    diff --git a/docs/reference/draws_of.html b/docs/reference/draws_of.html index bb599298..81420a41 100644 --- a/docs/reference/draws_of.html +++ b/docs/reference/draws_of.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0
    diff --git a/docs/reference/draws_rvars.html b/docs/reference/draws_rvars.html index bb8ede22..188a1371 100644 --- a/docs/reference/draws_rvars.html +++ b/docs/reference/draws_rvars.html @@ -21,7 +21,7 @@ posterior - 1.5.0 + 1.6.0 @@ -182,11 +182,11 @@

    Details

    See also

    Other formats: +draws, draws_array(), draws_df(), draws_list(), -draws_matrix(), -draws

    +draws_matrix()

    diff --git a/docs/reference/draws_summary.html b/docs/reference/draws_summary.html index e2416de6..9b1ffd29 100644 --- a/docs/reference/draws_summary.html +++ b/docs/reference/draws_summary.html @@ -22,7 +22,7 @@ posterior - 1.5.0 + 1.6.0
    diff --git a/docs/reference/drop-rvar-method.html b/docs/reference/drop-rvar-method.html index 7370fa52..8cc9f12b 100644 --- a/docs/reference/drop-rvar-method.html +++ b/docs/reference/drop-rvar-method.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/entropy.html b/docs/reference/entropy.html index 424579ff..92d2abe9 100644 --- a/docs/reference/entropy.html +++ b/docs/reference/entropy.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/ess_basic.html b/docs/reference/ess_basic.html index 52b65cdf..7b11c10f 100644 --- a/docs/reference/ess_basic.html +++ b/docs/reference/ess_basic.html @@ -22,7 +22,7 @@ posterior - 1.5.0 + 1.6.0 @@ -189,9 +189,11 @@

    See also

    mcse_mean(), mcse_quantile(), mcse_sd(), +pareto_diags(), +pareto_khat(), +rhat(), rhat_basic(), rhat_nested(), -rhat(), rstar()

    diff --git a/docs/reference/ess_bulk.html b/docs/reference/ess_bulk.html index aad47857..b3ef7cd1 100644 --- a/docs/reference/ess_bulk.html +++ b/docs/reference/ess_bulk.html @@ -22,7 +22,7 @@ posterior - 1.5.0 + 1.6.0 @@ -181,9 +181,11 @@

    See also

    mcse_mean(), mcse_quantile(), mcse_sd(), +pareto_diags(), +pareto_khat(), +rhat(), rhat_basic(), rhat_nested(), -rhat(), rstar()

    diff --git a/docs/reference/ess_mean.html b/docs/reference/ess_mean.html index 93a70275..0b5ff9e1 100644 --- a/docs/reference/ess_mean.html +++ b/docs/reference/ess_mean.html @@ -18,7 +18,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/ess_quantile.html b/docs/reference/ess_quantile.html index 98ca6c63..287678ab 100644 --- a/docs/reference/ess_quantile.html +++ b/docs/reference/ess_quantile.html @@ -18,7 +18,7 @@ posterior - 1.5.0 + 1.6.0 @@ -190,9 +190,11 @@

    See also

    mcse_mean(), mcse_quantile(), mcse_sd(), +pareto_diags(), +pareto_khat(), +rhat(), rhat_basic(), rhat_nested(), -rhat(), rstar()

    diff --git a/docs/reference/ess_sd.html b/docs/reference/ess_sd.html index 0ffc275b..4b186826 100644 --- a/docs/reference/ess_sd.html +++ b/docs/reference/ess_sd.html @@ -19,7 +19,7 @@ posterior - 1.5.0 + 1.6.0 @@ -173,9 +173,11 @@

    See also

    mcse_mean(), mcse_quantile(), mcse_sd(), +pareto_diags(), +pareto_khat(), +rhat(), rhat_basic(), rhat_nested(), -rhat(), rstar()

    diff --git a/docs/reference/ess_tail.html b/docs/reference/ess_tail.html index 4ee43339..c48cbfa7 100644 --- a/docs/reference/ess_tail.html +++ b/docs/reference/ess_tail.html @@ -22,7 +22,7 @@ posterior - 1.5.0 + 1.6.0 @@ -181,9 +181,11 @@

    See also

    mcse_mean(), mcse_quantile(), mcse_sd(), +pareto_diags(), +pareto_khat(), +rhat(), rhat_basic(), rhat_nested(), -rhat(), rstar()

    diff --git a/docs/reference/example_draws.html b/docs/reference/example_draws.html index 31881809..086226df 100644 --- a/docs/reference/example_draws.html +++ b/docs/reference/example_draws.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/extract_variable.html b/docs/reference/extract_variable.html index 6b278ec6..9a75d9ae 100644 --- a/docs/reference/extract_variable.html +++ b/docs/reference/extract_variable.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 @@ -116,6 +116,12 @@

    Extract draws of a single variable

    # S3 method for draws extract_variable(x, variable, ...) +# S3 method for draws_df +extract_variable(x, variable, ...) + +# S3 method for draws_list +extract_variable(x, variable, ...) + # S3 method for draws_rvars extract_variable(x, variable, ...)     @@ -128,7 +134,9 @@

    Arguments

    variable
    -

    (string) The name of the variable to extract.

    +

    (string) The name of the variable to extract. Must include +indices for array variables (e.g. "x[1]", "y[1,2]"). To extract all +dimensions from variables with indices, use extract_variable_array().

    ...
    @@ -139,7 +147,13 @@

    Arguments

    Value

    -

    A numeric vector of length equal to the number of draws.

    +

    A vector of length equal to the number of draws.

    + +
    +

    See also

    +

    Other variable extraction methods: +extract_variable_array(), +extract_variable_matrix()

    diff --git a/docs/reference/extract_variable_array.html b/docs/reference/extract_variable_array.html new file mode 100644 index 00000000..a0b3bd7d --- /dev/null +++ b/docs/reference/extract_variable_array.html @@ -0,0 +1,207 @@ + +Extract array of a single (possibly indexed) variable — extract_variable_array • posterior + + +
    +
    + + + +
    +
    +
    +

    Extract array of a single (possibly indexed) variable

    + Source: R/extract_variable_array.R + +
    + +
    +

    Extract an array of draws of a single variable, including any dimensions of +variables with indices.

    +
    + +
    + 
    extract_variable_array(x, variable, ...)
+
+# S3 method for default
+extract_variable_array(x, variable, ...)
+
+# S3 method for draws
+extract_variable_array(x, variable, ...)
    +
    + +
    +

    Arguments

    +
    x
    +

    (draws) A draws object or another R object for which the method +is defined.

    + + +
    variable
    +

    (string) The name of the variable to extract. To extract all +dimensions from variables with indices (e.g. "x[1]"), provide the base +variable name (e.g. "x").

    + + +
    ...
    +

    Arguments passed to individual methods (if applicable).

    + +
    +
    +

    Value

    + + +

    An array with dimension niterations(x) x nchains(x) x any remaining +dimensions determined by the indices of the variable x.

    +
    +
    +

    See also

    +

    Other variable extraction methods: +extract_variable(), +extract_variable_matrix()

    +
    + +
    +

    Examples

    + 
    x <- example_draws(example = "multi_normal")
+
+mu <- extract_variable_array(x, variable = "mu")
+str(mu)
+#>  num [1:100, 1:4, 1:3] 0.18119 -0.03419 -0.05875 -0.1536 0.00989 ...
+#>  - attr(*, "dimnames")=List of 3
+#>   ..$ : NULL
+#>   ..$ : NULL
+#>   ..$ : NULL
+
+mu1 <- extract_variable_array(x, variable = "mu[1]")
+str(mu1)
+#>  num [1:100, 1:4, 1] 0.18119 -0.03419 -0.05875 -0.1536 0.00989 ...
+#>  - attr(*, "dimnames")=List of 3
+#>   ..$ : NULL
+#>   ..$ : NULL
+#>   ..$ : NULL
+
+Sigma <- extract_variable_array(x, variable = "Sigma")
+str(Sigma)
+#>  num [1:100, 1:4, 1:3, 1:3] 1.2 1.14 1.12 1.14 1.19 ...
+#>  - attr(*, "dimnames")=List of 4
+#>   ..$ : NULL
+#>   ..$ : NULL
+#>   ..$ : NULL
+#>   ..$ : NULL
+
+
    +
    +
    + +
    + + +
    +

    Developed by Paul-Christian Bürkner, Jonah Gabry, Matthew Kay, Aki Vehtari.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/extract_variable_matrix.html b/docs/reference/extract_variable_matrix.html index 186d9b8d..2be61fc4 100644 --- a/docs/reference/extract_variable_matrix.html +++ b/docs/reference/extract_variable_matrix.html @@ -18,7 +18,7 @@ posterior - 1.5.0 + 1.6.0
    @@ -118,6 +118,12 @@

    Extract matrix of a single variable

    # S3 method for draws extract_variable_matrix(x, variable, ...) +# S3 method for draws_df +extract_variable_matrix(x, variable, ...) + +# S3 method for draws_list +extract_variable_matrix(x, variable, ...) + # S3 method for draws_rvars extract_variable_matrix(x, variable, ...)     @@ -130,7 +136,9 @@

    Arguments

    variable
    -

    (string) The name of the variable to extract.

    +

    (string) The name of the variable to extract. Must include +indices for array variables (e.g. "x[1]", "y[1,2]"). To extract all +dimensions from variables with indices, use extract_variable_array().

    ...
    @@ -143,6 +151,12 @@

    Value

    A matrix with dimension iterations x chains.

    +
    +

    See also

    +

    Other variable extraction methods: +extract_variable(), +extract_variable_array()

    +

    Examples

    diff --git a/docs/reference/for_each_draw.html b/docs/reference/for_each_draw.html index 9e3acfdc..4d62ba8d 100644 --- a/docs/reference/for_each_draw.html +++ b/docs/reference/for_each_draw.html @@ -18,7 +18,7 @@ posterior - 1.5.0 + 1.6.0
    @@ -124,7 +124,8 @@

    Arguments

    (expression) A bare expression that can contain references to variables in x by name. This expression will be executed once per draw of x, where references to variables in x resolve to the value of that -variable in that draw. The expression supports quasiquotation.

    +variable in that draw. The expression supports +quasiquotation.

    diff --git a/docs/reference/index.html b/docs/reference/index.html index baab84ab..f5dc5818 100644 --- a/docs/reference/index.html +++ b/docs/reference/index.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0
    @@ -166,9 +166,9 @@

    Draws objects and formats variables() `variables<-`() iteration_ids() chain_ids() draw_ids() nvariables() niterations() nchains() ndraws()

    +

    variables() nvariables()

    -

    Index draws objects

    +

    Get variable names from draws objects

    example_draws()

    @@ -189,6 +189,10 @@

    Working with draws objects extract_variable()

    Extract draws of a single variable

    + +

    extract_variable_array()

    + +

    Extract array of a single (possibly indexed) variable

    extract_variable_matrix()

    @@ -202,7 +206,7 @@

    Working with draws objects set_variables()

    +

    `variables<-`() set_variables()

    Set variable names in draws objects

    @@ -217,6 +221,10 @@

    Working with draws objects subset_draws() subset(<draws>)

    Subset draws objects

    + +

    iteration_ids() chain_ids() draw_ids() niterations() nchains() ndraws()

    + +

    Index draws objects

    rename_variables()

    @@ -301,6 +309,34 @@

    Summarizing and diagnosing dra

    mcse_sd()

    Monte Carlo standard error for the standard deviation

    + +

    pareto_diags() pareto_khat_threshold() pareto_min_ss() pareto_convergence_rate()

    + +

    Pareto smoothing diagnostics

    + +

    pareto_khat()

    + +

    Pareto khat diagnostic

    + +

    pareto_smooth()

    + +

    Pareto smoothing

    + +

    ps_convergence_rate()

    + +

    Pareto convergence rate

    + +

    ps_khat_threshold()

    + +

    Pareto k-hat threshold

    + +

    ps_min_ss()

    + +

    Pareto-smoothing minimum sample-size

    + +

    ps_tail_length()

    + +

    Pareto tail length

    quantile2()

    @@ -321,18 +357,6 @@

    Summarizing and diagnosing dra

    modal_category()

    Modal category

    - -

    pareto_diags()

    - -

    Pareto smoothing diagnostics

    - -

    pareto_khat()

    - -

    Pareto khat diagnostic

    - -

    pareto_smooth()

    - -

    Pareto smoothing

    Functionality specific to the rvar datatype

    The draws_rvar format (a structured list of rvar objects) has the same methods (e.g. bind_draws()) as the other draws formats. For individual rvar objects themselves, however, posterior provides additional functionality.

    @@ -346,7 +370,7 @@

    Functionality specific to t

    Density, CDF, and quantile functions of random variables

    -

    `%**%`

    +

    `%**%` matrixOps(<rvar>)

    Matrix multiplication of random variables

    diff --git a/docs/reference/is_rvar.html b/docs/reference/is_rvar.html index 4724eba3..f19f07f4 100644 --- a/docs/reference/is_rvar.html +++ b/docs/reference/is_rvar.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/is_rvar_factor.html b/docs/reference/is_rvar_factor.html index a771634d..38de9e33 100644 --- a/docs/reference/is_rvar_factor.html +++ b/docs/reference/is_rvar_factor.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/match.html b/docs/reference/match.html index c18dd181..42adcb70 100644 --- a/docs/reference/match.html +++ b/docs/reference/match.html @@ -19,7 +19,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/mcse_mean.html b/docs/reference/mcse_mean.html index c51f4260..d7965430 100644 --- a/docs/reference/mcse_mean.html +++ b/docs/reference/mcse_mean.html @@ -18,7 +18,7 @@ posterior - 1.5.0 + 1.6.0 @@ -169,9 +169,11 @@

    See also

    ess_tail(), mcse_quantile(), mcse_sd(), +pareto_diags(), +pareto_khat(), +rhat(), rhat_basic(), rhat_nested(), -rhat(), rstar()

    diff --git a/docs/reference/mcse_quantile.html b/docs/reference/mcse_quantile.html index 836681f7..c6760abe 100644 --- a/docs/reference/mcse_quantile.html +++ b/docs/reference/mcse_quantile.html @@ -18,7 +18,7 @@ posterior - 1.5.0 + 1.6.0 @@ -187,9 +187,11 @@

    See also

    ess_tail(), mcse_mean(), mcse_sd(), +pareto_diags(), +pareto_khat(), +rhat(), rhat_basic(), rhat_nested(), -rhat(), rstar()

    diff --git a/docs/reference/mcse_sd.html b/docs/reference/mcse_sd.html index 7907ad21..e1d0f975 100644 --- a/docs/reference/mcse_sd.html +++ b/docs/reference/mcse_sd.html @@ -19,7 +19,7 @@ posterior - 1.5.0 + 1.6.0 @@ -174,9 +174,11 @@

    See also

    ess_tail(), mcse_mean(), mcse_quantile(), +pareto_diags(), +pareto_khat(), +rhat(), rhat_basic(), rhat_nested(), -rhat(), rstar()

    diff --git a/docs/reference/merge_chains.html b/docs/reference/merge_chains.html index 1d65b227..041c85e0 100644 --- a/docs/reference/merge_chains.html +++ b/docs/reference/merge_chains.html @@ -21,7 +21,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/modal_category.html b/docs/reference/modal_category.html index 5e4a0421..4ba38bb7 100644 --- a/docs/reference/modal_category.html +++ b/docs/reference/modal_category.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/mutate_variables.html b/docs/reference/mutate_variables.html index 5a0abd21..7eeb05a7 100644 --- a/docs/reference/mutate_variables.html +++ b/docs/reference/mutate_variables.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 @@ -160,7 +160,7 @@

    Details

    diff --git a/docs/reference/order_draws.html b/docs/reference/order_draws.html index 8b024d90..d02aee2b 100644 --- a/docs/reference/order_draws.html +++ b/docs/reference/order_draws.html @@ -19,7 +19,7 @@ posterior - 1.5.0 + 1.6.0
    diff --git a/docs/reference/pareto_diags.html b/docs/reference/pareto_diags.html index 7348b046..fb1240b6 100644 --- a/docs/reference/pareto_diags.html +++ b/docs/reference/pareto_diags.html @@ -19,7 +19,7 @@ posterior - 1.5.0 + 1.6.0 @@ -121,11 +121,36 @@

    Pareto smoothing diagnostics

    r_eff = NULL, ndraws_tail = NULL, verbose = FALSE, + are_log_weights = FALSE, ... ) # S3 method for rvar -pareto_diags(x, ...) +pareto_diags(x, ...) + +pareto_khat_threshold(x, ...) + +# S3 method for default +pareto_khat_threshold(x, ...) + +# S3 method for rvar +pareto_khat_threshold(x, ...) + +pareto_min_ss(x, ...) + +# S3 method for default +pareto_min_ss(x, ...) + +# S3 method for rvar +pareto_min_ss(x, ...) + +pareto_convergence_rate(x, ...) + +# S3 method for default +pareto_convergence_rate(x, ...) + +# S3 method for rvar +pareto_convergence_rate(x, ...)
    @@ -150,15 +175,16 @@

    Arguments

    r_eff

    (numeric) relative effective sample size estimate. If -r_eff is omitted, it will be calculated assuming the draws are -from MCMC.

    +r_eff is NULL, it will be calculated assuming the draws are +from MCMC. Default is NULL.

    ndraws_tail

    (numeric) number of draws for the tail. If ndraws_tail is not specified, it will be calculated as ceiling(3 * sqrt(length(x) / r_eff)) if length(x) > 225 and -length(x) / 5 otherwise (see Appendix H in Vehtari et al. (2022)).

    +length(x) / 5 otherwise (see Appendix H in Vehtari et +al. (2024)).

    verbose
    @@ -166,6 +192,12 @@

    Arguments

    TRUE, messages related to Pareto diagnostics will be printed. Default is FALSE.

    + +
    are_log_weights
    +

    (logical) Are the draws log weights? Default is +FALSE. If TRUE computation will take into account that the +draws are log weights, and only right tail will be smoothed.

    +

    Value

    @@ -186,25 +218,47 @@

    Details

    Pareto smoothed estimates can be considered reliable. If the actual sample size is lower than min_ss, increasing the sample size might result in more reliable estimates. For further details, see -Section 3.2.3, Equation 11 in Vehtari et al. (2022).

    +Section 3.2.3, Equation 11 in Vehtari et al. (2024).

  • khat_threshold: Threshold below which k-hat values result in reliable Pareto smoothed estimates. The threshold is lower for smaller effective sample sizes. If k-hat is larger than the threshold, increasing the total sample size may improve reliability of estimates. For further details, see Section 3.2.4, Equation 13 -in Vehtari et al. (2022).

    • +in Vehtari et al. (2024).

  • convergence_rate: Relative convergence rate compared to the central limit theorem. Applicable only if the actual sample size is sufficiently large (greater than min_ss). The convergence rate tells the rate at which the variance of an estimate reduces when the sample size is increased, compared to the central limit -theorem convergence rate. See Appendix B in Vehtari et al. (2022).

    • +theorem convergence rate. See Appendix B in Vehtari et al. (2024).

    References

    Aki Vehtari, Daniel Simpson, Andrew Gelman, Yuling Yao and -Jonah Gabry (2022). Pareto Smoothed Importance Sampling. -arxiv:arXiv:1507.02646

    +Jonah Gabry (2024). Pareto Smoothed Importance Sampling. +Journal of Machine Learning Research, 25(72):1-58. +PDF

    +
    +
    +

    See also

    +

    pareto_khat, pareto_min_ss, +pareto_khat_threshold, and pareto_convergence_rate for +individual diagnostics; and pareto_smooth for Pareto smoothing +draws.

    +

    Other diagnostics: +ess_basic(), +ess_bulk(), +ess_quantile(), +ess_sd(), +ess_tail(), +mcse_mean(), +mcse_quantile(), +mcse_sd(), +pareto_khat(), +rhat(), +rhat_basic(), +rhat_nested(), +rstar()

    diff --git a/docs/reference/pareto_khat.html b/docs/reference/pareto_khat.html index 286f4195..f40686c0 100644 --- a/docs/reference/pareto_khat.html +++ b/docs/reference/pareto_khat.html @@ -2,7 +2,7 @@ Pareto khat diagnostic — pareto_khat • posterior @@ -20,7 +20,7 @@ posterior - 1.5.0 + 1.6.0
    @@ -110,7 +110,7 @@

    Pareto khat diagnostic

    Estimate Pareto k value by fitting a Generalized Pareto Distribution to one or two tails of x. This can be used to estimate the number of fractional moments that is useful for convergence -diagnostics. For further details see Vehtari et al. (2022).

    +diagnostics. For further details see Vehtari et al. (2024).

    @@ -123,6 +123,7 @@

    Pareto khat diagnostic

    r_eff = NULL, ndraws_tail = NULL, verbose = FALSE, + are_log_weights = FALSE, ... ) @@ -152,15 +153,16 @@

    Arguments

    r_eff

    (numeric) relative effective sample size estimate. If -r_eff is omitted, it will be calculated assuming the draws are -from MCMC.

    +r_eff is NULL, it will be calculated assuming the draws are +from MCMC. Default is NULL.

    ndraws_tail

    (numeric) number of draws for the tail. If ndraws_tail is not specified, it will be calculated as ceiling(3 * sqrt(length(x) / r_eff)) if length(x) > 225 and -length(x) / 5 otherwise (see Appendix H in Vehtari et al. (2022)).

    +length(x) / 5 otherwise (see Appendix H in Vehtari et +al. (2024)).

    verbose
    @@ -168,36 +170,73 @@

    Arguments

    TRUE, messages related to Pareto diagnostics will be printed. Default is FALSE.

    + +
    are_log_weights
    +

    (logical) Are the draws log weights? Default is +FALSE. If TRUE computation will take into account that the +draws are log weights, and only right tail will be smoothed.

    +

    Value

    -

    khat estimated Generalized Pareto Distribution shape parameter k

    +

    If the input is an array, returns a single numeric value. If any of the draws +is non-finite, that is, NA, NaN, Inf, or -Inf, the returned output +will be (numeric) NA. Also, if all draws within any of the chains of a +variable are the same (constant), the returned output will be (numeric) NA

    + + +

    as well. The reason for the latter is that, for constant draws, we cannot +distinguish between variables that are supposed to be constant (e.g., a +diagonal element of a correlation matrix is always 1) or variables that just +happened to be constant because of a failure of convergence or other problems +in the sampling process.

    + + +

    If the input is an rvar, returns an array of the same dimensions as the +rvar, where each element is equal to the value that would be returned by +passing the draws array for that element of the rvar to this function.

    References

    Aki Vehtari, Daniel Simpson, Andrew Gelman, Yuling Yao and -Jonah Gabry (2022). Pareto Smoothed Importance Sampling. -arxiv:arXiv:1507.02646

    +Jonah Gabry (2024). Pareto Smoothed Importance Sampling. +Journal of Machine Learning Research, 25(72):1-58. +PDF

    +
    +
    +

    See also

    +

    pareto_diags for additional related diagnostics, and +pareto_smooth for Pareto smoothed draws.

    +

    Other diagnostics: +ess_basic(), +ess_bulk(), +ess_quantile(), +ess_sd(), +ess_tail(), +mcse_mean(), +mcse_quantile(), +mcse_sd(), +pareto_diags(), +rhat(), +rhat_basic(), +rhat_nested(), +rstar()

    Examples

    mu <- extract_variable_matrix(example_draws(), "mu")
 pareto_khat(mu)
-#> $khat
 #> [1] 0.1979001
-#> 
 
 d <- as_draws_rvars(example_draws("multi_normal"))
 pareto_khat(d$Sigma)
-#> $khat
 #>            [,1]       [,2]        [,3]
 #> [1,] 0.05601935 0.04156719  0.05091481
 #> [2,] 0.04156719 0.10157218  0.06191862
 #> [3,] 0.05091481 0.06191862 -0.08123058
-#>
    diff --git a/docs/reference/pareto_smooth.html b/docs/reference/pareto_smooth.html index cbf7c19f..639bc4a8 100644 --- a/docs/reference/pareto_smooth.html +++ b/docs/reference/pareto_smooth.html @@ -1,7 +1,7 @@ Pareto smoothing — pareto_smooth • posterior @@ -19,7 +19,7 @@ posterior - 1.5.0 + 1.6.0 @@ -108,14 +108,14 @@

    Pareto smoothing

    Smooth the tail draws of x by replacing tail draws by order statistics of a generalized Pareto distribution fit to the -tail(s). For further details see Vehtari et al. (2022).

    +tail(s). For further details see Vehtari et al. (2024).

    pareto_smooth(x, ...)
 
 # S3 method for rvar
-pareto_smooth(x, return_k = TRUE, extra_diags = FALSE, ...)
+pareto_smooth(x, return_k = FALSE, extra_diags = FALSE, ...)
 
 # S3 method for default
 pareto_smooth(
@@ -123,9 +123,10 @@ 
    Pareto smoothing
    
   tail = c("both", "right", "left"),
   r_eff = NULL,
   ndraws_tail = NULL,
-  return_k = TRUE,
+  return_k = FALSE,
   extra_diags = FALSE,
-  verbose = FALSE,
+  verbose = TRUE,
+  are_log_weights = FALSE,
   ...
 )
    @@ -145,8 +146,9 @@

    Arguments

    return_k

    (logical) Should the Pareto khat be included in -output? If TRUE, output will be a list containing of smoothed -draws and diagnostics. Default is TRUE.

    +output? If TRUE, output will be a list containing smoothed +draws and diagnostics, otherwise it will be a numeric of the +smoothed draws. Default is FALSE.

    extra_diags
    @@ -165,15 +167,16 @@

    Arguments

    r_eff

    (numeric) relative effective sample size estimate. If -r_eff is omitted, it will be calculated assuming the draws are -from MCMC.

    +r_eff is NULL, it will be calculated assuming the draws are +from MCMC. Default is NULL.

    ndraws_tail

    (numeric) number of draws for the tail. If ndraws_tail is not specified, it will be calculated as ceiling(3 * sqrt(length(x) / r_eff)) if length(x) > 225 and -length(x) / 5 otherwise (see Appendix H in Vehtari et al. (2022)).

    +length(x) / 5 otherwise (see Appendix H in Vehtari et +al. (2024)).

    verbose
    @@ -181,33 +184,50 @@

    Arguments

    TRUE, messages related to Pareto diagnostics will be printed. Default is FALSE.

    + +
    are_log_weights
    +

    (logical) Are the draws log weights? Default is +FALSE. If TRUE computation will take into account that the +draws are log weights, and only right tail will be smoothed.

    +

    Value

    Either a vector x of smoothed values or a named list -containing the vector x and a named list diagnostics containing Pareto smoothing -diagnostics:

    • khat: estimated Pareto k shape parameter, and -optionally

      • -

    • min_ss: minimum sample size for reliable Pareto -smoothed estimate

      • -

    • khat_threshold: khat-threshold for reliable +containing the vector x and a named list diagnostics

      + + +

      containing numeric values:

      • khat: estimated Pareto k shape parameter, and optionally

        • +

      • min_ss: minimum sample size for reliable Pareto smoothed +estimate

        • +

      • khat_threshold: sample size specific khat threshold for +reliable Pareto smoothed estimates

        • +

      • convergence_rate: Relative convergence rate for Pareto smoothed estimates

        • -

      • convergence_rate: Relative convergence rate for Pareto smoothed estimates

        • -
    +

    If any of the draws is non-finite, that is, NA, NaN, Inf, or +-Inf, Pareto smoothing will not be performed, and the original +draws will be returned and and diagnostics will be NA (numeric).

    +

    References

    Aki Vehtari, Daniel Simpson, Andrew Gelman, Yuling Yao and -Jonah Gabry (2022). Pareto Smoothed Importance Sampling. -arxiv:arXiv:1507.02646

    +Jonah Gabry (2024). Pareto Smoothed Importance Sampling. +Journal of Machine Learning Research, 25(72):1-58. +PDF

    +
    +
    +

    See also

    +

    pareto_khat for only calculating khat, and +pareto_diags for additional diagnostics.

    Examples

    mu <- extract_variable_matrix(example_draws(), "mu")
 pareto_smooth(mu)
-#> $x
+#> Pareto k-hat = 0.2.
 #>          chain
 #> iteration          1            2           3           4
 #>       1    2.0058311   2.99038071  1.79436801  6.45897880
@@ -310,30 +330,23 @@ 
    Examples
    
 #>       98   6.1728283   1.51990114  0.15400719  2.72636415
 #>       99   1.5485347   8.53166943  3.17470254  0.61142881
 #>       100  7.5338964  -1.44854601  3.57555760  7.04723309
-#> 
-#> $diagnostics
-#> $diagnostics$khat
-#> [1] 0.1979001
-#> 
-#> 
 
 d <- as_draws_rvars(example_draws("multi_normal"))
 pareto_smooth(d$Sigma)
-#> $x
+#> Pareto k-hat = 0.06.
+#> Pareto k-hat = 0.04.
+#> Pareto k-hat = 0.05.
+#> Pareto k-hat = 0.04.
+#> Pareto k-hat = 0.1.
+#> Pareto k-hat = 0.06.
+#> Pareto k-hat = 0.05.
+#> Pareto k-hat = 0.06.
+#> Pareto k-hat = -0.08.
 #> rvar<100,4>[3,3] mean ± sd:
 #>      [,1]          [,2]          [,3]         
 #> [1,]  1.28 ± 0.17   0.53 ± 0.21  -0.40 ± 0.29 
 #> [2,]  0.53 ± 0.21   3.66 ± 0.45  -2.10 ± 0.49 
 #> [3,] -0.40 ± 0.29  -2.10 ± 0.49   8.12 ± 0.96 
-#> 
-#> $diagnostics
-#> $diagnostics$khat
-#>            [,1]       [,2]        [,3]
-#> [1,] 0.05601935 0.04156719  0.05091481
-#> [2,] 0.04156719 0.10157218  0.06191862
-#> [3,] 0.05091481 0.06191862 -0.08123058
-#> 
-#>
    diff --git a/docs/reference/posterior-package.html b/docs/reference/posterior-package.html index bf384314..fda7fc4b 100644 --- a/docs/reference/posterior-package.html +++ b/docs/reference/posterior-package.html @@ -31,7 +31,7 @@ posterior - 1.5.0 + 1.6.0 @@ -161,6 +161,26 @@

    Package options

    trigger an automatic merging of chains, for example, because chains do not match between two objects involved in a binary operation. Whether this causes a warning can be controlled by this option.

    + + +
    +

    Author

    +

    Maintainer: Paul-Christian Bürkner paul.buerkner@gmail.com

    +

    Authors:

    Other contributors:

    • Måns Magnusson [contributor]

      • +

    • Rok Češnovar [contributor]

      • +

    • Ben Lambert [contributor]

      • +

    • Ozan Adıgüzel [contributor]

      • +

    • Jacob Socolar [contributor]

      • +

    • Noa Kallioinen [contributor]

    diff --git a/docs/reference/print.draws_array.html b/docs/reference/print.draws_array.html index 1c65ef7d..c26582ad 100644 --- a/docs/reference/print.draws_array.html +++ b/docs/reference/print.draws_array.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/print.draws_df.html b/docs/reference/print.draws_df.html index 0472145a..9b95be58 100644 --- a/docs/reference/print.draws_df.html +++ b/docs/reference/print.draws_df.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/print.draws_list.html b/docs/reference/print.draws_list.html index 81574f4d..4ee47f81 100644 --- a/docs/reference/print.draws_list.html +++ b/docs/reference/print.draws_list.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/print.draws_matrix.html b/docs/reference/print.draws_matrix.html index 42bf6225..85db03e0 100644 --- a/docs/reference/print.draws_matrix.html +++ b/docs/reference/print.draws_matrix.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/print.draws_rvars.html b/docs/reference/print.draws_rvars.html index 2e2d42d9..3620971d 100644 --- a/docs/reference/print.draws_rvars.html +++ b/docs/reference/print.draws_rvars.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/print.draws_summary.html b/docs/reference/print.draws_summary.html index 9c830356..839f1c91 100644 --- a/docs/reference/print.draws_summary.html +++ b/docs/reference/print.draws_summary.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/print.rvar.html b/docs/reference/print.rvar.html index 67ece360..0f3029d0 100644 --- a/docs/reference/print.rvar.html +++ b/docs/reference/print.rvar.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/ps_convergence_rate.html b/docs/reference/ps_convergence_rate.html new file mode 100644 index 00000000..d31c252c --- /dev/null +++ b/docs/reference/ps_convergence_rate.html @@ -0,0 +1,173 @@ + +Pareto convergence rate — ps_convergence_rate • posterior + + +
    +
    + + + +
    +
    +
    +

    Pareto convergence rate

    + Source: R/pareto_smooth.R + +
    + +
    +

    Given number of draws and scalar or array of k's, compute the +relative convergence rate of PSIS estimate RMSE. See Appendix B of +Vehtari et al. (2024). This function is exported to be usable by +other packages. For user-facing diagnostic functions, see +pareto_convergence_rate and pareto_diags.

    +
    + +
    + 
    ps_convergence_rate(k, ndraws, ...)
    +
    + +
    +

    Arguments

    +
    k
    +

    pareto-k values

    + + +
    ndraws
    +

    number of draws

    + + +
    ...
    +

    unused

    + +
    +
    +

    Value

    + + +

    convergence rate

    +
    +
    +

    See also

    +

    Other helper-functions: +ps_khat_threshold(), +ps_min_ss(), +ps_tail_length()

    +
    + +
    + +
    + + +
    +

    Developed by Paul-Christian Bürkner, Jonah Gabry, Matthew Kay, Aki Vehtari.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/ps_khat_threshold.html b/docs/reference/ps_khat_threshold.html new file mode 100644 index 00000000..5e824367 --- /dev/null +++ b/docs/reference/ps_khat_threshold.html @@ -0,0 +1,171 @@ + +Pareto k-hat threshold — ps_khat_threshold • posterior + + +
    +
    + + + +
    +
    +
    +

    Pareto k-hat threshold

    + Source: R/pareto_smooth.R + +
    + +
    +

    Given number of draws, computes khat threshold for reliable Pareto +smoothed estimate (to have small probability of large error). See +section 3.2.4, equation (13) of Vehtari et al. (2024). This +function is exported to be usable by other packages. For +user-facing diagnostic functions, see pareto_khat_threshold and +pareto_diags.

    +
    + +
    + 
    ps_khat_threshold(ndraws, ...)
    +
    + +
    +

    Arguments

    +
    ndraws
    +

    number of draws

    + + +
    ...
    +

    unused

    + +
    +
    +

    Value

    + + +

    threshold

    +
    +
    +

    See also

    +

    Other helper-functions: +ps_convergence_rate(), +ps_min_ss(), +ps_tail_length()

    +
    + +
    + +
    + + +
    +

    Developed by Paul-Christian Bürkner, Jonah Gabry, Matthew Kay, Aki Vehtari.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/ps_min_ss.html b/docs/reference/ps_min_ss.html new file mode 100644 index 00000000..bf028f3c --- /dev/null +++ b/docs/reference/ps_min_ss.html @@ -0,0 +1,169 @@ + +Pareto-smoothing minimum sample-size — ps_min_ss • posterior + + +
    +
    + + + +
    +
    +
    +

    Pareto-smoothing minimum sample-size

    + Source: R/pareto_smooth.R + +
    + +
    +

    Given Pareto-k computes the minimum sample size for reliable Pareto +smoothed estimate (to have small probability of large error). See +section 3.2.3 in Vehtari et al. (2024). This function is exported +to be usable by other packages. For user-facing diagnostic functions, see +pareto_min_ss and pareto_diags.

    +
    + +
    + 
    ps_min_ss(k, ...)
    +
    + +
    +

    Arguments

    +
    k
    +

    pareto k value

    + + +
    ...
    +

    unused

    + +
    +
    +

    Value

    + + +

    minimum sample size

    +
    +
    +

    See also

    +

    Other helper-functions: +ps_convergence_rate(), +ps_khat_threshold(), +ps_tail_length()

    +
    + +
    + +
    + + +
    +

    Developed by Paul-Christian Bürkner, Jonah Gabry, Matthew Kay, Aki Vehtari.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/ps_tail_length.html b/docs/reference/ps_tail_length.html new file mode 100644 index 00000000..514d8ad6 --- /dev/null +++ b/docs/reference/ps_tail_length.html @@ -0,0 +1,169 @@ + +Pareto tail length — ps_tail_length • posterior + + +
    +
    + + + +
    +
    +
    +

    Pareto tail length

    + Source: R/pareto_smooth.R + +
    + +
    +

    Calculate the tail length from number of draws and relative efficiency +r_eff. See Appendix H in Vehtari et al. (2024). This function is +used internally and is exported to be available for other packages.

    +
    + +
    + 
    ps_tail_length(ndraws, r_eff, ...)
    +
    + +
    +

    Arguments

    +
    ndraws
    +

    number of draws

    + + +
    r_eff
    +

    relative efficiency

    + + +
    ...
    +

    unused

    + +
    +
    +

    Value

    + + +

    tail length

    +
    +
    +

    See also

    +

    Other helper-functions: +ps_convergence_rate(), +ps_khat_threshold(), +ps_min_ss()

    +
    + +
    + +
    + + +
    +

    Developed by Paul-Christian Bürkner, Jonah Gabry, Matthew Kay, Aki Vehtari.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/quantile2.html b/docs/reference/quantile2.html index 24a0721e..e2ce3067 100644 --- a/docs/reference/quantile2.html +++ b/docs/reference/quantile2.html @@ -18,7 +18,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/r_scale.html b/docs/reference/r_scale.html index 6aa29382..65b1e65f 100644 --- a/docs/reference/r_scale.html +++ b/docs/reference/r_scale.html @@ -19,7 +19,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/rdo.html b/docs/reference/rdo.html index 91851905..1ba8c754 100644 --- a/docs/reference/rdo.html +++ b/docs/reference/rdo.html @@ -18,7 +18,7 @@ posterior - 1.5.0 + 1.6.0 @@ -117,7 +117,7 @@

    Execute expressions of random variables

    Arguments

    expr

    (expression) A bare expression that can (optionally) contain -rvars. The expression supports quasiquotation.

    +rvars. The expression supports quasiquotation.

    dim
    diff --git a/docs/reference/reexports.html b/docs/reference/reexports.html index cd209a64..eb2e2209 100644 --- a/docs/reference/reexports.html +++ b/docs/reference/reexports.html @@ -24,7 +24,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/rename_variables.html b/docs/reference/rename_variables.html index 14fca7b3..fef58b4e 100644 --- a/docs/reference/rename_variables.html +++ b/docs/reference/rename_variables.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 @@ -137,29 +137,29 @@

    Value

    Examples

    x <- as_draws_df(example_draws())
-variables(x)
+variables(x)
 #>  [1] "mu"       "tau"      "theta[1]" "theta[2]" "theta[3]" "theta[4]"
 #>  [7] "theta[5]" "theta[6]" "theta[7]" "theta[8]"
 
 x <- rename_variables(x, mean = mu, sigma = tau)
-variables(x)
+variables(x)
 #>  [1] "mean"     "sigma"    "theta[1]" "theta[2]" "theta[3]" "theta[4]"
 #>  [7] "theta[5]" "theta[6]" "theta[7]" "theta[8]"
 
 x <- rename_variables(x, b = `theta[1]`) # or b  = "theta[1]"
-variables(x)
+variables(x)
 #>  [1] "mean"     "sigma"    "b"        "theta[2]" "theta[3]" "theta[4]"
 #>  [7] "theta[5]" "theta[6]" "theta[7]" "theta[8]"
 
 # rename all elements of 'theta' at once
 x <- rename_variables(x, alpha = theta)
-variables(x)
+variables(x)
 #>  [1] "mean"     "sigma"    "b"        "alpha[2]" "alpha[3]" "alpha[4]"
 #>  [7] "alpha[5]" "alpha[6]" "alpha[7]" "alpha[8]"
 
diff --git a/docs/reference/repair_draws.html b/docs/reference/repair_draws.html
index 1ee2335a..2228cf9b 100644
--- a/docs/reference/repair_draws.html
+++ b/docs/reference/repair_draws.html
@@ -18,7 +18,7 @@
       
       
         posterior
-        1.5.0
+        1.6.0
    diff --git a/docs/reference/resample_draws.html b/docs/reference/resample_draws.html index 79bc645f..c509774e 100644 --- a/docs/reference/resample_draws.html +++ b/docs/reference/resample_draws.html @@ -18,7 +18,7 @@ posterior - 1.5.0 + 1.6.0
    diff --git a/docs/reference/reserved_variables.html b/docs/reference/reserved_variables.html index f0fb854a..5c5ec954 100644 --- a/docs/reference/reserved_variables.html +++ b/docs/reference/reserved_variables.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 @@ -168,7 +168,6 @@

    Examples

    # if we add weights, the `.log_weight` reserved variable is used x <- weight_draws(x, rexp(ndraws(x))) -#> Loading required namespace: testthat reserved_variables(x) #> [1] ".log_weight" diff --git a/docs/reference/rfun.html b/docs/reference/rfun.html index dbe4c554..5489821f 100644 --- a/docs/reference/rfun.html +++ b/docs/reference/rfun.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/rhat.html b/docs/reference/rhat.html index e2c377c6..9ab5cd2a 100644 --- a/docs/reference/rhat.html +++ b/docs/reference/rhat.html @@ -19,7 +19,7 @@ posterior - 1.5.0 + 1.6.0 @@ -174,6 +174,8 @@

    See also

    mcse_mean(), mcse_quantile(), mcse_sd(), +pareto_diags(), +pareto_khat(), rhat_basic(), rhat_nested(), rstar()

    diff --git a/docs/reference/rhat_basic.html b/docs/reference/rhat_basic.html index 5b3e5330..42f61c06 100644 --- a/docs/reference/rhat_basic.html +++ b/docs/reference/rhat_basic.html @@ -20,7 +20,7 @@ posterior - 1.5.0 + 1.6.0 @@ -184,8 +184,10 @@

    See also

    mcse_mean(), mcse_quantile(), mcse_sd(), -rhat_nested(), +pareto_diags(), +pareto_khat(), rhat(), +rhat_nested(), rstar()

    diff --git a/docs/reference/rhat_nested.html b/docs/reference/rhat_nested.html index 6561f222..327c5ff0 100644 --- a/docs/reference/rhat_nested.html +++ b/docs/reference/rhat_nested.html @@ -18,7 +18,7 @@ posterior - 1.5.0 + 1.6.0 @@ -191,8 +191,10 @@

    See also

    mcse_mean(), mcse_quantile(), mcse_sd(), -rhat_basic(), +pareto_diags(), +pareto_khat(), rhat(), +rhat_basic(), rstar()

    diff --git a/docs/reference/rstar.html b/docs/reference/rstar.html index f64dab4d..a6a1957c 100644 --- a/docs/reference/rstar.html +++ b/docs/reference/rstar.html @@ -22,7 +22,7 @@ posterior - 1.5.0 + 1.6.0 @@ -226,9 +226,11 @@

    See also

    mcse_mean(), mcse_quantile(), mcse_sd(), +pareto_diags(), +pareto_khat(), +rhat(), rhat_basic(), -rhat_nested(), -rhat()

    +rhat_nested()

    @@ -249,6 +251,7 @@

    Examples

    # can use other classification methods in caret library print(rstar(x, method = "knn")) } +#> Warning: package ‘ggplot2’ was built under R version 4.2.3 #> randomForest 4.7-1.1 #> Type rfNews() to see new features/changes/bug fixes. #> diff --git a/docs/reference/rvar-dist.html b/docs/reference/rvar-dist.html index 041060ea..bea313a8 100644 --- a/docs/reference/rvar-dist.html +++ b/docs/reference/rvar-dist.html @@ -19,7 +19,7 @@ posterior - 1.5.0 + 1.6.0
    diff --git a/docs/reference/rvar-matmult.html b/docs/reference/rvar-matmult.html index eaed0eef..f14f8934 100644 --- a/docs/reference/rvar-matmult.html +++ b/docs/reference/rvar-matmult.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 @@ -108,7 +108,10 @@

    Matrix multiplication of random variables

    - 
    x %**% y
    + 
    x %**% y
+
+# S3 method for rvar
+matrixOps(x, y)
    @@ -140,8 +143,9 @@

    Details

    by rvars and are broadcasted across all draws of the rvar argument. Tensor multiplication is used to efficiently multiply matrices across draws, so if either x or y is an rvar, x %**% y will be much faster than rdo(x %*% y).

    -

    Because rvar is an S3 class and S3 classes cannot properly override %*%, rvars use -%**% for matrix multiplication.

    +

    In R >= 4.3, you can also use %*% in place of %**% for matrix multiplication +of rvars. In R < 4.3, S3 classes cannot properly override %*%, so +you must use %**% for matrix multiplication of rvars.

    diff --git a/docs/reference/rvar-slice.html b/docs/reference/rvar-slice.html index c6d628fa..54bd7b12 100644 --- a/docs/reference/rvar-slice.html +++ b/docs/reference/rvar-slice.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0
    diff --git a/docs/reference/rvar-summaries-over-draws.html b/docs/reference/rvar-summaries-over-draws.html index 9e6802a1..da3cbcaa 100644 --- a/docs/reference/rvar-summaries-over-draws.html +++ b/docs/reference/rvar-summaries-over-draws.html @@ -19,7 +19,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/rvar-summaries-within-draws.html b/docs/reference/rvar-summaries-within-draws.html index cbc05372..0fc61b17 100644 --- a/docs/reference/rvar-summaries-within-draws.html +++ b/docs/reference/rvar-summaries-within-draws.html @@ -19,7 +19,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/rvar.html b/docs/reference/rvar.html index 4f350500..93f77141 100644 --- a/docs/reference/rvar.html +++ b/docs/reference/rvar.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/rvar_apply.html b/docs/reference/rvar_apply.html index bebd22b3..9e35dd06 100644 --- a/docs/reference/rvar_apply.html +++ b/docs/reference/rvar_apply.html @@ -19,7 +19,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/rvar_factor.html b/docs/reference/rvar_factor.html index f0226646..b76b6620 100644 --- a/docs/reference/rvar_factor.html +++ b/docs/reference/rvar_factor.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/rvar_ifelse.html b/docs/reference/rvar_ifelse.html index 90afcfa7..5d833dd2 100644 --- a/docs/reference/rvar_ifelse.html +++ b/docs/reference/rvar_ifelse.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/rvar_is_finite.html b/docs/reference/rvar_is_finite.html index 69560d36..296c67ea 100644 --- a/docs/reference/rvar_is_finite.html +++ b/docs/reference/rvar_is_finite.html @@ -18,7 +18,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/rvar_rng.html b/docs/reference/rvar_rng.html index 8b40e0fe..044e9f01 100644 --- a/docs/reference/rvar_rng.html +++ b/docs/reference/rvar_rng.html @@ -18,7 +18,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/split_chains.html b/docs/reference/split_chains.html index 2b1a475a..150f7759 100644 --- a/docs/reference/split_chains.html +++ b/docs/reference/split_chains.html @@ -18,7 +18,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/sub-.draws_array.html b/docs/reference/sub-.draws_array.html index 197198f7..c9f4c838 100644 --- a/docs/reference/sub-.draws_array.html +++ b/docs/reference/sub-.draws_array.html @@ -23,7 +23,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/sub-.draws_matrix.html b/docs/reference/sub-.draws_matrix.html index cd37d42a..314d6b44 100644 --- a/docs/reference/sub-.draws_matrix.html +++ b/docs/reference/sub-.draws_matrix.html @@ -23,7 +23,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/reference/subset_draws.html b/docs/reference/subset_draws.html index 9c6594af..eb1fd8fd 100644 --- a/docs/reference/subset_draws.html +++ b/docs/reference/subset_draws.html @@ -17,7 +17,7 @@ posterior - 1.5.0 + 1.6.0 @@ -119,6 +119,8 @@

    Subset draws objects

    draw = NULL, regex = FALSE, unique = TRUE, + exclude = FALSE, + scalar = FALSE, ... ) @@ -131,6 +133,8 @@

    Subset draws objects

    draw = NULL, regex = FALSE, unique = TRUE, + exclude = FALSE, + scalar = FALSE, ... ) @@ -143,6 +147,8 @@

    Subset draws objects

    draw = NULL, regex = FALSE, unique = TRUE, + exclude = FALSE, + scalar = FALSE, ... ) @@ -155,6 +161,8 @@

    Subset draws objects

    draw = NULL, regex = FALSE, unique = TRUE, + exclude = FALSE, + scalar = FALSE, ... ) @@ -167,6 +175,8 @@

    Subset draws objects

    draw = NULL, regex = FALSE, unique = TRUE, + exclude = FALSE, + scalar = FALSE, ... ) @@ -189,8 +199,8 @@

    Arguments

    variable
    -

    (character vector) The variables to select. All elements of -non-scalar variables can be selected at once.

    +

    (character vector) The variables to select. All +elements of non-scalar variables can be selected at once.

    iteration
    @@ -202,21 +212,36 @@

    Arguments

    draw
    -

    (integer vector) The draw indices to be select. Subsetting draw -indices will lead to an automatic merging of chains via merge_chains.

    +

    (integer vector) The draw indices to be +select. Subsetting draw indices will lead to an automatic merging +of chains via merge_chains.

    regex

    (logical) Should variable should be treated as a -(vector of) regular expressions? Any variable in x matching at least one -of the regular expressions will be selected. Defaults to FALSE.

    +(vector of) regular expressions? Any variable in x matching at +least one of the regular expressions will be selected. Defaults +to FALSE.

    unique
    -

    (logical) Should duplicated selection of chains, iterations, or -draws be allowed? If TRUE (the default) only unique chains, iterations, -and draws are selected regardless of how often they appear in the -respective selecting arguments.

    +

    (logical) Should duplicated selection of chains, +iterations, or draws be allowed? If TRUE (the default) only +unique chains, iterations, and draws are selected regardless of +how often they appear in the respective selecting arguments.

    + + +
    exclude
    +

    (logical) Should the selected subset be excluded? +If FALSE (the default) only the selected subset will be +returned. If TRUE everything but the selected subset will be +returned.

    + + +
    scalar
    +

    (logical) Should only scalar variables be selected? +If FALSE (the default), all variables with matching names and +arbitrary indices will be selected (see examples).

    @@ -435,6 +460,9 @@

    Examples

    #> #> # ... with 95 more iterations, and 4 more variables +# trying to extract only a scalar 'theta' will fail +# subset_draws(x, variable = "theta", scalar = TRUE) +
    diff --git a/docs/reference/thin_draws.html b/docs/reference/thin_draws.html index afbc4697..16d871d3 100644 --- a/docs/reference/thin_draws.html +++ b/docs/reference/thin_draws.html @@ -1,5 +1,6 @@ -Thin draws objects — thin_draws • posteriorThin draws objects — thin_draws • posterior @@ -17,7 +18,7 @@ posterior - 1.5.0 + 1.6.0 @@ -104,17 +105,18 @@

    Thin draws objects

    -

    Thin draws objects to reduce their size and autocorrelation in the chains.

    +

    Thin draws objects to reduce their size and autocorrelation in +the chains.

    - 
    thin_draws(x, thin, ...)
+    
    thin_draws(x, thin = NULL, ...)
 
 # S3 method for draws
-thin_draws(x, thin, ...)
+thin_draws(x, thin = NULL, ...)
 
 # S3 method for rvar
-thin_draws(x, thin, ...)
    
+thin_draws(x, thin = NULL, ...)
    @@ -125,7 +127,15 @@

    Arguments

    thin
    -

    (positive integer) The period for selecting draws.

    +

    (positive numeric) The period for selecting draws. Must +be between 1 and the number of iterations. If the value is not an +integer, the draws will be selected such that the number of draws +returned is equal to round(ndraws(x) / thin). Intervals between +selected draws will be either ceiling(thin) or floor(thin), such +that the average interval will be close to the thin value. If +NULL, it will be automatically calculated based on bulk and +tail effective sample size as suggested by Säilynoja et +al. (2022).

    ...
    @@ -138,6 +148,13 @@

    Value

    A draws object of the same class as x.

    +
    +

    References

    +

    Teemu Säilynoja, Paul-Christian Bürkner, and Aki Vehtari (2022). +Graphical test for discrete uniformity and its applications in +goodness-of-fit evaluation and multiple sample comparison. +Statistics and Computing. 32, 32. doi:10.1007/s11222-022-10090-6

    +

    Examples

    diff --git a/docs/reference/u_scale.html b/docs/reference/u_scale.html index e01e2af6..31194a50 100644 --- a/docs/reference/u_scale.html +++ b/docs/reference/u_scale.html @@ -20,7 +20,7 @@ posterior - 1.5.0 + 1.6.0
    diff --git a/docs/reference/variables-set.html b/docs/reference/variables-set.html new file mode 100644 index 00000000..d410a547 --- /dev/null +++ b/docs/reference/variables-set.html @@ -0,0 +1,215 @@ + +Set variable names in draws objects — variables<- • posterior + + +
    +
    + + + +
    +
    +
    +

    Set variable names in draws objects

    + Source: R/variables.R + +
    + +
    +

    Set variable names for all variables in a draws object. The +set_variables() form is useful when using pipe operators.

    +
    + +
    + 
    variables(x, ...) <- value
+
+# S3 method for draws_matrix
+variables(x, with_indices = TRUE, ...) <- value
+
+# S3 method for draws_array
+variables(x, with_indices = TRUE, ...) <- value
+
+# S3 method for draws_df
+variables(x, with_indices = TRUE, ...) <- value
+
+# S3 method for draws_list
+variables(x, with_indices = TRUE, ...) <- value
+
+# S3 method for draws_rvars
+variables(x, with_indices = FALSE, ...) <- value
+
+set_variables(x, variables, ...)
    +
    + +
    +

    Arguments

    +
    x
    +

    (draws) A draws object or another R object for which the method +is defined.

    + + +
    ...
    +

    Arguments passed to individual methods (if applicable).

    + + +
    value, variables
    +

    (character vector) new variable names.

    + + +
    with_indices
    +

    (logical) Should indices be included in variable +names? For example, if the object includes variables named "x[1]" and +"x[2]", if TRUE, c("x[1]", "x[2]") is returned; if FALSE, only "x" +is returned. Defaults to TRUE for all formats except draws_rvars().

    + +
    +
    +

    Value

    + + +

    Returns a draws object of the same format as x, with +variables named as specified.

    +
    +
    +

    Details

    +

    variables(x) <- value allows you to modify the vector of variable names, +similar to how names(x) <- value works for vectors and lists. For renaming +specific variables, set_variables(x, value) works equivalently, but is more intuitive +when using the pipe operator.

    +

    For renaming specific variables, rename_variables() may offer a more +convenient approach.

    +
    + + +
    +

    Examples

    + 
    x <- example_draws()
+
+variables(x)
+#>  [1] "mu"       "tau"      "theta[1]" "theta[2]" "theta[3]" "theta[4]"
+#>  [7] "theta[5]" "theta[6]" "theta[7]" "theta[8]"
+nvariables(x)
+#> [1] 10
+variables(x) <- letters[1:nvariables(x)]
+
+# or equivalently...
+x <- set_variables(x, letters[1:nvariables(x)])
+
+
    +
    +
    + +
    + + +
    +

    Developed by Paul-Christian Bürkner, Jonah Gabry, Matthew Kay, Aki Vehtari.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/variables.html b/docs/reference/variables.html new file mode 100644 index 00000000..6705a7e1 --- /dev/null +++ b/docs/reference/variables.html @@ -0,0 +1,209 @@ + +Get variable names from draws objects — variables • posterior + + +
    +
    + + + +
    +
    +
    +

    Get variable names from draws objects

    + Source: R/variables.R + +
    + +
    +

    Get variable names from draws objects.

    +
    + +
    + 
    variables(x, ...)
+
+# S3 method for draws_matrix
+variables(x, reserved = FALSE, with_indices = TRUE, ...)
+
+# S3 method for draws_array
+variables(x, reserved = FALSE, with_indices = TRUE, ...)
+
+# S3 method for draws_df
+variables(x, reserved = FALSE, with_indices = TRUE, ...)
+
+# S3 method for draws_list
+variables(x, reserved = FALSE, with_indices = TRUE, ...)
+
+# S3 method for draws_rvars
+variables(x, reserved = FALSE, with_indices = FALSE, ...)
+
+nvariables(x, ...)
    +
    + +
    +

    Arguments

    +
    x
    +

    (draws) A draws object or another R object for which the method +is defined.

    + + +
    ...
    +

    Arguments passed to individual methods (if applicable).

    + + +
    reserved
    +

    (logical) Should reserved variables be included in the +output? Defaults to FALSE. See reserved_variables for an overview of +currently reserved variable names.

    + + +
    with_indices
    +

    (logical) Should indices be included in variable +names? For example, if the object includes variables named "x[1]" and +"x[2]", if TRUE, c("x[1]", "x[2]") is returned; if FALSE, only "x" +is returned. Defaults to TRUE for all formats except draws_rvars().

    + +
    +
    +

    Value

    + + +

    For variables(), a character vector.

    + + +

    For nvariables(), a scalar integer.

    +
    +
    +

    Details

    +

    variables() returns a vector of all variable names, and nvariables() +returns the number of variables.

    +
    +
    +

    See also

    +

    variables<-, rename_variables, draws-index

    +
    + +
    +

    Examples

    + 
    x <- example_draws()
+
+variables(x)
+#>  [1] "mu"       "tau"      "theta[1]" "theta[2]" "theta[3]" "theta[4]"
+#>  [7] "theta[5]" "theta[6]" "theta[7]" "theta[8]"
+nvariables(x)
+#> [1] 10
+variables(x) <- letters[1:nvariables(x)]
+
    +
    +
    + +
    + + +
    +

    Developed by Paul-Christian Bürkner, Jonah Gabry, Matthew Kay, Aki Vehtari.

    +
    + +
    +

    Site built with pkgdown 2.0.7.

    +
    + +
    + + + + + + + + diff --git a/docs/reference/weight_draws.html b/docs/reference/weight_draws.html index eac63e84..6eb3931d 100644 --- a/docs/reference/weight_draws.html +++ b/docs/reference/weight_draws.html @@ -21,7 +21,7 @@ posterior - 1.5.0 + 1.6.0 @@ -119,19 +119,19 @@

    Weight draws objects

    weight_draws(x, weights, ...)
 
 # S3 method for draws_matrix
-weight_draws(x, weights, log = FALSE, ...)
+weight_draws(x, weights, log = FALSE, pareto_smooth = FALSE, ...)
 
 # S3 method for draws_array
-weight_draws(x, weights, log = FALSE, ...)
+weight_draws(x, weights, log = FALSE, pareto_smooth = FALSE, ...)
 
 # S3 method for draws_df
-weight_draws(x, weights, log = FALSE, ...)
+weight_draws(x, weights, log = FALSE, pareto_smooth = FALSE, ...)
 
 # S3 method for draws_list
-weight_draws(x, weights, log = FALSE, ...)
+weight_draws(x, weights, log = FALSE, pareto_smooth = FALSE, ...)
 
 # S3 method for draws_rvars
-weight_draws(x, weights, log = FALSE, ...)
    +weight_draws(x, weights, log = FALSE, pareto_smooth = FALSE, ...)
    @@ -153,10 +153,15 @@

    Arguments

    log
    -

    (logicla) Are the weights passed already on the log scale? The +

    (logical) Are the weights passed already on the log scale? The default is FALSE, that is, expecting weights to be on the standard (non-log) scale.

    + +
    pareto_smooth
    +

    (logical) Should the weights be Pareto-smoothed? +The default is FALSE.

    +

    Value

    @@ -176,32 +181,36 @@

    Examples

    # sample some random weights for illustration wts <- rexp(ndraws(x)) head(wts) -#> [1] 0.2644506 1.4629054 1.9719158 0.8050840 2.4207868 1.4064785 +#> [1] 0.07943442 1.20975078 0.09003050 0.22634413 0.47107425 0.22054226 # add weights x <- weight_draws(x, weights = wts) # extract weights head(weights(x)) # defaults to normalized weights -#> [1] 0.0007016715 0.0038815529 0.0052321195 0.0021361438 0.0064231168 -#> [6] 0.0037318345 +#> [1] 0.0002133569 0.0032493306 0.0002418175 0.0006079491 0.0012652821 +#> [6] 0.0005923656 head(weights(x, normalize=FALSE)) # recover original weights -#> [1] 0.2644506 1.4629054 1.9719158 0.8050840 2.4207868 1.4064785 +#> [1] 0.07943442 1.20975078 0.09003050 0.22634413 0.47107425 0.22054226 head(weights(x, log=TRUE)) # get normalized log-weights -#> [1] -7.262045 -5.551520 -5.252939 -6.148753 -5.047852 -5.590855 +#> [1] -8.452544 -5.729306 -8.327327 -7.405419 -6.672460 -7.431387 # add weights which are already on the log scale log_wts <- log(wts) head(log_wts) -#> [1] -1.3301008 0.3804244 0.6790056 -0.2168086 0.8840926 0.3410891 +#> [1] -2.5328235 0.1904144 -2.4076068 -1.4856988 -0.7527396 -1.5116659 x <- weight_draws(x, weights = log_wts, log = TRUE) # extract weights head(weights(x)) -#> [1] 0.0007016715 0.0038815529 0.0052321195 0.0021361438 0.0064231168 -#> [6] 0.0037318345 +#> [1] 0.0002133569 0.0032493306 0.0002418175 0.0006079491 0.0012652821 +#> [6] 0.0005923656 head(weights(x, log=TRUE, normalize = FALSE)) # recover original log_wts -#> [1] -1.3301008 0.3804244 0.6790056 -0.2168086 0.8840926 0.3410891 +#> [1] -2.5328235 0.1904144 -2.4076068 -1.4856988 -0.7527396 -1.5116659 + +# add weights on log scale and Pareto smooth them +x <- weight_draws(x, weights = log_wts, log = TRUE, pareto_smooth = TRUE) +#> Pareto k-hat = 0.04.
    diff --git a/docs/reference/weights.draws.html b/docs/reference/weights.draws.html index 51f94eb2..6e4ced68 100644 --- a/docs/reference/weights.draws.html +++ b/docs/reference/weights.draws.html @@ -18,7 +18,7 @@ posterior - 1.5.0 + 1.6.0 @@ -152,32 +152,36 @@

    Examples

    # sample some random weights for illustration wts <- rexp(ndraws(x)) head(wts) -#> [1] 0.61086446 0.33461334 0.02989975 0.36790580 2.15576680 0.24003173 +#> [1] 0.44924386 0.01132425 0.79627288 0.06250828 0.26065786 0.04660613 # add weights x <- weight_draws(x, weights = wts) # extract weights head(weights(x)) # defaults to normalized weights -#> [1] 1.574879e-03 8.626719e-04 7.708502e-05 9.485037e-04 5.557816e-03 -#> [6] 6.188295e-04 +#> [1] 1.191764e-03 3.004123e-05 2.112371e-03 1.658234e-04 6.914792e-04 +#> [6] 1.236378e-04 head(weights(x, normalize=FALSE)) # recover original weights -#> [1] 0.61086446 0.33461334 0.02989975 0.36790580 2.15576680 0.24003173 +#> [1] 0.44924386 0.01132425 0.79627288 0.06250828 0.26065786 0.04660613 head(weights(x, log=TRUE)) # get normalized log-weights -#> [1] -6.453577 -7.055476 -9.470602 -6.960625 -5.192550 -7.387681 +#> [1] -6.732320 -10.412940 -6.159944 -8.704587 -7.276678 -8.998154 # add weights which are already on the log scale log_wts <- log(wts) head(log_wts) -#> [1] -0.4928802 -1.0947796 -3.5099051 -0.9999283 0.7681465 -1.4269842 +#> [1] -0.8001894 -4.4808090 -0.2278133 -2.7724563 -1.3445466 -3.0660231 x <- weight_draws(x, weights = log_wts, log = TRUE) # extract weights head(weights(x)) -#> [1] 1.574879e-03 8.626719e-04 7.708502e-05 9.485037e-04 5.557816e-03 -#> [6] 6.188295e-04 +#> [1] 1.191764e-03 3.004123e-05 2.112371e-03 1.658234e-04 6.914792e-04 +#> [6] 1.236378e-04 head(weights(x, log=TRUE, normalize = FALSE)) # recover original log_wts -#> [1] -0.4928802 -1.0947796 -3.5099051 -0.9999283 0.7681465 -1.4269842 +#> [1] -0.8001894 -4.4808090 -0.2278133 -2.7724563 -1.3445466 -3.0660231 + +# add weights on log scale and Pareto smooth them +x <- weight_draws(x, weights = log_wts, log = TRUE, pareto_smooth = TRUE) +#> Pareto k-hat = 0.08. diff --git a/docs/reference/z_scale.html b/docs/reference/z_scale.html index e2f83d8e..bbb6b5e9 100644 --- a/docs/reference/z_scale.html +++ b/docs/reference/z_scale.html @@ -20,7 +20,7 @@ posterior - 1.5.0 + 1.6.0 diff --git a/docs/sitemap.xml b/docs/sitemap.xml index 6546f2e1..7ff5a983 100644 --- a/docs/sitemap.xml +++ b/docs/sitemap.xml @@ -3,6 +3,9 @@ https://mc-stan.org/posterior/404.html + + https://mc-stan.org/posterior/CONTRIBUTING.html + https://mc-stan.org/posterior/LICENSE-text.html @@ -12,6 +15,9 @@ https://mc-stan.org/posterior/articles/index.html + + https://mc-stan.org/posterior/articles/pareto_diagnostics.html + https://mc-stan.org/posterior/articles/posterior.html @@ -120,6 +126,9 @@ https://mc-stan.org/posterior/reference/extract_variable.html + + https://mc-stan.org/posterior/reference/extract_variable_array.html + https://mc-stan.org/posterior/reference/extract_variable_matrix.html @@ -195,6 +204,18 @@ https://mc-stan.org/posterior/reference/print.rvar.html + + https://mc-stan.org/posterior/reference/ps_convergence_rate.html + + + https://mc-stan.org/posterior/reference/ps_khat_threshold.html + + + https://mc-stan.org/posterior/reference/ps_min_ss.html + + + https://mc-stan.org/posterior/reference/ps_tail_length.html + https://mc-stan.org/posterior/reference/quantile2.html @@ -300,6 +321,12 @@ https://mc-stan.org/posterior/reference/u_scale.html + + https://mc-stan.org/posterior/reference/variables-set.html + + + https://mc-stan.org/posterior/reference/variables.html + https://mc-stan.org/posterior/reference/vctrs-compat.html