BMB: Bayesian Mass Balance

In BayesMassBal: Bayesian Data Reconciliation of Separation Processes

Bayesian Mass Balance

Description

Allows the user to specify the covariance structure for a Bayesian mass balance, simulates draws from reconciled masses and relevant covariance matrix, and approximates the log-marginal likelihood.

Usage

BMB(
  X,
  y,
  cov.structure = c("indep", "component", "location"),
  priors = "default",
  BTE = c(500, 20000, 1),
  lml = FALSE,
  ybal = TRUE,
  diagnostics = TRUE,
  verb = 1
)

Arguments

X	A matrix that maps constrained masses to observed masses. Can be built from the function constrainProcess, see documentation for details.
y	A list of matrices of observed mass flow rates. Each matrix is a separate sample component. The rows of each matrix index the sampling location, and the columns index the sample set number. Can be specified using the importObservations function.
cov.structure	Character string. "indep" allows for no correlation. "component" indicates correlation within an individual sample component. "location" indicates correlation within an individual sampling location. Not specifying cov.structure defaults to the "indep" structure.
priors	List or character string. When the default value priors = "default" is used, the BMB uses a set of default conjugate priors. When passing a list to the argument, the list must contain user specified hyperparameter values for each conjugate prior. To see the required list structure run BMB with BTE = c(1,2,1) and inspect the output. When priors = "Jeffreys" the Jeffreys priors for Σ and σ^2 with known mean given in \insertCitepriorlistBayesMassBal. When priors = "Jeffreys", the prior used for β is proportional to the indicator function I\lbrack β > 0 \rbrack. See Details for more information.
BTE	Numeric vector giving c(Burn-in, Total-iterations, and Every) for MCMC approximation of target distributions. The function BMB produces a total number of samples of (T - B)/E. E specifies that only one of every E draws are saved. E > 1 reduces autocorrelation between obtained samples at the expense of computation time.
lml	Logical indicating if the log-marginal likelihood should be approximated. Default is FALSE, which reduces computation time. Log-marginal likelihood is approximated using methods in \insertCitechibBayesMassBal.
ybal	Logical indicating if the mass balanced samples for each y should be returned. Default is TRUE. Setting ybal=FALSE results in a savings in RAM and computation time.
diagnostics	Logical or list indicating if diagnostic functions geweke.diag and effectiveSize \insertCitecodaBayesMassBal should computed for the obtained samples. The default of TRUE indicates diagnostics should be run with their default parameters. Alternatively, passing a list of the structure list(frac1 = 0.1, frac2 = 0.5) will run both diagnostics and allow geweke.diag to be run with parameters other than the default.
verb	Numeric indicating verbosity of progress printed to R-console. The default of 1 prints messages and a progress bar to the console during all iterative methods. verb = 0 indicates no messages are printed.

Details

See vignette("Two_Node_Process", package = "BayesMassBal") for further details on how to use function outputs.

When the priors argument is left unspecified, a set of default conjugate priors are used, which are chosen to allow BMB() to work well in a general setting. In the current version of the BayesMassBal package, only the conjugate priors stated below can be used, but hyperparameter values can be specified by the user using the priors argument.

The prior distribution on beta is a normal distribution truncated at 0. The mean of this distribution before truncation is the ordinary least squares (OLS) estimate of β. OLS estimates less than 0, are changed to 0. The prior variance, before truncation, of each element of β is set to:

10^{\mathrm{number of integer digits of an element of } β + 6}

Currently, there is only support for diagonal prior covariance matrices for β

When cov.structure = "indep" the error of all observations in a sample set are independent. An inverse gamma prior distribution, with α_0 = 0.000001 and β_0 = 0.000001, is placed on the variance of the mass flow rate for each sample component at each sample location.

When cov.structure = "component" or "location", the prior distribution on Σ_i is inverse Wishart (ν_0, ν_0 \times S_0). The degrees of freedom parameter, ν_0, is equal to the dimension of Σ_i. The scale matrix parameter is equal to a matrix, S_0, with the sample variance of the relevant observation on the diagonal, multiplied by ν_0.

The user is able to specify the prior hyperparameters of the mean and variance of beta, α_0 and β_0 for each σ^2, and the degrees of freedom and scale matrix for each Σ_i using the priors argument. It is advisable for the user to specify their own prior hyperparameters for p(σ^2) if the variance of any element is well under 1, or p(β) if the there is a wide range in the magnitude of observations.

When priors = "Jeffreys" Jeffreys priors are used for the prior distribution of the variance and covariance parameters. Priors used are p(σ^2) \propto \frac{1}{σ^2} and p(Σ) \propto |Σ|^{-(p+1)/2}, as listed in \insertCitepriorlistBayesMassBal. The Jeffreys prior for a β with infinite support is p(β) \propto 1. To preserve the prior information that β > 0, p(β)\propto I\lbrack β > 0 \rbrack is chosen. It is not possible to calculate log-marginal likelihood using the methods in \insertCitechibBayesMassBal with Jeffreys priors. Therefore, if priors = "Jeffreys" and lml = TRUE, the lml argument will be ignored and a warning will be printed.

lml is reported in base e. See here for some guidance on how to interpret Bayes Factors, but note log base 10 is used on Wikipedia.

Value

Returns a list of outputs

beta	List of matrices of samples from the distribution of reconciled data. Each matrix in the list is a separate sample component. Each column of a matrix in beta is a draw from the target distribution.
Sig	List of matrices containing draws from the distribution of each covariance matrix. If S.t is the t^{th} draw from the distribution of covariance matrix S and: cov.structure = "indep", the t^{th} column of a matrix in Sig is diag(S.t). cov.structure = "component" or "location", the t^{th} column of a matrix in Sig is equal to S.t[upper.tri(S.t, diag = TRUE)].
priors	List of prior hyperparameters used in generating conditional posterior distributions and approximating log-marginal likelihood. The structure of the input argument priors is required to be the same as the structure of this returned list slice. See Details.
cov.structure	Character string containing the covariance structure used.
y.cov	List of character matrices indicating details for the structure of each covariance matrix. Only returned when cov.structure = "location"
lml	Numeric of the log-marginal likelihood approximation. Returns NA when lml = FALSE
diagnostics	List containing results from diagnostic functions geweke.diag and effectiveSize
ybal	List of samples from the distribution of reconciled mass flow rates, in the same format as the function argument y. Produced with argument ybal = TRUE. Equivalent to lapply(BMB(...)$beta,function(X,x){x %*% X} , x = X) . Viewing this output is more intuitive than viewing samples of beta, at the expense of RAM and some computation time.
X	The function argument X is passed to the output so that it can be used with other BayesMassBal functions.
type	Character string used by plot.BayesMassBal. type = "BMB" for an object returned from the BMB function.

References

\insertRef

chibBayesMassBal \insertRefgibbsexplBayesMassBal \insertRefcodaBayesMassBal \insertRefpriorlistBayesMassBal

Examples

y <- importObservations(file = system.file("extdata", "twonode_example.csv",
                                    package = "BayesMassBal"),
                   header = TRUE, csv.params = list(sep = ";"))

C <- matrix(c(1,-1,0,-1,0,0,1,-1,0,-1), byrow = TRUE, ncol = 5, nrow = 2)
X <- constrainProcess(C = C)

BMB_example <- BMB(X = X, y = y, cov.structure = "indep",
                   BTE = c(10,300,1), lml = FALSE, verb=0)

summary(BMB_example)

BayesMassBal documentation built on June 18, 2022, 1:08 a.m.