Package {GeoVersa}

Title: Design-Based Residual-Correction Forests for Digital Soil Mapping
Version: 0.3.0
Description: Implements DB-TARF (Design-Based Targeted Adaptive Residual Forest) for large-scale digital soil and ecological mapping evaluated under the design-based paradigm of Wadoux et al. (2021) <doi:10.1016/j.ecolmodel.2021.109692>. A random forest is augmented by a cross-fitted, out-of-fold-selected residual correction (residual forests, ordinary kriging, recalibration), together with design-based conformal prediction intervals.
License: MIT + file LICENSE
Encoding: UTF-8
Imports: ranger, caret, stats, withr
Suggests: Cubist, gstat, sp, nnet, testthat (≥ 3.0.0)
RoxygenNote: 7.3.3
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2026-06-30 03:56:03 UTC; rodrigues.h
Author: Hugo Rodrigues [aut, cre]
Maintainer: Hugo Rodrigues <rodrigues.machado.hugo@gmail.com>
Repository: CRAN
Date/Publication: 2026-07-06 12:30:14 UTC

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)