R/recipe_steps.R

Defines functions required_pkgs_specproc_step tunable_specproc_step tidy_specproc_step print_specproc_step bake_specproc_step prep_specproc_step fit_step_filter strip_filter step_clutter step_outcome step_predictors specproc_step_new glsw_alpha step_y_gradient_glsw step_glsw step_epo step_o2pls step_opls step_projected_osc step_direct_osc step_direct_orthogonal step_osc

Documented in glsw_alpha step_direct_orthogonal step_direct_osc step_epo step_glsw step_o2pls step_opls step_osc step_projected_osc step_y_gradient_glsw

# Recipe steps for the orthogonalization filters (tidymodels).
#
# Each step estimates its filter in prep() and applies it in bake(), so that
# inside workflows and tune the filter is re-estimated on the analysis set of
# every resample. The steps replace the selected columns in place. recipes is
# only suggested: the S3 methods are registered when recipes is loaded.

#' @title Orthogonal Signal Correction Recipe Step
#'
#' @author Christian L. Goueguel
#'
#' @description
#' `step_osc()` creates a *specification* of a recipe step that removes the
#' variation of the selected predictors that is orthogonal to the outcome,
#' with [osc()]. The filter is estimated on the training data when the recipe
#' is prepped and applied to new data when it is baked.
#'
#' @details
#' The selected columns are replaced by the corrected values, which are
#' centered (and scaled, if `options = list(scale = TRUE)`). Because the
#' filter uses the outcome, it must be estimated on training data only.
#' Within a [workflows::workflow()] and [tune::tune_grid()], this happens
#' automatically for every resample. The outcome is not needed when new data
#' are baked.
#'
#' The related steps [step_direct_orthogonal()], [step_direct_osc()],
#' [step_projected_osc()], [step_opls()] and [step_o2pls()] (which also
#' handles several outcomes) remove response-orthogonal variation with other
#' algorithms. [step_epo()] and [step_glsw()] remove variation described by
#' external clutter, and [step_y_gradient_glsw()] down-weights variation
#' between samples with similar outcomes.
#'
#' # Tuning
#'
#' `num_comp` can be tuned with [tune::tune()]; its default range is
#' [dials::num_comp()] with values 1 to 4. When the model also has a
#' `num_comp` argument (for example, [parsnip::pls()]), give the step's
#' parameter its own id, such as `num_comp = tune("filter_comp")`, so that
#' the two can be tuned together:
#'
#' ```r
#' rec <- recipe(K ~ ., data = spectra) |>
#'   step_osc(all_predictors(), method = "fearn", num_comp = tune("filter_comp"))
#' model <- parsnip::pls(num_comp = tune()) |>
#'   set_mode("regression") |>
#'   set_engine("mixOmics", scale = FALSE)  # center only, like pls::plsr()
#' wf <- workflow(rec, model)
#' tune_grid(wf, resamples = group_vfold_cv(spectra, group = Sample), grid = 9)
#' ```
#'
#' # Tidying
#'
#' [tidy()][recipes::tidy.recipe] returns a tibble with columns `terms` (the
#' selected predictors), `num_comp` and `id`.
#'
#' @param recipe A recipe object. The step will be added to the sequence of
#'   operations for this recipe.
#' @param ... One or more selector functions to choose the predictors (for
#'   example, the spectral channels). See [recipes::selections()].
#' @param role Not used by this step, since no new variables are created.
#' @param trained A logical indicating whether the step has been trained.
#' @param outcome The outcome variable, as a bare name or a selector. If
#'   `NULL` (default), the single outcome of the recipe is used.
#' @param method The OSC algorithm: `"wold"`, `"sjoblom"` (default) or
#'   `"fearn"`. See [osc()].
#' @param num_comp The number of orthogonal components to remove.
#' @param options A list of further arguments passed to the underlying
#'   function, such as `scale`, `tol` or `max_iter` for [osc()].
#' @param res The fitted filter, stored once the step has been trained.
#' @param columns The names of the selected predictors, stored once the step
#'   has been trained.
#' @param skip A logical. Should the step be skipped when the recipe is baked
#'   by [recipes::bake()]? Keep the default `FALSE`, so that new data are
#'   corrected with the same filter as the training data.
#' @param id A character string that is unique to this step.
#'
#' @return An updated version of `recipe` with the new step added to the
#'   sequence of existing steps.
#'
#' @seealso [osc()], [predict.specproc_filter()]
#'
#' @export
#'
#' @examplesIf rlang::is_installed("recipes")
#' library(recipes)
#' data(forageLIBS)
#' # potassium and the K I resonance lines
#' wl <- suppressWarnings(as.numeric(names(forageLIBS)))
#' dat <- forageLIBS[c(which(names(forageLIBS) == "K"), which(wl > 760 & wl < 780))]
#' rec <- recipe(K ~ ., data = dat[1:300, ]) |>
#'   step_osc(all_predictors(), method = "fearn", num_comp = 2)
#' prepped <- prep(rec)
#' tidy(prepped, number = 1)
#' # new spectra are corrected with the filter estimated on the training data
#' bake(prepped, new_data = dat[301:368, -1])
step_osc <- function(recipe, ..., role = NA, trained = FALSE, outcome = NULL,
                     method = "sjoblom", num_comp = 2, options = list(),
                     res = NULL, columns = NULL, skip = FALSE,
                     id = recipes::rand_id("osc")) {
  rlang::check_installed("recipes")
  method <- match.arg(method, c("wold", "sjoblom", "fearn"))
  recipes::add_step(recipe, specproc_step_new(
    "osc", terms = rlang::enquos(...), role = role, trained = trained,
    outcome = rlang::enquos(outcome), method = method, num_comp = num_comp,
    options = options, res = res, columns = columns, skip = skip, id = id
  ))
}

#' @title Direct Orthogonalization Recipe Step
#'
#' @description
#' `step_direct_orthogonal()` creates a *specification* of a recipe step that
#' removes response-orthogonal variation from the selected predictors with
#' [direct_orthogonal()].
#'
#' @inherit step_osc details return
#' @inheritParams step_osc
#' @param options A list of further arguments passed to
#'   [direct_orthogonal()], such as `scale`.
#'
#' @seealso [direct_orthogonal()], [predict.specproc_filter()]
#' @export
#'
#' @examplesIf rlang::is_installed("recipes")
#' data(forageLIBS)
#' # potassium and the K I resonance lines
#' wl <- suppressWarnings(as.numeric(names(forageLIBS)))
#' dat <- forageLIBS[c(which(names(forageLIBS) == "K"), which(wl > 760 & wl < 780))]
#' rec <- recipes::recipe(K ~ ., data = dat[1:300, ]) |>
#'   step_direct_orthogonal(recipes::all_predictors(), num_comp = 2)
#' prepped <- recipes::prep(rec)
#' recipes::bake(prepped, new_data = dat[301:368, ])
step_direct_orthogonal <- function(recipe, ..., role = NA, trained = FALSE,
                                   outcome = NULL, num_comp = 2, options = list(),
                                   res = NULL, columns = NULL, skip = FALSE,
                                   id = recipes::rand_id("direct_orthogonal")) {
  rlang::check_installed("recipes")
  recipes::add_step(recipe, specproc_step_new(
    "direct_orthogonal", terms = rlang::enquos(...), role = role,
    trained = trained, outcome = rlang::enquos(outcome), num_comp = num_comp,
    options = options, res = res, columns = columns, skip = skip, id = id
  ))
}

#' @title Direct Orthogonal Signal Correction Recipe Step
#'
#' @description
#' `step_direct_osc()` creates a *specification* of a recipe step that
#' removes response-orthogonal variation from the selected predictors with
#' [direct_osc()].
#'
#' @inherit step_osc details return
#' @inheritParams step_osc
#' @param options A list of further arguments passed to [direct_osc()], such
#'   as `scale` or `tol`.
#'
#' @seealso [direct_osc()], [predict.specproc_filter()]
#' @export
#'
#' @examplesIf rlang::is_installed("recipes")
#' data(forageLIBS)
#' # potassium and the K I resonance lines
#' wl <- suppressWarnings(as.numeric(names(forageLIBS)))
#' dat <- forageLIBS[c(which(names(forageLIBS) == "K"), which(wl > 760 & wl < 780))]
#' rec <- recipes::recipe(K ~ ., data = dat[1:300, ]) |>
#'   step_direct_osc(recipes::all_predictors(), num_comp = 2)
#' prepped <- recipes::prep(rec)
#' recipes::bake(prepped, new_data = dat[301:368, ])
step_direct_osc <- function(recipe, ..., role = NA, trained = FALSE,
                            outcome = NULL, num_comp = 2, options = list(),
                            res = NULL, columns = NULL, skip = FALSE,
                            id = recipes::rand_id("direct_osc")) {
  rlang::check_installed("recipes")
  recipes::add_step(recipe, specproc_step_new(
    "direct_osc", terms = rlang::enquos(...), role = role, trained = trained,
    outcome = rlang::enquos(outcome), num_comp = num_comp, options = options,
    res = res, columns = columns, skip = skip, id = id
  ))
}

#' @title Projected Orthogonal Signal Correction (OPLS Filter) Recipe Step
#'
#' @description
#' `step_projected_osc()` creates a *specification* of a recipe step that
#' removes `num_comp` response-orthogonal components from the selected
#' predictors with [projected_osc()]. The result is the OPLS-filtered data
#' (equivalently, [o2pls()] with a single outcome).
#'
#' @inherit step_osc details return
#' @inheritParams step_osc
#' @param num_comp The number of orthogonal components to remove (`ncomp` of
#'   [projected_osc()]).
#' @param options A list of further arguments passed to [projected_osc()],
#'   such as `scale` or `tol`.
#'
#' @seealso [projected_osc()], [predict.specproc_filter()]
#' @export
#'
#' @examplesIf rlang::is_installed("recipes")
#' data(forageLIBS)
#' # potassium and the K I resonance lines
#' wl <- suppressWarnings(as.numeric(names(forageLIBS)))
#' dat <- forageLIBS[c(which(names(forageLIBS) == "K"), which(wl > 760 & wl < 780))]
#' rec <- recipes::recipe(K ~ ., data = dat[1:300, ]) |>
#'   step_projected_osc(recipes::all_predictors(), num_comp = 2)
#' prepped <- recipes::prep(rec)
#' recipes::bake(prepped, new_data = dat[301:368, ])
step_projected_osc <- function(recipe, ..., role = NA, trained = FALSE,
                               outcome = NULL, num_comp = 2, options = list(),
                               res = NULL, columns = NULL, skip = FALSE,
                               id = recipes::rand_id("projected_osc")) {
  rlang::check_installed("recipes")
  recipes::add_step(recipe, specproc_step_new(
    "projected_osc", terms = rlang::enquos(...), role = role,
    trained = trained, outcome = rlang::enquos(outcome), num_comp = num_comp,
    options = options, res = res, columns = columns, skip = skip, id = id
  ))
}

#' @title Orthogonal Projections to Latent Structures (OPLS) Recipe Step
#'
#' @description
#' `step_opls()` creates a *specification* of a recipe step that removes
#' `num_comp` orthogonal components from the selected predictors with the
#' OPLS model of [opls()]: the selected columns are replaced by the
#' OPLS-filtered data.
#'
#' @details
#' The filtered data are the same as those of [step_projected_osc()] with the
#' same `num_comp`. For Pareto scaling, add [step_pareto_scale()] before this
#' step. The model is fitted without cross-validation or permutation test,
#' which do not change the filter.
#' The number of orthogonal components is not selected automatically: tune
#' `num_comp` instead. As for [step_osc()], the filter uses the outcome and
#' is estimated on the training data only; the outcome is not needed when new
#' data are baked.
#'
#' # Tuning
#'
#' `num_comp` can be tuned with [tune::tune()]; its default range is
#' [dials::num_comp()] with values 1 to 4.
#'
#' # Tidying
#'
#' [tidy()][recipes::tidy.recipe] returns a tibble with columns `terms` (the
#' selected predictors), `num_comp` and `id`.
#'
#' @inherit step_osc return
#' @inheritParams step_osc
#' @param num_comp The number of orthogonal components to remove.
#' @param options A list of further arguments passed to [opls()]: `center`
#'   and `scale`.
#'
#' @seealso [opls()], [predict.specproc_opls()]
#' @export
#'
#' @examplesIf rlang::is_installed("recipes")
#' data(forageLIBS)
#' # potassium and the K I resonance lines
#' wl <- suppressWarnings(as.numeric(names(forageLIBS)))
#' dat <- forageLIBS[c(which(names(forageLIBS) == "K"), which(wl > 760 & wl < 780))]
#' # Pareto scaling, then the OPLS filter
#' rec <- recipes::recipe(K ~ ., data = dat[1:300, ]) |>
#'   step_pareto_scale(recipes::all_predictors()) |>
#'   step_opls(recipes::all_predictors(), num_comp = 2)
#' prepped <- recipes::prep(rec)
#' recipes::bake(prepped, new_data = dat[301:368, ])
step_opls <- function(recipe, ..., role = NA, trained = FALSE,
                      outcome = NULL, num_comp = 2, options = list(),
                      res = NULL, columns = NULL, skip = FALSE,
                      id = recipes::rand_id("opls")) {
  rlang::check_installed("recipes")
  recipes::add_step(recipe, specproc_step_new(
    "opls", terms = rlang::enquos(...), role = role,
    trained = trained, outcome = rlang::enquos(outcome), num_comp = num_comp,
    options = options, res = res, columns = columns, skip = skip, id = id
  ))
}

#' @title O2PLS Filter Recipe Step for One or Several Outcomes
#'
#' @description
#' `step_o2pls()` creates a *specification* of a recipe step that removes
#' `num_comp` outcome-orthogonal components from the selected predictors
#' with [o2pls()]. Unlike the other orthogonalization steps, the filter can
#' be estimated against several outcomes at once.
#'
#' @details
#' The joint (predictive) directions are the `joint_comp` dominant singular
#' vectors of \eqn{\textbf{Y}^T\textbf{X}}, and the removed components are the
#' systematic variation of the predictors orthogonal to them (Trygg and Wold,
#' 2003). Only the predictors are filtered: the outcomes are left unchanged,
#' so that models are fitted to, and assessed on, the measured values. (The
#' outcome-side filtering of [o2pls()], its `ny` argument, does not change the
#' filtered predictors.)
#'
#' With a single outcome and `joint_comp = 1`, the filtered data are those of
#' [step_opls()] and [step_projected_osc()] with the same `num_comp`.
#'
#' The selected columns are replaced by the filtered values, which are
#' centered (and scaled, if `options = list(scale = TRUE)`). The filter uses
#' the outcomes, so it is estimated on the training data only (on the
#' analysis set of each resample within [tune::tune_grid()]); the outcomes are
#' not needed when new data are baked.
#'
#' # Several outcomes
#'
#' Declare the outcomes in the recipe formula; a model that handles several
#' outcomes, such as [parsnip::pls()] with the mixOmics engine, then predicts
#' them all, with one column per outcome (`.pred_K`, `.pred_Ca`, ...):
#'
#' ```r
#' rec <- recipe(K + Ca ~ ., data = spectra) |>
#'   step_o2pls(all_predictors(), num_comp = 2, joint_comp = 2)
#' model <- parsnip::pls(num_comp = 2) |>
#'   set_mode("regression") |>
#'   set_engine("mixOmics", scale = FALSE)
#' fitted <- fit(workflow(rec, model), data = spectra)
#' predict(fitted, new_data = new_spectra)
#' ```
#'
#' Use `outcome` to estimate the filter against some of the outcomes only.
#'
#' # Tuning
#'
#' `num_comp` and `joint_comp` can be tuned with [tune::tune()] when the
#' recipe has a single outcome. Their default ranges are [dials::num_comp()]
#' with values 1 to 4 and 1 to 3; `joint_comp` cannot exceed the number of
#' outcomes.
#'
#' [tune::tune_grid()] does not support several outcomes. Instead, create
#' one workflow per outcome with the workflowsets package, and tune them all
#' with `workflowsets::workflow_map("tune_grid", ...)`. Each recipe has a
#' single outcome, for the model, but the filter can still be estimated
#' against all the outcomes: give the others a role of their own
#' (`"reference"` here), not needed to bake new data, and select them with
#' `outcome`. Each outcome gets its own number of filter and model components:
#'
#' ```r
#' outcomes <- c("K", "Ca", "Mg")
#' recipes <- purrr::map(outcomes, \(y) {
#'   recipe(reformulate(".", response = y), data = spectra) |>
#'     update_role(all_of(setdiff(outcomes, y)), new_role = "reference") |>
#'     update_role_requirements("reference", bake = FALSE) |>
#'     step_o2pls(all_predictors(), outcome = c(all_outcomes(), has_role("reference")),
#'                num_comp = tune("filter"), joint_comp = length(outcomes))
#' }) |>
#'   purrr::set_names(outcomes)
#' model <- parsnip::pls(num_comp = tune()) |>
#'   set_mode("regression") |>
#'   set_engine("mixOmics", scale = FALSE)
#'
#' wf_set <- workflow_set(preproc = recipes, models = list(pls = model))
#' res <- workflow_map(wf_set, "tune_grid", resamples = vfold_cv(spectra, v = 5),
#'                     grid = 10, metrics = metric_set(rmse), seed = 1)
#'
#' # best settings and final model of each outcome
#' fits <- purrr::map(purrr::set_names(res$wflow_id), \(id) {
#'   best <- select_best(extract_workflow_set_result(res, id), metric = "rmse")
#'   extract_workflow(res, id) |>
#'     finalize_workflow(best) |>
#'     fit(data = spectra)
#' })
#' purrr::map(fits, \(f) predict(f, new_data = new_spectra))
#' ```
#'
#' Select the outcomes by role (`all_outcomes()`, `has_role()`) rather than
#' with `all_of(outcomes)`, which refers to a variable outside the recipe.
#' To filter each outcome against itself only, drop the other outcomes from
#' its recipe instead; the step is then equivalent to [step_opls()]. Read
#' the results outcome by outcome: `workflowsets::rank_results()` would rank
#' workflows of different outcomes, whose RMSE are in different units.
#'
#' # Tidying
#'
#' [tidy()][recipes::tidy.recipe] returns a tibble with columns `terms` (the
#' selected predictors), `num_comp`, `joint_comp` and `id`.
#'
#' @inherit step_osc return
#' @inheritParams step_osc
#' @param outcome The outcome variables, as bare names or selectors. If
#'   `NULL` (default), all the outcomes of the recipe are used.
#' @param num_comp The number of outcome-orthogonal components to remove
#'   (`nx` in [o2pls()]).
#' @param joint_comp The number of joint (predictive) components (`ncomp` in
#'   [o2pls()]), at most the number of outcomes. Default is 1.
#' @param options A list of further arguments passed to [o2pls()]: `center`
#'   and `scale`.
#'
#' @references
#'    - Trygg, J., Wold, S., (2003).
#'      O2-PLS, a two-block (X–Y) latent variable regression (LVR) method with an integral OSC filter.
#'      J. Chemom. 17(1):53–64.
#'
#' @seealso [o2pls()], [predict.o2pls()][predict.specproc_filter]
#' @export
#'
#' @examplesIf rlang::is_installed("recipes")
#' data(forageLIBS)
#' # potassium, calcium and the spectral channels
#' dat <- forageLIBS[-c(1:2, 4:10, 12:14)]
#' rec <- recipes::recipe(K + Ca ~ ., data = dat[1:300, ]) |>
#'   step_o2pls(recipes::all_predictors(), num_comp = 2, joint_comp = 2)
#' prepped <- recipes::prep(rec)
#' recipes::tidy(prepped, number = 1)
#' dim(recipes::bake(prepped, new_data = dat[301:368, ]))
step_o2pls <- function(recipe, ..., role = NA, trained = FALSE,
                       outcome = NULL, num_comp = 2, joint_comp = 1, options = list(),
                       res = NULL, columns = NULL, skip = FALSE,
                       id = recipes::rand_id("o2pls")) {
  rlang::check_installed("recipes")
  recipes::add_step(recipe, specproc_step_new(
    "o2pls", terms = rlang::enquos(...), role = role,
    trained = trained, outcome = rlang::enquos(outcome), num_comp = num_comp,
    joint_comp = joint_comp, options = options, res = res, columns = columns,
    skip = skip, id = id
  ))
}

#' @title External Parameter Orthogonalization Recipe Step
#'
#' @description
#' `step_epo()` creates a *specification* of a recipe step that projects the
#' selected predictors onto the space orthogonal to the dominant directions
#' of a clutter matrix, with [epo()].
#'
#' @details
#' The clutter describes variation that should not affect the outcome, for
#' example the differences between repeated measurements of the same samples.
#' It is external information, supplied when the step is specified, and is
#' not estimated from the training data. If `clutter = NULL`, the dominant
#' directions of the training data themselves are removed, as in [epo()].
#' The outcome is not used.
#'
#' The selected columns are replaced by the corrected values (not centered).
#' `num_comp` can be tuned with [tune::tune()]. [tidy()][recipes::tidy.recipe]
#' returns the selected `terms`, `num_comp` and `id`.
#'
#' @inherit step_osc return
#' @inheritParams step_osc
#' @param clutter A numeric matrix or data frame of clutter spectra. If it
#'   has column names, the columns matching the selected predictors are used;
#'   otherwise it must have one column per selected predictor, in the same
#'   order.
#'
#' @seealso [epo()], [predict.specproc_filter()]
#' @export
#'
#' @examplesIf rlang::is_installed("recipes")
#' data(forageLIBS)
#' # potassium and the K I resonance lines
#' wl <- suppressWarnings(as.numeric(names(forageLIBS)))
#' dat <- forageLIBS[c(which(names(forageLIBS) == "K"), which(wl > 760 & wl < 780))]
#' # the three samples measured twice
#' twice <- forageLIBS$Sample[duplicated(forageLIBS$Sample)]
#' first <- match(twice, forageLIBS$Sample)
#' second <- vapply(twice, function(s) max(which(forageLIBS$Sample == s)), integer(1))
#' # their differences describe the variation between repeated measurements
#' clutter <- as.matrix(dat[second, -1]) - as.matrix(dat[first, -1])
#' rec <- recipes::recipe(K ~ ., data = dat[1:300, ]) |>
#'   step_epo(recipes::all_predictors(), clutter = clutter, num_comp = 1)
#' prepped <- recipes::prep(rec)
#' recipes::bake(prepped, new_data = dat[301:368, ])
step_epo <- function(recipe, ..., role = NA, trained = FALSE, clutter = NULL,
                     num_comp = 2, res = NULL, columns = NULL, skip = FALSE,
                     id = recipes::rand_id("epo")) {
  rlang::check_installed("recipes")
  recipes::add_step(recipe, specproc_step_new(
    "epo", terms = rlang::enquos(...), role = role, trained = trained,
    clutter = clutter, num_comp = num_comp, res = res, columns = columns,
    skip = skip, id = id
  ))
}

#' @title Generalized Least Squares Weighting Recipe Step
#'
#' @description
#' `step_glsw()` creates a *specification* of a recipe step that down-weights
#' the directions of the selected predictors that vary in a clutter matrix,
#' with the generalized least squares weighting filter of [glsw()].
#'
#' @details
#' `clutter` holds differences between spectra that should be identical, such
#' as `x2 - x1` for the paired spectra of [glsw()]. It is centered, so the
#' filter equals `glsw(x1, x2, alpha = a)`, where the absolute `a` is `alpha`
#' times the largest eigenvalue of the centered clutter cross-product. Setting
#' `alpha` relative to that eigenvalue makes it independent of the scale of
#' the spectra, which simplifies tuning: small values remove the clutter
#' directions almost completely (like [step_epo()]), large values leave the
#' data nearly unchanged.
#'
#' The filter is stored in factored form, so its memory use grows with the
#' number of predictors rather than its square. The selected columns are
#' replaced by the filtered values (not centered). `alpha` can be tuned with
#' [tune::tune()], using [glsw_alpha()]. [tidy()][recipes::tidy.recipe]
#' returns the selected `terms`, `alpha` (relative) and `id`.
#'
#' @inherit step_osc return
#' @inheritParams step_epo
#' @param clutter A numeric matrix or data frame of difference spectra. It is
#'   matched to the selected predictors as in [step_epo()].
#' @param alpha A positive number: the weighting parameter, relative to the
#'   largest eigenvalue of the clutter. Default is 0.01.
#'
#' @seealso [glsw()], [step_y_gradient_glsw()]
#' @export
#'
#' @examplesIf rlang::is_installed("recipes")
#' data(forageLIBS)
#' # potassium and the K I resonance lines
#' wl <- suppressWarnings(as.numeric(names(forageLIBS)))
#' dat <- forageLIBS[c(which(names(forageLIBS) == "K"), which(wl > 760 & wl < 780))]
#' # the three samples measured twice
#' twice <- forageLIBS$Sample[duplicated(forageLIBS$Sample)]
#' first <- match(twice, forageLIBS$Sample)
#' second <- vapply(twice, function(s) max(which(forageLIBS$Sample == s)), integer(1))
#' # their differences describe the variation between repeated measurements
#' clutter <- as.matrix(dat[second, -1]) - as.matrix(dat[first, -1])
#' rec <- recipes::recipe(K ~ ., data = dat[1:300, ]) |>
#'   step_glsw(recipes::all_predictors(), clutter = clutter, alpha = 0.01)
#' prepped <- recipes::prep(rec)
#' recipes::bake(prepped, new_data = dat[301:368, ])
step_glsw <- function(recipe, ..., role = NA, trained = FALSE, clutter,
                      alpha = 0.01, res = NULL, columns = NULL, skip = FALSE,
                      id = recipes::rand_id("glsw")) {
  rlang::check_installed("recipes")
  if (missing(clutter)) {
    stop("'clutter' must be provided.", call. = FALSE)
  }
  recipes::add_step(recipe, specproc_step_new(
    "glsw", terms = rlang::enquos(...), role = role, trained = trained,
    clutter = clutter, alpha = alpha, res = res, columns = columns,
    skip = skip, id = id
  ))
}

#' @title y-Gradient Generalized Least Squares Weighting Recipe Step
#'
#' @description
#' `step_y_gradient_glsw()` creates a *specification* of a recipe step that
#' down-weights variation between samples with similar outcomes, with the
#' filter of [y_gradient_glsw()].
#'
#' @details
#' As in [step_glsw()], `alpha` is relative to the largest eigenvalue of the
#' (weighted) gradient matrix, and the filter is stored in factored form. The
#' filter uses the outcome, so it is estimated on training data only; the
#' outcome is not needed when new data are baked. The selected columns are
#' replaced by the filtered values (not centered). `alpha` can be tuned with
#' [tune::tune()], using [glsw_alpha()]. [tidy()][recipes::tidy.recipe]
#' returns the selected `terms`, `alpha` (relative) and `id`.
#'
#' @inherit step_osc return
#' @inheritParams step_osc
#' @inheritParams step_glsw
#' @param window An odd integer giving the width of the Savitzky-Golay window
#'   used to compute the gradients. Default is 5.
#'
#' @seealso [y_gradient_glsw()], [step_glsw()]
#' @export
#'
#' @examplesIf rlang::is_installed("recipes")
#' data(forageLIBS)
#' # potassium and the K I resonance lines
#' wl <- suppressWarnings(as.numeric(names(forageLIBS)))
#' dat <- forageLIBS[c(which(names(forageLIBS) == "K"), which(wl > 760 & wl < 780))]
#' rec <- recipes::recipe(K ~ ., data = dat[1:300, ]) |>
#'   step_y_gradient_glsw(recipes::all_predictors(), alpha = 0.01)
#' prepped <- recipes::prep(rec)
#' recipes::bake(prepped, new_data = dat[301:368, ])
step_y_gradient_glsw <- function(recipe, ..., role = NA, trained = FALSE,
                                 outcome = NULL, alpha = 0.01, window = 5,
                                 res = NULL, columns = NULL, skip = FALSE,
                                 id = recipes::rand_id("y_gradient_glsw")) {
  rlang::check_installed("recipes")
  recipes::add_step(recipe, specproc_step_new(
    "y_gradient_glsw", terms = rlang::enquos(...), role = role,
    trained = trained, outcome = rlang::enquos(outcome), alpha = alpha,
    window = window, res = res, columns = columns, skip = skip, id = id
  ))
}

#' @title Relative GLSW Weighting Parameter
#'
#' @description
#' A [dials][dials::dials-package] parameter for the `alpha` argument of
#' [step_glsw()] and [step_y_gradient_glsw()], on a log10 scale.
#'
#' @param range A two-element vector with the range of `alpha`, in log10
#'   units. Default is `c(-4, 0)`, i.e. 0.0001 to 1.
#' @param trans A transformation object from the scales package. Default is
#'   log10.
#'
#' @return A `quant_param` object.
#' @export
#'
#' @examplesIf rlang::is_installed("dials")
#' glsw_alpha()
#' dials::value_seq(glsw_alpha(), 5)
glsw_alpha <- function(range = c(-4, 0), trans = scales::transform_log10()) {
  rlang::check_installed("dials")
  dials::new_quant_param(
    type = "double",
    range = range,
    inclusive = c(TRUE, TRUE),
    trans = trans,
    label = c(glsw_alpha = "GLSW weighting (relative)"),
    finalize = NULL
  )
}

# ---- internals ---------------------------------------------------------------

specproc_step_new <- function(subclass, terms, role, trained, skip, id, ...) {
  recipes::step(
    subclass = subclass, terms = terms, role = role, trained = trained,
    skip = skip, id = id, ...
  )
}

step_titles <- c(
  osc = "Orthogonal signal correction on ",
  direct_orthogonal = "Direct orthogonalization on ",
  direct_osc = "Direct orthogonal signal correction on ",
  projected_osc = "Projected OSC (OPLS filter) on ",
  opls = "OPLS filter on ",
  o2pls = "O2PLS filter on ",
  epo = "External parameter orthogonalization on ",
  glsw = "GLSW filter on ",
  y_gradient_glsw = "y-gradient GLSW filter on "
)

# Selected predictors, checked to be numeric.
step_predictors <- function(x, training, info) {
  rlang::check_installed("recipes")
  cols <- recipes::recipes_eval_select(x$terms, training, info)
  recipes::check_type(training[, cols], types = c("double", "integer"))
  unname(cols)
}

# Outcome names: the `outcome` argument, or the recipe's outcomes. Steps
# other than step_o2pls() and step_rsimpls() need a single outcome.
step_outcome <- function(x, training, info) {
  rlang::check_installed("recipes")
  y_name <- if (is.character(x$outcome)) {
    x$outcome  # already resolved when the step was trained
  } else if (length(x$outcome) == 0 || rlang::quo_is_null(x$outcome[[1]])) {
    info$variable[info$role %in% "outcome"]
  } else {
    recipes::recipes_argument_select(x$outcome, training, info, single = FALSE)
  }
  several <- inherits(x, c("step_o2pls", "step_rsimpls"))
  if (length(y_name) == 0 || (length(y_name) > 1 && !several)) {
    stop("`", class(x)[1], "()` needs ", if (several) "an" else "a single",
         " outcome: specify `outcome`.", call. = FALSE)
  }
  for (nm in y_name) {
    if (!is.numeric(training[[nm]])) {
      stop("The outcome `", nm, "` must be numeric.", call. = FALSE)
    }
  }
  y_name
}

# Clutter columns matching the selected predictors.
step_clutter <- function(clutter, cols) {
  rlang::check_installed("recipes")
  clutter <- as_numeric_matrix(clutter, "clutter")
  if (!is.null(colnames(clutter))) {
    missing_cols <- setdiff(cols, colnames(clutter))
    if (length(missing_cols) > 0) {
      stop("'clutter' has no column for ", length(missing_cols), " selected predictor(s), e.g. `",
           missing_cols[1], "`.", call. = FALSE)
    }
    clutter <- clutter[, cols, drop = FALSE]
  } else if (ncol(clutter) != length(cols)) {
    stop("'clutter' must have one column per selected predictor (", length(cols), ").", call. = FALSE)
  }
  clutter
}

# Keeps only what predict() needs from a fitted filter.
strip_filter <- function(fit) {
  fit[c("correction", "clutter", "scores", "score", "angle", "R2", "newdata", "singular_values",
        "x_scores", "orthoScores", "y_scores", "fitted", "correction_y")] <- NULL
  fit
}

# Fits the filter of a step to the training predictors (matrix x) and outcome.
fit_step_filter <- function(x, xmat, y) {
  k <- x$num_comp
  if (!is.null(k)) check_count(k, "num_comp")
  opts <- x$options %||% list()
  switch(
    class(x)[1],
    step_osc = strip_filter(do.call(osc, c(list(xmat, y, method = x$method, ncomp = k), opts))),
    step_direct_orthogonal = strip_filter(do.call(direct_orthogonal, c(list(xmat, y, ncomp = k), opts))),
    step_direct_osc = strip_filter(do.call(direct_osc, c(list(xmat, y, ncomp = k), opts))),
    step_projected_osc = strip_filter(do.call(projected_osc, c(list(xmat, y, ncomp = k), opts))),
    step_o2pls = {
      check_count(x$joint_comp, "joint_comp")
      strip_filter(do.call(o2pls, c(list(xmat, y, ncomp = x$joint_comp, nx = k, ny = 0), opts)))
    },
    step_opls = strip_filter(do.call(opls, c(list(xmat, y, ncomp = k, crossval = 0, permutation = 0), opts))),
    step_epo = {
      clutter <- if (is.null(x$clutter)) NULL else step_clutter(x$clutter, colnames(xmat))
      strip_filter(epo(xmat, ncomp = k, clutter = clutter))
    },
    step_glsw = {
      check_number(x$alpha, "alpha", lower = 0, lower_open = TRUE)
      d <- step_clutter(x$clutter, colnames(xmat))
      glsw_factor(scale(d, scale = FALSE), x$alpha)
    },
    step_y_gradient_glsw = {
      check_number(x$alpha, "alpha", lower = 0, lower_open = TRUE)
      check_count(x$window, "window", lower = 3)
      if (x$window %% 2 == 0) stop("'window' must be an odd integer.", call. = FALSE)
      g <- y_gradient(xmat, y, x$window)
      glsw_factor(g$w_i * g$x_diff, x$alpha)
    }
  )
}

prep_specproc_step <- function(x, training, info = NULL, ...) {
  cols <- step_predictors(x, training, info)
  supervised <- !class(x)[1] %in% c("step_epo", "step_glsw")
  y_name <- if (supervised) step_outcome(x, training, info) else NULL
  xmat <- as.matrix(training[, cols])
  storage.mode(xmat) <- "double"
  y <- if (!supervised) NULL else if (length(y_name) > 1) as.matrix(training[y_name]) else training[[y_name]]
  if (anyNA(xmat) || anyNA(y)) {
    stop("`", class(x)[1], "()` does not handle missing values; impute or remove them first.",
         call. = FALSE)
  }
  x$res <- fit_step_filter(x, xmat, y)
  x$columns <- cols
  if (supervised) x$outcome <- y_name
  x$trained <- TRUE
  x
}

bake_specproc_step <- function(object, new_data, ...) {
  cols <- object$columns
  recipes::check_new_data(cols, object, new_data)
  if (length(cols) == 0) {
    return(new_data)
  }
  xmat <- as.matrix(new_data[, cols])
  storage.mode(xmat) <- "double"
  corrected <- if (inherits(object$res, "specproc_filter") || inherits(object$res, "o2pls")) {
    as.matrix(stats::predict(object$res, xmat))
  } else {
    apply_glsw_factor(xmat, object$res)
  }
  new_data[cols] <- as.data.frame(corrected)
  new_data
}

print_specproc_step <- function(x, width = max(20, options()$width - 30), ...) {
  title <- step_titles[[sub("^step_", "", class(x)[1])]]
  recipes::print_step(x$columns, x$terms, x$trained, title, width)
  invisible(x)
}

tidy_specproc_step <- function(x, ...) {
  terms <- if (recipes::is_trained(x)) x$columns else recipes::sel2char(x$terms)
  param <- if (class(x)[1] %in% c("step_glsw", "step_y_gradient_glsw")) "alpha" else "num_comp"
  value <- x[[param]]
  if (!is.numeric(value)) value <- NA_real_
  res <- tibble::tibble(terms = terms)
  res[[param]] <- rep(value, length(terms))
  if (inherits(x, "step_o2pls")) {
    joint <- if (is.numeric(x$joint_comp)) x$joint_comp else NA_real_
    res$joint_comp <- rep(joint, length(terms))
  }
  res$id <- x$id
  res
}

tunable_specproc_step <- function(x, ...) {
  if (class(x)[1] %in% c("step_glsw", "step_y_gradient_glsw")) {
    tibble::tibble(
      name = "alpha",
      call_info = list(list(pkg = "specProc", fun = "glsw_alpha")),
      source = "recipe", component = class(x)[1], component_id = x$id
    )
  } else if (inherits(x, "step_o2pls")) {
    tibble::tibble(
      name = c("num_comp", "joint_comp"),
      call_info = list(
        list(pkg = "dials", fun = "num_comp", range = c(1L, 4L)),
        list(pkg = "dials", fun = "num_comp", range = c(1L, 3L))
      ),
      source = "recipe", component = class(x)[1], component_id = x$id
    )
  } else {
    tibble::tibble(
      name = "num_comp",
      call_info = list(list(pkg = "dials", fun = "num_comp", range = c(1L, 4L))),
      source = "recipe", component = class(x)[1], component_id = x$id
    )
  }
}

required_pkgs_specproc_step <- function(x, ...) {
  c("specProc")
}

# ---- S3 methods (registered when recipes / generics are loaded) ---------------

#' @exportS3Method recipes::prep
prep.step_osc <- prep_specproc_step
#' @exportS3Method recipes::prep
prep.step_direct_orthogonal <- prep_specproc_step
#' @exportS3Method recipes::prep
prep.step_direct_osc <- prep_specproc_step
#' @exportS3Method recipes::prep
prep.step_projected_osc <- prep_specproc_step
#' @exportS3Method recipes::prep
prep.step_opls <- prep_specproc_step
#' @exportS3Method recipes::prep
prep.step_o2pls <- prep_specproc_step
#' @exportS3Method recipes::prep
prep.step_epo <- prep_specproc_step
#' @exportS3Method recipes::prep
prep.step_glsw <- prep_specproc_step
#' @exportS3Method recipes::prep
prep.step_y_gradient_glsw <- prep_specproc_step

#' @exportS3Method recipes::bake
bake.step_osc <- bake_specproc_step
#' @exportS3Method recipes::bake
bake.step_direct_orthogonal <- bake_specproc_step
#' @exportS3Method recipes::bake
bake.step_direct_osc <- bake_specproc_step
#' @exportS3Method recipes::bake
bake.step_projected_osc <- bake_specproc_step
#' @exportS3Method recipes::bake
bake.step_opls <- bake_specproc_step
#' @exportS3Method recipes::bake
bake.step_o2pls <- bake_specproc_step
#' @exportS3Method recipes::bake
bake.step_epo <- bake_specproc_step
#' @exportS3Method recipes::bake
bake.step_glsw <- bake_specproc_step
#' @exportS3Method recipes::bake
bake.step_y_gradient_glsw <- bake_specproc_step

#' @export
print.step_osc <- print_specproc_step
#' @export
print.step_direct_orthogonal <- print_specproc_step
#' @export
print.step_direct_osc <- print_specproc_step
#' @export
print.step_projected_osc <- print_specproc_step
#' @export
print.step_opls <- print_specproc_step
#' @export
print.step_o2pls <- print_specproc_step
#' @export
print.step_epo <- print_specproc_step
#' @export
print.step_glsw <- print_specproc_step
#' @export
print.step_y_gradient_glsw <- print_specproc_step

#' @exportS3Method generics::tidy
tidy.step_osc <- tidy_specproc_step
#' @exportS3Method generics::tidy
tidy.step_direct_orthogonal <- tidy_specproc_step
#' @exportS3Method generics::tidy
tidy.step_direct_osc <- tidy_specproc_step
#' @exportS3Method generics::tidy
tidy.step_projected_osc <- tidy_specproc_step
#' @exportS3Method generics::tidy
tidy.step_opls <- tidy_specproc_step
#' @exportS3Method generics::tidy
tidy.step_o2pls <- tidy_specproc_step
#' @exportS3Method generics::tidy
tidy.step_epo <- tidy_specproc_step
#' @exportS3Method generics::tidy
tidy.step_glsw <- tidy_specproc_step
#' @exportS3Method generics::tidy
tidy.step_y_gradient_glsw <- tidy_specproc_step

#' @exportS3Method generics::tunable
tunable.step_osc <- tunable_specproc_step
#' @exportS3Method generics::tunable
tunable.step_direct_orthogonal <- tunable_specproc_step
#' @exportS3Method generics::tunable
tunable.step_direct_osc <- tunable_specproc_step
#' @exportS3Method generics::tunable
tunable.step_projected_osc <- tunable_specproc_step
#' @exportS3Method generics::tunable
tunable.step_opls <- tunable_specproc_step
#' @exportS3Method generics::tunable
tunable.step_o2pls <- tunable_specproc_step
#' @exportS3Method generics::tunable
tunable.step_epo <- tunable_specproc_step
#' @exportS3Method generics::tunable
tunable.step_glsw <- tunable_specproc_step
#' @exportS3Method generics::tunable
tunable.step_y_gradient_glsw <- tunable_specproc_step

#' @exportS3Method generics::required_pkgs
required_pkgs.step_osc <- required_pkgs_specproc_step
#' @exportS3Method generics::required_pkgs
required_pkgs.step_direct_orthogonal <- required_pkgs_specproc_step
#' @exportS3Method generics::required_pkgs
required_pkgs.step_direct_osc <- required_pkgs_specproc_step
#' @exportS3Method generics::required_pkgs
required_pkgs.step_projected_osc <- required_pkgs_specproc_step
#' @exportS3Method generics::required_pkgs
required_pkgs.step_opls <- required_pkgs_specproc_step
#' @exportS3Method generics::required_pkgs
required_pkgs.step_o2pls <- required_pkgs_specproc_step
#' @exportS3Method generics::required_pkgs
required_pkgs.step_epo <- required_pkgs_specproc_step
#' @exportS3Method generics::required_pkgs
required_pkgs.step_glsw <- required_pkgs_specproc_step
#' @exportS3Method generics::required_pkgs
required_pkgs.step_y_gradient_glsw <- required_pkgs_specproc_step

Try the specProc package in your browser

Any scripts or data that you put into this service are public.

specProc documentation built on Nov. 20, 2026, 5:11 p.m.