Added a var.mcmc.list() pseudo-method and cleaned up documentation fo…

…r the others.

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: statnet.common
-Version: 4.10.0-439
-Date: 2023-12-18
+Version: 4.10.0-441
+Date: 2024-01-30
 Title: Common R Scripts and Utilities Used by the Statnet Project Software
 Authors@R: c(
     person(c("Pavel", "N."), "Krivitsky", role=c("aut","cre"), email="[email protected]", comment=c(ORCID="0000-0002-9101-3362", affiliation="University of New South Wales")),

NAMESPACE

@@ -138,6 +138,7 @@ export(ult)
 export(unused_dots_warning)
 export(unwhich)
 export(update_snctrl)
+export(var.mcmc.list)
 export(vector.namesmatch)
 export(xAxT)
 export(xTAx)

R/mcmc-utils.R

@@ -10,15 +10,15 @@
 #' @name mcmc-utilities
 #' @title Utility operations for [`mcmc.list`] objects
 #' 
-#' @description \code{colMeans.mcmc.list} is a "method" for (non-generic) [`colMeans`] applicable to [`mcmc.list`] objects.
+#' @description \code{colMeans.mcmc.list} is a "method" for (non-generic) [colMeans()] applicable to [`mcmc.list`] objects.
 #' 
 #' @param x a \code{\link{mcmc.list}} object.
 #' @param \dots additional arguments to \code{\link{colMeans}} or
 #'   \code{\link{sweep}}.
 #' @return \code{colMeans.mcmc} returns a vector with length equal to
 #'   the number of mcmc chains in \code{x} with the mean value for
 #'   each chain.
-#' @seealso [`colMeans`], [`mcmc.list`]
+#' @seealso [colMeans()], [`mcmc.list`]
 #' @examples
 #' data(line, package="coda")
 #' summary(line) # coda
@@ -29,15 +29,41 @@
 #' @export colMeans.mcmc.list
 colMeans.mcmc.list<-function(x,...) colMeans(as.matrix(x),...)
 
+#' @rdname mcmc-utilities
+#'
+#' @description \code{var.mcmc.list} is a "method" for (non-generic)
+#'   [var()] applicable to [`mcmc.list`] objects. Since MCMC chains
+#'   are assumed to all be sampling from the same underlying
+#'   distribution, pooled mean is used. This implementation should be
+#'   equivalent (within numerical error) to `var(as.matrix(x))` while
+#'   avoiding constructing the large matrix.
+#'
+#' @seealso [var()]
+#' @examples
+#' data(line, package="coda")
+#' var(as.matrix(line)) # coda
+#' var.mcmc.list(line) # "Method"
+#' \dontshow{
+#' stopifnot(isTRUE(all.equal(var.mcmc.list(line), var(as.matrix(line)))))
+#' }
+#' @export var.mcmc.list
+var.mcmc.list <- function(x, ...){
+  nchain <- length(x)
+  niter <- NROW(x[[1]])
+  SSW <- Reduce(`+`, lapply(x, cov)) * (niter-1)
+  SSB <- cov(t(sapply(x, colMeans))) * niter
+  (SSW+SSB) / (niter*nchain-1)
+}
+
 #' @rdname mcmc-utilities
 #'
 #' @description \code{sweep.mcmc.list} is a "method" for (non-generic)
-#'   [`sweep`] applicable to [`mcmc.list`] objects.
+#'   [sweep()] applicable to [`mcmc.list`] objects.
 #' 
-#' @param STATS,FUN,check.margin See help for [`sweep`].
+#' @param STATS,FUN,check.margin See help for [sweep()].
 #' @return \code{sweep.mcmc.list} returns an appropriately modified
 #'   version of \code{x}
-#' @seealso [`sweep`]
+#' @seealso [sweep()]
 #' @examples
 #' data(line, package="coda")
 #' colMeans.mcmc.list(line)-1:3
@@ -56,12 +82,12 @@ sweep.mcmc.list<-function(x, STATS, FUN="-", check.margin=TRUE, ...){
 #' @rdname mcmc-utilities
 #'
 #' @description \code{lapply.mcmc.list} is a "method" for (non-generic)
-#'   [`lapply`] applicable to [`mcmc.list`] objects.
+#'   [lapply()] applicable to [`mcmc.list`] objects.
 #' 
 #' @param X An [`mcmc.list`] object.
 #' @return `lapply.mcmc.list` returns an [`mcmc.list`] each of
 #'   whose chains had been passed through `FUN`.
-#' @seealso [`lapply`]
+#' @seealso [lapply()]
 #' @examples
 #' data(line, package="coda")
 #' colMeans.mcmc.list(line)[c(2,3,1)]