Fit every discovered response–dataset training cell

Training-only wrapper around trainRegressionModel(). It discovers split files created by buildDataset(), constructs the response–dataset grid, and requests every learner under ssel's standard fitting defaults. It does not evaluate fitted models, write metrics, or predict unseen rows.

Usage

trainModel(.path.train, .path.model, .path.metrics, .path.response,
  METHODS, PPROC = NULL, OVERRIDE = FALSE, .min = -Inf, .max = Inf,
  .responses = NULL)

Arguments

.path.train: Path to an existing directory containing split files. Files are discovered non-recursively by the suffix _TRAIN.csv.
.path.model: Path to the model-output directory. It is created non-recursively when absent, so its parent must exist and be writable.
.path.metrics: Path to a metrics directory. It is created when absent but receives no metric file from this training-only wrapper.
.path.response: Path to a prediction directory. It is created when absent but receives no prediction file from this training-only wrapper.
METHODS: A character vector of method identifiers accepted by caret::train(). Duplicate identifiers are removed. Their execution order is randomized for each dataset. An empty vector is not rejected, but no learner is then fitted.
PPROC: NULL, a character vector, or another preprocessing specification accepted by the preProcess argument of caret::train().
OVERRIDE: A non-missing logical scalar. If FALSE, an existing model is reused only when its companion feature-name hash exists and matches. If TRUE, every discovered cell is fitted again.
.min, .max: Numeric response bounds, in the response's units. They are forwarded to the cell engine for API consistency; this wrapper invokes training mode only, so the bounds do not alter fitting or training data. Their order and finiteness are not validated.
.responses: NULL, or a character vector restricting the discovered response names. NULL fits every discovered response. Requested names absent from the discovered files are ignored.

Value

Invisibly returns NULL. The fitted .Rds and .Rds.hash files are the result; .path.metrics and .path.response are only prepared for later evaluation calls.

Choosing the API layer

Use modelPipeline() when starting from assembled dataset CSVs and the complete supervised workflow is required. Use trainModel() when TRAIN split files already exist and the standard five-fold/RMSE fitting policy is appropriate. Call trainRegressionModel() with TRAIN = TRUE only when the requested response–dataset identifier grid, fold count, tuning granularity, preprocessing, metric, or parallel mode must be controlled directly. Fitted-model evaluation and delivery belong to predictModel(); this wrapper performs no evaluation despite receiving metrics and response paths.

Split-file contract

A training filename must have the form response_dataset_TRAIN.csv; suffix matching is case-sensitive. Discovery interprets the first two underscore-separated fields as response and dataset; those identifiers therefore cannot contain underscores. This restriction is not proactively validated. The parsed responses and datasets are deduplicated separately, then their Cartesian product is attempted. In a sparse set of source files, reconstructed pairs that were not present therefore warn and skip. Each CSV that is found must satisfy the trainRegressionModel() training schema: predictor columns followed by, or otherwise including, a numeric response column named y with at least two distinct non-missing values. If no filename matches, the output directories are still prepared and the function returns without fitting a model or emitting a warning.

Dataset order and the unique learner order are randomized with R's current random-number generator. Call set.seed() immediately before this function when repeatable ordering and caret resampling are required. Separate learner fits do not receive a shared caret resampling index, so the function does not promise identical folds across learners.

Fitting and cache policy

The wrapper fixes five-fold caret cross-validation, tuneLength = 10, metric = "RMSE", saved final-tuning holdout predictions, and the trainRegressionModel() default parallel policy. tuneLength requests a method-specific grid granularity; it is not ten values for every tuning parameter.

A successful learner fit writes a caret train object to method_response_dataset.Rds and a companion .Rds.hash text file under .path.model. The eight-character hash is derived only from the sorted predictor names. With OVERRIDE = FALSE, equal predictor names reuse the model even if response values, predictor values or classes, preprocessing, resampling, tuning, or other fitting arguments changed. Set OVERRIDE = TRUE whenever any of those inputs changed.

Conditions and side effects

A malformed discovered basename can be parsed into a reconstructed cell filename that does not exist; that cell is skipped with a warning. A split with no usable y, or with a constant y, is also skipped with a warning. A learner-specific caret failure warns and skips that learner; successfully fitted cells continue. The wrapper muffles caret's generic missing-resample- performance warning because the cell engine emits method/cell counts for missing tuning-grid or selected-fold RMSE values after a successful fit. Unused-connection warnings are muffled without a replacement diagnostic.

The fitting engine registers a PSOCK backend with at most two workers, then stops it and leaves foreach registered sequentially. Progress is emitted as messages unless options(aR.quiet = TRUE) is set. Existing model/hash files may be reused or overwritten as described above; other files are preserved.

References

Kuhn, M. (2008). Building predictive models in R using the caret package. Journal of Statistical Software, 28(5), 1–26. doi:10.18637/jss.v028.i05 . See also the caret documentation for caret::train() and caret::trainControl().

Examples

# \donttest{
root <- tempfile("ssel-trainModel-")
train_dir <- file.path(root, "train")
model_dir <- file.path(root, "model")
metrics_dir <- file.path(root, "metrics")
response_dir <- file.path(root, "response")
dir.create(train_dir, recursive = TRUE)

split <- data.frame(
  x = seq_len(20),
  z = rep(c(0, 1), 10),
  y = seq_len(20) / 3 + rep(c(-1, 1), 10)
)
utils::write.csv(
  split,
  file.path(train_dir, "target_demo_TRAIN.csv"),
  row.names = FALSE
)

set.seed(2026)
suppressMessages(trainModel(
  .path.train = train_dir,
  .path.model = model_dir,
  .path.metrics = metrics_dir,
  .path.response = response_dir,
  METHODS = "lm"
))
sort(basename(list.files(model_dir)))
#> [1] "lm_target_demo.Rds"      "lm_target_demo.Rds.hash"
# The result is one caret model and its predictor-name hash.

unlink(root, recursive = TRUE)
# }