diff --git a/R/rvar-.R b/R/rvar-.R index da4398c0..10f09d4d 100755 --- a/R/rvar-.R +++ b/R/rvar-.R @@ -58,6 +58,62 @@ #' on the underlying array using the [draws_of()] function. To re-use existing #' random number generator functions to efficiently create `rvar`s, use [rvar_rng()]. #' +#' @section `rvar` Internals: +#' +#' The `rvar` datatype is not intended to be modified directly; rather, you should +#' only use exported functions from \pkg{posterior}, such as [rvar()], [draws_of()], +#' [log_weights()], and [weight_draws()] to create and manipulate `rvar`s. +#' For completeness, and to aid internal development, this section documents the +#' internal structure of the `rvar` datatype. While the public-facing API is +#' intended to be stable, **this internal structure is subject to change without +#' notice**. +#' +#' An `rvar` `x` consists of: +#' +#' - A zero-length `list()` with class `c("rvar", "vctrs_vctr")`. If `draws_of(x)` +#' is a [`factor`], the class will be `c("rvar_factor", "rvar", "vctrs_vctr")`, +#' and if `draws_of(x)` is an [`ordered`], the class will be +#' `c("rvar_ordered", "rvar_factor", "rvar", "vctrs_vctr")`. These classes are +#' set automatically if the underlying draws are modified. +#' +#' The list has these attributes: +#' +#' - `draws`: An [`array`] containing the draws, where the first dimension +#' indexes draws. **Always** get this attribute using [draws_of()] and set it +#' using `draws_of(x) <- value`. To simplify programming, `dim(draws_of(x))` +#' is guaranteed to always be greater than or equal to 2. Zero-length `rvar`s +#' have `dim(draws_of(x)) = c(1,0)`. The draws may be a [`numeric`], +#' [`integer`], [`logical`], [`factor`], or [`ordered`] array. +#' +#' The dimensions after the first are reported as the dimensions of `x`; i.e. +#' `dim(x) == dim(draws_of(x))[-1]` and `dimnames(x) = dimnames(draws_of(x))[-1]`. +#' Because `rvar`s *always* have dimensions (unlike base R datatypes, where +#' there is a distinction between a length-*n* vector with no dimensions and +#' a length-*n* array with only 1 dimension), `names(x) = dimnames(x)[[1]]`; +#' i.e., `names()` refers to the names along the first dimension only. +#' +#' - `nchains`: A scalar [`numeric`] giving the number of chains in this `rvar`. +#' **Always** get this attribute using [nchains()]. It cannot be set using the +#' public (exported) API, but can be modified through other functions (e.g. +#' [merge_chains()] or creating a new [rvar()]). In internal code, **always** +#' set it using `nchains_rvar(x) <- value`. +#' +#' - `log_weights`: A vector [`numeric`] with length `ndraws(x)` giving the +#' log weight on each draw of this `rvar`, or `NULL` if the `rvar` is not +#' weighted. **Always** get this attribute using [weights()] or [log_weights()], +#' and set this attributes using [weight_draws()]. In internal code, it may +#' also be modified directly using `log_weights_rvar(x) <- value`. +#' +#' - `cache`: An [`environment`] that may contain cached output of the \pkg{vctrs} +#' proxy functions on `x` to improve performance of code that makes multiple +#' calls to these functions. The cache is updated automatically and invalidated +#' when necessary so long as the `rvar` is only modified using the functions +#' described in this section (or other functions in the publicly-exported +#' `rvar` API). The environment may contain these variables: +#' +#' - `vec_proxy`: cached output of [vctrs::vec_proxy()]. +#' - `vec_proxy_equal`: cached output of [vctrs::vec_proxy_equal()]. +#' #' @seealso [as_rvar()] to convert objects to `rvar`s. See [rdo()], [rfun()], and #' [rvar_rng()] for higher-level interfaces for creating `rvar`s. #' diff --git a/man/rvar.Rd b/man/rvar.Rd index 2dc1861f..30a0c4d5 100755 --- a/man/rvar.Rd +++ b/man/rvar.Rd @@ -89,6 +89,64 @@ As \code{\link[=rfun]{rfun()}} and \code{\link[=rdo]{rdo()}} incur some performa on the underlying array using the \code{\link[=draws_of]{draws_of()}} function. To re-use existing random number generator functions to efficiently create \code{rvar}s, use \code{\link[=rvar_rng]{rvar_rng()}}. } +\section{\code{rvar} Internals}{ + + +The \code{rvar} datatype is not intended to be modified directly; rather, you should +only use exported functions from \pkg{posterior}, such as \code{\link[=rvar]{rvar()}}, \code{\link[=draws_of]{draws_of()}}, +\code{\link[=log_weights]{log_weights()}}, and \code{\link[=weight_draws]{weight_draws()}} to create and manipulate \code{rvar}s. +For completeness, and to aid internal development, this section documents the +internal structure of the \code{rvar} datatype. While the public-facing API is +intended to be stable, \strong{this internal structure is subject to change without +notice}. + +An \code{rvar} \code{x} consists of: +\itemize{ +\item A zero-length \code{list()} with class \code{c("rvar", "vctrs_vctr")}. If \code{draws_of(x)} +is a \code{\link{factor}}, the class will be \code{c("rvar_factor", "rvar", "vctrs_vctr")}, +and if \code{draws_of(x)} is an \code{\link{ordered}}, the class will be +\code{c("rvar_ordered", "rvar_factor", "rvar", "vctrs_vctr")}. These classes are +set automatically if the underlying draws are modified. + +The list has these attributes: +\itemize{ +\item \code{draws}: An \code{\link{array}} containing the draws, where the first dimension +indexes draws. \strong{Always} get this attribute using \code{\link[=draws_of]{draws_of()}} and set it +using \code{draws_of(x) <- value}. To simplify programming, \code{dim(draws_of(x))} +is guaranteed to always be greater than or equal to 2. Zero-length \code{rvar}s +have \code{dim(draws_of(x)) = c(1,0)}. The draws may be a \code{\link{numeric}}, +\code{\link{integer}}, \code{\link{logical}}, \code{\link{factor}}, or \code{\link{ordered}} array. + +The dimensions after the first are reported as the dimensions of \code{x}; i.e. +\code{dim(x) == dim(draws_of(x))[-1]} and \code{dimnames(x) = dimnames(draws_of(x))[-1]}. +Because \code{rvar}s \emph{always} have dimensions (unlike base R datatypes, where +there is a distinction between a length-\emph{n} vector with no dimensions and +a length-\emph{n} array with only 1 dimension), \code{names(x) = dimnames(x)[[1]]}; +i.e., \code{names()} refers to the names along the first dimension only. +\item \code{nchains}: A scalar \code{\link{numeric}} giving the number of chains in this \code{rvar}. +\strong{Always} get this attribute using \code{\link[=nchains]{nchains()}}. It cannot be set using the +public (exported) API, but can be modified through other functions (e.g. +\code{\link[=merge_chains]{merge_chains()}} or creating a new \code{\link[=rvar]{rvar()}}). In internal code, \strong{always} +set it using \code{nchains_rvar(x) <- value}. +\item \code{log_weights}: A vector \code{\link{numeric}} with length \code{ndraws(x)} giving the +log weight on each draw of this \code{rvar}, or \code{NULL} if the \code{rvar} is not +weighted. \strong{Always} get this attribute using \code{\link[=weights]{weights()}} or \code{\link[=log_weights]{log_weights()}}, +and set this attributes using \code{\link[=weight_draws]{weight_draws()}}. In internal code, it may +also be modified directly using \code{log_weights_rvar(x) <- value}. +\item \code{cache}: An \code{\link{environment}} that may contain cached output of the \pkg{vctrs} +proxy functions on \code{x} to improve performance of code that makes multiple +calls to these functions. The cache is updated automatically and invalidated +when necessary so long as the \code{rvar} is only modified using the functions +described in this section (or other functions in the publicly-exported +\code{rvar} API). The environment may contain these variables: +\itemize{ +\item \code{vec_proxy}: cached output of \code{\link[vctrs:vec_proxy]{vctrs::vec_proxy()}}. +\item \code{vec_proxy_equal}: cached output of \code{\link[vctrs:vec_proxy_equal]{vctrs::vec_proxy_equal()}}. +} +} +} +} + \examples{ set.seed(1234)