Response Family Constructors
dbartsFamilies.RdA list of constructor functions building the response families that the
family argument of bart, dbarts,
dbartsSpec and xbart accepts. Bundling them
keeps generic names like gaussian and probit out of the
search path, where another package - stats::gaussian first among
them - could mask them or be masked depending on attach order.
family takes either a token string (family = "gaussian"),
meaning that family at its defaults, or one of these calls
(family = student(df = 4)), meaning that family with settings.
Inside the family argument the constructors resolve by bare name
whatever the caller has attached, exactly as the prior vocabulary does
inside split.probs, including when a wrapper forwards the argument
through its own ...; elsewhere reach them through this list. That
vocabulary shadows the caller's own frame for these ten names only, so a
variable named gaussian holding student(3) resolves there
to the gaussian family, not to its own value; name such a variable
something else, or write dbartsFamilies$student(3). A wrapper's
named formal that instead forces a bare constructor call before passing it
on reaches R's own could-not-find-function error, extended with the same
hint naming dbartsFamilies$student(...) and its siblings.
Base R's family objects are accepted as glm takes them.
stats::gaussian(), or stats::gaussian(link = "identity"), is
the gaussian family (dbarts's own gaussian() below takes no
link, since the identity link is the only one it fits, and refuses
one by name),
binomial(link = "probit") is probit, and
binomial(link = "logit") is logistic; the word
"binomial" and the bare function binomial mean
binomial(), the logit link, so a 0/1 response fit with
family = binomial is logistic where "auto" is probit. Any
other link of those two, and every other stats, quasi or foreign
family (poisson, Gamma, quasibinomial,
MASS::negative.binomial, ...), is refused by name.
Every setting that only one family reads rides its family object rather
than a formal of the fitting function. That includes the residual
scale's own prior, sigma, on the four families that draw a
residual scale: it takes a dbartsPriors residual prior,
chisq(df, quant) or fixed(value), resolved in the prior
vocabulary inside the family call. The retired spellings
resid.prior, sigdf and sigquant are accepted for
one release with a once-per-session warning and are removed in dbarts
1.1-0; resid.prior is retired that way on dbarts
and xbart as well (dbartsSpec refuses it), so the family
object is the one home of the residual prior. A call that writes the prior
both ways is refused where the two disagree, naming both spellings, and
accepted in silence where they say the same thing.
Format
A list of functions:
gaussian(sigma = NULL)A continuous response with normal errors; the default for a numeric response under
family = "auto".sigmais the prior on the residual scale:NULLis the shippedchisq(3, 0.9),chisq(df, quant)names another scaled-inverse-chi-squared, andfixed(value)pins the residual variance and suppresses the sampler's own draw, which is what an outer sampler owning \(\sigma\) wants. The formerresid.prior,sigdfandsigquantarguments.sigest, the estimate thechisqquantile is calibrated against, is not a family setting and stays a fitting-function argument; it stands besidechisq, and is refused besidefixed, which has no scale to calibrate.student(df = NULL, sigma = NULL)A continuous response with outlier-robust Student-t errors, drawn by the Gaussian scale-mixture augmentation.
df = NULLestimates the degrees of freedom on a capped grid; a positive number fixes them.sigmais the scale-mixture's own residual prior, as forgaussian.probit(),logistic()Binary latent-variable models for a 0/1 response.
multinomial(),ordinal()Unordered K-category softmax and ordered cumulative-probit models.
nbinom(shape = NULL)Negative-binomial counts on a log link: the forest models the log of the mean count, and the variance is \(\mu + \mu^2 / r\) for shape \(r\). A larger shape is closer to Poisson; \(r\) is
sizeinrnbinomandthetain MASS and mgcv.NULLestimates the shape \(r\) on a capped positive-integer grid; a positive integer fixes it. Each sweep's latent draw costs time in proportion to \(y + r\), so a large fixed \(r\) is slow: at \(r = 10^4\), a thousand sweeps over a thousand observations take about half an hour. By \(r\) in the hundreds the model is already close to a Poisson one. A fixed shape above \(10^6\) is refused, as a count above it is.aft(sigma = NULL)Accelerated failure time (log-normal) survival. The log-time residual scale is drawn as a gaussian one is, so
sigmais its prior, as forgaussian.hazard(breaks = NULL, link = c("probit", "logistic"))Discrete-time survival hazard by person-period expansion.
breakssets the period grid:NULLuses the sorted distinct observed times of the subjects in the likelihood (those of positive weight), a single positive integer bins at that many quantiles of those times, and a numeric boundary vector gives explicit right-closed intervals.linkselects the binary link the expanded rows are fit under, and is what the tokens"hazard.probit"and"hazard.logistic"name.A hazard fit keeps its trees by default (
keepTrees = NULLinbart), because its survival curves replay them; the trees take about 20 to 27 MB at the defaults, whatever the row count.keepTrees = FALSEdrops them, and thensurvivalProbabilitiesrefuses.A subject is at risk for one row a period, so on the default grid with distinct times the rows grow as the square of the subjects (1,000 subjects give about 500,000 rows) and on a grid of \(K\) periods as \(K\) times the subjects. Memory, not time, is what a row costs: at
bart's defaults (four chains of 500 kept draws, 75 trees) about 35 KB a row at its peak, about 32 KB of which are the kept draws of the training fits (8 bytes a draw a chain in the fit returned, and about 16 while they are copied out), so a million rows take about 35 GB.keepTrainingFits = FALSEleaves about 3 KB a row: about 300 bytes the chains share and about 620 a chain, 8 bytes a tree. A predictor column beyond three adds about 34 bytes a row, and a held-out subject passed astestis expanded to every period. No row count is refused: when the peak projected from these figures exceeds the machine's physical memory, the fit warns once per session, before any row is built, with a warning of classdbartsMemoryWarningthat names the rows, the two figures and the ways out (a coarserhazard(breaks = ),keepTrainingFits = FALSEor fewer chains), and then runs; a sampler's$setDatawarns the same way. The memory read is the smaller of the machine's installed memory and, on Linux, the limit a container or a job scheduler sets on the process (its cgroup'smemory.max, ormemory.limit_in_bytesin version 1), and the warning says “this process may use” that limit where it is the smaller. Where neither can be read there is no warning.hurdle.lognormal(sigma = NULL)A semicontinuous two-part response: a zero-part probit glued to a lognormal positive part. Composed from two samplers, so only
bartfits it.sigmais the positive part's residual prior; the zero-part probit has a fixed unit latent scale and takes none.
Details
Which entry points accept which family:
| family | bart | dbarts | dbartsSpec | xbart |
gaussian | yes | yes | yes | yes |
student | yes | yes | yes | no |
probit | yes | yes | yes | yes |
logistic | yes | yes | yes | yes |
aft | yes | yes | yes | no |
multinomial | yes | yes | yes | no |
ordinal | yes | yes | yes | no |
nbinom | yes | yes | yes | no |
hazard | yes | yes | no | no |
hurdle.lognormal | yes | no | no | no |
A family the entry point does not fit is refused by name. See
dbarts's family argument for what each family
models and what it supports.
Examples
f <- dbartsFamilies$student(df = 4)
f
#> dbarts response family: student(df = 4)
## the residual prior rides the family too
dbartsFamilies$gaussian(sigma = dbartsPriors$chisq(df = 5, quant = 0.75))
#> dbarts response family: gaussian(sigma = chisq(5, 0.75))
set.seed(99)
n <- 100L
x <- matrix(rnorm(n * 2L), n, 2L)
y <- x[, 1L] + rt(n, 4)
fit <- bart(
x, y,
family = student(df = 4),
n.samples = 50L, n.burn = 50L, n.chains = 1L, verbose = FALSE
)
#> dbarts: 'bart' is the function 0.9-x called 'bart2', with its own defaults (75 trees; four chains, their draws merged) rather than those of 0.9-x's 'bart' (200 trees, one chain). Call 'bartBT' for the BayesTree-style fit and its defaults. Shown once per session until dbarts 1.1-0.