plot.spectral_model: Plot results of a given model

In proximetricsR: Spectral Preprocessing and Chemometric Calibration of NIR Sensors

Plot results of a given model

Description

\loadmathjax

Create a html file for a number of useful analytical plots using the R Quarto file "model_plot_template.qmd" for the given model x of class spectral_model.

Usage

## S3 method for class 'spectral_model'
plot(
  x,
  validations = NULL,
  output_file = x$target_variable,
  output_dir = NULL,
  spectral = c("weights", "coefficients", "scores", "mahalanobis"),
  cv = c("error", "response", "residuals", "qq", "distributions"),
  regression = NULL,
  validation = if (!is.null(validations)) "all" else NULL,
  sample_group = NULL,
  validation_group = NULL,
  verbose = TRUE, open_file = TRUE, ...
 )

Arguments

x	an object of class "spectral_model". This model should be generated using the calibrate function.
validations	an optional object of class "spectral_validation". This object, if provided, should be generated using validate_prediction. Default is NULL.
output_file	a character string for the name of the generated file. Default is the target name saved in model x.
output_dir	a string for the directory in which the file is generated. Default is NULL, which writes the file to tempdir().
spectral	a character vector of spectral plots to include, "all" to include every spectral plot, or NULL to skip the section entirely. Available names: "raw", "preprocessed", "weights", "loadings", "coefficients", "scores", "scores_3d", "scaled_scores", "mahalanobis".
cv	a character vector of cross-validation plots to include, "all" to include every CV plot, or NULL to skip the section entirely. Available names: "error", "response", "response_overview", "residuals", "qq", "q_values", "distributions".
regression	a character vector of regression analysis plots to include, "all" to include every regression plot, or NULL (default) to skip the section entirely. Available names: "response", "response_overview", "residuals", "qq", "residuals_vs_fitted", "scale_location", "leverage".
validation	a character vector of validation plots to include, "all" to include every validation plot, or NULL to skip. Available names: "predicted_vs_reference", "leverage_vs_residual". Defaults to "all" when validations is supplied, NULL otherwise.
sample_group	a named list of samples that should have the same color. See details. Default is NULL, meaning no grouping is done. Note that this is only to distinguish samples for the plots; the model itself remains unchanged.
validation_group	a named list of validation samples that should have the same color, analogous to sample_group but for the plots in the validation section. Indices refer to the position of each sample within the validation set (as returned by validate_prediction), not to calibration sample indices. Default is NULL, meaning no grouping is done.
verbose	a logical. When TRUE (default), prints the path of the generated file. Pandoc output is always suppressed.
open_file	a logical, indicating whether the file should automatically be opened in a browser after compilation. Defaults to TRUE.
...	additional graphical parameters. See details.

Details

This function creates a html file from rendering the R Markdown file 'model_plot_template.qmd' using quarto::quarto_render(). This will generate an .html file with the given output_file as its name in the directory specified by output_dir. Note that any existing file in the given directory of similar name will be overwritten.

The file opens automatically in the default browser of the system if open_file is set to TRUE.

Depending on the size of the provided dataset, the produced file might take a long time to process, and the files can quickly get quite large. The four section arguments (spectral, cv, regression, validation) control which plots are included. Each accepts a character vector of plot names, "all" to include the entire section, or NULL to skip it. For example, to render every available plot:

plot(x, spectral = 'all', cv = 'all', regression = 'all',
     validation = 'all')

The available plots per section are as follows (defaults marked with *):

spectral

• Raw Spectra: A line plot of all raw spectra. Only available if input data is saved inside the model x, i.e. if the method calibrate was called with return_inputs is set to TRUE. Note that the depicted spectrum always has a resolution of 10.

• Preprocessed spectra: A line plot of all preprocessed spectra. Note that the depicted spectrum always has a resolution of 10.

• Weights*: A line plot of all weights.

• Loadings: A line plot of all loadings.

• Coefficients*: A line plot of all regression coefficients.

• Scores*: A points plot of scores for each component.

• 3D Scores: A three dimensional points plot of scores for each component. The component for the x-axis can be selected with a slider. The corresponding y- and z-axis are the previous and next component, respectively.

• Scaled Scores: A points plot of the scaled scores for each component.

• Mahalanobis Distance*: A points plot of the Mahalanobis distance of the scaled scores of each component.

cv

Only available if the calibration used cross-validation. For leave-group-out cross-validation, only "error" is available.

• Error measures*: A plot of error and precision measures. In particular, this plot depicts the largest residual, the RMSE and the R- squared measures for the cross-validation for all components. The optimal component is highlighted.

• CV Response Plot*: A points plot of the reference values versus the cross-validation predictions made by the model for each component. Additionally, the identity line is added, plus a regression line fitted with the use of the a linear regression model.

• CV Response Plot Overview: An overview of all CV Response Plot in a single plot.

• CV Residuals*: A points plot of the residuals of the cross-validated predictions, for every component.

• Q-Q Plot of CV Residuals*: A Q-Q plot of the sample quantiles of the standardized cross-validated residuals against the theoretical quantiles of a normal distribution for each component. A line with intercept zero and slope one is depicted.

• CV Q-Values: A points plot of the Q-values of the cross- validation in the model for each component. See details of calibrate for an explanation of the Q-values.

• Distributions*: A line plot of the densities of the reference values and the cross-validated predictions for each component.

regression

These plots do not necessarily indicate model performance - more components generally improve fit but may overfit. Useful for identifying outliers. Similar to plot.lm.

• Response Plot: A points plot of the reference values versus the fitted values for each component. Additionally, the identity line is added and a regression line is fitted using a linear regression model.

• Response Plots Overview: An overview of all Response plots in a single plot.

• Residuals: A points plot of the residuals of the fitted values for each component.

• Q-Q Plot of Residuals: A Q-Q plot of the sample quantiles of the standardized residuals against the theoretical quantiles of a normal distribution for each component. A line with intercept zero and slope one is depicted.

• Residuals vs Fitted: A points plot of the fitted values against their residuals for each component. Additionally, a line for the LOESS smoother is depicted.

• Scale Location Plot: A points plot of the fitted values against the square roots of the absolute values of the standardized residuals for each component. Additionally, a line for the LOESS smother is depicted.

• Leverage vs Residuals: A points plot of the leverages of the fitted values against the standardized residuals for each component. Additionally, a line for the LOESS smother is depicted.

validation

Only available when validations is supplied (an object of class spectral_validation from validate_prediction).

• Predicted vs. Reference*: Shows the predictions of the new data obtained from the model versus the actual reference values, with an identity line, plus a regression line fitted with the use of a linear regression model. Additionally, the \mjeqnR^2R^2 and RMSE of both the validated predictions and model is depicted. See validate_prediction and predict for more details on the prediction and validation process.

• Leverage vs. Spectral Residual*: A points plot of the Mahalanobis distance (leverage) of each validated sample against its spectral (X-space) residual (Q). Both statistics are shown relative to their control limits (the leverage limit and the Q limit reported by predict at its control_limit_conf), so the limit is a dotted line at 1 on each axis and samples beyond 1 exceed the limit. When those limits are unavailable the raw statistics are plotted without limit lines. Not to be confused with the Leverage vs Residuals plot in the regression section, which uses the classical (univariate) leverage of the fitted response instead.

Most of above plots contain a slider, which may be used to adjust the considered component. The sliders start at the optimal components (if any calibration control was applied) or at the maximum number of components (otherwise).

Sample groups

The parameter sample_group defines samples that belong to the same group and should be displayed with the same color. The legend displays each group by the name given in the list (and an "Other" group for samples not listed).

The idea of this parameter is to allow the user to distinguish e.g. between different instruments. Each sample must belong to a single group, otherwise, this argument is ignored. Indices refer to the sample indices in the calibration statistics in the model.

The parameter validation_group works analogously, but for the plots in the validation section. Since validation samples are not part of the calibration set, indices instead refer to the position of a sample within the validation set (as returned by validate_prediction).

Additional parameters for graphics

The plots are constructed with the help of the plotly package. As such, the possibilities to manipulate the plots are as in that package. The arrangement of the plots is controlled by the quarto package.

Additional graphical parameters may be supplied to this function by using the ellipsis argument .... These arguments will be passed to some of the scatter and layout functions of plotly. More precisely, the arguments are passed to possible attributes of add_trace, and layout function of plotly. However, the following arguments will always be ignored:
c("p", "sliders", "x", "x0", "dx", "y", "y0", "dy", "visible", "type", "name", "hovertext", "text", "mode"),
as well as arguments passable to both add_trace, and layout. The "line" attribute is ignored when plotting markers and vice-versa. Some plots ignore the ellipsis argument altogether.

Possible attributes of these functions may be found by using the function schema of plotly.

Value

NULL. The desired plots are opened in a browser window.

Author(s)

Claudio Orellano, Leonardo Ramirez-Lopez

Examples

data("proximateCannabis")
control <- calibration_control(validation_type = "kfold", number = 3, folds = "sequential")
prepro_recipe <- preprocess_recipe(
  prep_resample(grid = c(1001, 1700, 2)),
  prep_snv(),
  prep_derivative(m = 1, w = 9, p = 7, algorithm = "nwp"),
  device = "proximate"
)
skips <- c(5, 13, 21, 73)
my_model <- calibrate(CBDA ~ spc,
  data = proximateCannabis, preprocess = prepro_recipe,
  method = fit_plsr(15), control = control, skip = skips, verbose = FALSE
)

plot(my_model, output_dir = tempdir())
# Include every available plot in every section
plot(my_model,
  output_dir = tempdir(),
  spectral = "all", cv = "all", regression = "all", validation = "all"
)
# Custom section selection with sample grouping
plot(
  my_model,
  output_file = "example_plot",
  output_dir = tempdir(),
  spectral = c("weights", "scores"),
  cv = "all",
  regression = NULL,
  sample_group = list(
    "Batch A" = 1:20,
    "Batch B" = 21:60,
    "Batch C" = 61:80
  )
)
# Make predictions and validate
preds <- predict(my_model, proximateCannabis[skips, ])
validations <- validate_prediction(preds, proximateCannabis$CBDA[skips])
# Plot validation section only, grouping validation samples by instrument.
# Indices in validation_group refer to the position of a sample within the
# validation set (i.e. within 'skips'), not to calibration sample indices.
plot(
  my_model,
  output_dir = tempdir(),
  output_file = "example_plot",
  validations = validations,
  spectral = NULL,
  cv = NULL,
  regression = NULL,
  validation_group = list(
    "Instrument A" = 1:2, # rows 5 and 13 of proximateCannabis (skips[1:2])
    "Instrument B" = 3:4 # rows 21 and 73 of proximateCannabis (skips[3:4])
  )
)

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