Discrete Bayesian Additive Regression Trees Sampler Specification
dbartsSpec.RdResolves the control/model/data triple and family token that describe a sampler, without constructing one. Intended for packages that embed dbarts - in particular LinkingTo: dbarts packages that build a sampler in R from the returned pieces and hold its handle for the C API in dbarts.h - and that supply their own design matrix.
Usage
dbartsSpec(
data, control = dbarts::dbartsControl(),
power = 2, base = 0.95, split.probs = NULL, leaf.prior = normal,
proposal.probs = c(
birth_death = 0.6, swap = 0, change = 0.4, perturb = 0,
rule_gibbs = 0, birth = 0.5),
monotone = NULL, interactions = NULL, blocks = NULL,
variance = NULL,
forests = NULL, n.trees = NULL,
sigest = NULL, seed = NULL,
family = c("auto", "gaussian", "student", "probit", "logistic", "aft",
"multinomial", "ordinal", "nbinom"),
weights.type = NULL,
survival = NULL, tree.prior = NULL,
parentEnv = parent.frame(), ...)Arguments
- data
A
dbartsDataobject, as built bydbartsData. Unlikedbarts, this function does no response ingestion of its own: the response must already be materialized. A data object carrying an \(n \times K\)countsmatrix resolves tofamily = "multinomial"even from"auto"- the slot IS the declaration - and is refused under any other family. Wherefamily = "auto"resolves, the family is reported in a one-line message whencontrolwas built withverbose = TRUE; this function has noverboseargument of its own.- control, power, base, split.probs, tree.prior, leaf.prior, proposal.probs, monotone, interactions, blocks, variance, forests, n.trees, sigest, seed, family, weights.type, ...
As in
dbarts(except thatproposal.probs, the control's setting, is still accepted here as it is atdbarts: it is used, with a deprecation warning, is refused beside acontrolwhose own call named it, and does not reach a forest that states its own), including the frozenproposal.probsmixture - all five structural probabilities zero, which proposes no structure and draws only the leaf values,sigmaand the family's latents. The prior arguments are evaluated in dbarts's own prior vocabulary, so bare expressions such asnormal(k = chi(1.25, Inf))resolve regardless of what the caller has attached; so do the forest constructors insidemonotone,interactions,blocks,varianceandforests, evaluated inparentEnv(seedbartsForests). The residual prior ridesfamilyhere as everywhere (family = gaussian(sigma = chisq(df, quant))); the 0.9-x spellingsresid.prior,sigmaandnode.priorwere never arguments of this function and are refused by name, namingfamily = gaussian(sigma = ),sigestandleaf.priorrespectively. Aforest'sbasisis read againstdataasdbartsreads one beside a data object: a name is read from the frame the object keeps, or from the columns it holds, its predictors and response and a sampler's bases by the text each was written as, and otherwise whereforest()was called; a value has one entry for each row the object was handed, before itssubsetandna.action, and is cut with them. The list states the forests in full: what the data object held is replaced, a forest keeping a held basis by writing it as it was written, with its recorded scale, and no list, or a list of one forest with no basis, gives one forest.family's eight-token vocabulary is narrower thandbarts's by design - multinomial's K-forest engine andhurdle.lognormal's two-sampler composition build throughbart, never through this construct-only bypass; the wider set lives there.- survival
For
family = "aft"only: a vector of per-observation status codes, 1 for an observed event and 0 for a right-censored observation, with the response holding log event/censoring times.dbartsreads this off aSurvor two-column response; a caller supplying log-times directly supplies it here.NULLfor every other family.- parentEnv
The environment in which the prior and forest constructor arguments are evaluated; defaults to the caller's frame, which is almost always what is wanted. Pass explicitly when forwarding arguments from another function.
Details
dbarts does two separable things: it ingests a formula or a pair of matrices into a dbartsData, and it then resolves that data into a full sampler specification - choosing the response family, coding the response, applying the family's weight policy, estimating a starting sigma, parsing the priors, and recording on the model and data the monotonicity, interaction and block constraints, the forests and a variance forest, the residual degrees of freedom, and the survival status. dbartsData exposes the first half. This function exposes the second, and returns the pieces rather than a sampler.
Both entry points call the same resolution on the dbartsData they end up with, so a sampler built from this function's output draws the same samples as the equivalent dbarts call given the SAME data object. The two can still resolve a given family differently, because dbarts performs its own response ingestion first - coding a factor response into a count matrix, for instance - while this function does none: a call this function refuses for the raw response dbarts can still accept, by ingesting it into the shape this function requires.
Use with the C API
The family element of the returned list names the family the sampler is built with, and the dbarts_family enumerator dbarts_sampler_family reports for it ("gaussian" names DBARTS_FAMILY_GAUSSIAN, and so on). "auto" asks this function to dispatch on the shape of the response, which is correct for "gaussian", "probit", and "ordinal" - each is inferable from the response coding or from an attribute - but is wrong for "aft" and "logistic", which are indistinguishable by shape from "gaussian" and "probit" respectively, and for "nbinom", which is never inferred (a count vector resolves to "gaussian"). Name the family and the question does not arise.
Differences from dbarts()
sigest defaults to NULL, which like "auto" estimates the starting sigma from the data's response, as dbarts does: a starting estimate or response scale a sampler wrote into the data object is not read, since a new fit is a new model (use the sampler's copy() for the same model again). A number states it, and "dense" or "sparse" names the routine. An explicit NA for sigest is a missing value and is refused. Cut points are taken from control only when the data does not already carry resolved per-column counts.
Families that require ingestion this function does not perform are unavailable: "hazard" needs person-period expansion, and "hurdle.lognormal" describes more than one sampler. "multinomial" is in this function's own vocabulary, but only for a data object whose response is already an \(n \times K\) counts matrix (see data above, and dbartsData's counts argument); given a factor-coded or plain numeric response instead, it is refused with a message naming the counts route, even though dbarts accepts the same factor by coding it into that shape first.
Value
A list with components
- control
a
dbartsControl, holding the run settings; itsn.trees,useQuantilesandbinaryare copies of the model's and the data's, which a sampler built from the list writes on it.- model
a
dbartsModel, carrying the parsed priors, each forest's record and the variance forest's, the category count, the shape setting, the hazard periods, the resolvedweights.type(neverNA), and any monotone, interaction, block, and residual-degrees-of-freedom attributes.- data
a
dbartsData, with the response coded,sigmaresolved, and the censoring status and quantile rule recorded. Its weights slot holds the fit's weights, a"probit","ordinal"or"nbinom"fit's 0/1 weights among them, all ones as none, sonew("dbartsSampler", spec$control, spec$model, spec$data)makes the samplerdbartsmakes: the response's scale, a count fit's center, alinearorgpleaf's covariate centers and scales and a numeric forest's defaultsdare read over the rows the weights keep, and the two areidentical()in the stored state and every arrayrun()returns from the same seed. A mask handed to that call asactivecomposes with the weights, a row being in when its weight is positive and the mask keeps it. On a gaussian or Student-t list, where the rows the weights keep hold fewer than two distinct values of the response and a forest on a numeric column states nosd, that route warns twice, here for the response's scale and center and at creation for those and the column's scale, wheredbartswarns once.- family
the resolved family token, never
"auto".
Examples
f <- function(x) {
10 * sin(pi * x[,1] * x[,2]) + 20 * (x[,3] - 0.5)^2 +
10 * x[,4] + 5 * x[,5]
}
set.seed(99)
sigma <- 1.0
n <- 100
x <- matrix(runif(n * 10), n, 10)
Ey <- f(x)
y <- rnorm(n, Ey, sigma)
data <- dbartsData(x, y)
control <- dbartsControl(n.chains = 1L, n.samples = 20L, n.burn = 10L, updateState = FALSE)
## an ordinary specification, then the sampler it describes
spec <- dbartsSpec(data, control = control, n.trees = 25L)
spec$family
#> [1] "gaussian"
sampler <- new("dbartsSampler", spec$control, spec$model, spec$data)
samples <- sampler$run()
## additive-only fit, monotone in the fourth predictor
constrained <- dbartsSpec(data, control = control,
interactions = interactions(max.order = 1L),
monotone = c(rep(0, 3), 1, rep(0, 6)), n.trees = 25L)
attr(constrained$model, "interaction.max.order")
#> [1] 1