Skip to contents

The na.action that bart, dbarts and dbartsData default to. It drops the rows whose response is missing and keeps the rows whose predictors are.

Usage

na.keepPredictors(object, ...)

Arguments

object

A model frame, as model.frame hands its na.action; the response is the column the frame's terms attribute names, and a frame with no response loses no rows.

...

Ignored, for compatibility with the other na.action functions.

Details

BART routes a missing predictor value down a learned side of each split rule (“Missingness Incorporated in Attributes”), so an incomplete row is data rather than a hole and dropping it discards information the model can use. A missing response, on the other hand, is nothing to fit. This function is that distinction: na.omit would drop both. rpart's na.rpart is the behavioral precedent.

The dropped rows are recorded exactly as na.exclude records them - a named integer vector of class "exclude" - so the training fits pad back to the caller's own row count through naresid: fitted, residuals and yhat.train.mean on the fit are as long as the data, NA where a row was dropped, while yhat.train and extract hold the kept rows only.

The base functions keep their usual meaning on these entry points: na.omit drops any row with a missing value anywhere and pads nothing, na.exclude drops the same rows and pads, na.fail refuses any missing value, and na.pass keeps every row - after which a missing response is an error, since there is nothing to fit it against.

On the matrix (x.train, y.train) interface, where there is no model frame, the na.action is applied to a frame standing for the (response, predictors) pair, so every one of these functions means on that interface what it means on the formula one.

At Prediction

Every predict method on a fit (predict.bart and bart's four own classes) and survivalProbabilities take an na.action for newdata, defaulting to this function; NULL applies no action, which on new data gives the default's result, and getOption("na.action") is never consulted.

A missing value in newdata is routable when its column can hold missing values: it had them in training or, on a sampler, has been given them since (see dbartsSampler). Every split rule on that column then holds a side for them, and the row predicts like any other. On a column that has never held one no rule holds a side, so the value is unroutable. Only the default and na.pass look at this:

  • na.keepPredictors predicts every routable row and refuses an unroutable one, naming its columns;

  • na.pass predicts every routable row and returns NA for an unroutable one;

  • na.omit drops every row with a missing value;

  • na.exclude drops the same rows and pads them back as NA, so the result stays aligned with newdata, as the fit-time record does (predict.lm instead treats it as na.omit on new data);

  • na.fail refuses any missing value, naming its columns.

Any other function is applied to a one-column frame that is NA on the rows with a missing value, on every interface, and the rows it keeps then meet the default's refusal. The result carries newdata's row names and no "na.action" attribute. When no row survives, or newdata has none, the result has the usual draw dimensions and zero rows (NA rows under na.exclude and na.pass), and R's random number stream is left as it was.

A per-row offset, weights or bases must match newdata's rows and loses the rows na.action drops; a single value passes through unaffected. A missing value in a per-row offset or weights (an n x K category shift counts as one, on a multinomial fit) marks its row incomplete exactly as an unroutable predictor does, and every na.action above governs it the same way: the default and na.fail refuse it by name, na.pass returns NA for it, and na.omit/na.exclude drop it (na.exclude padding it back). On a binomial fit given no weights, a predictive draw's missing success or failure count in newdata's response columns marks its row the same way, unless the columns miss a count in every row and so are read as absent (see the family item of bart). A missing value in a single (length-one) offset or weights is always an error, whatever na.action is, since there is then no row for it to mark. A missing value in bases never marks its row: on a row that is incomplete for its predictors, its offset or its weights, which the na.action drops or returns NA for, it is passed by, and on any other row it is an error, whatever na.action is.

With no newdata, predict answers the training rows, which have no predictor to route, and a missing value in a per-row offset or weights marks its row incomplete in the same way: every na.action above governs it as it does at newdata, the default and na.fail refusing it, na.pass returning the row with NA draws, and na.omit and na.exclude dropping it, na.exclude padding it back. Only the rows na.action keeps are read and drawn, as at newdata, so under one seed a posterior predictive draw is that of the call at newdata with the same action, and with the rows dropped it is that of the call on the rows kept (except for a multinomial fit on a matrix of counts, whose own rows draw a count vector each where newdata draws one category), and a single missing value is always an error. survivalProbabilities answers a missing value in the offset it is given for the fit's own subjects in the same way. The sampler's own predict, predictForests and getTrees methods take no na.action, keep the default, and check no per-row offset.test for a missing value at all: an NA there reaches the engine unrouted.

Value

object with the missing-response rows removed, carrying an "na.action" attribute of class "exclude" naming them; or object unchanged when no response value is missing.

Examples

df <- data.frame(y = c(1, NA, 3, 4), x = c(1, 2, NA, 4))

# the response row goes, the predictor row stays
model.frame(y ~ x, df, na.action = na.keepPredictors)
#>   y  x
#> 1 1  1
#> 3 3 NA
#> 4 4  4

# and the fit's training values pad back to the data's own length
fit <- bart(
  y ~ x, df,
  n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE
)
length(fitted(fit)) == nrow(df)
#> [1] TRUE