Package 'stan4bart'

Title: Bayesian Additive Regression Trees with Gradient-Sampled Parametric Extensions
Description: Fits semiparametric linear and multilevel models with non-parametric additive Bayesian additive regression tree (BART; Chipman, George, and McCulloch (2010) <doi:10.1214/09-AOAS285>) components and gradient-sampled parametric ones. The parametric conditional is drawn with a hand-derived analytic log-posterior gradient and the WALNUTS sampler (<arXiv:2506.18746>), taken from the Walnutpie library (vendored from <https://github.com/flatironinstitute/walnutpie>, commit f3c1833; MIT licensed, Copyright (c) 2025--2026 by the Walnutpie Developers). Multilevel models can be expressed using 'lme4' syntax (Bates, Maechler, Bolker, and Walker (2015) <doi:10.18637/jss.v067.i01>).
Authors: Vincent Dorie [aut, cre] (ORCID: <https://orcid.org/0000-0002-9576-3064>), Ben Goodrich [ctb] (rstanarm_functions.R), Jonah Gabry [ctb] (rstanarm_functions.R), Imad Ali [ctb] (rstanarm_functions.R), Sam Brilleman [ctb] (rstanarm_functions.R), Paul-Christian Burkner [ctb] (rstanarm_functions.R, ORCID: <https://orcid.org/0000-0001-5765-8995>), Bob Carpenter [ctb] (Walnutpie headers (WALNUTS sampler)), Brian Ward [ctb] (Walnutpie headers (WALNUTS sampler)), Walnutpie Developers [cph] (inst/include/walnutpie.hpp and inst/include/walnutpie/, vendored Walnutpie headers, MIT license), Trustees of Columbia University [cph] (rstanarm_functions.R), Douglas Bates [ctb] (lme4_functions.R, ORCID: <https://orcid.org/0000-0001-8316-9503>), Martin Maechler [ctb] (lme4_functions.R, ORCID: <https://orcid.org/0000-0002-8685-9910>), Ben Bolker [ctb] (lme4_functions.R, ORCID: <https://orcid.org/0000-0002-2127-0443>), Steve Walker [ctb] (lme4_functions.R, ORCID: <https://orcid.org/0000-0002-4394-9078>), Armon Dadgar [ctb] (adaptive radix tree), Bothner Per [ctb] (config.guess), Elliston Ben [ctb] (config.guess), Free Software Foundation [cph] (config.sub), Guido U Draheim [ctb] (ax_check_compile_flag.m4), Maarten Bosmans [ctb] (ax_check_compile_flag.m4), Christophe Tournayre [ctb] (ax_ext.m4), Michael Petch [ctb] (ax_ext.m4, ax_gcc_x86_avx_xgetbv.m4, ax_gcc_x86_cpuid.m4), Rafael de Lucena Valle [ctb] (ax_ext.m4), Steven G. Johnson [ctb] (ax_gcc_x86_cpuid.m4, ORCID: <https://orcid.org/0000-0001-7327-4967>), Matteo Frigo [ctb] (ax_gcc_x86_cpuid.m4), Scott Pakin [ctb] (ax_func_posix_memalign.m4, ORCID: <https://orcid.org/0000-0002-5220-1985>)
Maintainer: Vincent Dorie <[email protected]>
License: GPL (>= 3)
Version: 0.0-14
Built: 2026-11-11 18:56:30 UTC
Source: https://github.com/vdorie/stan4bart

Help Index


Multivariate BART for Correlated Outcomes (Seemingly-Unrelated Regressions)

Description

Jointly fits Bayesian additive regression tree (BART) models to two or more continuous outcomes that share a predictor set but have correlated residuals. Each outcome gets its own “sum-of-trees” mean surface; the surfaces are coupled through a residual covariance matrix Σ\Sigma that is given a conjugate inverse-Wishart prior and sampled jointly. This is the seemingly-unrelated regressions (SUR) analogue of BART: modeling the cross-outcome residual covariance yields a better-calibrated joint predictive distribution than fitting an independent BART per outcome whenever the outcomes are genuinely correlated.

For qq outcomes fits:

Yik=fk(xi)+eik,ei=(ei1,…,eiq)∼Nq(0,Σ),Y_{ik} = f_k(x_i) + e_{ik}, \quad e_i = (e_{i1}, \ldots, e_{iq}) \sim \mathrm{N}_q(0, \Sigma),

where each fkf_k is a BART model and Σ\Sigma is the q×qq \times q residual covariance.

Usage

mvbart(formula,
       data = NULL,
       subset,
       na.action = getOption("na.action", "na.omit"),
       test = NULL,
       n.samples = 1000L,
       n.burn = 1000L,
       n.chains = 4L,
       n.trees = 75L,
       prior = NULL,
       seed = NA_integer_,
       verbose = FALSE,
       bart_args = list())

Arguments

formula

a formula whose left-hand side is a multivariate response with at least two columns, e.g. cbind(y1, y2) ~ x1 + x2. The right-hand side gives the shared predictors used by every outcome's BART component; factors are expanded by dbarts.

data

an optional data frame containing the variables in the formula.

subset, na.action

optional components adjusting the model frame. See model.frame. na.action cannot be "na.pass".

test

an optional data frame of held-out predictors. When present, the per-outcome forest predictions fk(x∗)f_k(x^*) are stored for each retained draw.

n.samples

positive integer; number of retained posterior draws per chain.

n.burn

non-negative integer; number of burn-in sweeps discarded per chain.

n.chains

positive integer; number of independent chains, run sequentially.

n.trees

positive integer; number of trees in each outcome's forest.

prior

an optional named list specifying the inverse-Wishart prior on Σ\Sigma, with elements df (degrees of freedom ν0\nu_0) and scale (a q×qq \times q positive-definite scale matrix Ψ0\Psi_0). Either may be omitted. The prior has mean Ψ0/(ν0−q−1)\Psi_0 / (\nu_0 - q - 1). Defaults to a weakly-informative prior: df =q+2= q + 2 (the smallest integer giving a finite mean) and scale chosen so that the prior mean of Σ\Sigma equals the diagonal matrix of marginal outcome variances.

seed

optional integer. If supplied, per-chain seeds are drawn deterministically from it and results are reproducible; the caller's RNG state is restored afterwards.

verbose

logical or integer; if a positive number, prints progress every verbose sweeps.

bart_args

an optional named list of further arguments forwarded to each outcome's BART sampler. Recognized dbartsControl arguments not already set by mvbart (such as keepTrees) are applied to the shared control, and n.cuts and useQuantiles are passed to each outcome's dbarts call; the leaf-prior scale k is also honored. Any other name is an error rather than being dropped, and the rng seed is set with mvbart's own seed argument, not here.

Details

Conditional on the other equations' current residuals, updating one outcome's forest is an ordinary univariate BART step: the working outcome is Gaussian with a per-observation offset (the conditional mean implied by Σ\Sigma) and a scalar conditional variance. These are injected into the outcome's dbarts sampler through its setOffset and setSigma methods; the sampler is created with a fixed residual prior so the engine never draws its own nugget. After the forest sweep, Σ\Sigma is drawn from its inverse-Wishart full conditional, Σ∣⋅∼IW(ν0+n,Ψ0+E′E)\Sigma \mid \cdot \sim \mathrm{IW}(\nu_0 + n, \Psi_0 + E'E), where EE is the matrix of structural residuals. The routine is built entirely on the public dbarts R interface and adds no compiled code.

Diagnostics

Because the response passed to each sampler is fixed (only the offset moves), the creation-time [−0.5,0.5][-0.5, 0.5] response rescaling used internally by BART stays anchored across sweeps. The returned mMax records, per retained draw, the largest per-sweep max⁡i∣mik∣/range(Yk)\max_i |m_{ik}| / \mathrm{range}(Y_k); values well below 1 indicate the fixed scale is well anchored. If the maximum drift exceeds 1 a warning is issued: for such heavy-tailed cases the recommended fallback is a longer warmup, or a warmup-only response rescale (re-anchoring the internal scale to include the offset range during burn-in only).

Caveat: residual correlation bias with shared predictors

When all outcomes share the same predictors, BART's flexibility introduces a small positive bias in the recovered residual correlation (on the order of +0.01+0.01 to +0.02+0.02 at moderate to high correlation), because finite-sample mean-fitting error is correlated across equations. This makes interval coverage of the true correlation mildly liberal. The bias shrinks toward zero as nn grows and is inherent to the nonparametric mean model, not a defect of the sampler.

Future extension

mvbart is a pure-SUR sampler with no random-effect component. Combining the cross-outcome residual covariance modeled here with stan4bart's multilevel machinery (SUR ×\times random effects, i.e. a multivariate mixed model) is a natural extension that is not yet implemented.

Value

Returns a list assigned class mvbartFit with components:

Sigma

a q×q×q \times q \times n.samples ×\times n.chains array of residual covariance draws, with the outcome names on the first two dimensions.

train

an n×q×n \times q \times n.samples ×\times n.chains array of per-outcome forest fits fk(xi)f_k(x_i) on the training data.

test

when test was supplied, a n.test ×q×\times q \times n.samples ×\times n.chains array of per-outcome forest predictions fk(x∗)f_k(x^*); otherwise NULL.

mMax

a n.samples ×\times n.chains matrix of the per-sweep scale-drift diagnostic.

y

the response matrix.

outcome.names

character vector of outcome names.

n.samples, n.burn, n.chains

sampler settings.

prior

the inverse-Wishart prior actually used, a list with df and scale.

mixing

named vector of the split rank-normalized R-hats (Vehtari et al., 2021) of each outcome's residual standard deviation, “y sd”, and of its in-sample fit, “y fit”, the draw-by-draw root mean squared difference between the forest's fit and the response. A single chain is checked by comparing its halves. summary prints them on one line, as values with no flag.

call, formula, terms

the matched call, formula, and model terms.

Author(s)

Vincent Dorie: [email protected].

See Also

stan4bart, bart, dbarts

Examples

# two correlated outcomes sharing three predictors
set.seed(99)
n <- 200L
x <- matrix(runif(n * 3L), n, 3L)
colnames(x) <- paste0("x", 1:3)
B <- matrix(c(1.5, -1.0, 0.7, -0.6, 1.1, -0.9), 3L, 2L)
rho <- 0.7; s1 <- 1.0; s2 <- 1.3
Sigma <- matrix(c(s1^2, rho * s1 * s2, rho * s1 * s2, s2^2), 2L, 2L)
Y <- x %*% B + matrix(rnorm(n * 2L), n, 2L) %*% chol(Sigma)
df <- data.frame(y1 = Y[, 1L], y2 = Y[, 2L], x)

fit <- mvbart(cbind(y1, y2) ~ x1 + x2 + x3, data = df,
              n.samples = 200L, n.burn = 100L, n.chains = 1L,
              n.trees = 50L, seed = 1L)

# posterior of the residual correlation
Sig <- fit$Sigma
rho.draws <- Sig[1L, 2L, , ] / sqrt(Sig[1L, 1L, , ] * Sig[2L, 2L, , ])
c(mean = mean(rho.draws), quantile(rho.draws, c(0.025, 0.975)))

Print and Summarize stan4bart Model Fits

Description

Print a brief description of a fitted model, or compute and print a short summary of it. Both check the sampling-phase leapfrog-step diagnostic and warn when it suggests the model was under-warmed.

Usage

## S3 method for class 'stan4bartFit'
print(x, ...)

## S3 method for class 'stan4bartFit'
summary(object, ...)

## S3 method for class 'summary.stan4bartFit'
print(x, ...)

Arguments

x, object

a fitted model resulting from a call to stan4bart, or for print.summary.stan4bartFit, the result of a call to summary on one.

...

unused, but provided to match the signatures of other generics.

Details

Both print and summary examine object$adaptation$mean_leapfrog, the mean number of leapfrog (gradient evaluation) steps per transition during the sampling phase, per chain (see stan4bart). When the largest per-chain value exceeds 30, a one-line message is issued: “parametric sampler tuning looks poor (mean leapfrog steps per transition = ...); consider increasing warmup.” A well-tuned fit - one run with at least the default warmup, or with warmup at or above roughly 100 for large fits with many random-effect levels - should fall well under this value; the message is a cue to lengthen warmup rather than an error. No message is issued for a fit with no adaptation record, e.g. one run with warmup = 0.

summary additionally returns an object of class summary.stan4bartFit, printed by print.summary.stan4bartFit, giving the formula, family, chain/sample counts, the per-chain warmup and sampling mean leapfrog counts, and the fit's R-hats, which are the numbers of the mixing check (see “Mixing check” in stan4bart): one compact line such as R-hat: sigma 1.00, g sd 1.01, fit 1.00, each value as it is, with no star, bar or note, and NA: could not be checked, with the reason when a computation failed, when a value is NA. print is unchanged.

R-hat compares each chain's spread with the spread of the chains pooled, so a value above 1 says the chains disagree, not that pooling them is wrong. At the defaults BART's chains routinely disagree on sigma, on the standard deviations of the random effects, on the in-sample error and on a single row's prediction, so values above 1 there are expected, and no single bar says whether a fit is usable. Averaged estimands, such as the mean prediction over a subgroup or a contrast between two subgroups, mix far better, so read R-hat on the estimand you report. extract with combine_chains = FALSE gives each chain's draws of the expected value; the example computes R-hat of a contrast of subgroup means with them and dbarts::rhat. Call both with the dbarts:: prefix, as other packages export functions of the same names (see rhat).

Value

print.stan4bartFit and print.summary.stan4bartFit return their argument, invisibly.

summary.stan4bartFit returns a list of class summary.stan4bartFit, printed by print.summary.stan4bartFit.

Author(s)

Vincent Dorie: [email protected].

See Also

stan4bart

Examples

# R-hat of the estimand reported: the difference between the mean expected
# value of two subgroups, one value per draw and chain
set.seed(1)
n <- 200L
df <- data.frame(g = sample(10L, n, replace = TRUE), x1 = rnorm(n),
                 xb = runif(n))
df$y <- 3 * sin(pi * df$xb) + df$x1 + rnorm(df$g[1:10])[df$g] + rnorm(n)

fit <- stan4bart(y ~ x1 + bart(xb) + (1 | g), df, chains = 2L, iter = 300L,
                 warmup = 150L, verbose = -1, bart_args = list(n.trees = 25L))
summary(fit)

# observations by samples by chains
ev <- dbarts::extract(fit, "ev", combine_chains = FALSE)
group <- df$xb > 0.5
contrast <- apply(ev[group, , , drop = FALSE], 2:3, mean) -
  apply(ev[!group, , , drop = FALSE], 2:3, mean)
dbarts::rhat(contrast) # rhat() takes iterations by chains

Semiparametric Models Using a Gradient-Based Sampler and BART

Description

This function fits semi-parametric linear and probit models that have a non-parametric, BART component and one or more of a parametric fixed effect (unmodeled coefficients), or a parametric random effect (modeled coefficients). If f(x)f(x) is a BART “sum-of-trees” model, fits:

  • For continuous response variables:

    Y∣b∼N(f(Xb)+Xfβ+Zb,σ2)b∼N(0,Σb)Y \mid b \sim \mathrm{N}\left(f(X^b) + X^f\beta + Zb, \sigma^2\right) \\ b \sim \mathrm{N}(0, \Sigma_b)

  • For binary response variables:

    P(Y=1∣b)=Φ(f(Xb)+Xfβ+Zb)b∼N(0,Σb)P(Y = 1 \mid b) = \Phi\left(f(X^b) + X^f\beta + Zb\right) \\ b \sim \mathrm{N}(0, \Sigma_b)

Usage

stan4bart(formula,
          data = NULL,
          subset,
          weights,
          na.action = getOption("na.action", "na.omit"),
          offset,
          contrasts = NULL,
          test = NULL,
          treatment = NULL,
          offset_test = NULL,
          verbose = FALSE,
          iter = 2000L,
          warmup = iter %/% 2L,
          skip = 1L,
          chains = 4L,
          cores = getOption("mc.cores", 1L),
          refresh = max(iter %/% 10L, 1L),
          offset_type = c("default", "fixef", "ranef", "bart", "parametric"),
          seed = NA_integer_,
          keep_fits = TRUE,
          save_warmup = FALSE,
          store = c("fits", "trees"),
          callback = NULL,
          stan_args = NULL,
          bart_args = NULL,
          bart_range = c("mixed", "lm", "response"),
          prior = normal(0, 2.5, autoscale = TRUE),
          prior_aux = exponential(autoscale = TRUE),
          prior_covariance = decov(1, 1, 1, 1),
          QR = FALSE,
          adapt_delta = 0.8,
          init_r = 2)

Arguments

formula

a formula object, or one that can be coerced to that type. Terms on the right-hand-side of the formula that are encased in a symbolic call to bart() will be used to create the non-parametric component. Terms that use the lmer-style grouping syntax will be added as parametric, hierarchical varying intercepts and slopes. All other terms will be added as fixed effects. A formula whose bart() columns each hold one value on the rows kept has no non-parametric component and is refused, naming the columns: no tree can split on them.

data

an optional data frame containing the variables in the formula. Its use is strongly encouraged.

subset, weights, na.action, offset, contrasts

optional components adjusting the constructed model matrices and otherwise changing the linear predictor. na.action cannot be "na.pass". See lm and model.matrix.default. A row with a missing value in any part of the model - the response, a fixed effect, a variable of a random term, a BART predictor, the weights or the offset - is dropped from every part, so the model is fitted to the rows that are complete; under na.exclude the dropped rows are missing in what extract, fitted and residuals report. weights and offset are used as double precision numbers whatever type they are given in. For a binary response, weights follow dbarts's probit rule: weights identically 1 are treated as absent, weights that are all 0 and 1 name the rows in the data set and install as the BART component's active-row mask (a 0 row leaves both components' likelihoods but keeps its leaf occupancy, its latent and its fitted value), and any other weights are refused.

test

an optional data frame to be used as test data. If present, the test predictions will be stored as the sampler runs and can be extracted later.

treatment

an optional symbol, that when present and refers to a binary variable, will be used to create a test data frame with the treatment variable set to its counterfactual. Only one of test and treatment can be supplied.

offset_test

optional vector which will be added to the test predictions.

verbose

a logical or integer. If FALSE or non-positive, runs quietly. Additional levels of information may be displayed for increasingly positive numbers, however a large number of diagnostics are suppressed when running multi-threaded. If negative, all diagnostic information is ignored. A positive value also prints, before the chains start, lines about the initial fit. For a continuous response: one saying how the BART response range is being estimated, one where no BART predictor enters that estimate, and one where the range is the response's own because the initial fit is not defined on the data, because the fitted range has no width, or because it was wider than the response's own; see bart_range. For a binary response: one where the initial probit regression did not converge, or fits a probability of 0 or 1, and the fit starts from zero. That lme4 is not installed, and that an initial fit failed, are warnings and do not depend on verbose.

iter

positive integer indicating the number of posterior samples to draw and return. Includes warmup samples.

warmup

non-negative integer indicating number of posterior samples to draw and throw away. Also controls the number of iterations for which adaptation is run. The default (half of iter) is ample for the parametric sampler's step size and mass tuning to converge. If iter is shortened, keep warmup at or above roughly 100 for large-nn fits with many random-effect levels: under-warming leaves the tuning poor and can roughly double the per-iteration cost of the parametric step. The diagnostic is fit$adaptation$mean_leapfrog (mean leapfrog steps per transition during sampling; see ‘Value’ below) - a high value relative to a well-tuned fit indicates under-warming, and print and summary warn when it looks poor.

skip

one or two positive integers. Every skip sample will be kept, while every other sample will be discarded. If argument is length two, the named elements "bart" for BART and "stan" for the parametric part (the name is kept from earlier releases, which ran it in Stan) are used, and any other name is an error. If not named, BART is the first skip element and the parametric part is the second. This argument does not impact the number of iters returned, unlike a conventional “thinning” parameter. The parametric element applies to the sampling phase only; warmup keeps one parametric transition per sweep so that the parametric block cannot outrun the still-growing forest and park the response mean in the random intercepts. Raising it is the available remedy for a poorly mixing random-effect standard deviation - see ‘Details’.

chains

positive integer giving the number of Markov Chains to sample.

cores

positive integer giving the number of units of parallelization. Computation for each chain will be divide among the cores available. When greater than one, verbose output within chains will not be available.

refresh

positive integer giving the frequency with which diagnostic information should be printed as the sampler runs. Only applies with cores (or chains) equal to 1.

offset_type

character; an experimental/testing feature that controls how offset is to be interpreted. When one of "fixef", "ranef", or "bart", the offset is used to replace that part of the model. When "parametric", it replaces both of the fixed and random parametric components. Sampling is still done for these components and their draws are stored, however whenever they were present in the fit the supplied value is used instead.

seed

Optional integer specifying the desired pRNG seed. It should not be needed when running single-threaded - calling set.seed will suffice. The primary use of seed is to obtain reproducible results when multi-threaded. See Reproducibility section below.

keep_fits

Logical that, when false, prevents the sampler from storing each draw. Intended to be used with callback.

save_warmup

Logical; when FALSE (the default) the warmup draws are not stored. In their place, per chain, the frozen sampler tuning (step size and diagonal inverse mass), a warmup-end position snapshot, and a thinned trace of the monitored scalars are recorded in the adaptation component of the fit; this is what the 2026 Stan/mixed-model toolchain does and cuts the fit object roughly in half at scale (see the storage-policy note in docs/design/walnuts.md). When TRUE, the full per-draw warmup is stored under warmup as before, and include_warmup = TRUE accessors work; on a default fit those accessors raise an informative error.

store

character; how the fitted BART component is retained. "fits" (the default) stores the full n×n \times draws ×\times chains bart_train (and bart_test) blocks, as in prior releases. "trees" instead stores only the kept trees and recomputes those blocks on demand through the dbarts predict path; it implies keepTrees (and errors if bart_args contradicts it with keepTrees = FALSE). This is an opt-in memory/time trade: at rest the fit no longer carries the bart_train block, which is 94-98% of a large fit object (n >= 10000); in exchange every reader of the BART fits pays a recompute cost on access. fitted streams the posterior mean in row blocks, so its peak memory stays bounded, but extract must materialize the whole block (unavoidable) - roughly 15 s per call at n = 10000 with 4 chains x 1000 draws, and over a minute at n = 50000. Storing trees costs essentially nothing during sampling, but the mixing check replays the kept trees once when the fit ends, in row blocks, so its memory stays bounded. The saving only exists above a crossover near n = 550: below it the kept trees cost as much as the fits they replace and add latency, so "fits" remains the default and the recommended choice at small n. Under "trees" the bart_train/bart_test components are absent; read the BART fits through extract, fitted, or predict instead - those generics work unchanged under either setting. A "fits" fit retaining more than a gigabyte of per-draw blocks notes this alternative once per session.

callback

A function that will be called at each iteration, accepting three arguments: yhat.train, yhat.test, stan_pars. See details for more information.

stan_args

deprecated; its entries are now arguments of stan4bart of the same names (prior, prior_aux, prior_covariance, QR, adapt_delta, init_r). Given, each entry is used as the argument and a warning, once per session, names the arguments; an entry also given as an argument is an error, and a name that was never one is refused. It will be removed in a future release.

bart_args

optional list, specifying further arguments to BART. See details below.

prior

the prior on the fixed effect coefficients, as in stan_glmer of the rstanarm package. One of normal(location = 0, scale = NULL, autoscale = TRUE), student_t(df = 1, location = 0, scale = NULL, autoscale = TRUE) or cauchy(location = 0, scale = NULL, autoscale = TRUE); the default is normal(0, 2.5, autoscale = TRUE). NULL is a flat (improper) prior, as in rstanarm. The shrinkage families (hs, hs_plus, lasso, laplace, product_normal) are not supported by the gradient-based sampler and raise an error. The constructor is written in the argument and needs nothing attached, as k = chi(2, Inf) does in bart_args; a name is bound only where it is called. Passed on through a wrapper's ..., it is read where the wrapper's caller wrote it, so a local variable there is found, as it is for prior_aux, prior_covariance and bart_args. For a binary response stan4bart does not apply rstanarm's probit factor (dnorm(0) / dlogis(0) = 1.596): the normal, student_t and cauchy priors read their scales with the identity link, as written, so the same call is about 1.6 times narrower than in rstanarm.

prior_aux

the prior on the residual standard deviation (continuous responses only): exponential(rate = 1, autoscale = TRUE), the default, normal, student_t or cauchy, as in rstanarm; NULL is a flat (improper) prior, as in rstanarm.

prior_covariance

the prior on the random effect covariance matrices: decov(regularization = 1, concentration = 1, shape = 1, scale = 1), the default and the only choice.

QR

logical, default FALSE: whether to fit the fixed effects on a QR decomposition of their design matrix, mapped back after sampling. It needs two or more fixed predictors, and changes how the prior is read as well as the sampler's geometry, as in rstanarm.

adapt_delta

the acceptance rate the parametric sampler's step size is tuned to, a value in (0,1)(0, 1), default 0.8. A higher value gives a smaller step size and more gradient evaluations per transition, and is the setting to raise if the parametric block shows divergences; a lower value takes larger, cheaper steps.

init_r

half-width of the interval, centered at zero, that the parametric sampler's initial position is drawn from uniformly, on the unconstrained scale; at least zero, default 2.

bart_range

for a continuous response, the range of values the BART component is calibrated to: a pair of numbers c(lower, upper), or the name of an estimate, one of "mixed", "lm", or "response". BART states its prior between the two numbers: the prior on the sum-of-trees function at any point has its mean at the middle of the range and, at the default k = 2, a standard deviation of a quarter of its width. The range is fixed before sampling and is the same for every chain.

  • "mixed", the default - a linear mixed model is fitted first to the observations of positive weight: the model's fixed and random terms as written, with the BART predictors added as linear terms (an unordered factor as indicators of its levels). The range is the smallest and largest value of the response, less any offset, less the fixed and random part of that fit that belongs to the model as written; the part that belongs to the BART predictors is left in. The mixed model is fitted by lme4; see the subsection on the initial fit below. A model with no random term is fitted as a linear model.

  • "lm" - the same fit without the random terms. It is the choice for large crossed grouping factors, where the mixed model can take longer than the sampler itself; in small samples it gives a wider range than "mixed" and a less accurate fit.

  • "response" - the range of the response less any offset. Nothing is fitted.

Under "response" and under a pair, BART's first sweep is fitted to the response less any offset, with no part of it assigned to the model's own terms. An estimated range is never wider than the response's own: where the fit would give a wider one, and where the fit cannot be computed, the response's own range is used and the range.fallback component of the result says why. A pair is used as it is given, whatever the data, and is the way to ask for any other range, for example range(y). Where the response less any offset takes one value on the observations of positive weight there is no range to fix: none is recorded, and BART's own treatment of such a response stands. A response that is constant altogether stops the fit under the default prior on the residual standard deviation, which is scaled by the response's.

Where a column of the model's own takes one value in each category of an unordered BART factor, as a region's median income beside region inside bart(), the factor's indicators and the intercept span it, and the initial fit alone would set its coefficient by which categories are left without an indicator, that is by the order of the category names. It is given instead the slope of the least-squares line through the fit's category totals (the part of its fixed effects constant within the categories), each category counted once whatever its number of observations or weights; the category totals' deviations from the line belong to the BART predictors. Several such columns of one factor take one least-squares fit. Where the column is constant within the categories of two BART factors, those of one lying each within one of the other's (states within regions), the line is the finer factor's, each of its categories counted once. The coefficient is left as the fit sets it, so that the range can still depend on the order of the category names, for a column constant only within the joint categories of two factors, for one constant within a factor's categories only in combination with other columns, and where some combination of the initial fit's other columns, other than a constant, is also constant within the factor's categories, as the indicators of a second factor are when the categories of both lie within those of a coarser grouping.

A BART factor with many categories makes the initial fit slow and memory-hungry: its indicators are a dense block of observations by categories. A pair or "response" fits nothing and avoids it.

Too narrow a range leaves group-level signal in the random effects that belongs to BART, and too wide a one costs accuracy and mixing in small samples. The linear terms that stand in for BART in the initial fit cannot follow a strongly curved group-level effect, which is a case for giving a pair. A binary response has no range, and a value other than the default is ignored with a warning.

Details

Fits a Bayesian “mixed effect” model with a non-parametric Bayesian Additive Regression Trees (BART) component. For continuous responses:

  • Yi∣b∼N(f(Xib)+Xifβ+Zibg[i],σ2)Y_i \mid b \sim \mathrm{N}\left(f(X^b_i) + X^f_i\beta + Z_ib_{g[i]}, \sigma^2\right)

  • bj∼N(0,Σb)b_j \sim \mathrm{N}(0, \Sigma_b)

where bjb_j are the “random effects” - random intercepts and slopes - that correspond to group jj, g[i]g[i] is a mapping from individual ii to its group index, ff - a BART sum-of-trees model, XbX^b are predictors used in the BART model, XfX^f are predictors in a parametric, linear “fixed effect” component, ZZ is the design matrix for the random intercept and slopes, and sigmasigma and SigmabSigma_b are variance components.

Binary outcome models are obtained by assuming a latent variable that has the above distribution, and that the observed response is 1 when that variable is positive and 0 otherwise. The response variable marginally has the distribution:

  • P(Yi=1∣b)=Φ(f(Xib)+Xifβ+Zibg[i])P(Y_i = 1 \mid b) = \Phi\left(f(X^b_i) + X^f_i\beta + Z_ib_{g[i]}\right)

where Φ\Phi is the cumulative distribution function of the standard normal distribution.

Terminology

As stan4bart fits a Bayesian model, essentially all components are “modeled”. Furthermore, as it has two first-level, non-hierarchical components, “fixed” effects are ambiguous. Thus we adopt:

  • “fixed” - refers only to the parametric, linear, individual level mean component, XfβX^f\beta; these are “unmodeled coefficients” in other contexts

  • “random” - refers only to the parametric, linear, hierarchical mean component, ZbZb; these are “modeled coefficients” in other contexts

  • “bart” - refers only to the nonparametric, individual level mean component, f(Xb)f(X^b)

Model Specification

Model specification occurs in the formula object, according to the following rules:

  • variables or terms specified inside a pseudo-call to bart are used for the “bart” component, e.g. y ~ bart(x_1 + x_2)

  • variables or terms specified according to lmer syntax are used for the “random” effect component, e.g. y ~ (1 | g_1) + (1 + x_3 | g_1)

  • remaining variables not inside a bart or “bars” construct are used for the “fixed” effect component; e.g. y ~ x_4

All three components can be present in a single model, however are bart part must present. If you wish to fit a model without one, use stan_glmer in the rstanarm package instead.

Factor variables are handled differently in each component. In the fixed and random components they use the usual model.matrix contrasts and lme4 grouping-factor machinery, respectively. In the bart component a factor is encoded as dbarts's categorical splits: a single column whose tree prior chooses level subsets to split on, rather than one indicator column per level. Consequently extract(type = "varcount") reports one row per factor, named by the factor's variable name, not one row per level. A factor level in newdata (to predict) or test that was not observed when fitting is an error for a bart factor; this is unlike the random component, where an unseen grouping level is handled per sample_new_levels in extract.

Additional Arguments

The parametric part of the model is configured by prior, prior_aux, prior_covariance, QR, adapt_delta and init_r, which follow rstanarm's names and meanings, and the BART part by bart_args. stan4bart no longer uses Stan: the parametric component is sampled by a gradient-based WALNUTS sampler driven by a hand-derived analytic log-posterior gradient. The prior constructors (normal, student_t, cauchy, exponential, decov) are written inside the argument that takes them; see the help page for stan_glmer in the rstanarm package for what each means. There is no prior on an intercept: BART carries it. bart_args is similar to bart, but not identical, as stan4bart constructs its own model internally.

Two settings of the sampler are for measurement and debugging and are not arguments. The option stan4bart.ridge_move (default TRUE) switches the exact slice move that draws the random-effect scale once per sweep along the curve that rescales a grouping factor's standard deviation; the option stan4bart.save_raw_parameters (default FALSE), when TRUE, keeps the raw unconstrained rows of the stored parametric draw and its placeholder diagnostic rows.

Until 0.0-13 these entries were given as one list, stan_args. It is deprecated and used as the arguments: each entry named prior, prior_aux, prior_covariance, QR, adapt_delta or init_r goes to the argument of that name, with one warning a session naming them. prior_intercept, adapt_gamma, adapt_kappa, adapt_t0, adapt_init_buffer, adapt_term_buffer, adapt_window, stepsize, stepsize_jitter and max_treedepth configured Stan and have no analog under WALNUTS; they are accepted so that existing scripts do not error, are ignored, and a warning names each one supplied. Any other name is an error that names the accepted ones.

BART arguments include:

  • further arguments to dbartsControl that are not specified by stan4bart, such as keepTrees; keeping trees can be costly in terms of memory, but is required to use predict

  • n.trees, the number of trees, and n.cuts and useQuantiles, which place the cut points; each is a setting of the model or the data and not of the control

  • the prior arguments of dbartsSpec - leaf.prior and the tree prior's power, base and split.probs. These are expressions, not values: dbarts resolves them in its own prior vocabulary (see dbartsPriors), so a bare leaf.prior = normal(k = chi(1.25, Inf)) works whether or not dbarts is attached. They must be written literally in the stan4bart call, since bart_args is read off it unevaluated; a prior assembled beforehand has to be built with dbarts::dbartsPriors$... instead

  • the remaining model-level arguments of dbartsSpec - proposal.probs, monotone, and seed. Unlike the priors these are ordinary values, evaluated in the caller's frame like any other argument

  • interactions and blocks, dbarts's forest vocabulary (see dbartsForests). Written as a call inside bart_args, such as interactions(max.order = 1), they resolve to the dbarts constructor whether or not dbarts is attached, and are evaluated in the caller's own frame, so a local variable referenced inside the call is found, also where bart_args is passed on through a wrapper's .... A specification assembled beforehand has to be built with dbarts::dbartsForests$... instead

  • k, shorthand for leaf.prior = normal(k = k). It is a value too, not an expression, so it does not see dbarts's prior-evaluation environment; write the prior out in full when that matters. Supplying both k and leaf.prior is an error

sigma, resid.prior, resid.dist, and variance are not accepted: the parametric component draws the residual standard deviation and the BART component conditions on it, so the forest holds its own error scale fixed and has no residual model to configure. Neither is family, beyond naming the one the response already implies ("gaussian" or "probit") - the response family follows the fitted data, and the remaining dbarts families are not wired into the two-block sampler.

The initial fit and lme4

Before sampling, the model is fitted once without its BART component: for a continuous response whose range is estimated, "mixed" or "lm", to fix the range BART is calibrated to (see bart_range) and the values the first sweep starts from, and for a binary response to give the first sweep the values it starts from. Where the model has random terms this is a mixed model, fitted by lme4 when it is installed: that of lmer for a continuous response and of glmer for a binary one.

lme4 is a suggested package. Without it, a continuous model with random terms takes the response's own range and a binary one starts from a probit regression on its fixed effects alone, each with a warning. The fit is then not the one obtained with lme4 installed, including under a fixed seed; results can also differ between versions of lme4. What that costs was measured on simulated data of 500 rows with a random intercept on groups of 4 or of 25, ten data sets each, fitted with four chains of 1000 warmup and 1000 kept draws. Without lme4 a continuous response was given a range 1.3 to 1.4 times as wide. The error of its fitted mean was 1.5 percent higher with groups of 4 and 0.5 percent higher with groups of 25, where a second seed with lme4 moved it by 1.0 and 0.7 percent, and the fitted mean's effective sample size was 20 and 13 percent lower, where a second seed moved it by 8 and 1 percent. The error of a binary response's fitted probabilities moved by 0.7 percent or less, and by 0.4 percent or less at a second seed with lme4.

A model with no random term never uses lme4. Where lme4's fit stops, or returns estimates that are not finite, a warning says so and the fit proceeds as it does without lme4, a binary one from a start of zero. The initial fits were checked against lmer and glmer of lme4 2.1.0 and 1.1-35.5.

Random effect scale mixing

The random effect covariance is sampled in its non-centered form: a scale and a block of standardized effects whose product is the effect itself. When the group effects are well identified - many observations per group - the log scale and the standardized effects are constrained to a product ridge, a direction the sampler's diagonal metric cannot rescale. Every other direction of the parametric block mixes freely; that one does not, and the random effect standard deviations inherit its autocorrelation.

The remedy is the "stan" element of skip: it takes that many parametric transitions per BART sweep and keeps the last, at that multiple of the parametric block's cost and no change to the number of draws returned. On a 20-group, 100-observations-per-group Gaussian random intercept fit, skip = c(bart = 1, stan = 8) takes the scale's lag-1 autocorrelation from about 0.96 to about 0.77 and stan = 16 to about 0.63, at 1.4x and 2.0x the wall time. How far it has to go tracks how strongly the groups are identified, so read the autocorrelation of the fit in hand rather than carrying a number over. The wall-time cost is real - a parametric transition is roughly a third of a BART sweep - so raise it when the scale is the quantity of interest, not by default.

Reproducibility

Behavior differs when running multi- and single-threaded, as the pseudo random number generators (pRNG) used by R are not thread safe. When single-threaded, R's built-in generator is used; if set at the start, .Random.seed will be used and its value updated as samples are drawn. When multi-threaded, the default behavior is draw new random seeds for each thread using the clock and use thread-specific pRNGs.

This behavior can be modified by setting seed. For the single-threaded case, that seed will be installed and the existing seed replaced at the end, if applicable. For multi-threaded runs, the seeds for threads are drawn sequentially using the supplied seed, and will not change the state of R's built-in generator.

Consequently, the seed argument should not be needed when running single-threaded - set.seed will suffice. When multi-threaded, seed can be used to obtain reproducible results.

Callbacks

Callbacks can be used to avoid expensive memory allocation, aggregating results as the sampler proceeds instead of waiting until the end. A callback funtion must accept the arguments:

  • yhat.train - BART predictions of the expected value of the training data, conditioned on the Stan parameters

  • yhat.test - when applicable, the same values as above but for the test data; NULL otherwise

  • stan_pars - named vector of parametric-component samples, including fixed and random effects and variance parameters

It is expected that the callback will return a vector of the same length each time. If not, invalid memory writes will likely result. If the result of the callback has names, they will be added to the result.

Serialization

At present, stan4bart models cannot be safely saved and loaded in a way that the sampler can be restarted. This feature may be added in the future.

Mixing check

After each fit, the split rank-normalized R-hat (Vehtari et al., 2021, as posterior::rhat) is computed for sigma (not for a binary response), for the standard deviations of each grouping factor's random effects, and for fit: each draw's in-sample root mean squared difference between the expected value and the response (on the probability scale for a binary response). Fixed effects, individual group effects and trees are not checked. No warning is issued; summary prints all of them on one line, as values with no flag (see summary.stan4bartFit for how to read them). A single chain is checked by comparing its halves. Only the saved draws are read, never warmup, and a quantity that cannot be compared, such as one with fewer than four draws per chain, is not checked. fit is summed in blocks of rows, as fitted streams, so its memory stays bounded; if computing it fails, as for want of memory, it is left unchecked (NA, with the reason in summary) and the fit is returned.

Value

Returns a list assigned class stan4bartFit. Has components below, some of which will be NULL if not applicable.

Input values:

y

response vector

weights

weights vector or null

offset

offset vector or null

frame

joint model frame for all components

formula

formula used to specify the model

na.action

supplied na.action

call

original call

Stored data:

bartData

data object used for BART component

X

fixed effect design matrix or NULL

X_means

column means of fixed effect design matrix when appropriate

reTrms

random effect “terms” object when applicable, as used by lmer

test

named list when applicable, having components X and reTrms; test data for BART is added to the bartData result

treatment

treatment vector, when applicable

Results, better accessed using extract:

bart_train

samples of individual posterior predictions for BART component; absent (recomputed from the kept trees on access) when store = "trees"

bart_test

predicted test values for BART component, when applicable; likewise absent under store = "trees"

bart_varcount

BART variable counts

sigma

samples of residual standard error; not present for binary outcomes

k

samples of the leaf sensitivity parameter; only present when it is modeled

ranef

samples of random effects, or modeled coefficients; will be a named list, with effects for each grouping factor

Sigma

samples of covariance of random effects; also a named list with one element for each grouping factor

fixef

samples of the fixed effects, or unmodeled coefficients

callback

samples returned by an optional callback function

Other items:

mixing

named vector of the split R-hats of the checked quantities: sigma, one “group sd” per grouping factor term, and fit; NA for one that could not be computed

warmup

a list of warmup samples, containing the same objects in the results subsection; present only when save_warmup = TRUE

adaptation

present when warmup was run and save_warmup is FALSE. A list with, per chain, the frozen step_size, the diagonal inv_mass, the mean number of leapfrog (gradient evaluation) steps per transition during the sampling phase (mean_leapfrog) and during warmup (mean_leapfrog_warmup) - the runtime-relevant tuning diagnostic; a high mean_leapfrog relative to a well-tuned fit indicates under-warming (see the warmup argument above) - a warmup-end snapshot of the parametric draw, and a trace (a thinned warmup trace of the monitored scalars: the parametric stan rows and the BART sigma) for a qualitative where-did-it-stabilize plot

range.bart

for a continuous response, the pair c(lower, upper) the BART component is calibrated to, the same for every chain; NULL for a binary response, and for a response that, less any offset, takes one value on the observations of positive weight

range.route

how that range was asked for: "mixed", "lm", "response", or "supplied" for a pair

range.fallback

present only where the range is the response's own although another was asked for: "lme4", it is not installed; "undefined", the initial fit is not defined on these data or its range has no width; "failed", the initial fit raised an error; or "wider", the fitted range was wider than the response's own

range.info

a list describing the initial fit behind the range: the number of observations n and of fixed columns p it used; fit, one of "lme4", "linear", or "none"; the names of the BART columns added, of the columns dropped as linear combinations of earlier ones, and of the BART factors left.out because they are nested in a grouping factor; and the fit's variance parameters theta and sigma with the optimizer's message

sampler.bart

present when keepTrees is TRUE: a list of one BART sampler per chain, each holding its chain's kept trees. Read by predict, by extract and fitted under store = "trees", and by extract(type = "trees"). The samplers do not survive a reload; they are rebuilt from state.bart the first time one is needed and kept in bart_env, and the same happens when this element is removed. A saved fit holds copies of the training data in each sampler, so removing both, fit$sampler.bart <- NULL and fit$bart_env$ptr <- NULL, just before saveRDS makes the file smaller. The cost is the rebuild, which draws from R's random number generator, as after a reload

state.bart

present when keepTrees is TRUE: each chain's stored sampler state, from which the samplers are rebuilt

bart_env

present when keepTrees is TRUE: an environment whose element ptr holds the rebuilt samplers. It is shared by every copy of the fit and saved with it

Author(s)

Vincent Dorie: [email protected].

See Also

bart, lmer, and stan_glmer in the rstanarm package

Examples

# simulate data (extension of Friedman MARS paper)
# x consists of 10 variables, only first 5 matter
# x_4 is linear
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
n.g.1 <- 5L
n.g.2 <- 8L

# sample observation level covariates and calculate marginal mean
x <- matrix(runif(n * 10), n, 10)
mu.bart  <- f(x) - 10 * x[,4]
mu.fixef <- 10 * x[,4]

# varying intercepts and slopes for first grouping factor
g.1 <- sample(n.g.1, n, replace = TRUE)
Sigma.b.1 <- matrix(c(1.5^2, .2, .2, 1^2), 2)
b.1 <- matrix(rnorm(2 * n.g.1), n.g.1) %*% chol(Sigma.b.1)

# varying intercepts for second grouping factor
g.2 <- sample(n.g.2, n, replace = TRUE)
Sigma.b.2 <- as.matrix(1.2)
b.2 <- rnorm(n.g.2, 0, sqrt(Sigma.b.2))

mu.ranef <- b.1[g.1,1] + x[,4] * b.1[g.1,2] + b.2[g.2]

y <- mu.bart + mu.fixef + mu.ranef + rnorm(n, 0, sigma)

df <- data.frame(y, x, g.1, g.2)

fit <- stan4bart(
    formula = y ~
        X4 +                         # linear component ("fixef")
        (1 + X4 | g.1) + (1 | g.2) + # multilevel ("ranef")
        bart(. - g.1 - g.2 - X4),    # use bart for other variables
    verbose = -1, # suppress ALL output
    # low numbers for illustration
    data = df,
    chains = 1, iter = 10, bart_args = list(n.trees = 5))

# posterior means of individual expected values
y.hat <- fitted(fit)

# posterior means of the random effects
ranef.hat <- fitted(fit, type = "ranef")

Generic Functions for stan4bart Model Fits

Description

Commonly expected utility functions to derive useful quantities from fitted models.

Usage

## S3 method for class 'stan4bartFit'
extract(
  object,
  type = c("ev", "ppd", "fixef", "indiv.fixef", "ranef", "indiv.ranef",
           "indiv.bart", "sigma", "Sigma", "k", "varcount", "stan",
           "trees", "callback"),
  sample = c("train", "test"),
  combine_chains = TRUE,
  sample_new_levels = TRUE,
  include_warmup = FALSE,
  ...)
  
## S3 method for class 'stan4bartFit'
fitted(
  object,
  type = c("ev", "ppd", "fixef", "indiv.fixef", "ranef", "indiv.ranef",
           "indiv.bart", "sigma", "Sigma", "k", "varcount", "stan",
           "callback"),
  sample = c("train", "test"),
  sample_new_levels = TRUE,
  ...)

## S3 method for class 'stan4bartFit'
residuals(object, ...)

## S3 method for class 'stan4bartFit'
predict(
  object, newdata,
  type = c("ev", "ppd", "indiv.fixef", "indiv.ranef", "indiv.bart"),
  combine_chains = TRUE,
  sample_new_levels = TRUE,
  offset,
  ...)

Arguments

object

a fitted model resulting from a call to stan4bart.

type

a character vector; one of the options listed below.

sample

one of "train" or "test", indicating if the training or test data frames should be used.

combine_chains

logical controlling if chain information should be discarded and the result returned as a matrix instead of an array.

sample_new_levels

logical; if TRUE, levels out of the training sample will have random effects drawn from their posterior predictive distribution. If FALSE, their random effects will be fixed to 0.

include_warmup

logical or "only"; when TRUE/FALSE, warmup samples will or will not be included in the result respectively. When "only", only the warmup samples will be returned.

newdata

data frame for making out of sample predictions.

offset

optional vector which will be added to test predictors.

...

not currently in use, but provided to match signatures of other generics.

Details

extract is used to obtain raw samples using the training or test data, fitted averages those samples, and predict operates on data not available at the time of fitting. Note: predict requires that the model be fit with bart_args = list(keepTrees = TRUE).

Return type

The type argument accepts:

  • "ev" - the individual level expected value, that is draws from E[Y∣Xb,Xf,Z]∣Y=f(Xb)+Xfβ+Zb∣YE[Y \mid X^b, X^f, Z] \mid Y = f(X^b) + X^f\beta + Zb \mid Y where the expectation is with respect to the posterior distribution of the parameters given the data

  • "ppd" - draws from the individual level posterior predictive distribution, generally speaking adding noise to the result for "ev" or simulating new Bernoulli trials. The mean of these draws estimates the same quantity as the mean of the "ev" draws (times the weights, for a weighted binomial model), so if only the posterior-predictive mean is needed, fitted(type = "ev") computes it exactly and faster; fitted(type = "ppd") notes this once per session. fitted(type = "ppd") averages freshly drawn samples, so under a fixed seed it reproduces an average of extract(type = "ppd") bitwise.

  • "fixef" - draws from the posterior of the fixed effects (also known as the “unmodeled” coefficients), β∣Y\beta \mid Y

  • "indiv.fixef" - draws from the posterior distribution of the individual level mean component deriving from the fixed effects, XfβX^f\beta

  • "ranef" - the random effects, varying intercepts and slopes, or “modeled” coefficients, bb; bb has substantial structure that is represented as the returned value, where coefficients are reported within their grouping factors

  • "indiv.ranef" - individual level mean component deriving from the random effects, ZbZb

  • "indiv.bart" - individual level mean component deriving from the BART model, f(Xb)f(X^b)

  • "sigma" - for continuous responses, the residual standard error

  • "Sigma" - when applicable, the covariance matrices of the random effects

  • "stan" - raw matrix or array of the parametric component's sampled transformed parameters (named "stan" for historical reasons; the parametric component is now sampled with a gradient-based WALNUTS sampler rather than Stan's NUTS).

  • "trees" - a data frame of flatted trees; see the subsection on extracted trees in bart and note that stan4bart variable names can be found in the bartData@x element of a fitted stan4bart model. The chain column is present only for a fit with more than one chain. For a continuous response a leaf's value is in the one internal unit every chain shares, set by the fit's range.bart: at an observation, the values of the leaves it falls in, summed over a draw's trees, times the width of that range, plus its middle, are that draw's BART fit. A fit saved by a version that fixed no range has none, and its leaf values are in each chain's own unit

  • "callback" - if a callback function was provided while fitting, the results of that for each sample

Value

extract and predict return either arrays of dimensions equal to n.observations x n.samples x n.chains when combine_chains is FALSE, or matrices of dimensions equal to n.observations x (n.samples * n.chains) when combine_chains is TRUE.

fitted returns a vector of the appropriate length by averaging the result of a call to extract.

residuals returns the response residuals on the training rows: the observed response less fitted(object, type = "ev"), the posterior mean of its expected value. For a binary response that expected value is the probability of a 1.

Author(s)

Vincent Dorie: [email protected].