From df28355f364215472b9f4ce55f99cb7404c1e85e Mon Sep 17 00:00:00 2001
From: n-kall <n-kall@github.com>
Date: Wed, 11 Oct 2023 15:38:30 +0300
Subject: [PATCH] add nested rhat documentation

---
 man/rhat_nested.Rd | 72 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)
 create mode 100644 man/rhat_nested.Rd

diff --git a/man/rhat_nested.Rd b/man/rhat_nested.Rd
new file mode 100644
index 0000000..875f19f
--- /dev/null
+++ b/man/rhat_nested.Rd
@@ -0,0 +1,72 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/nested_rhat.R
+\name{rhat_nested}
+\alias{rhat_nested}
+\alias{rhat_nested.default}
+\title{Nested Rhat convergence diagnostic}
+\usage{
+rhat_nested(x, superchain_ids, ...)
+
+\method{rhat_nested}{default}(x, superchain_ids, ...)
+}
+\arguments{
+\item{x}{(multiple options) One of:
+\itemize{
+\item A matrix of draws for a single variable (iterations x chains). See
+\code{\link[=extract_variable_matrix]{extract_variable_matrix()}}.
+\item An \code{\link{rvar}}.
+}}
+
+\item{superchain_ids}{(numeric) Vector of length nchains specifying
+which superchain each chain belongs to}
+
+\item{...}{Arguments passed to individual methods (if applicable).}
+}
+\value{
+If the input is an array, returns a single numeric value. If any of the draws
+is non-finite, that is, \code{NA}, \code{NaN}, \code{Inf}, or \code{-Inf}, the returned output
+will be (numeric) \code{NA}. Also, if all draws within any of the chains of a
+variable are the same (constant), the returned output will be (numeric) \code{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 \code{\link{rvar}}, returns an array of the same dimensions as the
+\code{\link{rvar}}, where each element is equal to the value that would be returned by
+passing the draws array for that element of the \code{\link{rvar}} to this function.
+}
+\description{
+Compute the Nested Rhat convergence diagnostic for a single variable
+proposed in Margossian et al. (2023).
+}
+\examples{
+mu <- extract_variable_matrix(example_draws(), "mu")
+rhat_nested(mu, superchain_ids = c(1,1,2,2))
+
+d <- as_draws_rvars(example_draws("multi_normal"))
+rhat(d$Sigma, superchain_ids = c(1,1,2,2))
+
+}
+\references{
+Charles C. Margossian, Matthew D. Hoffman, Pavel Sountsov, Lionel
+Riou-Durand, Aki Vehtari and Andrew Gelman (2023). Nested R-hat:
+Assessing the convergence of Markov chain Monte Carlo when running
+many short chains.  arxiv:arXiv:2110.13017
+}
+\seealso{
+Other diagnostics: 
+\code{\link{ess_basic}()},
+\code{\link{ess_bulk}()},
+\code{\link{ess_quantile}()},
+\code{\link{ess_sd}()},
+\code{\link{ess_tail}()},
+\code{\link{mcse_mean}()},
+\code{\link{mcse_quantile}()},
+\code{\link{mcse_sd}()},
+\code{\link{rhat_basic}()},
+\code{\link{rhat}()},
+\code{\link{rstar}()}
+}
+\concept{diagnostics}