Forest Specification for Multi-Forest Models
forest.RdOne forest of a model of several forests. Such a model fits the mean as a
sum of forests, each multiplied by columns of the data:
y ~ forest(x1 + x2) + forest(x1 + x2, basis = dose) is
\(a_1 f_1(x) + a_2 \cdot \mathrm{dose} \cdot f_2(x)\),
where each \(f\) is a forest and each \(a\) a coefficient the
sampler draws. A forest is written as a term of a bart or
dbarts formula, as in that example, or as an element of the
forests list of dbarts or dbartsSpec:
forests = list(forest(), forest(basis = dose)). Either way
vars is the predictors the forest splits on and basis is what
it is multiplied by. Every setting is per forest and stated on the forest.
The constructor is not exported: it resolves by bare name inside the
arguments that take it, and elsewhere is written
dbartsForests$forest(...); see dbartsForests.
Usage
forest(
vars = NULL, basis = NULL, sd = NULL,
n.trees = NULL, base = NULL, power = NULL, amplitude = NULL,
interactions = NULL, blocks = NULL,
proposal.probs = NULL, n.perturb.cuts = NULL, treeShift = NULL)Arguments
- vars
The predictors this forest splits on. In short:
It is the one argument given without its name:
forest(x1 + x2). Every other argument is given by name.Left out, the forest splits on every predictor of the fit.
In a formula it is terms joined by
+, as on the right of any model formula:forest(x1 + x2),forest(log(x1) + factor(g)),forest(. - z).In a
forestslist the same terms select among the fit's predictors,forest(x1 + x3),forest(. - x2); names or positions do too,forest(c("x1", "x3")),forest(c(1, 3)).A one-sided formula is its right-hand side, the tilde accepted and never required:
forest(~ x1 + x2), or a formula held in a variable,f <- ~ x1 + x2and thenforest(f). A formula with a left-hand side is refused.A name of a predictor is that predictor. Anything else is read where
forest()is called, at that moment.
The rest of this item is the detail of each.
In a formula given to
bartordbartsit is written as the right-hand side of a model formula of the forest's own:forest(x1 + x2),forest(log(x1) + factor(g)),forest(. - z), where.is every column ofdatabut the response and-removes a term. The fit's predictors are the terms of all of its forests, each once, and a forest splits on the columns of its own terms; a term that gives several columns, such aspoly(x1, 2)or a factor underfactors = "indicators", is all of them. Predictors may also be named, asforest(c("x1", "x2")): a name of a column ofdatais the term that name written out is, and any other name is a column of the predictors as the fit builds them, one of a factor's indicator columns for instance. A position is not taken in a formula. Anoffset()and an intercept term (1,0or- 1) belong to the fit and are written beside the forests, not inside one. A removal written beside the forests takes its term from the forest with nobasisand from no forest that names predictors of its own: the forest with nobasishas the terms of the formula with itsforest()replaced by what is inside it and every forest with abasisleft out. Soy ~ forest(.) - x3 + forest(x3, basis = z)andy ~ . - x3 + forest(x3, basis = z)are one model, in which the second forest alone splits onx3; a removal that leaves the first forest no predictor is refused. Written with no first argument, that forest is every predictor the other forests name, less what is removed beside it. A removal of a term the forest with nobasisdoes not have is passed by, as R passes it by in a plain formula:y ~ x1 + x2 + forest(x3, basis = z) - x3is the model without the removal.updatecannot take a term out of aforest():update(f, . ~ . - x3)returnsfunchanged whenx3stands inside one.In a
forestslist it selects among the fit's predictors, in one of two ways. When a name in it is a predictor of the fit, it is read as terms in the same way:forest(x1 + x3),forest(. - x2),forest(. - log(x1)). There.is every column of the fit's predictors, and a term names a predictor as the fit holds it, by its term label when the fit has a formula and by its column name when it has a matrix, written as code or as a backticked name; a term that names no predictor is refused, a removed one too. Anything else is a value: it is evaluated once, whereforest()is called and at that moment, and gives the predictors' names or their positions among the fit's columns:forest(c("x1", "x3")),forest(c(1, 3)), or a variable holding either. A warning that evaluation raises is kept and raised when a fit uses the value. A name or a position given twice is refused, and so are a logical, a factor and a formula: the multiplier of a forest is itsbasis, by name. A column with no name is selected by position or by.only, and a name that two columns share is refused. A number is a position only as the whole argument: among terms, as inforest(. - 2), it is refused, and a column named2is written backticked. With a factor expanded to indicator columns, removing one of them, asforest(. - g.u), leaves the forest able to separate that level through the others; remove the factor,forest(. - g), to keep it out.A name of a predictor is that predictor, and anything else is read where
forest()is called, at that moment. A forest built in a loop, bylapply(names, forest, basis = z)or byMap()therefore keeps the selection each call was given, whatever its variables hold by the time the model is fitted, and a forest saved to a file carries its selection with it. A variable that does not exist yet whenforest()is called is not looked for later. One case needs care: a predictor hides a variable of yours with the same name, so inforest(x1)with a predictorx1and a variablex1that holds names, the predictor is meant. Where the two could meet, hand the value over:do.call(forest, list(vars = nms)).Any forest may be restricted, a single declared forest included: given the same residual scale estimate, that fit is the fit on the named columns alone, and its other columns report no splits. The estimate is taken from every column unless
sigeststates it, so the two fits agree draw for draw when it does. On a single forestsplit.probs = dart()besidevarslays its Dirichlet over the named columns, every other column reporting probability 0, andsplit.probskeeps its ratios among the named columns and must give one of them a positive probability (seedbartsPriors). On every forest of a hazard fit theperiodcolumn the fit appends is always allowed, named or not:varsrestricts the columns the caller supplied. The restriction holds for the sampler's life;$setModelrefuses a model that states another, or none.- basis
What the forest is multiplied by. In short:
A name of a column of
datais that column:basis = dose.A basis is one numeric column, or a factor, a character column or a logical column of two levels, with a coefficient for each level. A number is one column, whatever its values:
basis = zfor azof 0s and 1s is one coefficient, andbasis = factor(z)is the two levels.I(dose + age)is one column, their sum. Several columns,dose + age, and three or more levels are refused: give each column, or each level but the first, a forest of its own.Anything that is not a column of
datais read whereforest()is called, at that moment, with or without a tilde written in place:forest(basis = w),forest(basis = ~ w).A formula held in a variable,
b <- ~ wand thenforest(basis = b), is read the same way, whenforest()is called, and is left as you made it.cbind()is refused: write its one column alone, or give each column a forest of its own.
The rest of this item is the detail of each.
What it does. With a basis of columns \(B_1, \ldots, B_K\) the forest \(f\) enters the fit as \((\sum_k a_k B_k(x_i)) f(x_i)\), each column with a coefficient \(a_k\) of its own, called its amplitude: \(K = 1\) for a numeric column, and the two columns of a factor's levels, \(K = 2\). A forest with no basis is multiplied by a single coefficient. A model may have several forests with no basis, which then share one prior size (see Details), or none; a model whose only forest has a basis is refused.
Writing it. A basis is the right-hand side of a model formula, without the tilde, and means what it means in
lm:a name is a column:
basis = dose;+separates columns:dose + ageis two columns, which this version refuses (below);arithmetic is written inside
I():I(dose + age)is one column, the sum, andI(dose / 30)isdoserescaled;a function of columns is a term, as in
lm:log(dose),scale(age)andpoly(dose, 1);a factor, a character column or a logical column of two levels gives one column for each, none left out:
factor(z)for azof 0 and 1 is the two columns whose coefficients are \((b_0, b_1)\), in the order of the levels;dose:ageis one column, the product;there is no constant column unless
1asks for one, and1 + dose, a column of ones besidedose, is refused, while0 + doseanddose - 1aredose.
A basis is either one factor (or character or logical column) or numeric columns; the two are not mixed in one forest. The forest does not center or scale a basis, so a multiplier that should be standardized is written so:
basis = scale(age). A numeric column constant over the observations in the likelihood when the sampler is created is refused,sdstated or not: a forest multiplied by a constant is a forest with no basis, writtenforest(x2)or, for ansdper unit of the column, with the column's size times it:forest(x2, sd = 6)forsd = 2on a column of 3. A factor, a character or a logical column left with one level on those observations is refused likewise. A later$setForestBasisto such a column is taken.One size. In this version a basis is one numeric column, or a factor, a character or a logical vector of two levels, counted on the rows the fit keeps once a level they leave empty is dropped. Three or more levels are refused, with the form to write, a forest for each level but the first:
forest(x1, basis = arm == "b") + forest(x1, basis = arm == "c"). Several numeric columns are refused however they are written,dose + age,poly(dose, 2),splines::ns(dose, 3), a matrix, or a factor's indicator columns handed over as numbers, with the form to write, a forest for each column:forest(x1, basis = dose) + forest(x1, basis = age); indicator columns are handed over as the factor itself.1 + doseis refused for its constant column: writebasis = dose. Each is refused drawn or held, at every place a basis is given, and a basis handed over as a value is told the form in words.Which kind it is. The class of the basis decides whether the forest multiplies levels or numbers, the same way at every place a basis is given:
forest()written as code or with a value,$setForestBasisandpredict'sbases. A factor, ordered or not, a character vector and a logical vector are levels, with a coefficient for each: in the order of a factor's levels, in sorted order for a character vector,FALSEthenTRUEfor a logical vector. An integer or a double is numbers, whatever its values, and a numeric matrix is its columns. The values are never looked at to decide: a column of 0s and 1s is one column with one coefficient, and is two levels only when writtenfactor(z)or as a logical vector. A matrix of characters or of logicals, and a factor matrix, is refused, one of a single column included, since a vector is levels and a matrix is numbers: hand over its column as a vector,cm[, 1]. An array of one dimension is its vector. A data frame and any other class are refused too. Handed over as a value, the refusal names the class; written as code, a class a model frame does not take, a data frame or a list, is refused in R's own words.The kind is fixed when the forest is created. A forest created with no basis cannot be given one, and a forest of levels keeps the same levels, in the same order, for as long as the sampler lives, so that coefficient \(j\) multiplies level \(j\)'s rows after any replacement. See
$setForestBasisindbartsSamplerand thebasesargument ofpredictinbartBTfor what a replacement takes.A level that no row the fit keeps has gives no column and no message, written as code or handed over as a value:
factor(z, levels = 0:2)of azwith no 2, or a factor of three levels under asubsetthat leaves two of them, is the two columns of the levels that remain. The count is made after the rows are cut, and fewer than two levels left is refused. A row of weight zero is a row the fit keeps.A missing value is looked for on the rows the fit keeps, after
subsetand thena.action, aslmlooks for one in its variables. On a kept row it is refused. On a row the fit drops it is not looked at, so a basis fits the same way written as code or handed over as a value.NAis not a level: a factor made withaddNA()orexclude = NULLthat has a kept row atNAis refused, and the remedy is to give that level a name, as inlevels(f)[is.na(levels(f))] <- "none". With no kept row at it theNAlevel is dropped like any other level no row has.Some forms a model formula would take are refused, each by name and with what to write instead:
*between terms (writeI(dose * age)for the product, or givedose,ageandI(dose * age)a forest each for all three); a term multiplied or divided by a number (writeI(dose / 30));-between terms, other than- 1;^,/,%in%and|between terms;.; anoffset();cbind()(write its one column alone, or give each column a forest of its own); and a term that calls one ofnormal,fixed,student,cauchy,linear,gp,cgm,dart,chisq,chi,invchi,forestorvarianceForest, since a prior is not stated on a term of a basis.Names of the columns. They are named as
coef(lm(y ~ 0 + <basis>))names them:dose;factor(z)0,factor(z)1; and, for a basis of several columns, which is read and named before it is refused and whose refusal quotes the names,dose,age,poly(dose, 2)1,poly(dose, 2)2and(Intercept)for the column of ones. They are the column names ofdata@bases[[f]]on the sampler. A forest's label, where its place in aforestslist has no name, is the text of its basis,"scale(age)", orforest<i>for a forest with no basis or with one given as a value; seedbarts. Wherever a method or anextractorpredicttakes aforest, a string is a forest's label (failing an exact match, the label that is the same code, so"I(dose / 30)"findsI(dose/30)), a number is its position as base R reads a list element by number, andforest<i>names position i, though a per-forest margin of a fit is named by the forests' labels. A string is never a position:"2"is a forest labeled"2"or none. A string that is one forest's label and another position's name, or the same code as two labels, is refused. A refusal that names a forest names it by its label, as the fit's results do, at creation and at$setForestalike, and by position (forest 2) where it has no name and no basis text.Rows. A basis has a value for every row of
data, and is cut to the rows the fit keeps:dataandsubsetare each evaluated once, for the fit, and the basis is given the same rows in the same order, less those thena.actiondrops. So withdata = d[sample(nrow(d)), ]orsubset = sample(n, 100)the basis has the rows the fit has.scale(),poly()and anything else a term computes across rows,I(age - mean(age))among it, are computed on every row ofdata, as inlm, whateversubsetkeeps. A level of a factor that no kept row has gives no column. Refused are a missing value in a row the fit keeps, wherelmwould drop the row; a factor, a character column or a logical column with one level on the rows kept; and a numeric column that is zero on all of them.New rows.
predictbuilds the basis again from the new rows, aspredictdoes forlm. Taken from the fitted rows are the center, scale and knots ofscale(),poly(),ns()andbs(), and the levels of a factor. Everything else is computed again on the rows given:I(age - mean(age))uses the mean of the new rows, andfactor(dose > median(dose))their median; seeSafePrediction. Every column ofdatathe basis names must be among the new rows, a factor's columns keep the order of the fit's levels, and a level the fit did not have is refused. A basis given as a value cannot be built again: give it at the new rows throughpredict'sbasesargument.Where a name is found. It depends on who wrote the code.
In a call of
forest()that you write, as in aforestslist or for a forest built ahead of the fit, a name of a column ofdatais that column. Every other variable of yours that the code uses is copied whenforest()is called. This is so whether or not a tilde is written in place:forest(basis = ~ I(dose + age))isforest(basis = I(dose + age)). A forest built in a loop therefore keeps what each call was given,is one forest multiplied by
dose / 10and one bydose / 30, at the fit and atpredict, whateverkholds later, and a saved forest carries its numbers with it. A variable that does not exist whenforest()is called is not looked for later, and is refused. What R or an attached package supplies, a function such asscaleor a constant such aspi, is not copied: a basis that names a column ofdatalooks it up when the model is fitted. With no data frame, as with the matrix interface anddbartsSpec, there is no column to name and every variable is yours.One case needs care: a column of
datahides a variable of yours with the same name, whether that variable holds a column, a set of names or a one-sided formula. Where the two could meet, hand the value over:do.call(forest, list(basis = w))for a column you hold,list(basis = as.name(nm))for a column ofdataby its name,list(basis = f)for a one-sided formula, andlist(vars = nms)for predictors by name.A formula made elsewhere, held in a variable or handed over as above, is read in the same way and at the same moment, when
forest()is called: a name of a column ofdatais that column, and every other variable the formula uses is copied, as it is then, from where the formula was made. What counts is whenforest()is called, not when the formula was made. Infs <- list(forest()) for (k in c(10, 30)) { f <- ~ I(dose / k) fs[[length(fs) + 1]] <- forest(x1, basis = f) }each forest has its own
k, becauseforest()is called inside the loop. Formulas made in a loop and given toforest()only after it all see the lastk: a formula holds its environment and no value, as everywhere in R. A variable changed afterforest()is called changes neither the fit nor a prediction. The formula itself is not touched: it is the formula you made, in its environment, and nothing is assigned there.A
forest()term inside the formula ofbartordbartsis part of that formula and is read with it, as R reads a formula, with a tilde or without: indataand then where the formula was written, when the model is fitted and again bypredict. Change a number such a term uses between the fit and the prediction and the prediction changes, with no message.An argument that
lapply(),Map()or another function of base R writes for you, as inlapply(columns, forest, vars = "x1"), is a value handed over, whatever the data's columns are called. A name or a call that such a function is handed and passes on, as inMap(forest, nms, MoreArgs = list(basis = quote(dose))), is code, as it is throughdo.call().Code or a single string passed on to
forest()through the...of a function of your own is read where that function's caller wrote it: withmyForest <- function(...) forest(n.trees = 50, ...),myForest(basis = "w")written in a function reads that function'sw, asmyForest(basis = w)does. A function that takes the basis as an argument of its own and callsforest(basis = name)hands over what the argument holds, read where it callsforest(), as is a string passed on through the...of a call that has returned.A value. What is handed over as an object, through
do.call()or in a call built by a program, is used as it is: a numeric vector or matrix is its columns, and a factor, a character vector or a logical vector is its levels, as written as code. Its column keeps the name it has. Its forest's label isforest<i>. It has one row for every row ofdataand is cut to the rows the fit keeps; a value already cut to those rows is refused by name. A level that no row the fit keeps has gives no column, whetherdata,subsetor thena.actionis what empties it. Beside a data object it has one row for each row the object was handed, before itssubsetandna.action. A value that the rows kept leave with one level, or one numeric column that is zero on all of them, is refused as the same basis written as code is. A single number is refused. A single string, written in place or held in a variable, names a column:basis = "dose"andnm <- "dose"; forest(basis = nm)arebasis = dose, at every place a basis is given and inpredict'sbases, which reads it fromnewdata; a character vector of one value per row stays a basis of its levels.Where a name is read. A name is read from the data first and then where
forest()was called, at every place a basis is given: a column of the data frame or list a formula fit is given; a column of the matrix the matrix interface is given; beside adbartsDataobject, a column of the frame it keeps, or, where it keeps none (a sampler's data,keep.data = FALSE), a column it holds, its predictors and response, and a basis a sampler's data hold, named by the text it was written as:forest(basis = factor(z))beside the data of a sampler created with that basis reads the held columns, whileforest(basis = z)there is refused, naming the written form. A name of the data such an object was built from that it does not hold is refused, naming the data object built with its frame. Beside a data object built from a formula with no data, a name is read whereforest()was called, as beside that formula. Beside any data, a sampler's data included, aforestslist states the forests in full: a forest declaring no basis has none, and no list gives one forest. A forest that keeps a held basis keeps the scale recorded for it when the sampler was first created, wherever it stands in the list (seesd); a basis given as a new value takes its scale from that value. After creation a basis is replaced by$setForestBasis, whose formula is read at once, where it was made; seedbartsSampler.A hazard fit. Under
family = "hazard"a basis has one value per subject, cut bysubsetand thena.actionand repeated over the subject's periods, as weights and offsets are; a vector of one value per person-period row is refused, naming the number of subjects.A lone forest carrying a
basisis refused, the coefficients being what distinguish a forest from another. For varying coefficients declare an intercept forest plus one basis forest per covariate,forests = list(forest(), forest(basis = z1), forest(basis = z2)), or use one forest withlinear()leaves.- n.trees, base, power
This forest's tree count and tree-structure prior. Each one stated here governs this forest, and each one left out takes the default of the forest's kind, whatever the forest's place. A forest with a
basishas 50 trees atbase = 0.25,power = 3- shallower and fewer than a prognostic forest's, the modulating surface normally being the smoother of the two. The forest with nobasishas the fitting function's: then.treesofdbartsorbart, and itspowerandbase. The fitting function and the forest with nobasisstate one setting between them:bartrefuses its ownn.trees,powerorbasebeside one stated here, the default's own value included, the two being the same setting, and a count written on a control beside one stated here is refused, since a control holds run settings only. Where every forest has abasisthe fitting function's tree count and tree prior have no forest to belong to, and one that is stated is refused, the default's own value included: state it on a forest. The count at the fitting function's level is the model's and not the control's: a sampler'scontrol@n.treesis a copy of it, the count of the forest with nobasis, or of the first forest where every forest has abasis. Itsmodel@tree.priorholds the first forest's.- sd
The size of what this forest contributes, in the response's units: the units of \(y\) for a continuous response, and of the latent index under
"probit"and"logistic", where the link's own error has standard deviation 1 and \(\pi/\sqrt{3}\). One number; a name on it is ignored. What it is the size of depends on what multiplies the forest. It is a number, not a prior: a function of your own namednormal,fixed,studentorinvchithat you have defined is called there, as insd = normal(0.5), and where you have defined none the call is refused, those names meaning dbarts's priors only inamplitude(and inleaf.priorat the fitting function). The same holds for the other arguments that take a number.No basis. The forest enters as \(a\,f(x)\), and
sdis the size of \(a\,f(x)\).A factor (a factor, a character vector or a logical vector, of two levels). The forest enters with one coefficient for each level, and
sdis the size of the difference between the two: the treatment effect where the levels are control and treated.A number \(w\). A column that is an ordinary covariate should be centered:
basis = scale(w), orbasis = I(w - c)for a reference value \(c\). The other forests describe the response where \(w\) is 0, and a column that never comes near 0, an age or a year, makes them an extrapolation and the fit poor, with nothing in the chain to show it. A dose or an exposure, where 0 means none, is left as it is. The forest enters as \(w\,(a\,f(x))\), andsdis the size of \(a\,f(x)\), the change in the response for one unit of \(w\); the term at an observation has size \(|w|\)sd. The column is used as given: it is never centered and never divided, so a statedsdis per unit of \(w\), and the samesdwith \(w\) in grams and in milligrams states two priors a thousand times apart.Where the coefficient is held, by
amplitude = fixed()or on a forest with no basis that states no prior, it is 1, what it multiplies is the basis, and "size" is the prior standard deviation, exactly. Where it is drawn it is a multiplier whose prior median size is 1 (on a factor, the difference between two levels' coefficients, a level's own being 0.71): the forest's size is the coefficient timessd, uncertain, and a coefficient of size 1 means the size stated.Not stated,
sdfor a forest with no basis is the size the fitting function's leaf prior gives the one forest of a fit, beside whatever other forests the model has: by default a quarter of the response's range under a continuous response and, under"probit"and"logistic", the sizekgives,kbeing drawn underchi(1.5, 2). It is \(\mathrm{sd}(y)\), or one unit of the link's error under"probit"and"logistic", for a factor; and for a number that same size for one standard deviation of the column, \(\mathrm{sd}(y) / \mathrm{sd}(w)\) per unit, held or drawn. None of these depends on how many forests the model has, save that two or more forests with no basis share the leaf prior's total (see ‘Details’). A default fit is then the same fit whatever units \(w\) is in. \(\mathrm{sd}(y)\) and \(\mathrm{sd}(w)\) are taken once, over the observations in the likelihood when the sampler is created (thosesubsetand the missing-value handling keep, with a positive weight, and not masked out), and kept: replacing the column, the weights or the mask later does not move the prior, unless the column is replaced with$setForestBasis(updateBasisScale = TRUE), and a copy, a saved and reloaded sampler and a sampler made again from its own control, model and data keep it. Where those observations hold fewer than two distinct values of the response, both are taken over every observation, under one warning (two by the route ofdbartsSpecandnew(), see itsactive)."probit"and"logistic"read no \(\mathrm{sd}(y)\), and where fewer than two observations are in, \(\mathrm{sd}(w)\) is taken over every one, under one warning; two or more that hold one value of \(w\) are refused. \(\mathrm{sd}(y)\) is of the response net of its offset; on a gaussian response that does not vary over those observations it is a quarter of the window of width one the response is then scaled by. \(\mathrm{sd}(w)\) is kept with the data, in itsbasis.scaleslot (seedbartsData), and$getLeafPrior(f)$basis.scalereports it. A caller who replaces a column during burn-in and wants the default of the new one replaces it with$setForestBasis(f, w.new, updateBasisScale = TRUE), which takes \(\mathrm{sd}(w)\) again over the observations in the likelihood then (seedbartsSampler). At creation a column constant over those observations is refused. A later swap to one is taken and, withupdateBasisScale = TRUE, keeps the scale it had.A treatment belongs in a factor or a logical vector, where
sdis the treatment effect. Written as a 0/1 number it is scaled as any number: \(\mathrm{sd}(z)\) is 0.5, 0.4 and 0.22 at 50, 20 and 5 percent treated, so the default effect is 2, 2.5 and 4.6 times the onefactor(z)gets;sd = sd(y)on the number states the factor's. The same holds for a coding written as a number and held,basis = z - 0.5withamplitude = fixed().A held coefficient cannot adapt to an
sdthat is too small. At the default it is sized for a slope of about one \(\mathrm{sd}(y)\) per \(\mathrm{sd}(w)\); where the effect may be larger, under"probit"and"logistic"above all, statesdor let the coefficient be drawn.A default is not a stated number:
$getLeafPrior(f)$sdreports the number of the response's units it comes to, a numeric forest's named by its column, and$getLeafPrior(f)$sd.statedisFALSE. A stated number is kept as written and divided by the unit once, at each creation. A control or aforestslist taken to other data states the same numbers in that data's units, and the sampler made from it derives its own. It is one number, positive and finite. A vector of any other length and anything that is not a number are refused. The one forest of a model of one forest takes it as the fitting function'sleaf.prior = normal(sd = ), in the same units, and stating the size at both places is refused.A live sampler restates it through
$setForest(forest, sd = ), as it doespower,baseand the move settings; it states it from then on, unless it is the number in force, which changes nothing, and leaves the recorded \(\mathrm{sd}(w)\).$getLeafPrior(f)$leaf.priorreturns the statement,forest(sd = )where one was stated andforest()where none was, andforest()written back leaves its forest as it is (seedbartsSampler). A forest's kind is fixed at creation:$setForestBasisrefuses to give a basis to a forest created without one, and moves no forest's prior.printof a fit andshowof a sampler give a short block of one line for each forest of a model of several: its label, what it multiplies, for a numeric column the mean and sd it has over the observations in the likelihood as they stand, and the sd the forest resolved to. For a numeric column that is its sd per sd of the column as it now stands, named by the forest's label, the size of the forest's term over one sd of the column in the response's units: for a default it is \(\mathrm{sd}(y)\) (the link's error sd under"probit"and"logistic") wherever the column, and the observations it is read over, are those the default was taken from, and for a statedsdit is thatsdtimes the column's sd. Where a swap left the column constant it is thesdper unit. For a factor it is the sd between the two levels. The sd per unit of a numeric column, which is whatforest(sd = )states, is in the full block and in the reader. The last line of the short block says where each forest's prior is to be had in full:summary()of a fit, which prints the full block, or$getLeafPrior()of a sampler, which returns it. Thesummaryof a fit and the creation of a sampler withverbose = TRUEgive the full block. Its header gives the unit the sds are in: \(\mathrm{sd}(y)\), as taken above, or the link's error sd. A numeric line gives the sd per unit and per sd of the column and adds the column's range; every line adds whether the sd was stated or is the default, and whether the coefficient is held. A default whose column has another sd over the observations now in the likelihood than the one it was taken from (the column replaced, the weights or the active rows changed, or, under"gaussian", every observation read because those in the likelihood held fewer than two values of the response) says so. A fit made withkeepFits = FALSEkeeps its labels, tree counts and unit, and in place of each basis the few numbers the block reads (a numeric column's mean, sd, range and whether it is constant over the rows in the likelihood, a factor's levels), so it gives the same block. Two things to look for. The mean of a numeric column, in either block, and its range, in the full one: a mean far from 0 is a column that never comes near 0, an age or a year, and should be centered, unless 0 means none, as for a dose; and one wild value shows in the range, and moves the mean and sd. And the figure per sd of the column, in either block, the size of the forest's term over one sd of the column (sdtimes the column's sd): for a default it is \(\mathrm{sd}(y)\) on every numeric line whose column, and the observations it is read over, are those the default was taken from, so a line that differs has had its column or its observations changed, and for a statedsdit is where a number in the wrong units shows. Nothing in the fit warns of either.- interactions, blocks
Optional
interactionsandblocksconstraints on this forest. The arguments of the same names ondbartsare those of the forest with nobasis, wherever it stands, so one stated there and on that forest is refused as one constraint given twice. A forest with abasisstates its own here, and where every forest has one those arguments of the fitting function are refused. Holding the two forests to different structures is the calibrated-additivity idiom - an additive or low-order modulating forest beside a free prognostic one. Ablockspartition covers the columns the forest may split on, i.e. thevarssubset when one is given, and the forest's own tree count.- amplitude
The prior on this forest's coefficient: the one a forest with no
basiscarries, or one for each level of itsbasis. Left out, it is drawn each sweep under a normal prior on a forest with abasis, and a forest with none is held at 1, its size thesdit states or its leaf prior's.normal()draws it under a normal prior, on a forest with no basis too, and takes nokorsdof its own.student(df)draws it under a Student-t prior withdfdegrees of freedom, finite and at least 1;student()isstudent(1), the half-Cauchy. On every kind a drawn coefficient's prior median size is 1, undernormal()andstudent(df), so only the tails move (on a factor it is the difference between two levels' coefficients that has median size 1, a level's own having 0.71): a coefficient ten times its median size has prior probability 0.06 understudent(1), 0.005 understudent(3)and about \(10^{-11}\) under the normal. That tail lets the coefficient follow a multiplier whose scale is far from what thesdstates, at the cost of slower mixing along the ridge the coefficient shares with the forest's leaves. At onesd, a drawn normal's contribution has about 1.48 times the standard deviation of afixed()forest's, since the coefficient and the trees are both random, and thinner tails thanstudent(df)'s. With no basissdis the size of the trees or, where none is stated, the size the fitting function's leaf prior gives, its prior median wherekhas achi()prior or thesdaninvchi()prior, and refused where that prior orkis flat and gives no size. Bayesian causal forests' prognostic prior is writtenamplitude = student(1), sd = 2 * sd(y), withsd = 1under"probit"andsd = pi / sqrt(3)under"logistic". The draw is exact: understudent(df)a normal coefficient given a variance drawn from its inverse-gamma conditional, undernormal()a normal coefficient alone. A forest on a factor, a character or a logical vector has two coefficients, and understudent(df)they share one scale, one variance drawn for the pair, so that their difference is itself a Student-t with the median size of the normal's.fixed()holds it at 1 until$setForest(f, amplitude = )changes it; a held coefficient is 1, and what it multiplies is the basis, so a forest with nobasisenters at 1, a forest on a numeric column at the column as given, and a forest on a factor, a character or a logical vector of two levels at 0 for the first level and 1 for the second. The forest is then held out of the first level and enters at full size for the second, so it is the second level's difference from the first. Another coding is another basis, and another size issd, which a held coefficient makes exact: the forest's contribution then has prior standard deviationsd. A held forest with no basis that states nosdtakes the leaf priorbartgives the one forest of an ordinary fit, sofixed()restates what such a forest has with no prior stated. A numeric column held enters as given, its forest at full size wherever the column is 1:basis = z - 0.5held is the forest times -0.5 and 0.5. A held coefficient cannot adapt to ansdthat is too small; where the effect may be larger, statesdor let the coefficient be drawn.fixedalone is taken asfixed(),normalalone asnormal()andstudentalone asstudent(); no other value is, a response family among them. Outside the argument that takes them the constructors aredbartsPriors$fixed(),dbartsPriors$normal()anddbartsPriors$student(). The prior is stated for a forest of a model of several, at creation; a model of one forest has no coefficient to give a prior, so therefixed()restates the default andnormal()andstudent()are refused, its size being drawn through the fitting function's leaf prior, asleaf.prior = normal(k = chi(1.5, 2))ornormal(sd = invchi(1.5, s)).$getLeafPrior(f)$amplitudereads it back, and a live sampler changes it through$setForest(f, amplitude = ), between held and drawn and betweennormal()andstudent(df)(seedbartsSampler).- proposal.probs, n.perturb.cuts, treeShift
This forest's tree moves - its proposal mixture, perturb window and level-shifting step - as
dbartsControldescribes each. Each one stated here governs this forest and each one left out takes the control's:$setControlchanges a forest's setting only where the forest states none, and one stated here is changed by$setForest(forest, proposal.probs = )and its siblings, not by$setControl, which refuses a mixture or window no forest would take. A statedproposal.probsis a whole mixture, filled against the package defaults asdbartsControl()'s is and not edits to the control's, so an omittedbirthis 0.5. A forest frozen by its own mixture is still grown byn.grow.sweepsand replaced bywarm.start, as under the control's, andtreeShiftacts on the constant leaves of two or more trees, as the control's does.n =andp =each abbreviate more than one argument, so writen.treesandpowerin full.
Details
With two forests, the second carrying a two-level factor basis, this is the
shape of the Bayesian causal forest
\(y = a\,\mu(x) + b_z\,\tau(x) + \epsilon\): a prognostic forest \(\mu\) over every predictor, a modulating
forest \(\tau\) over the columns vars allows, and the
amplitudes \((a, b_0, b_1)\) joining them, read back with
$getForestAmplitudes; \(a\) is 1 unless the prognostic forest
states amplitude = student(1), as Bayesian causal forests' prior does, or
normal(). Gaussian, "probit" and "logistic"
responses; under a latent family the combination is the index rather than
the mean, on the link's own fixed scale, and "aft", "ordinal"
and "nbinom" are refused at creation naming what each is missing.
What the defaults put on the combined location, since under a latent family
that location IS the index and no drawn \(\sigma\) stands between it
and the fitted probabilities. At two forests of the shipped shape - one
carrying no basis - a probit model's prior puts
\(P(p < 0.01 \mathrm{~or~} p > 0.99)\) at 0.29,
the forest with no basis alone having the shipped single-forest binary
default's own 0.238. A forest's default does not depend on how many forests
the model has, so each forest added widens the prior on the combined
location. When every forest carries
a factor the induced prior standard deviation of the index is
\(1.049\sqrt{K}\) latent units, 1.484 at
\(K = 2\), which is 0.989 of the classic \(k = 2\) binary
leaf-scale budget; a numeric column at its default contributes 1.484 for
each standard deviation of the column the row is from 0. When one forest
carries none, its prior is the fitting function's leaf prior, whose
k is drawn and has no variance to enter that budget with, and the
others contribute
\(1.049\sqrt{K - 1}\), 0.699 of the budget at
\(K = 2\). Where many forests share one index, state their
sd. Read the values in force off
$getLeafPrior(f)'s sd entry, in the response's units.
Forests with no basis. One beside any other forests takes the
fitting function's leaf prior as its one forest does, whole: its k,
a chi() prior on k or normal(sd = ), held at 1 and with
$getLeafPrior(f) and $getK(f) reading as one forest's, so the
forest is what bart would fit, the other forests added. It
leaves that prior by stating sd, held at it, or
amplitude = normal() or student(), drawn. A model may hold any number, as
y ~ forest(x1) + forest(x2) + forest(x3) or a forests list. Two or more
of them that state no sd and no amplitude = normal() or student() share
one prior total, the size the fitting function gives its one forest: its
k or leaf.prior, k = 2 by default under a continuous
response and k drawn under chi(1.5, 2) under
"probit" and "logistic". Each of the \(K\) forests
that share is held at 1 and takes an equal part, \(1/K\), of the
total's variance whatever its number of trees, so the sum has the one
forest's prior at every point and each forest 0.71 of its sd at two, 0.58
at three; a drawn k is one k for the group, and a named
leaf.prior = normal(sd = ) is the total's size. The model is the
one forest with its trees in blocks, a block for each
forest. The forests with no basis split the fitting function's
n.trees as blocks() splits a forest's trees, the first
ones taking one more: 38 and 37 of 75. A forest stating n.trees
keeps its own, outside the split, and its count says how finely it divides
its part, not how large the part is. The fitting function's
n.trees, power and base reach each such forest that
states none, and are refused only where every one states its own; its
interactions and blocks, a constraint on one forest, are
refused and stated on the forest they constrain. A forest that states
sd has that size and leaves the share, its coefficient held unless
it states amplitude = normal() or student().
amplitude = fixed() on a forest that shares is taken and changes
nothing; normal() and student() are refused there, since such a forest has no
coefficient of its own. $getLeafPrior(f) on it gives the fitting
function's leaf prior as leaf.prior, its part in force as
sd (NA where k is drawn) and prior.sd.of
"forest, shared", and $getK(f) the group's k.
The part of a group is set once, at creation. A forest of a group leaves
it by $setForest(forest, sd = ), at that size with its k
pinned at 1, and the forests still sharing keep their parts and sizes;
nothing puts it back but a new sampler. A total stated later, by
$setLeafPrior(leaf.prior) or $setModel, reaches the forests
still sharing, each at its creation part, so their sizes no longer add up
to it. One forest alone leaves the leaf prior by
$setForest(forest, sd = ) as by stating sd at creation, its
k then pinned at 1. Printed, a line after the forests' own gives
each forest's tree count and their total, and another which forests share,
or which one is left of a group.
The leaf scales of a forest with a basis and of one stating sd come
from the model's own calibration map rather than from the leaf prior, so a
k hyperprior, a non-default k and a named leaf-prior
sd are refused where every forest with no basis states its size, as
forest(x1 + x2, sd = 2), in the response's units as
normal(sd = ) is, and a linear or Gaussian-process leaf prior
wherever a second forest is declared. In a model of several forests this sd
states one forest's share of the combined location's prior, per unit of a
numeric basis, where normal(sd = ) states a single forest's whole
spread. Every value here is validated at fit time, and
anything today's engine cannot honor is refused there by name rather than
dropped.
In a bart or dbarts formula each
forest() term is one forest of the model, without a separate
forests = list:
y ~ forest(x1 + x2) + forest(x1 + x2, basis = z). A term stands at
the top of the formula's right-hand side, joined to the others by +;
a forest() crossed with another term, as z:forest(x1 + x2) or
z * forest(x1 + x2), is refused with the forest() to write in
its place. The first forest with no basis is the model's first, wherever it
is written; a forest's default tree
count and tree prior go by whether it has a basis and not by where
it is written. A forest with no basis may be left as plain
terms, y ~ x1 + x2 + forest(x1 + x2, basis = z), which is the same
model, but a formula's plain predictor terms beside a forest() with
no basis are refused, as two readings of one model.
Alone, y ~ forest(x1 + x2) is the single-forest fit
y ~ x1 + x2, in every family that takes a formula. The other forests
keep the order they are written in. forest() may also be written
there as dbartsForests$forest(). A term's predictors and its basis
are read as code; every other argument is evaluated where the formula was
written. The same basis written in a formula's term and in a forests
list is the same columns on the same rows, and so the same model.
See also
dbartsForests,
dbarts, bart, dbartsSpec,
interactions, blocks
bart's ‘Formula Terms’ section is the full term
grammar - the forests of a formula, a forest's predictors, and the refusal
list - of which the ‘Details’ paragraph above is the
constructor-side summary.
Examples
set.seed(0)
n <- 100L
x <- matrix(runif(n * 3), n, 3, dimnames = list(NULL, c("x1", "x2", "x3")))
z <- rbinom(n, 1L, 0.5)
y <- 2 * x[, 1] + z * (1 + 2 * x[, 3]) + rnorm(n, 0, 0.2)
sampler <- dbarts(x, y,
forests = list(forest(),
forest(x1 + x3, basis = factor(z),
n.trees = 25L, sd = 1.5)),
control = dbartsControl(n.chains = 1L,
n.samples = 20L, n.burn = 20L),
n.trees = 25L)
samples <- sampler$run(20L, 20L)
amplitudes <- sampler$getForestAmplitudes()
# the induced prior sd of the combined location, read off the sampler rather
# than recomputed from the call: forest 2 is the one carrying a basis
calibration <- sampler$getLeafPrior(2L)
basis <- sampler$data@bases[[2L]]
# its coefficients' prior variance is 1/2 over 0.674^2
indexSd <- sqrt((calibration$k.scale / 0.674)^2 * 0.5 * rowSums(basis^2))
# the same model written in a formula, the first forest written out; the
# columns of a basis are named as lm() would name them
d <- data.frame(y = y, x1 = x[, 1], x2 = x[, 2], x3 = x[, 3], z = z,
w = 50 + 10 * rnorm(n))
written <- dbarts(y ~ forest(x1 + x2 + x3) +
forest(x1 + x3, basis = factor(z), n.trees = 25L, sd = 1.5),
d, control = dbartsControl(n.chains = 1L), n.trees = 25L)
colnames(written$data@bases[[2L]])
#> [1] "factor(z)0" "factor(z)1"
# a standardized multiplier: predict centers and scales the new rows by the
# training rows' mean and sd of w
fit <- bart(y ~ forest(x1 + x3) +
forest(x1 + x3, basis = scale(w), n.trees = 10L),
d, n.trees = 10L, n.samples = 10L, n.burn = 10L,
n.chains = 1L, n.threads = 1L, keepTrees = TRUE)
#> estimating the starting sigma by a dense linear regression on 100 rows and 3 columns; see 'sigest'
#> family = "auto": continuous response detected, fitting family = "gaussian"; set 'family' to override
#>
#> Running BART with numeric y
#>
#> number of trees: 10
#> number of chains: 1, default number of threads 1
#> tree thinning rate: 1
#> Prior:
#> k prior fixed to 2.000000
#> degrees of freedom in sigma prior: 3.000000
#> quantile in sigma prior: 0.900000
#> scale in sigma prior: 0.008222
#> power and base for tree prior: 2.000000 0.950000
#> use quantiles for rule cut points: false
#> level fiber gibbs step: auto
#> proposal probabilities: birth/death 0.60, swap 0.00, change 0.40, perturb 0.00, rule_gibbs 0.00; birth 0.50; perturb window 1
#> data:
#> number of training observations: 100
#> number of test observations: 0
#> number of explanatory variables: 2
#> init sigma: 0.951555, curr sigma: 0.951555
#>
#> Cutoff rules c in x<=c vs x>c
#> Number of cutoffs: (var: number of possible c):
#> (1: 100) (2: 100)
#> forests, sd in the response's units (sd(y) 1.139):
#> 1 forest1: no basis; sd 1.158 (default)
#> 2 scale(w): numeric basis, mean 0, sd 1, range -2.666 to 1.923; sd 1.139 per unit, 1.139 per sd (default)
#> trees: 10, 10; 20 in all
#> Running mcmc loop:
#> total seconds in loop: 0.000468
#>
#> Tree sizes, last iteration:
#> [1] 2 2 2 2 2 2 5 2 3 2
#>
#> Variable Usage, last iteration (var:count):
#> (1: 9) (2: 5)
#> DONE BART
#>
predict(fit, d[1:3, ])
#> 1 2 3
#> [1,] 2.383965 1.197879 1.8524920
#> [2,] 2.119845 1.203424 2.3978240
#> [3,] 2.294449 1.564122 1.4466121
#> [4,] 2.468549 1.547928 1.5190212
#> [5,] 2.297864 1.596273 1.1539704
#> [6,] 2.801400 1.648708 1.3656214
#> [7,] 2.505019 1.549685 1.7550429
#> [8,] 2.433355 1.844821 0.9018371
#> [9,] 2.550464 1.821681 1.7565315
#> [10,] 2.323143 2.240946 1.6905198
# forests built in a loop: each keeps the number its own call was given
forest <- dbartsForests$forest
forests <- list(forest())
for (k in c(25, 100))
forests[[length(forests) + 1L]] <- forest(x1, basis = I(w / k))
looped <- dbarts(y ~ x1 + x3, d, forests = forests,
control = dbartsControl(n.chains = 1L), n.trees = 10L)
vapply(looped$data@bases[-1L], function(basis) basis[1L, 1L], 0) * c(25, 100)
#> [1] 58.93674 58.93674
# two columns are a forest each, with a coefficient each; I() holds arithmetic
perColumn <- dbarts(y ~ forest(x1 + x3) + forest(x1, basis = z) +
forest(x1, basis = I(w / 50)),
d, control = dbartsControl(n.chains = 1L), n.trees = 10L)
lapply(perColumn$data@bases[-1L], colnames)
#> [[1]]
#> [1] "z"
#>
#> [[2]]
#> [1] "I(w/50)"
#>