Skip to contents

A 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.

Usage

# S4 method for class 'dbartsFamily'
show(object)

Arguments

object

A family object, as one of the constructors below returns. Printing one names the call that would build it. A family object carrying a setting its constructor does not take is refused by name.

Format

A list of functions:

gaussian(sigma = NULL)

A continuous response with normal errors; the default for a numeric response under family = "auto". sigma is the prior on the residual scale: NULL is the shipped chisq(3, 0.9), chisq(df, quant) names another scaled-inverse-chi-squared, and fixed(value) pins the residual variance and suppresses the sampler's own draw, which is what an outer sampler owning \(\sigma\) wants. The former resid.prior, sigdf and sigquant arguments. sigest, the estimate the chisq quantile is calibrated against, is not a family setting and stays a fitting-function argument; it stands beside chisq, and is refused beside fixed, 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 = NULL estimates the degrees of freedom on a capped grid; a positive number fixes them. sigma is the scale-mixture's own residual prior, as for gaussian.

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 size in rnbinom and theta in MASS and mgcv. NULL estimates 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 sigma is its prior, as for gaussian.

hazard(breaks = NULL, link = c("probit", "logistic"))

Discrete-time survival hazard by person-period expansion. breaks sets the period grid: NULL uses 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. link selects 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 = NULL in bart), because its survival curves replay them; the trees take about 20 to 27 MB at the defaults, whatever the row count. keepTrees = FALSE drops them, and then survivalProbabilities refuses.

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 = FALSE leaves 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 as test is 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 class dbartsMemoryWarning that names the rows, the two figures and the ways out (a coarser hazard(breaks = ), keepTrainingFits = FALSE or fewer chains), and then runs; a sampler's $setData warns 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's memory.max, or memory.limit_in_bytes in 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 bart fits it. sigma is 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:

familybartdbartsdbartsSpecxbart
gaussianyesyesyesyes
studentyesyesyesno
probityesyesyesyes
logisticyesyesyesyes
aftyesyesyesno
multinomialyesyesyesno
ordinalyesyesyesno
nbinomyesyesyesno
hazardyesyesnono
hurdle.lognormalyesnonono

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.

See also

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.