Package 'GeoVersa'

Fit DB-TARF and predict a test set

Description

DB-TARF (Design-Based Targeted Adaptive Residual Forest) fits a random-forest base learner on train_df and adds a cross-fitted, out-of-fold-selected residual correction, then predicts test_df. A correction is adopted only when it lowers the out-of-fold RMSE of the calibration sample.

Usage

dbtarf_train_predict(
  train_df,
  test_df,
  response_name,
  predictor_names = NULL,
  coord_names = "auto",
  ...
)

Arguments

train_df	A data frame with the response, predictors and (optionally) coordinate columns.
test_df	A data frame with the same predictor (and coordinate) columns as train_df.
response_name	Character; name of the response column in train_df.
predictor_names	Character vector of predictor column names, or NULL (default) to infer them from train_df.
coord_names	Length-2 character vector of coordinate column names, or "auto" (default) to detect them.
...	Further arguments passed to the internal training routine (e.g. n_folds, lambda_grid, rf_tune, train_seed), and the top-k profile-ensemble controls ensemble_top_k (integer $\ge 1$, default 1: the single best profile, i.e. no blending), ensemble_weighting ("softmax", "inverse" or "uniform") and ensemble_temperature (positive, default 0.75); see dbtarf_default_params. The ensemble blends the top-k RF profiles (ranked by out-of-fold RMSE) and only activates when fair_profile_search is TRUE, (rf_tune or resid_rf_tune) is TRUE and ensemble_top_k > 1.

Value

A list with the test predictions (pred_test), the base-RF predictions (pred_test_base), conformal prediction-interval half-widths (pi_q90, pi_q95), per-run diagnostics and the candidate_table. When ensemble_top_k > 1 the diagnostics additionally record ensemble_applied, ensemble_size, ensemble_weighting, ensemble_temperature, ensemble_profiles, ensemble_profile_oof_rmse and ensemble_weights, and candidate_table gains ensemble_member, ensemble_rank and ensemble_weight columns. Note that when the ensemble is applied the conformal half-widths (pi_q90, pi_q95 and the _w/_sp variants) are inherited from the single best (top-ranked OOF) profile and are not recalibrated against the blended pred_test; the conformal coverage guarantee therefore pertains to the best single profile, not to the blended point estimate (diagnostics$ensemble_pi_from_best flags this).

Examples

set.seed(1)
n <- 120
tr <- data.frame(y = rnorm(n), a = rnorm(n), b = rnorm(n))
te <- tr[1:15, ]
out <- dbtarf_train_predict(tr, te, "y", c("a", "b"),
                            coord_names = NULL, rf_tune = FALSE,
                            fair_profile_search = FALSE)
head(out$pred_test)

---