Range-ratio pseudo-label promotion • ssel

semiSupervisedPipeline() implements ssel’s row-promotion layer. It promotes selected prediction rows as pseudo-labels, refits the supervised helper family, and uses a separate OOF gauge to accept or revert a candidate round. Pseudo-labeling is a broad semi-supervised pattern (van Engelen and Hoos 2020), but the range ratio, budget, gauge, and state transitions below are package-defined policies. They are not tri-training, co-training regression, held-out validation, or calibrated predictive uncertainty.

Symbols and input pools

Let s=0,1,\ldots index rounds, r a response, u a prediction-row key, m a learner, and d a dataset. The first retained input CSV alone defines two ordered row-level vectors:

L=(u:\texttt{set}="train").

U=(u:\texttt{set}="predict").

These are vectors, not mathematical sets: order, duplicates, and missing keys remain. Consequently, |U|=\operatorname{length}(U) counts rows, while a later promotion budget spends unique keys. Other input CSVs are not checked to have matching pools.

allResponses should name every response column so non-target responses are removed before fitting. Missing names are ignored; an omitted response can therefore remain and be numerically coerced as a predictor.

Optional augmented-data warm start

When .path.iter is supplied, exactly one target response is required. The function reads lexically ordered metrics_<integer>.csv files, keeps that response’s ensemble.RMSE rows, and chooses the first row attaining the global maximum R^2. Its iteration number selects one datasets_<iterStar> directory.

This is an augmented-dataset snapshot selection. It does not consume a stitched model, rerun a chain sweep, or provide an iteration-zero fallback. Without .path.iter, iterStar in the return value is NA_integer_.

Range-ratio promotion score

For original prediction key u, response r, and round s, collect all available projected ordinary base-method predictions across configured datasets:

A_{ur}^{(s)}= \{f_{mdr}^{(s)}(u)\}_{\mathrm{available}}.

S_{ur}^{(s)}=\max A_{ur}^{(s)}-\min A_{ur}^{(s)}.

A pair is eligible only when at least two distinct method names are available; multiple datasets from one method do not satisfy this condition. Let \bar f_{ur,last}^{(s)}(u) be the last matching ordinary ensemble.RMSE value in response-file concatenation and update order. ssel defines

D_{ur}^{(s)}= \frac{S_{ur}^{(s)}} {\max\{1,|\bar f_{ur,last}^{(s)}(u)|\}}.

Promotion uses the strict comparison D_{ur}^{(s)}<\tau. Equal finite base predictions give D=0; a missing member makes the score missing. The score is dimensionless, but the fixed denominator floor makes it non-invariant to response rescaling and translation. It is neither a probability nor an uncertainty calibration.

base_predictions <- c(lm = 10, glm = 11)
ensemble_last <- 10.5
score <- diff(range(base_predictions)) / max(1, abs(ensemble_last))
c(score = score, promotes_at_tau_0.1 = score < 0.1)
#>               score promotes_at_tau_0.1 
#>           0.0952381           1.0000000

Key budget and pseudo-label rows

Let c=\texttt{promotionCap}, let P be the accepted pseudo-label table, and let K(P) be its unique keys. The remaining key budget is

B_s=\lfloor c|U|\rfloor-|K(P)|.

Candidate response pairs are ordered by ascending score. First-encountered new keys consume the budget; all eligible response pairs for retained keys remain. Pseudo-label values are all matching ordinary ensemble.RMSE rows. There is no median or cross-dataset reduction, so one pair can contribute several label rows.

This distinction is visible in the return value: history$promoted counts candidate pairs, whereas accepted history$cumulative and the returned promoted table count label rows. Because |U| counts rows but spending counts unique keys, duplicate prediction keys change the effective cap.

U <- c("P1", "P2")
promotion_cap <- 0.5
accepted_keys <- character()
floor(promotion_cap * length(U)) - length(unique(accepted_keys))
#> [1] 1

OOF acceptance gauge

For response r, let H_r^{(s)} contain reconstructed OOF residual rows whose key occurs in the original labelled vector L. Rows from all datasets and duplicates retain their multiplicity. The response score is squared sample correlation, and the round gauge is

g_s=\operatorname{mean}_r \{\operatorname{cor}(y,\hat y_{OOF})^2\}.

Missing response-level scores are omitted; surviving responses receive equal weight rather than row-count weight. This gauge uses oofEnsemble()’s independent cell-local inverse-RMSE reconstruction. It is not held-out risk, a fully nested OOF estimate, or a guarantee of generalization gain.

Let b_{s-1} be the historical best gauge and \varepsilon=\texttt{epsRevert}. A candidate is rejected only when

g_s<b_{s-1}-\varepsilon.

Equality is accepted. On acceptance, b_s=\max\{b_{s-1},g_s\}, so the accepted fitted state may be up to \varepsilon below the historical maximum. Returned finalR2 is that historical maximum; it is not necessarily the final fitted state’s gauge.

State transitions and return value

The history actions are:

Action	Meaning
`baseline`	supervised round-zero gauge
`accept`	candidate labels retained and historical best updated
`empty-stop`	no eligible pair passed the strict score gate
`saturation-stop`	no positive/new-key budget remained
`REVERT-stop`	candidate gauge crossed the absolute reversion threshold

Exhausting maxRounds adds no terminal row. Reversion materially refits the accepted pool, but it does not recompute the restoration gauge. The function returns history, accepted promoted label rows (or NULL), baselineR2, historical-best finalR2, and iterStar; it does not return a fitted model.

A minimal call has the following shape. See ?semiSupervisedPipeline for the complete executable temporary-directory example and all validation and file contracts.

result <- semiSupervisedPipeline(
  .path.datasets = datasets_dir,
  .path.work = work_dir,
  key = "SampleID",
  responses = "target",
  allResponses = "target",
  datasets = "demo",
  methods = c("lm", "glm"),
  seed = 2026,
  tau = 0.1,
  maxRounds = 1,
  epsRevert = Inf,
  promotionCap = 0.5
)
result$history

Final re-emission boundary

Every baseline, candidate, and restoration fit rebuilds the current round and calls the supervised workflow with the same seed. After the loop, the function rebuilds TEST files for the original prediction vector U and runs a serial trainRegressionModel(TRAIN = FALSE) pass. That pass overwrites cell metric and response files only. It does not rerun offset, summary, optimism, or final aggregation helpers; those products remain from the preceding full round.

This boundary matters when interpreting files after promotion. “Re-emission” means original-pool cell predictions, not regeneration of every summary and export product.

Limitations

A successful standalone teaching call uses one response. A standalone multi-response call can finish its full rounds and then fail final serial evaluation because other target columns remain as extra TEST-only columns.
Bounds are not reordered. For a>b, ordinary evaluation and OOF reconstruction execute different nested minimum/maximum operations; neither is interval projection.
Thresholds, caps, and tolerances are not proactively restricted to customary ranges. An all-missing response gauge can become NaN and later comparison can fail.
ssel establishes neither an empirical gain range nor a theorem that pseudo-label promotion improves or preserves predictive performance.

These are method limits, not optional fallback modes. Detailed input schemas, side effects, and failure timing are part of the function reference.

References

van Engelen, Jesper E., and Holger H. Hoos. 2020. “A Survey on Semi-Supervised Learning.” Machine Learning 109 (2): 373–440. https://doi.org/10.1007/s10994-019-05855-6.