calibrate_models: Calibrate models for multiple response variables
In proximetricsR: Spectral Preprocessing and Chemometric Calibration of NIR Sensors

calibrate_models

R Documentation

Calibrate models for multiple response variables

Description

\loadmathjax

Calibrate independent models (iteratively) for multiple properties with optimization of both the pre-processing recipe (based on a list of different recipes) and the regression method. This function uses calibrate to construct such list of models.

Usage

calibrate_models(formulas,
                 data, group = NULL,
                 preprocess_recipes,
                 methods,
                 control = calibration_control(seed = 1),
                 metadata_list = NULL,
                 skip_indices_list = NULL,
                 return_inputs = TRUE,
                 ...,
                 na_action = na.pass,
                 verbose = TRUE,
                 save_all = FALSE)

## S3 method for class 'spectral_multimodel'
predict(object, newdata, verbose = TRUE, ...)

Arguments

`formulas`	a list containing one or more objects of class `formula` where each of them represents the model to be calibrated.
`data`	a data.frame containing the data of the variables in the model (as in the `calibrate` function).
`group`	an optional factor (or character vector that can be coerced to `factor` by `as.factor`) that assigns a group/class label to each observation in `X` (e.g. groups can be given by spectra collected from the same batch of measurements, from the same observation, from observations with very similar origin, etc). This is taken into account for cross-validation for pls tuning (factor optimization) to avoid pseudo- replication. When one observation is selected for cross-validation, all observations of the same group are removed and assigned to validation. The length of the vector must be equal to the number of observations in `X`.
`preprocess_recipes`	a list with one or more objects of class `preprocess_recipe` that are to be tested for finding the optimal one for each model in the list passed to `formulas`.
`methods`	a list containing one or more objects of class `fit_constructor` as returned by `fit_plsr` or `fit_xlsr`, indicating what type of regression method to use along with its parameters.
`control`	a `calibration_control` object as returned by the `calibration_control` function, indicating how some aspects of the calibration process must be conducted (e.g. cross-validation and outlier detection). Default is `calibration_control(seed = 1)`. See details.
`metadata_list`	a list containing the specifications for the metadata of each model in `formulas` given in the same order. Each element in the list should be defined as in the `metadata` argument of `calibrate` using the `add_model_metadata` function. Defaults to `NULL`.
`skip_indices_list`	a list of vectors of integers for the indices in the input data to be skipped for the computation of each of the models in `formulas`. The vectors in this list must be provided in the same order as their corresponding counterparts in `formulas`. Defaults to `NULL`. In case a list is passed, the list components must be filled with `numeric()` for those `formulas` where there is no indices to be skipped.
`return_inputs`	a logical. For `calibrate` methods, indicates if the input data should be attached to the returned object. Note that this data is crucial for creating an application file.
`...`	arguments to be passed to the `calibrate` method. Not currently used for the `predict.spectral_multimodel` method.
`na_action`	a function to specify the action to be taken if `NA`s are found in the object passed in `data`. Default is `na.pass`.
`verbose`	a logical indicating whether or not to print a progress bar for the iterations of the validation along with messages of the execution of the cross-validation. For the predict method, messages about the progress are printed. Default is `TRUE`. Note: In case parallel processing is used, these progress bars are not printed.
`save_all`	a logical indicating if all the models tested (with the different pre-processing recipes) are to be saved. Default is `FALSE`.
`object`	an object of class `spectral_multimodel`.
`newdata`	a data.frame containing the new spectral data of the variables in the model, of similar form as `data`. Alternatively, can also be a matrix of spectra.

Details

The object passed to the control argument should indicate a seed for the random number generator (RNG). This allows the function to use the same cross-validation validation groups (for leave group-out cross-validation, see calibration_control) across the same formula with different recipes. This enables proper model comparisons.

Value

A list of class "spectral_multimodel" containing the following objects:

results_grid: a data.frame with the validation results of the best models found for each pre-processing recipe with the best regression method applied on the spectral data of the model built for each formula.
all_models: if save_all, a list with the spectral_model objects corresponding to all the models tested.
final_models: a list containing only the spectral_model objects corresponding to the best models found for each formula. This list can be used/passed later to the proximate_write_nax function to produce an application file (in that case it might be convenient to add some metadata to the resulting models in the list using the add_model_metadata function).

For predict(), a list with the following elements:

predictions: A matrix with the predictions of the response variable using the new spectral data (newdata), based on the provided models (object). Contains only the predictions of the optimal number of components (ncomp).
model_information: A list, containing information on the models inputs in object. Each component in the list contains the following information:
- target_var: A character, indicating the name of the target variable.
- preprocess_recipe: A character, indicating the spectral preprocessing recipe and its order.
- model_grid: A matrix, containing the grid of the model object, such as the coefficient of determination and the RMSE of the validation for the requested number of components.
- unit: A character, indicating the units of the model.
- opt_comp: An integer, signifying the optimal number of components as computed by the validation process of the model.

Parallel cross-validation

The cross-validation loop inside each call to calibrate is implemented with foreach, so it can be parallelised transparently by registering a parallel backend before calling calibrate_models. Set allow_parallel = TRUE in calibration_control (the default) and register a backend, for example:

cl <- parallel::makeCluster(parallel::detectCores() - 1L)
doParallel::registerDoParallel(cl)

result <- calibrate_models(...)

parallel::stopCluster(cl)

When no parallel backend is registered, foreach falls back silently to sequential execution regardless of the allow_parallel setting. Note that progress bars are suppressed during parallel execution.

Author(s)

Leonardo Ramirez-Lopez and Claudio Orellano

Examples


data("proximateCannabis")
# the list of formulas for the models to be built
app_formulas <- list(THC ~ spc, THCA ~ spc, CBD ~ spc, CBDA ~ spc)

# the list of pre-processing recipes to be tested
precipes <- list(
  recipe_1 = preprocess_recipe(
    prep_resample(grid = c(1001, 1700, 2)),
    prep_snv(),
    prep_derivative(m = 1, w = 9, p = 7, algorithm = "nwp"),
    device = "proximate"
  ),
  recipe_2 = preprocess_recipe(
    prep_resample(grid = c(1001, 1700, 2)),
    prep_snv(),
    prep_derivative(m = 2, w = 11, p = 9, algorithm = "nwp"),
    device = "proximate"
  )
)

optimized_app <- calibrate_models(
  formulas = app_formulas,
  data = proximateCannabis,
  preprocess_recipes = precipes,
  methods = list(fit_plsr(15, type = "nwp")),
  return_inputs = TRUE,
  save_all = FALSE
)

optimized_app

proximetricsR documentation built on Sept. 4, 2026, 5:08 p.m.