R 4.2.0 or newer is required (0.9-34 needed 3.1.0), as is a compiler supporting C++20.
bart is now the formula-first interface that 0.9-34
called bart2, with its argument names and defaults (75
trees, four chains, 500 draws after 500 burn-in). 0.9-34's
bart, with BayesTree's argument names and defaults
(200 trees, one chain, factors expanded to indicator columns,
incomplete rows dropped), is now bartBT; it
returns an ordinary "bart" fit. For this release a
bart call that uses a name only bartBT has
(x.train, ntree, ndpost, and so on) is
forwarded to bartBT with a warning. A call that uses no
such name, such as bart(x, y, x.test), runs under the new
bart's defaults and prints a one-time message; rename it
to bartBT to keep 0.9-34's defaults. A fourth or later
positional argument to bart is an error, since 0.9-34
read it as sigest.
bart defaults to combineChains = TRUE, where
bart2 defaulted to FALSE, so the draws of a
multi-chain fit come back with the chains merged. Pass
combineChains = FALSE for the previous shape. The
bart2 alias keeps the default FALSE.
pdbart and pd2bart fit through bart, with
its names and defaults (75 trees, four chains merged, so
fd has 2000 rows by default; a factor is one predictor).
Their data arguments are formula and data;
positional calls are unchanged. A BayesTree name
(ntree, keepevery, x.train, ...) is
translated with a warning until 1.1-0, and an argument neither
takes is an error where it was ignored. The 0.9-34 model is
pdbart(bartBT(x, y, keeptrees = TRUE)), its results still
subject to the changes below. In a formula fit xind
names variables of the data, where it named model-matrix
columns. Multinomial and ordinal fits are refused, pointing at
predict.
Every name and argument kept reachable for one release past its
removal or rename (a tombstone) warns once per session, names
its successor, and is removed in dbarts 1.1-0; the list is on
dbarts-deprecated. bart2 forwards to
bart. rbart_vi and its methods
(predict.rbart, extract.rbart,
fitted.rbart, residuals.rbart, plot.rbart,
print.rbart) are deprecated; see the next item. On
dbarts, tree.prior becomes power,
base and split.probs, as on bart;
tree.prior = cgm(power, base, split.probs), or a tree
prior saved by 0.9-34, is still accepted with a warning, once
a session, and its value used, and is refused from 1.1-0. On
bart, sigdf and sigquant become
family = gaussian(sigma = chisq(df, quant)); on
bart, dbarts and xbart,
resid.prior becomes family = gaussian(sigma = );
on bart and dbarts, proposal.probs becomes
control = dbartsControl(proposal.probs = ). On
dbartsControl, n.trees moves to dbarts,
dbartsSpec and forest, and n.cuts and
useQuantiles to dbarts and dbartsData.
rngSeed (bart, dbartsControl) is now
seed, sigma (dbarts, xbart) is now
sigest, node.prior (dbarts) is now
leaf.prior, and chi()'s degreesOfFreedom is
now df. On the sampler,
$sampleNodeParametersFromPrior is now
$sampleLeafParametersFromPrior, $startThreads and
$stopThreads do nothing, a thread count passed to
$run is ignored (use $setControl), and a logical
updateCutPoints given to $setPredictor is read as
"position" or "none". NULL
rather than NA now means “not given”; where
0.9-34's default was NA, an explicit NA is still
read as NULL with a warning.
An n.cuts with more values than there are predictor
columns is an error; 0.9-34 dropped the extra values silently.
A package that forwards arguments to dbarts by filtering them
against formals(dbartsControl) will now silently drop
rngSeed and fit unseeded; accept seed instead.
A call giving both rngSeed and seed to
bart, bart2 or dbartsControl is an error;
0.9-34's bart2 used seed.
rbart_vi still runs for this release, with the fixes
listed under BUG FIXES, but multilevel models belong to
stan4bart::stan4bart, which fits the same random
intercepts and slopes, and more, through an lmer-style formula.
Its prior on the group spread differs, so results move. A
binary rbart_vi fit now refuses weights other than 0 and
1, and takes 1.0-0's defaults for k and the tree moves.
Removed without replacement: dbartsControl's
rngKind and rngNormalKind (every chain now runs
its own generator), and the configure options
--enable-match-bayes-tree,
--enable-thread-safe-unload and --with-xint-size,
which stop the build naming the removal.
Sampler states saved by 0.9-34, including those inside saved
fits, cannot be restored, so such a fit cannot predict
on new rows or give its trees, and says so; refit it. A
sampler saved by 0.9-34 (or a fit's $fit) refuses every
method call, each saying to refit; print of such a fit shows its
call and says the same as a note; fitted, residuals, summary and
extract of the saved draws still work. A
dbartsData object saved by 0.9-34 keeps its old factor
coding and fits differently from one built fresh; rebuild it
with dbartsData.
A data object made by dbartsData() from a formula and a
data frame keeps the frame and the positions of the rows it
keeps; its x, y, weights and
offset slots, which held the model matrix and the
response in 0.9-34, no longer hold them:
model.frame(object) returns the model's variables,
factors as factors, and nobs(object) counts the rows with
a positive weight.
A forest given to dbarts() or dbartsSpec()
beside a data object finds its basis in the frame.
keep.data = FALSE keeps the matrix and the response in
the object instead, as before, and so does a build whose
formula, weights or offset draw random numbers.
Writing a sampler's data field
(sampler$data <- newData) is an error naming
$setData: in 0.9-34 the write changed only the R-side
copy, which the running sampler ignored and a copy then failed
on. Call sampler$setData(newData).
Weights. A probit fit refuses case weights: 0.9-34 fit a
weighted probit, which was incorrect. Weights that are all 1
are ignored, and weights of 0 and 1 mark which rows enter the
likelihood; count weights belong on
family = "logistic". On the x/y interface
a weights vector of the wrong length is an error rather
than recycled, and negative or non-finite weights are refused
everywhere.
Posterior predictive draws follow the case weights on gaussian
and Student-t fits, and on an aft fit given
predict(weights =), which takes no case weights at fit
time: a row's noise sd is sigma over the square root of its
weight. 0.9-34 applied the weights to a test sample and to
predict(weights =), and used sigma at every training
row. A row at weight 0 has NA draws, in extract,
fitted and predict alike, with no warning
(0.9-34 gave NA with the warning "NAs produced" for a
test-sample row and for predict(weights = 0), and drew
a training row at sigma): a weight of 0 holds a row out of the
fit and gives it no noise scale. To draw such a row as a new
observation, state its weight, as in
predict(fit, type = "ppd", weights = 1). A fit whose
weights were a column of its data (weights = w) reads that
column from the newdata given to predict, when it
holds the column and no weights are stated, with the
fit's meaning, as a test sample does: on a gaussian or Student-t
fit predict(fit, d) on the training frame d draws
as predict(fit, d, weights = d$w), and on every family a
row of weight 0 has NA draws.
On a probit fit a
row of weight 0, training or test, likewise has NA draws
and every other row draws one 0/1 observation, where 0.9-34 gave
NA at every row of a fit with any weight of 0 and drew a
test row as its weight times a 0/1 draw.
New predictors for a fit with a factor column come as a data
frame, coded by label: setPredictor(x) with no
column takes one (0.9-34 stopped on it), as do
setTestPredictor and predict. A numeric matrix
is taken only where every predictor column is numeric, and is
refused by name on a fit with a factor column; predict
had read the codes of such a matrix as levels.
setData reads its data the same way, a factor by label
against the sampler's levels and the columns by name: fewer
levels, another order and declared levels no row has are
taken, and a label the sampler never had is refused by name,
as is a column name that is not the sampler's, as
predict refuses one. setPredictor(x) refuses
such names too. A matrix with no column names is read by
position, as before. 0.9-34 refused another count of levels
with rows and read reordered, renamed or replaced levels, and
columns under other names, by position, so that the kept draws
no longer predicted what they did.
Split probabilities. split.probs with a negative or
non-finite entry, or with no positive entry, is refused, as
sample(prob = ) refuses such weights; 0.9-34 turned a
negative weight into a probability by dividing by a negative
sum.
A named vector of one value, such as
split.probs = c(x2 = 0.9), is refused for the columns it
leaves out, as any named vector is; 0.9-34 fit it with equal
probabilities and no message.
Predictors that cannot split. bart, bartBT,
xbart and rbart_vi refuse a fit in which every predictor holds one
value on the rows kept and no forest has a basis, naming the
columns; dbarts still creates such a sampler. 0.9-34's
bart fit a matrix call silently, as an intercept-only model.
Test data frames. A data frame given as test data
(test, predict's newdata,
$setTestPredictor) to a fit made from a matrix is read
by name,
as a formula fit reads one, and columns beyond the training
predictors are ignored; 0.9-34 refused the extra columns on
such a fit. A matrix keeps its exact width.
Offsets. An offset that is not numeric, a logical or a factor,
is refused when fitting and by predict; 0.9-34 coerced
it, a factor to its level codes. An offset that is all
NA is read as missing.
New data given to predict. Test column names that do not
cover the training columns are an error (0.9-34 warned and
matched by position). A factor level that training never saw is
an error (0.9-34 silently predicted it as another level); under
factors = "indicators" and in bartBT that includes
a level declared but with no training rows. There, a test factor
is now matched to the training levels by label, as in
lm, so one declaring only some of the levels predicts as
the full-level factor would, where 0.9-34 failed. A
missing value in a column that had none in training is an error
by default, naming the column (0.9-34 sent it down an arbitrary
branch); the new na.action argument of every
predict method chooses otherwise, na.pass returning
NA for such rows. 0.9-34 also dropped a data frame's
incomplete rows, returning fewer rows than given; see
na.keepPredictors.
A named vector given as newdata is one row matched by
name, as a named one-row matrix is; 0.9-34 read it by position,
whatever its names.
Argument checking is stricter. A fractional value for a count
(n.trees = 100.5, say) is an error rather than truncated.
predict, extract, fitted and
residuals warn about, or refuse, arguments they do not
use instead of ignoring them. On predict.bart,
type now comes before offset and weights,
and n.threads is last; pass them by name.
dbartsControl's proposal.probs must name every
entry from its moves; an unnamed vector or an unknown name is
an error listing them, where 0.9-34 dropped such entries and ran
the default mixture. New arguments make two shortened names
ambiguous, so they are errors: u = on bart
(0.9-34's bart2 read it as useQuantiles) and
n.th = on xbart (read as n.threads);
write the name in full.
The sampler's $setResponse gains updateScale as its
second argument, pushing updateState to third, so pass
updateState by name. It defaults to FALSE: the
response's scaling stays as set at creation when the response
is swapped, as a conditional update inside a larger sampler
needs. 0.9-34 re-derived it from each new continuous response;
updateScale = TRUE restores that. $setData given a
data object from dbartsData() keeps it too (see
USER-VISIBLE CHANGES).
$getSumsOfSquaredResiduals returns the sum of squares
itself rather than that sum divided by the response range.
names(fit) no longer lists yhat.test, or, on a
binary bart fit without an offset, binaryOffset,
when the fit has none; test with is.null rather than names.
A formula calling a function from no package, such as one
defined in the session, is refused, naming it; compute the
column in data instead. A fit stores its formula's terms
and offset expression without their environment, with
every name that is not a data column fixed at its value when
fitting, so a fit predicts from newdata alone, the same
after a reload, and carries no frame of the function it was made
in.
A fit made with keepCall = FALSE stores call =
NULL, as base R fits without a call do, so update
refuses it as it refuses such an lm fit; 0.9-34 stored
the placeholder call NULL().
The sampler's $setControl keeps the sampler's tree
count; 0.9-34 resized the sampler in place. A control that names
another count is refused, and one that carries another, as a
control taken from a fit does, is taken with a warning and the
sampler's count kept. Create a new sampler with the count wanted.
A control taken from a fit carries that fit's run settings and
nothing else, and can be given to any function that takes a
control, bart and xbart among them. It sets no
tree count, cut count or quantile rule for the next fit,
and one it carries that differs from what the call takes draws a
warning, on every call, saying it is not used. The same holds of
the control handed to new("dbartsSampler", ...).
[email protected] is an error on a control that no one
wrote a cut count to and on a sampler's control; the cut count is
the data object's. [email protected], @useQuantiles
and @binary read what the sampler runs.
A per-column n.cuts reads as split.probs reads, at
every function that takes it: by column or term name with
.default for the rest, or unnamed, one value or one per
column. In 0.9-34 it was read by position, names ignored, and
shorter vectors recycled, so c(x2 = 10) and c(25, 10)
on three columns, taken then, are now refused, and
c(x3 = 5, x1 = 25, x2 = 10) gives each column its own.
A sampler assembled by hand, new("dbartsSampler", control,
model, data), takes its tree count from the model and its
quantile rule from the data object where the control's are fresh
or copied from a fit, with a warning where a copied value differs;
0.9-34 read the control's. A count or rule written on the control
is used where the model or the data object states none and refused
where it states another.
The sampler's $setModel refuses a residual prior other
than the sampler's own on a binary response, which has no
residual scale; 0.9-34 stored it and held sigma at 1.
A split probability of zero in cgm(split.probs = )
excludes its column on every path, as a forest's vars
does. 0.9-34 split on such a column below a node where the
columns of positive probability were used up, so results of a
fit stating a zero change where that happens. A stored state
that splits on such a column is declined by $setState
unless forced, and $setModel refuses a zero on a column
the sampler's trees split on.
On a fit of one named predictor, a named newdata,
test or $setTestPredictor value whose column has
another name is an error, as it is with several predictors;
0.9-34 read it by position. An unnamed column is still taken.
$setPredictor, $setTestPredictor and
$setCutPoints refuse a logical column and a column
given twice; 0.9-34 read TRUE as column 1 and installed
the last of a repeated column's values.
$setCutPoints refuses an infinite cut point, which
0.9-34 took. To separate values at -Inf, use a cut at
-.Machine$double.xmax.
pdbart, pd2bart and plot of a
pdbart result refuse an xind that is not whole
column numbers in range or known names, is empty, names a
variable twice, or for pd2bart is not a pair; 0.9-34 read
-1 and 1.5 as other columns and pd2bart
dropped a third variable. plot also takes the result's
variable names.
A bart fit that keeps its trees stores its sampler's
state at the end of the fit, so it reloads whole after
saveRDS or save: 0.9-34's fit with
keeptrees = TRUE needed fit$fit$storeState()
before saving. A hazard fit at the defaults adds up to about
9 MB of file and 15 to 25 MB of memory, growing with draws and
trees.
A TRUE/FALSE argument takes a single logical or
number, read as as.logical reads it (0 is FALSE),
and refuses NA, a string or another length by name.
0.9-34 took such an argument unchecked, or failed on it with an
error that did not name it, in places such as bartBT's
keepcall and keeptrees, rbart_vi's
keepTestFits, a sampler's $copy(shallow) and
$getTrees(current), and makeind's all;
and drop = 1 to makeModelMatrixFromDataFrame
failed. A sampler method's
updateState also takes NULL, the control's
setting.
An observation of weight zero no longer takes part in the response's scale, which the leaf prior is stated against, so a fit with zero weights has the leaf prior of the fit on the remaining rows; 0.9-34 took the scale over every row. The observation is still in the design.
A probit or logistic fit whose response holds one class is fitted, with one warning saying so; 0.9-34 stopped on it with an unrelated message.
A residual prior with infinite degrees of freedom, as in
bart(sigdf = Inf), is refused, naming fixed(),
which holds \sigma at a value; 0.9-34 returned
NaN.
Results differ from 0.9-34, including seeded ones. The new
engine draws a different random stream, and the corrections
under BUG FIXES change the posterior itself. Every chain now
runs its own generator: seeded results do not depend on the
thread count, set.seed alone makes any run reproducible,
and sampling no longer advances R's random stream, so R-level
draws made after a fit also change.
The default tree-move mixture drops the swap move:
proposal.probs defaults to c(birth_death = 0.6,
swap = 0, change = 0.4, perturb = 0, rule_gibbs = 0, birth =
0.5) rather than c(birth_death = 0.5, swap = 0.1, change
= 0.4, birth = 0.5). On five simulated designs and on four
benchmark datasets and two designs after Tan, Ronen, Saarinen
and Yu (2024), with forests of 75 and 200 trees, dropping swap
changed the coverage of 95 percent intervals by less than 0.011
and RMSE by less than 9 percent in every setting, and on
average by less than about 0.001 and 0.6 percent. Averaged over
settings it cost nothing in R-hat or effective sample size
(within 3 percent for the latter); one setting lost 15 percent
of effective sample size. A single-tree fit
(n.trees = 1) should still set it positive.
bartBT keeps 0.9-34's mixture.
The default prior on k for a binary response, on
bart, dbarts and xbart, is the proper
chi(1.5, 2), where 0.9-34 used the improper
chi(1.25, Inf). It centers k near the usual fixed
value of 2 while still adapting to the data. chi()'s own
scale now defaults to 2 rather than Inf. Pass
k = chi(1.5, Inf) for the prior 0.9-34 actually sampled
(see the chi fix under BUG FIXES).
Unordered factor predictors are split on subsets of their
levels, and an ordered factor is one ordinal predictor split
between its levels, where 0.9-34 expanded both into indicator
columns. The design matrix, the varcount column names and
the draws change for any fit with a factor predictor. Pass
factors = "indicators" (bart, dbarts,
dbartsData, xbart) for the previous expansion;
bartBT expands as before.
A fit's or sampler's data@x, when it was made from a
formula or a data frame, is now a container that keeps each
factor as one column, not a numeric matrix. as.data.frame
gives the predictors as the model sees them, factors as factors
over their declared levels, with the model matrix's column
names; predict and setTestPredictor take it as new
data for a formula of plain variables, but not for one that
transforms or expands a variable (I(z^2),
factor(i), poly(z, 2), a matrix term).
as.matrix gives a numeric matrix with a factor as its
codes. Base functions that do not dispatch on the class, such
as cbind, do not see it as a matrix.
Rows with missing predictors are kept and their missingness
modeled, where 0.9-34 dropped them. The new na.action
of bart, dbarts and dbartsData defaults to
na.keepPredictors, which drops only rows missing
the response; na.action = na.omit restores the old rule.
xbart always keeps such rows, and bartBT drops
them as before. Hence fitted, residuals,
yhat.train.mean and predict give one value per
row passed in, rows with missing predictors included, where
0.9-34 gave fewer; a row dropped for a missing response is
NA in fitted, residuals and
yhat.train.mean, and yhat.train and
extract hold the kept rows only. Code that fills only the
complete rows by position must index every row.
A predictor column that is first given a missing value after
the sampler was created ($setPredictor,
$setData, updatePredictorPerObservationJointly)
has the side its existing split rules send missing values to
drawn at random, in the current trees and in the saved draws,
and keeps routing them whatever it holds afterwards; 0.9-34
sent them down an arbitrary branch. A state stored before that
first missing value and installed after it has those sides
drawn at the install.
$setState installs a state only where it fits the
sampler as it stands, and says whether it did: it returns
TRUE, or FALSE with the sampler left as it was
when a tree of the state would have to be changed, as when a
leaf is reached by no row after a $setPredictor. The new
forceUpdate = TRUE installs such a state, merging what
does not fit as a forced $setPredictor does, and returns
NULL invisibly, the sampler's stored state then being
the chain as installed, repairs included. 0.9-34 installed
whatever state it was given and returned NULL.
$setState no longer brings back the cut points a state
was stored on, which 0.9-34's did: the cut points, like the
predictors, stay the sampler's. A state with a split on a
value the sampler's cut points do not hold is declined
(FALSE), and with forceUpdate = TRUE has that
split moved to the nearest cut point its tree allows, or
merged. To restore the cut points as well, hold the state in a
variable and set them first:
sampler$setCutPoints(attr(state, "cutPoints")), then
sampler$setState(state). A copy and a reloaded sampler
keep the cut points the sampler's data object records, below.
What a sampler derives from its data - its cut points and their
weights, the response range its leaf prior is scaled by, a
linear or Gaussian-process leaf's covariate standardization and,
with several forests, their calibration - is recorded on the
data object it holds, sampler$data, in the new slots
cutPoints, response.range,
standardization and forest.calibration (see
dbartsData). A
sampler created from a data object uses what it records and
derives the rest, so new("dbartsSampler", ...,
sampler$data) and samplePriorPredictive(sampler) are made
on the sampler's cut points and response range, where 0.9-34
derived them again from the data. A new fit, dbarts(sampler$data),
bart(sampler$data) or dbartsSpec(sampler$data),
takes the cut points and standardization the data record and
derives the response range and sigma's starting estimate from the
data's response, unless sigest states one, as 0.9-34 did;
sampler$copy() makes the same model again. A data object
made afresh derives them all, as before. xbart(sampler$data) takes the
cut points in every fold and derives the rest there. A copy and a
reloaded sampler are made
on the record: a copy of a sampler takes its current chain, where
0.9-34 installed the last stored state, and a sampler saved after
$setCutPoints with no $storeState() since reloads
on the new cut points, the stored splits moved onto them by
value, where 0.9-34 brought back the stored cut points. A sampler
saved with no stored state refuses to be copied or run, where
0.9-34 made the copy afresh and ran from a fresh start.
$setData uses what the data object it is handed
records in the same way: the sampler's own data object, handed back
whole (sampler$setData(sampler$data)), keeps the
sampler's cut points and response range, as does
sampler$setPredictor(newValues, 1, forceUpdate = TRUE) for
one column, where 0.9-34 derived them again from the new
data, while a data object made by dbartsData() records
none and derives the cut points, as before. Such an object no
longer moves the response's scale: the sampler keeps its own, as
$setResponse does, where 0.9-34 derived it again from the
new response; pass updateScale = TRUE for that. A cut count or quantile rule
the object states wins and the sampler derives by it from then
on, where 0.9-34 kept the sampler's, and an object carrying cut
points brings the count and rule that made them. Its new arguments
updateCutPoints, updateScale and
updateStandardization, after updateState, derive a
value ("position", "value" or TRUE) or keep
the sampler's ("none" or FALSE) whatever the object
records. $setPredictor(updateStandardization = TRUE)
derives a linear or Gaussian-process leaf's standardization again
for the columns it replaces, over their new values at the rows
in the likelihood, keeping a covariate those rows hold at one
value, with a warning.
A state whose saved draws (keepTrees) number more or
fewer than the sampler keeps is installed with the newest that
fit, the sampler's n.samples unchanged. 0.9-34 took a
larger or smaller store as it was and crashed R on a state
with none where the sampler kept some.
family = "auto" recognizes more responses. A two-level
factor, logical or character response fits as probit. A factor
with three or more levels fits as "multinomial" on
bart if unordered and as "ordinal" on bart
and dbarts if ordered, and is an error naming the family
elsewhere; a matrix of three or more count columns fits as
multinomial. 0.9-34 fit a factor's level codes as a continuous
response, or failed on the formula interface. A one-line
message reports the family chosen; bart prints it by
default, and verbose = FALSE silences it.
n.threads keeps its meaning as a total thread budget, but
each chain samples on one thread, and dbartsControl's
default is now min(guessNumCores(), n.chains), or one
where guessNumCores() is NA, where dbartsControl,
bart (0.9-x's bart2), rbart_vi and xbart
used to refuse to run.
bart and dbarts warn when n.threads exceeds
n.chains; the extra threads serve test fits and
predict only.
xbart. With k not given it scores the default a
bart fit would use: fixed 2 for a continuous response and
chi(1.5, 2) for a binary one, where 0.9-34 used
chi(1.25, Inf); with drop = FALSE the result
then has a labeled k dimension. n.burn takes two
values; a third is an error. A chain is no longer carried from
one fold or replication to the next (0.9-34 could score a
setting on rows it had effectively been trained on), the
default sigest is estimated from each fold's training
rows rather than from all rows, held-out responses included,
and every fold uses the full data's cut points, so results
change. Seeded
runs are reproducible at any n.threads and leave
.Random.seed as they found it, and warnings from the
workers are now reported.
A predictor holding Inf or -Inf has its cut points
placed over its finite values, the infinite ones falling past the
end cut points; 0.9-34 stretched the cut points to infinity,
leaving the column unused, or under useQuantiles = TRUE
placed an infinite cut point.
When the starting sigest cannot be estimated because of
such a value, the error names the column.
pdbart and pd2bart evaluate a factor predictor
at every level by default, take and report its levels by name
in levs, and plot one point per level.
pdbart's and pd2bart's fd includes the
fit's offset, as BayesTree's included binaryOffset; rows
a fit gives a 0 weight are left out of the average. The result
carries n.chains and its type, and
combineChains = FALSE gives fd a chain margin.
Output shapes. Per-observation results carry the data's row
names. Under combineChains = FALSE, extract and
predict keep the chain dimension on a one-chain fit, so a scalar such as sigma
is a 1 x samples matrix rather than a vector.
extract(type = "trees") always has a chain
column.
predict applies the fit's offset argument at
newdata, as predict.lm does: the expression it was
given as, such as offset = log(exposure), is evaluated on
newdata, and an offset given to predict
adds to it. One given as a plain vector for the training rows
applies only to a newdata of as many rows, as in
lm, and is otherwise refused unless predict is
given an offset for the new rows.
0.9-34 predicted without the fit's offset. The default
offset.test is formed the same way on test.
An offset() term in a formula is used, as in lm:
it is added to any offset argument at fit time and
evaluated on test and on predict's
newdata, which must then be data frames carrying its
variables. 0.9-34 ignored it unless an offset vector was
also given. An explicit
offset.test is one value or one per test row, where
0.9-34 recycled or cut it, and a bare name given as
offset.test is looked up in test before
data.
The warnings a caller has a reason to catch apart from the rest
carry a class inheriting from dbartsWarning, so they can
be caught or muted without matching their text: deprecations
(dbartsDeprecatedWarning, also a base R
deprecatedWarning), the slow-count warning of a monotone
fit (dbartsSlowCountWarning), and warnings that a supplied
input was replaced by another (dbartsFallbackWarning
and dbartsGPFallbackWarning). Every other warning is an
ordinary one. A fixed residual scale,
sigma = fixed(value), is new; a sigest (or
sigma) beside it is refused when it differs
from the square root of value, and accepted with a
message when it equals it, until 1.1-0. No starting estimate is
made under one: the fit reports the square root of
value as its sigest, and a predictor holding
Inf no longer stops the fit there.
sigest also takes "auto" (the default),
"dense" or "sparse", naming the routine that
makes the starting estimate; ?dbarts says what each
costs and what to pass in place of an expensive one. A sparse
x takes the sparse routine by default.
Where the linear regression behind the starting sigest
leaves no residual degrees of freedom, as with more columns
than rows (each row counted once under frequency weights, not
as often as its weight), the fit starts from the standard
deviation of the response, weighted as the regression is
(sd(y) at unit weights, and over the rows of positive
weight where frequency weights total at most 1, up to the
rounding of their sum), saying so in a line under
verbose and in its summary; 0.9-34 stopped.
xbart's sigest may be a function, called on
each fold's training rows.
Draws a sampler has saved (keepTrees) keep their
values when the response scale is re-derived: after
setResponse or setOffset with
updateScale = TRUE, or setData with
updateScale = TRUE, predict
returns for them what it returned before the call. 0.9-34
replayed saved trees on the scale in force, so they came back
in the new response's units.
A fit on a constant response is centered on it: the response is mapped from the window half a unit either side of its value, where 0.9-34 mapped it from the value to one unit above, so the leaf prior sat half a unit above the data.
A sampler draws its augmentation variables (the probit and
ordinal latents, the Polya-Gamma precisions, the Student-t
scales and aft's imputed times) at the start of each sweep,
before its trees, and no setter draws them. A larger sampler
that changes the offset, predictors or sigma between sweeps is
exact whether its own step reads $getLatents() or
integrates the latents out; in 0.9-34 the second was not, the
next sweep's trees fitting latents drawn before the change.
$setResponse on a probit sampler no longer redraws the
latents, as it did in 0.9-34; $getLatents() returns the
earlier values until the next sweep draws them.
Every fit answers sigma(), the posterior mean of its
residual sd (1 on a family with none), and nobs(), the
rows in its likelihood, as an lm or glm fit does;
0.9-34 returned an empty vector with a warning and an error.
dbarts and dbartsSpec take n.trees, the
tree count of the forest with no basis, and dbarts
and dbartsData take n.cuts and
useQuantiles, so a control holds run settings only. The
three arguments of dbartsControl still work, with a
warning once per session, and are removed in dbarts 1.1-0.
forests = forest() takes a single forest without
list().
The sampler's $setWeights takes updateScale, after
updateState: with TRUE it takes the response's
scale, and a negative binomial fit's center, again from the rows
the new weights leave in, as $setOffset does, where
0.9-34 held the scale set at creation. It defaults to
FALSE.
predict with no newdata returns each type
at the training rows from the draws the fit stored, on every
family and without saved trees (0.9-34 stopped); an
offset given there replaces the fit's own. So does
survivalProbabilities (it refused an offset
without newdata).
pdbart and pd2bart take type
("auto": the link scale, 0.9-34's, except the mean
response on hurdle fits and survival at the median survival
time on accelerated failure time and hazard fits, with
"event", "cumhaz" and times),
newdata, n.average.rows and average.weights;
they serve negative binomial,
hurdle, accelerated failure time and hazard fits, and their
plots label the scale and take plot.type.
Sampling is faster. Against 0.9-34 on a four-core x86-64
machine, fitting through the BayesTree-style interface with 200
trees and 1000 draws after 500, with defaults that changed
pinned to 0.9-34's: 1.7 times faster at 1,000 observations, 2.6
times at 10,000, 1.7 times for four chains on four threads, and
1.6 times for a probit fit. The gap widens with the number of
observations. storage = "single" (a
dbartsControl and bart argument) keeps the running residual in single
precision for a further 10 to 30 percent at a million
observations; it is opt-in, for continuous responses with
constant leaves.
Large fits use less memory: packaging a fit no longer holds an
extra copy of the training and test draws, which lowers peak
memory by 1.6 GB on a 100,000-observation, four-chain, 500-draw
fit. dbarts-package has a ‘Memory’ section
giving a fit's footprint and the options that control it. A
per-draw compiled callback with keepFits = FALSE
(bart, dbarts, $run) lets a caller reduce
draws as they are made without storing them.
Response families. bart, dbarts and xbart
take a family, as a name or as a family object with its
own settings (not every family on every function);
dbartsFamilies lists them, and base
R's gaussian() and binomial() are accepted as
glm takes them. New are "logistic" (Polya-Gamma
augmentation, accepting integer count weights),
student() (robust Student-t errors),
"multinomial", "ordinal" (cumulative probit),
"nbinom" (negative-binomial counts on a log link, with
an integer shape fixed or sampled on a grid), "aft"
(log-normal accelerated failure time for a right-censored
Surv response), "hazard" and
"hazard.logistic" (discrete-time survival), and
"hurdle.lognormal" (a non-negative response with exact
zeros, bart only). survivalProbabilities
gives survival-curve draws from a survival fit, at the training
subjects, at newdata or, with sample = "test", at
the test subjects the fit stored. A hazard sampler's
$setData takes data built from a Surv response and
spreads it onto the sampler's own periods as dbarts
does, a time past the last period leaving its subject censored
there. A hazard sampler refuses a hand-built
person-period matrix whose last column is not named
period. Each new fit
class has fitted, predict, extract,
residuals, summary and plot methods, and
family() returns the family of any fit. See
bart.
Frequency weights. bart, dbarts,
dbartsSpec and xbart take weights.type:
"frequency" reads a gaussian or Student-t fit's weight
as a count of identical observations, real values taken, so
the starting sigma, the residual scale's posterior and the
log-likelihood count them, where NULL, the default,
keeps 0.9-34's precision. Every other family reads its weights
as counts or, at 0 and 1, as the rows in: "nbinom" and
"multinomial" take whole-number counts, a 0/1 vector
on "probit" and "ordinal" is kept on the data
object as the rows in, and a weight of 0 takes a row out of
the likelihood on every family. A test sample's weights mean
what the fit's do, and predict's weights on a count
family are new trials, a 0 drawing none.
A binomial response. Under family = binomial or
"logistic", bart, dbarts and xbart
take cbind(successes, failures) on a formula, or an
n x 2 matrix on the matrix interface, as glm does, where
0.9-34 stopped on it. Fits report probabilities, and
predictive draws and the log-likelihood are binomial at a
training row's trials; at new rows the trials are
predict's weights, or, where none are given, the
successes and failures newdata carries, at a test
frame those it carries, its weights only holding rows out, and
one trial otherwise; a row missing a count is
refused by default, predict's na.action = na.pass
giving it NA draws and na.omit dropping it, and
columns missing a count in every row are read as absent.
A row of
no trials is fitted and enters no likelihood. xbart's
"log" and "mcr" losses score the rows as their
trials written out one each.
A "hurdle.lognormal" fit takes a formula and
data, or a data object; a test set, read by
extract and fitted with
sample = "test"; subset; weights of 0
and 1, a 0 row being out of both parts' likelihoods with
NA predictive draws; and offset. A plain
offset or offset() term enters the positive
part, which models \log y, and
offset = list(zero = , positive = ) gives each part its
own. predict takes offset and weights, and
pdbart and pd2bart carry each part's offset.
Leaf models. leaf.prior = linear(columns) fits a linear
function of chosen predictors in each leaf, and
leaf.prior = gp(columns) a Gaussian-process function. The
covariates are centered and scaled over the rows in the
likelihood when the sampler is created, over every row where
fewer than two are in (subjects, in a hazard fit), and in each
fold of xbart over that fold's; a covariate the rows read
hold at one value, a constant column among them, is refused
unless a gp leaf states its lengthscale. The sampler keeps
its standardization: a restored state and a warm start put the
slopes in as stored under it, and $setWeights and
$setActiveRows take it again from the rows then in
only with their updateStandardization = TRUE, for a
loop whose rows in change during burn-in.
normal(sd = ) states the leaf prior's spread directly on
the response (or latent) scale instead of through k, as a
number or under the new invchi() hyperprior. Available on
bart, dbarts and xbart; see
dbartsPriors.
Tree priors. split.probs = dart() runs DART (Linero
2018), a sparsity-inducing prior on which predictors the trees
split on, on bart, dbarts, dbartsSpec and
xbart; split.probs also takes a vector of fixed,
unequal split probabilities. bart gains
leaf.prior, taking the same prior objects as
dbarts, which are listed in dbartsPriors.
Multi-forest models. dbarts(forests = ) takes a list of
forest specifications, each with its own trees,
priors and predictors, and fits the mean as their sum, a forest
given a basis entering multiplied by it. The Bayesian
causal forest has the shape of the two-forest case with a
treatment factor of two levels as the basis, its prognostic
forest stating amplitude = student(1). In a bart or
dbarts formula, each forest is a term:
y ~ forest(x1 + x2) + forest(x1 + x2, basis = factor(z))
declares the same thing. A basis names a column of the data,
or of the matrix the matrix interface is given, before a
variable where forest() was called; a single string,
basis = "z", names column z. Several forests
with no basis,
y ~ forest(x1) + forest(x2) + forest(x3), share one
prior total, the fitting function's leaf prior and its
k, each an equal part, and split its n.trees as
blocks() splits a forest's trees, so the model is one
forest with its trees in blocks; one with no basis beside
others takes that leaf prior whole, held at 1, as bart's
one forest does; and one with no basis stating its
sd has its own size, drawn only under
amplitude = normal() or student(). A basis is
one numeric column, with one coefficient, or a factor, a
character vector or a logical vector of two levels, with a
coefficient for each level; its
class decides which, whatever its values, so a 0/1 number is
one column and factor(z) is two levels. A larger basis,
three or more levels or several numeric columns, is refused
with the form to write: a forest of its own for each level but
the first, or for each column.
The same basis is the same fit however it is handed over, in
a formula, in forests, to $setForestBasis or
to predict(bases = ):
a level no kept row has gives no column, and a missing value
matters only on a row the fit keeps. A forest keeps its kind
for life, and a replacement basis must be of its class, a
factor being matched to the forest's levels by name. A fit's
bases holds the factor for a forest of levels, which
predict(bases = ) takes back. summary gives each
basis forest's average effect per unit of its basis over the
training rows, each row at its count under frequency weights, and
its spread across them, each a posterior median with an interval;
on a binary, binomial or hazard response a second line gives the
change in probability (a factor's second level against its
first) or the slope of the probability per unit.
Gaussian, probit, logistic and discrete-time hazard responses;
predict and extract report each forest separately
(type = "forest") or combined. A forest's size is its
sd, forest(sd = ), a number of the response's
units (those of the latent index under probit, logistic and the hazards),
which $setForest restates and
$getLeafPrior() returns, with whether it was stated; the
one forest of a single-forest model states its size as
leaf.prior = normal(sd = ). A numeric forest that
states none takes its size per standard deviation of its
column, read when the sampler is created, which
$setForestBasis(updateBasisScale = TRUE) reads again
from the replacement column, for burn-in. That sd is
the scale of the forest's trees, so its size where the
coefficient is held; a drawn coefficient is a multiplier with
prior median size 1 (on a factor, the difference between two
levels' coefficients), under a normal prior, or a heavy-tailed
one as amplitude = student(df).
Heteroscedastic BART (Pratola et al. 2020): variance = ~ x1
+ x2, variance = TRUE or a
varianceForest in bart and dbarts
adds a forest for the residual variance, reported as
s.train and s.test, and returned by
extract and predict as type = "sigma"
in place of a scalar sigma. For gaussian and "aft"
responses.
A live sampler changes one forest through
$setForest(forest, sd = , power = , base = , amplitude = ,
proposal.probs = , n.perturb.cuts = , treeShift = ), by label or
position, in forest()'s names, leaving the trees as they
are, and $getForest(forest) gives every value in force as
a list that goes back with no change. A forest sharing one prior
total that states its sd there leaves the group, and the
others keep their parts, set at creation. amplitude there
holds a forest's coefficient or releases it, and switches it
between normal() and student(df).
$setVarianceForest and $getVarianceForest do the
same for the variance forest.
$setTreePrior(power = , base = , split.probs = ) changes
the fitting function's tree prior; it, $setModel and
$setLeafPrior reach, on a sampler of several forests, the
forests that state none of their own, and the one forest with no
basis whatever it states. $setModel installs a forest's
own sd, power or base, and the variance
forest's power or base, where the model's record
states one, as those methods write it, and leaves a number the
record does not state; it refuses, by name and before storing
anything, a model that differs in structure or in a
coefficient's prior, the second naming $setForest, and
one that gives a forest another part of a shared total.
Constraints. monotone = c(x1 = "increasing", x2 =
"decreasing"), or 1, -1 and 0 by name
or position, makes the fit monotone in those predictors
(Chipman et al. 2022). monotone(directions,
prior = ) also chooses the prior: "joint", the
default, conditions the trees and their leaf values on
monotonicity together; "leaf" keeps the ordinary tree
prior and restricts only the leaf values, at a cost in run
time with very few trees.
interactions = interactions(max.order = , forbid =
, groups = ) limits which predictors may interact, and
blocks = blocks(...) makes the fit an exact sum
of functions of separate predictor groups, each group taking an
equal part of the forest's prior whatever its number of trees.
All three on
bart and dbarts; interactions and
blocks also hold on each category forest of a
multinomial fit.
Predictors. Factors split on level subsets, with up to 65535
levels; missing predictor values are modeled in place, each
split learning which way they go (Twala et al. 2008). Sparse
Matrix::dgCMatrix predictors are used without being
expanded, and a data frame may mix
ordinary columns with sparse ones, including the new
sparseFactor column. Any other
Matrix class, dense or sparse, and a sparseVector
are converted, and integer and logical
matrices are taken as numbers, in fitting and in
predict; 0.9-34 refused an integer matrix.
Starting points. bart's warm.start starts the
chains from a previous fit's trees, taking all of the earlier
fit that the new one can hold, and with verbose = TRUE
says in one line how many trees were taken, moved and cut
back; n.grow.sweeps builds the starting trees by
XBART-style grow-from-root sweeps (He et al. 2019); the sampler
offers both as $installTrees and $growFromRoot;
installTrees(donor) returns TRUE for a donor
taken as stored and FALSE, the sampler untouched, for
one that would have to be changed, which
forceUpdate = TRUE installs. Neither changes the
posterior, only where the chains start. A previous fit with
fewer trees than the new one is taken whole, the rest of the
trees starting as single leaves, and one with more gives the
trees whose fitted values vary most over the new fit's rows.
Under blocks() each block takes the trees it can hold as
they stand, so a fit with the same blocks is taken whole, and
where not all go in so, the trees that vary most within it.
A previous fit with constant where the new fit has linear
leaves or the reverse, or with DART or a variance forest on one
side only, is taken in part.
Tree moves. proposal.probs gains two optional moves,
"perturb" (shift one split point, by at most
dbartsControl(n.perturb.cuts = ) cut positions) and
"rule_gibbs" (redraw a split rule from its conditional
distribution), both off by default, and accepts all-zero
structural probabilities, holding the trees' shapes fixed while
everything else is sampled. dbartsControl(treeShift = )
adds a step that improves mixing of the leaf values when the
shapes are fixed. forest and
varianceForest take proposal.probs and
n.perturb.cuts, and forest treeShift, of
their own, defaulting to the control's, and a sampler's
$setControl changes them on the forests that state none.
Binary fits under the probit link that draw
k - the default for bart, dbarts,
xbart and the hazard fit - take a further step each
iteration that rescales the latent variables, the leaf values
and k together, drawn from its exact conditional
distribution. k and the fit's overall scale mix far
faster, most where the response is nearly separated, where a
chain could otherwise hold k for tens of thousands of
iterations; the posterior is unchanged.
bart gains a control argument for
treeShift and the other
dbartsControl settings.
Prediction and summaries. fitted and predict take
ci.level to return credible or prediction intervals.
predict's n.threads splits the work across draws,
so single-chain fits parallelize too, with identical results.
summary.bart tabulates the parameters a fit
sampled, sigma and the leaf scale (k, or
leaf.prior.sd on a fit whose leaf prior was named by
sd), with split R-hat and effective sample sizes, and
names every one it held fixed, a Student-t df included, on a line
under the table.
rhat returns the rank-normalized split R-hat of one
quantity's draws, a matrix of iterations by chains, as
posterior::rhat does; call it as dbarts::rhat.
extract(type = "loglik") returns the pointwise
log-likelihood, for use with WAIC or PSIS-LOO (for example
loo), and extract also reads "sigma",
"k", "leaf.prior.sd" and "varcount":
draws for a parameter the fit sampled and one number for one it
held fixed, "sigma" being 1 on a family with no residual
scale, and on a fit with several forests "k" is one
number per forest and "leaf.prior.sd" a list of each
forest's sd, named by the forests' labels. A fit stores the k its
sampler recorded, the leaf.prior it ran under and the
scalars it held fixed. plotTree plots a
tree directly from a fit. samplePriorPredictive
draws from a model's prior before fitting it; on a multinomial
sampler its "ppd" draws a category for a response
written as a factor and a count vector of one trial for one
written as a count matrix. Runs can be
interrupted with Ctrl-C.
xbart runs over the same sampler as bart, so it
takes family, factors, split.probs
(a vector or dart()), leaf.prior and sparse
predictors; it accepts only
storage = "double". Its
k may mix fixed values and hyperpriors
(k = list(1, 2, chi())), sd crossvalidates the
leaf spread, and parallel and cl choose forked,
socket or caller-supplied workers.
Using dbarts inside a larger sampler. New sampler methods include
$setActiveRows (drop rows from the likelihood between
draws), $getFitsWithoutOffset, $getLeafPrior,
$setLeafPrior, $getK, $getVariance, and per-forest
readers and setters; an "aft" sampler's censoring can be
changed through $setResponse(y, status = ).
dbartsDrawLatents and dbartsWorkingResponse
expose a family's augmentation draws to R. dbartsSpec
resolves a model specification without building a sampler, for
packages supplying their own design.
dbartsValidateComposition checks by
simulation-based calibration that a composed sampler targets the
posterior it claims. The vignette
vignette("dbarts-as-a-component") and the help page
dbarts-embedding show worked compositions.
The C++ headers (dbarts/R_C_interface.hpp and those
beside it) are removed with the engine they exposed. A package
compiling against dbarts uses the flat C header
dbarts/dbarts.h, whose entry points are reached through
R_GetCCallable (or the stubs enabled by defining
DBARTS_USE_STUBS) and versioned by
DBARTS_C_API_MAJOR and DBARTS_C_API_MINOR, with
dbarts_apiHash() as an opt-in exact-ABI check. The header
declares no R type and no longer defines USE_FC_LEN_T or
includes Rversion.h; a consumer that needs them includes
them itself.
The header creates no sampler: build it in R
(dbarts or dbartsSpec) and read its
handle out of the object's external pointer with
R_ExternalPtrAddr. The C entries run the sampler into a
caller-owned dbarts_results (initialize it with
DBARTS_RESULTS_INIT), swap its response, offset and
residual scale (copying them), read its latents, predict, store
and print trees, and register a per-draw callback; saving state,
reading trees and changing predictors or weights go through the
R methods. See dbarts-embedding.
bartBT with keepcall = FALSE used equal split
probabilities whatever splitprobs was given; 0.9-34 did
the same. It now fits the probabilities it is given.
The tree change move now satisfies detailed balance. It omitted a proposal-density ratio, which biased the trees toward predictors with fewer cut points whenever predictors differed in their number of cut points, so variable selection in mixed continuous and categorical designs, and under DART, is now correct.
With useQuantiles = TRUE (usequants on
bartBT), a predictor with more distinct values than its
cut points can separate has them spread evenly over the whole
column. They had been taken at a fixed stride from the bottom,
which could stop well short of the top, where no tree could
then split: at the default 100 cut points, a third of the
distinct values lay above the highest one at 150 distinct
values, half at 199 and a tenth at 999. Results change for
nearly every such fit, bartBT's included, and likewise
for a $setPredictor that updates cut points onto more
distinct values than the column's cut points could separate,
which had kept only the lowest ones, with a warning, and now
derives up to n.cuts of them. A predictor with no
more than n.cuts + 1 distinct values, and the default
useQuantiles = FALSE, are unaffected.
A predictor's cut points are distinct. A column whose range
cannot hold n.cuts distinct equally spaced points gets
fewer, where 0.9-34 repeated them, and a constant column gets
one; fits on a column that narrow, or on one with a single
value beside missing ones, change. A
$setPredictor that updates cut points derives up to
n.cuts of them from the new values whatever number the
column held, and no longer stops when they induce fewer.
Under the default useQuantiles = FALSE, a predictor with
fewer distinct values than n.cuts (a 0/1 column, a small
count, a sparse column, any column on fewer rows than
n.cuts) gets one cut point halfway between each pair of
neighboring values, each chosen in proportion to the width of
its gap, where 0.9-34 placed n.cuts equally spaced
points. A 0/1 column has one cut point where it had 100, no
proposal moves among cut points that split the same rows, and
fits with such a column change, bartBT's included. Where
two neighboring values are so close that their halfway point
rounds onto one of them, the cut point is the lower value, under
either rule.
$setPredictor's updateCutPoints is one of
"none", "position" and "value": the last
two derive the cut points again, each split keeping its
position, as TRUE did, or moving to the cut point
nearest its threshold. A logical is taken until dbarts 1.1-0
with a warning once per session. $setCutPoints takes
the same choice as splits; by position, the default, a
split's position is rescaled when the number of cut points
changes, where 0.9-34 kept its index.
The chi(df) hyperprior on k samples the degrees of
freedom asked for; it had sampled chi(2 * df - 1).
Observations of weight zero no longer count in the residual
variance's degrees of freedom, which had biased sigma
low. Such an observation is still in the design, as before: it
occupies a leaf and receives a fitted value.
The starting forest, and trees drawn from the prior by
$sampleTreesFromPrior, now follow the sampler's tree
prior, which excludes empty leaves; they had been drawn without
that restriction and pruned afterward.
A fixed residual scale, fixed(value), given when a
sampler is created is now held; it had been ignored, and one
installed through $setModel had been read as a standard
deviation.
Prior arguments no longer see internal variables named
control and data, which had shadowed the caller's
own (as in split.probs = data).
An offset.test expression is evaluated in test,
then in data, each with the formula's environment, as
model.frame evaluates its arguments, and failing that in
the caller's frame; without a formula, in the caller's frame. A
formula fit's test and weights are evaluated in
data with the formula's environment, and otherwise taken
as given. They had seen internal variables such as x, and
then the global environment ahead of the caller's own objects, so
offset.test = d$o inside a function could read a global
d.
An offset.test passed through a wrapper's ... is
read as the wrapper's caller wrote it, as offset is: a
name, an expression in offset or a column of
test. 0.9-34 stopped with “cannot find test
offset '..1'”.
xbart's RMSE loss on a binary response compares the
response with the predicted probability (the link applied to
each posterior draw, then averaged); 0.9-34 compared it with the
latent scale.
xbart's weighted RMSE loss is on the scale of the
response, and loss = "log" on a continuous response is an
error rather than silently computing RMSE.
bartBT (0.9-34's bart) keeps its weights
on the fit, so extract(type = "ppd") on a weighted fit is
no longer computed unweighted.
update works on a fit made through a wrapper that passes
its ... on to bart, bartBT, dbarts
or xbart; it failed with “..1 used in an incorrect
context”.
A data-dependent formula term, such as poly(),
ns() or scale(), is rebuilt on test and on
predict's newdata from the training data, as
predict.lm rebuilds it; 0.9-34 recomputed it from the new
rows, so a prediction depended on the other rows given with it.
A formula with no response is refused by bart and
xbart; 0.9-34 failed, or silently fit an all-zero
response when sigest was given.
Several inputs that failed with an unrelated low-level error now
get a clear one: a non-finite response, zero rows, a multi-column
response to dbartsData, a sample count that thins to
zero, a : or * term in a formula, heavy thinning
that drove printEvery to zero, and predict on a
multi-chain fit, or predict(type = "ppd") on any fit,
kept without keepTrees.
The starting estimate of sigma no longer depends on the
machine's linear algebra library: an exactly fit response could
give an estimate of 0, which the sampler then refused. Such an
estimate is now raised to a floor of 2^{16} times
the machine epsilon (about 1.5e-11) times the largest absolute
response less its offset (under precision weights, each times
the square root of its weight), below which only rounding
noise falls; an estimate above the floor, including that of a
mean far above its spread, is 0.9-34's.
plot.bart, plot.pd2bart and tree plots restore the
caller's graphical parameters.
Sampler methods. $setResponse and $setData check
that a probit response is 0 or 1. A whole-matrix
$setPredictor keeps column names, so later by-name column
updates work. A sampler run more than once with
keepTrees replays its saved trees in the order they were
drawn; they had been rotated against the other results.
pd2bart on a model with exactly two predictors returns
one column per grid point, where it averaged over the whole
grid and plot then failed.
plot on a pdbart result accepts type,
xlab and ylab, which collided with its own.
Arguments given beside a dbartsData object, which it
already fixes, such as subset and weights, are
reported in a warning rather than ignored silently.
$setCutPoints refuses a NaN cut point.
A predictor whose range is wider than the largest double, such
as one running from -1e308 to 1e308, gets finite cut
points and is split on; 0.9-34 never split it under the default
(uniform) rule.
rbart_vi's prior may name the caller's own
function, or be passed on by a wrapper, and an unknown name is
refused by name; only the built-in names worked.
predict takes a character or numeric group.by,
as the fit does; random effects came back empty and unseen
groups failed.
An n.cuts above 65533, the most a predictor's grid can
hold, is an error; 0.9-34 accepted it and could hang.
predict on a fit kept with keepSampler = TRUE
and keepTrees = FALSE is an error when the fit has more
than one chain, asking for keepTrees = TRUE; 0.9-34
returned the first chain's values and arbitrary numbers for
the others. A one-chain fit still predicts from its current
trees.
rbart_vi: the intercepts are drawn with precision weights
and start from a sweep of the trees, where a start from prior
trees could inflate the posterior of tau many times over
on a skewed response; with an offset and a test set of the same
size, a group's intercept is no longer counted twice in the test
fits; a fit saved and reloaded predicts as before;
predict with several chains handles groups the fit did
not see; a one-chain extract(type = "trees") works;
a group.by naming a variable that is not a column of
data is found in the calling environment, as documented,
where 0.9-34 grouped by the first column of data without
a warning; a seeded call leaves
the random stream as it found it; and set.seed
reproduces a multithreaded run at the same n.threads.
makeModelMatrixFromDataFrame keeps the missing value of
an integer or logical column, or of an integer or logical
matrix column, as NA. 0.9-34 turned it into
-2147483648 in the model matrix, where a double column's
stayed NA. A call to the function met it directly, and
factors = "indicators" with missing predictors kept
(na.keepPredictors) reaches it through a data frame
that has an integer column holding NA.
A weights bound to NULL draws no warning about
test, though none were supplied. 0.9-34 warned that
weights were not found in test when test had no
response column or a vector offset was given, and, in
the matrix interface, that weights are ignored for test.
An offset.test bound to NULL is no test offset
in the matrix interface, as with a formula; 0.9-34 refused it
there as not found.
An integer k, sigdf or offset, as in
bart(x, y, k = 2L), normal(k = 2L) or
chisq(3L), is the same number as a double, where 0.9-34
stopped with an error such as “k must be of real type if
NA is not allowable and no default is specified”.
Weights given as a column of test are read whether or not
test has the response column, and whether or not a
vector offset was given. 0.9-34 dropped them, with a
warning that they were not found.
A data frame given as newdata or test, or to
$setTestPredictor, on a fit made from a numeric matrix
keeps every column, so a one-row frame, or one with a column
held at a single value, predicts as the matrix of the same
values does. 0.9-34 dropped a column constant on those rows and
stopped with “number of columns in 'test' must be equal
to that of 'x'”.
A data-frame column that is a matrix of characters is an error naming the column, at the fit and at predict. 0.9-34 kept its first column as a factor and dropped the others, with only R's warning that a replacement element had too many rows. A logical or numeric matrix column is one predictor per column, as before.
A formula reads a column whose name is not syntactic, such as
1x, x-y, x:y or if in a frame
read with check.names = FALSE, through y ~ . or
written in backticks. 0.9-34 stopped with “undefined
columns selected” unless the name held a space.
'setPredictor' accepts 'forceUpdate = "partial"', installing a column one observation at a time and rolling back only those that would empty a node.
'updatePredictorPerObservationJointly' applies a '"partial"'-style update across several samplers at once, installing an observation only when it keeps every sampler's nodes non-empty.
The 'getTrees' method of a sampler accepts 'current = TRUE' to return the live working trees (the current sampler position) even when 'keepTrees' is 'TRUE', rather than the saved samples.
'getTrees' and 'extract(., "trees")' accept a 'newdata' matrix, routing those observations through each tree so the 'n' column counts them instead of the training data.
Added 'dbarts_getTreesCountingData', which routes a supplied matrix through the trees for the 'newdata' feature above.
'dbarts_getTrees' gained a trailing 'useLiveTrees' argument (for the 'current = TRUE' feature); callers linking to dbarts must update.
'copy' now works for samplers with a stored state.
Fixed reading a saved tree back from binary IO, which recursed with the writing routine instead of the reading one.
Fixed installation under R-devel, where RNGkind gained an
additional binom.kind argument and the code that parsed
its body via deparse produced invalid R once the
deparsed header spanned two lines. Fix thanks to Brian King
(PR #81).
Replaced a std::bit_cast cast used when registering the
.Call interface with a plain DL_FUNC cast; Apple
clang 14.0.3 on Intel macOS accepts -std=gnu++20 but its
libc++ lacks std::bit_cast, so compilation failed. Fix
thanks to Brian King (PR #81).
Fixed multi-chain and multi-threaded runs under R-devel, which
warned that .Random.seed was not a valid integer and fell
back to seeding from the clock, so that set.seed no longer
controlled their results. R's new binom.kind field pushed
the encoded value past the bound used to validate it; the uniform
and standard normal kinds that dbarts uses are now validated
individually and any further fields R encodes are ignored.
The fallback used to validate rngKind when the arguments of
RNGkind cannot be read no longer fails in a session that has
yet to use the random number generator, and now restores the
generator's state and all of its kinds afterwards.
Slot and attribute temporaries in the .Call interface are now
protected across the calls that can allocate, as reported by
rchk's static analysis of the protection stack.
predict now accepts a n.threads argument and will use native
threads to parallelize the saved-tree replay, one task per chain.
(The chain axis is the 0.9-x one; 1.0-0 partitions per chain and
posterior draw instead, and the argument's spelling is unchanged.)
When running with multiple threads, threads no longer persist after
runing or predicting and will be re-created on the next call.
Prior to this, threads were initialized at object creation and
would run in the background for the life-cycle of the sampler
object, waiting for work. To prevent frequent stopping/starting of
threads, new sampler-object functions startThreads() and
stopThreads() have been added that can bookend sampling or
prediction loops.
rbart_vi no longer fails when there are multiple out-of-sample
grouping factors in test data. Bug report thanks to github user
drcthal.
Should now correctly install on non-Mac OS arm64 systems. Bug report thanks to Bob Dröge.
rbart_vi now works when k is a variable. Bug report thanks
to Bruno Tancredi.
dbarts now works to initialize a sampler for binary outcomes when
resid.prior is left at its default. Bug report thanks to github
user LennMass.
Installs correctly on Alpine Linux. Bug report thanks to Sebastian Meyer.
Fixed an error in sampler when setting test offsets when there was only a single test observation.
Issues a warning instead of failing when weights are present in training data but not present in test. Suggestion thanks to github user Pentaonia (Loubert).
No longer depends on gfortran.
Uses SIMD instructions on M1 Macs.
Added experimental callback functionality to
rbart_vi.
Custom loss functiosn for xbart now require an additional
weights argument.
Fixed a multithreaded issue leading to inconsistent results
with xbart.
rbart_vi should now correctly use default arguments.
rbart_vi now works with keepTrainingFits as false.
Weighted binary responses sample latent variables from the correct distribution.
Extracting the values from the posterior predictive distribution for models with weights now incorporates them into the variance.
Weighted values are considered in loss functions for crossvalidation.
extract now accepts as a type "trees", which
allows for easier inspection of models fit with
"keepTrees" as TRUE.
print generics now exist for bart and rbart
fits; implementation thanks to Emil Hvitfeldt.
xbart now accepts a seed argument to enhance
reproducibility.
bart/bart2 (and dbarts through its
tree.prior argument) accept splitprobs/
split.probs which controls the prior probability that any
variable is used when splitting observations.
fitted for rbart_vi models now uses a C++
implementation for the expected value that uses less memory
and is faster.
xbart for binary outcomes with log loss no longer returns
NaN when some subset of the response is perfectly predicted by the
covariates. Bug report thanks to Marcela Veselkova.
dbarts now exposes access to the underlying proposal
rules and their probabilities through its proposal.probs
argument. bart2 response to the same argument, while
bart uses proposalprobs.
bart, bart2, and rbart_vi accept a
seed argument that will yield reproducible results, even
when running with multiple threads and multiple chains.
The interface registered under R_RegisterCCallable has
changed to reflect proper fixed hyperpriors for k.
Samples of the end-node sensitivity parameter, k,
are returned by rbart_vi when it modeled.
Burn-in samples of the end-node sensitivity parameter,
k, are included in the results of bart,
bart2, and rbart_vi.
rbart_vi will now look for group.by and
group.by.test in the data and test arguments
before looking in the formula or calling environments.
Fix for k mixing across chains when running multithreaded
and with k being modeled. Bug report thanks to Noah
Greifer.
Fix for xbart with method = "k-fold" when data
not evenly divided by number of folds. Rug report thanks to Jesse
(@ALEXLANGLANG on Github).
Sampler method getLatents and corresponding C function now
add user supplied offset to result.
Saved, flattened trees now correctly partition observations on left and right.
Samplers now have method sampleNodeParametersFromPrior.
When used in conjunction with sampleTreesFromPrior allow
the model to fully make predictions from the prior distribution.
dbartsControl (and now bart/bart2 through
...) now accept rngSeed argument. This can be used
to generate reproducible results with multiple threads. It should
only be used for testing, as the thread-specific pRNGs are seeded
using sequential draws from a pRNG created with the user-supplied
seed.
C interface supports dbarts_createStateExpression and
dbarts_initializeState which can be used to re-create
samplers that were allocated using forked multithreading.
C interface also supports dbarts_predict,
dbarts_setControl, and dbarts_printTrees.
Exports makeTestModelMatrix to allow package authors to
create test data at a later point from training data.
varcount for bart fits now has dimnames set.
residuals generic added to bart and rbart_vi.
Parallelization for rbart now creates the correct
number of chains.
Should now compile on non-x86 architectures. Report thanks to Lars Viklund.
Fixed hang when verbose = TRUE for multiple threads and
multiple chains. Report thanks to Noah Greifer.
Fixed potential memory access errors when recreating sample from saved state.
Correctly de-serializes saved tree structure.
Sampler now explicitly supports setSigma for use in
hierarchical models.
Sampler function setOffset has an additional argument
of updateScale. When the response is continuous and
updateScale is TRUE, the implicit scaling,
effecting the node parameters' variance, is adjusted to match
the range of the new data. This optionally reverts the change
of version 0.9-13 with the intention of being used only during
warmup when using an offset that is itself being sampled.
Extraneous print line from debugging 0.9-17.
Eliminated two race conditions from multithreaded crossvalidation. Report thanks to Ignacio Martinez.
Eliminated garbage read on construction of crossvalidation sampler, removing inconsistencies across multiple runs with the same starting seed.
makeModelMatrixFromDataFrame now converts character vectors
to factors instead of dropping them. Report thanks to Colin Carlson.
Memory leak for predict when keepTrees is FALSE.
Added extract and fitted generics for bart
models. Respects "train" and "test" sets of
observations while returning "ev" - samples from the
posterior of the individual level expected value, "bart"
- the sum of trees component; same as "ev" for linear
models but on the probit scale for binary ones, and "ppd"
- samples from the posterior predictive distribution. To synergize
with fitted.glm, "response" can be used as a synonym
for "ev" and "link" can be used as a synonym for
"bart".
predict for bart models with binary outcomes returns
a result on the probability scale, not probit. The argument
value is deprecated - use type instead.
predict further conforms to the same system of arguments as
extract and fitted.
xbart with a k-hyperprior should no longer crash. Report thanks
to Colin Carlson.
Fits from rbart_vi now work with generics fitted,
extract, and predict. extract retrieves
samples from the posterior distribution for the training and test
samples, fitted applies averages across those samples,
while predict can be used to obtain values for completely
new observations.
predict for rbart_vi takes value "ev" instead of "post-mean"
to clarify what is being returned, i.e. samples from the posterior
distribution of the observation-level expected values.
save/load should work correctly. Report thanks to Jeremy Coyle.
predict now works when trees aren't saved, for use in testing
Metropolis-Hasting proposals.
The offset slot no longer changes the relative scaling of the
response. This stabilizes predictions across iterations. For a semantic
where the scaling does change, use setResponse instead.
Varying intercepts model for probit regression.
A hyperpriors for k has now been implemented. Passing
k = chi(degreesOfFreedom, scale) now penalizes small values of
k, encouraging more shrinkage.
Hyperprior of chi(1.25, Inf) is now default for bart2
with binary outcomes. The default accuracy should improve substantially.
xbart divides data correctly with random subsampling.
More control over cut points has been added. It is now possible to specify
the cut points for a variable once and subsequently change that predictor
without also modifying the cuts using sampler$setCutPoints and
sampler$setPredictor.
sampler$getTrees implemented to get a flattened, depth-first down
left traversal of the trees.
For sampler$setPredictor, an argument specifies whether or not to
rollback or force the change if the new data would result in a leaf
having 0 observations.
pdbart and pd2bart now work with formula/data specifications,
as well as taking models or samplers that have previously stored trees.
Stores x as integer matrix of the max of which cut point an observation is
to the left of, by default using 16 bit integers. Limited to 65535 cut points.
That can be increased with some special compilation instructions.
Uses CPU dispatch and SIMD instructions for some operations. This and the integer
x make BART about 30% faster on datasets of around 10k observations.
Saved trees are stored using significantly less memory.
plot now works for fits from rbart_vi.
rbart_vi new reports varcount.
bart2 now defaults to not storing trees due to the memory cost.
bart2 now defaults to using quantile rules to decide splits.
predict for binary outcomes now correct.
Fix for verbose multithreading on Linux, reported by @ignacio82 on github.
General improvements to slice sampler in rbart_vi thanks to reports from Yutao Liu.
sampler$plotTree now handles multiple chains correctly.
Negative log loss for xbart with binary outcomes should now be computed correctly.
rbart_vi fits a simple varying intercept, random effects model.
Now natively supports multiple chains running in parallel.
Objects fit by bart can be used with the predict generic
when instructed to save the trees.
New function bart2 introduced, similar to bart but with
more efficient default parameters.
dbartsControl has had two parameters renamed: numSamples
is now defaultNumSamples and numBurnIn is now
defaultNumBurnIn.
dbartsControl supports parameters runMode,
n.chains, rngKind and rngNormalKind.
In the C interface, a new function (setRNGState) has been
added to specify the states of the random number generators, of which there
is now one for every chain.
State objects saved by the handles no longer contain the total fits, since they can be rebuild from the tree fits. States are also lists of objects now, with one corresponding to each chain. Tree fits and strings are matrices corresponding to the number of trees and saved samples.
random subsampling crossvalidation (xbart) has been implemented
in C++. Refits model using current set of trees for changes in
hyperparameters n.trees, k, power, and base.
Natively parallelized.
Rudimentary tree plotting added to sampler (sampler$plotTree).
Exported dbartsData as a way of constructing data objects
and setting the data seen by the sampler all at once. Sampler now supports
sampler$setData().
keepevery argument to bart matches BayesTree.
bart now has argument keepcall to suppress
storing the call object.
bart now accepts a weights argument.
MakeModelMatrixFromDataFrame now implemented in C, supports
an argument for tracking/keeping dropped values from factors.
Usage of weights was causing incorrect updates to posterior for
\sigma^2.
Should now JIT byte compile correctly.
Cuts derived from quantiles should now be valid.
Uses a rejection sampler to simulated binary latent variables (CP Robert 2009, http://arxiv.org/pdf/0907.4010.pdf). Code thanks to Jared Murray.
Now encapsulates its own random number generator, so that the C++ objects can safely be used in parallel. Shouldn't affect pure-R users unless their RNG has non-exported state (i.e. Box-Muller normal kind).
Includes a offset.test vector that can be controlled
independently of the offset vector, but in general inherits
behavior from it. Set at creation with dbarts() or after
with setTestOffset or setTestPredictorAndOffset.
By default, no longer attempts to obtain identical results as
BayesTree. To recover this behavior, compile from source with
configure.args = "--enable-match-bayes-tree".
Changing the entirety of the test matrix using setTestPredictor
no longer allowed. Use setTestPredictors instead.
Changing the predictor can now result in failure if the covariates
would leave an end-node empty. setPredictor returns a logical
as to success.
Saved dbarts objects may not be compatible and should be
re-created to be sure of valdity.
Now requires R versions >= 3.1.0.
Corrected binary latent variable sampler and no longer multiply adds offset (reported by Jared Murray).
Relatively embarassing bug related to loop-unrolling when n mod 5 != 0
fixed.
Correct aggregation of results for multithreaded variance calculations.
More equitably distributed tasks across multiple threads.
Makevars tweaked to allow compilation on Ubuntu.
Initial public release.