Main Effects — mainEff • BayesMassBal

Calculates the main effect of a variable, which is independent of process performance, on a function.

Usage

mainEff(
  BMBobj,
  fn,
  rangex,
  xj,
  N = 50,
  res = 100,
  hdi.params = c(1, 0.95),
  ...
)

Arguments

BMBobj: A BayesMassBal object originally obtained from the BMB function. See BMB.
fn: A character string naming a function with arguments of BMBobj$ybal and independent random variables X. See Details and examples for more on function requirements.
rangex: A numeric matrix. Each column of rangex contains the minimum and maximum value of uniformly distributed random values making up vector $x$.
xj: Integer indexing which element in $x$ is used for conditioning for $E_x\lbrack f(x,y)|x_j\rbrack$. If a vector is supplied the marginal main effect of each element is calculated sequentially. The integers supplied in xj are equivalent to the indices of the columns in rangex.
N: Integer specifying the length of the sequence used for xj. Larger N trades a higher resolution of the main effect of xj for longer computation time and larger RAM requirements.
res: Integer indicating the number of points to be used for each Monte-Carlo integration step. Larger res reduces Monte-Carlo variance as the expense of computation time.
hdi.params: Numeric vector of length two, used to calculate Highest Posterior Density Interval (HPDI) of the main effect xj using hdi. hdi.params[1] = 1 indicates hdi is used, and the mean and HPDI bounds are returned instead of the every sample from the distribution of $E_x\lbrack f(x,y)|x_j\rbrack$. The second element of hdi is passed to the credMass argument in the hdi function. The default, hdi.params = c(1,0.95), returns 95% HPDI bounds.
...: Extra arguments passed to the named fn

Value

A list of length(xj) list(s). Each list specifies output for the main effect of a xj

g: The grid used for a particular xj
fn.out: A matrix giving results on $E_x\lbrack f(x,y)|x_j\rbrack$. If hdi.params[1] = 1, the mean and Highest Posterior Density Interval (HPDI) bounds of $E_x\lbrack f(x,y)|x_j\rbrack$ are returned. Otherwise, samples of $E_x\lbrack f(x,y)|x_j\rbrack$ are returned. The index of each column of fn.out corresponds to the the value of g at the same index.
fn: Character string giving the name of the function used. Same value as argument fn.
xj: Integer indicating the index of $x$ corresponding to a grouped fn.out and g.

Details

The mainEff function returns a distribution of $E_x\lbrack f(x,y)|x_j\rbrack$, marginalized over the samples of BMBobj$ybal, giving the distribution of $E_x\lbrack f(x,y)|x_j\rbrack$ which incorporates uncertainty of a chemical or particulate process.

In the current implementation of mainEff in the BayesMassBal package, only uniformly distributed values of $x$ are supported.

The $f(x,y)$ is equivalent to the supplied function named in mainEff(fn). For the arguments of fn, ybal is structured in a similar manner as BMBobj$ybal. The only difference being individual columns of each matrix are used at a time, and are vectorized. Note the way ybal is subset in the example function fn_example. The supplied X is a matrix, with columns corresponding to each element in $x$. The output to fn must be a vector of length nrow(x). The first argument of fn must be X, the second argument must be BMBobj$ybal. Order of other arguments passed to fn through ... does not matter. Look at the example closely for details!

Examples


## Importing Data, generating BMB object
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,200,1), lml = FALSE, verb=0)

fn_example <- function(X,ybal){
    cu.frac <- 63.546/183.5
    feed.mass <- ybal$CuFeS2[1] + ybal$gangue[1]
    ## Concentrate mass per ton feed
    con.mass <- (ybal$CuFeS2[3] + ybal$gangue[3])/feed.mass
    ## Copper mass per ton feed
    cu.mass <- (ybal$CuFeS2[3]*cu.frac)/feed.mass
    gam <- c(-1,-1/feed.mass,cu.mass,-con.mass,-cu.mass,-con.mass)
    f <- X %*% gam
    return(f)
    }

rangex <- matrix(c(4.00 ,6.25,1125,1875,3880,9080,20,60,96,208,20.0,62.5),
                  ncol = 6, nrow = 2)

mE_example <- mainEff(BMB_example, fn = "fn_example",rangex =  rangex,xj = 3, N = 15, res = 4)