Version:	0.14.2
Title:	Multivariate Data Analysis for Chemometrics
Date:	2024-08-02
Maintainer:	Sergey Kucheryavskiy <svkucheryavski@gmail.com>
Description:	Projection based methods for preprocessing, exploring and analysis of multivariate data used in chemometrics. S. Kucheryavskiy (2020) <doi:10.1016/j.chemolab.2020.103937>.
Encoding:	UTF-8
License:	MIT + file LICENSE
Imports:	methods, graphics, grDevices, stats, Matrix
RoxygenNote:	7.3.2
Suggests:	testthat, pcv
NeedsCompilation:	no
Packaged:	2024-08-03 13:08:07 UTC; svkucheryavski
Depends:	R (≥ 3.5.0)
URL:	https://mda.tools
BugReports:	https://github.com/svkucheryavski/mdatools/issues
Author:	Sergey Kucheryavskiy [aut, cre]
Repository:	CRAN
Date/Publication:	2024-08-19 10:30:15 UTC

as.matrix method for classification results

Description

Generic as.matrix function for classification results. Returns matrix with performance values for specific class.

Usage

## S3 method for class 'classres'
as.matrix(x, ncomp = NULL, nc = 1, ...)

Arguments

as.matrix method for ldecomp object

Description

Generic as.matrix function for linear decomposition. Returns a matrix with information about the decomposition.

Usage

## S3 method for class 'ldecomp'
as.matrix(x, ncomp = NULL, ...)

Arguments

as.matrix method for PLS-DA results

Description

Returns a matrix with model performance statistics for PLS-DA results

Usage

## S3 method for class 'plsdares'
as.matrix(x, ncomp = NULL, nc = 1, ...)

Arguments

as.matrix method for PLS results

Description

Returns a matrix with model performance statistics for PLS results

Usage

## S3 method for class 'plsres'
as.matrix(x, ncomp = NULL, ny = 1, ...)

Arguments

as.matrix method for regression coefficients class

Description

returns matrix with regression coeffocoents for given response number and amount of components

Usage

## S3 method for class 'regcoeffs'
as.matrix(x, ncomp = 1, ny = 1, ...)

Arguments

as.matrix method for regression results

Description

Returns a matrix with model performance statistics for regression results

Usage

## S3 method for class 'regres'
as.matrix(x, ncomp = NULL, ny = 1, ...)

Arguments

as.matrix method for SIMCAM results

Description

Generic as.matrix function for SIMCAM results. Returns matrix with performance values for specific class.

Usage

## S3 method for class 'simcamres'
as.matrix(x, nc = seq_len(x$nclasses), ...)

Arguments

as.matrix method for SIMCA classification results

Description

Generic as.matrix function for classification results. Returns matrix with performance values for specific class.

Usage

## S3 method for class 'simcares'
as.matrix(x, ncomp = NULL, ...)

Arguments

Capitalize text or vector with text values

Description

Capitalize text or vector with text values

Usage

capitalize(str)

Arguments

Raman spectra of carbonhydrates

Description

The dataset consists of Raman spectra of fructose, lactose, and ribose as well as spectra of their mixtures.

Usage

data(simdata)

Format

The data is a list (carbs) with the following fields:

Details

The dataset consists of Raman spectra of fructose, lactose, and ribose as well as spectra of their mixtures. The original spectra were downloaded from publicly available SPECARB library [1], created by S.B. Engelsen. The specta were truncated to the range from 200 to 1600 cm-1.

The spectra of mixtures were created by linear combinations of the original spectra:

D = CS' + E

Concentrations of the components, C, follow a simplex lattice design with four levels. Some noise calculated as a random number uniformly distributed between 0% and 3% of maximum initial intensity (E) was added to each spectrum of the dataset, D, individually.

References

1. Engelsen S.B., Database on Raman spectra of carbohydrates. Available at: http://www.models.life.ku.dk/~specarb/specarb.html [visited 31.05.2020]

Categorize PCA results

Description

Categorize PCA results

Usage

categorize(obj, ...)

Arguments

Categorize PCA results based on orthogonal and score distances.

Description

The method compares score and orthogonal distances of PCA results from res with critical limits computed for the PCA model and categorizes the corresponding objects as "regular", "extreme" or "outlier".

Usage

## S3 method for class 'pca'
categorize(obj, res = obj$res$cal, ncomp = obj$ncomp.selected, ...)

Arguments

Details

The method does not categorize hidden values if any.

Value

vector (factor) with results of categorization.

Categorize data rows based on PLS results and critical limits for total distance.

Description

The method uses full distance for decomposition of X-data and squared Y-residuals of PLS results from res with critical limits computed for the PLS model and categorizes the corresponding objects as "regular", "extreme" or "outlier".

Usage

## S3 method for class 'pls'
categorize(obj, res = obj$res$cal, ncomp = obj$ncomp.selected, ...)

Arguments

Details

The method does not categorize hidden values if any. It is based on the approach described in [1] and works only if data driven approach is used for computing critical limits.

Value

vector (factor) with results of categorization.

References

1. Rodionova O. Ye., Pomerantsev A. L. Detection of Outliers in Projection-Based Modeling. Analytical Chemistry (2020, in publish). doi: 10.1021/acs.analchem.9b04611

Calculates critical limits for distance values using Chi-square distribution

Description

The method is based on Chi-squared distribution with DF = 2 * (m(u)/s(u)^2

Usage

chisq.crit(param, alpha = 0.05, gamma = 0.01)

Arguments

Calculate probabilities for distance values using Chi-square distribution

Description

Calculate probabilities for distance values using Chi-square distribution

Usage

chisq.prob(u, param)

Arguments

PLS-DA classification

Description

Converts PLS predictions of y values to predictions of classes

Usage

classify.plsda(model, y)

Arguments

Details

This is a service function for PLS-DA class, do not use it manually.

Value

Classification results (an object of class classres)

SIMCA classification

Description

Make classification based on calculated T2 and Q values and corresponding limits

Usage

classify.simca(obj, pca.res, c.ref = NULL)

Arguments

Details

This is a service function for SIMCA class, do not use it manually.

Value

vector with predicted class values (c.pred)

Check reference class values and convert it to a factor if necessary

Description

Check reference class values and convert it to a factor if necessary

Usage

classmodel.processRefValues(c.ref, classnames = NULL)

Arguments

Results of classification

Description

classres is used to store results classification for one or multiple classes.

Usage

classres(c.pred, c.ref = NULL, p.pred = NULL, ncomp.selected = 1)

Arguments

Details

There is no need to create a classres object manually, it is created automatically when build a classification model (e.g. using simca or plsda) or apply the model to new data. For any classification method from mdatools, a class using to represent results of classification (e.g. simcares) inherits fields and methods of classres.

Value

The following fields are available only if reference values were provided.

See Also

Methods classres class:

Calculation of classification performance parameters

Description

Calculates and returns performance parameters for classification result (e.g. number of false negatives, false positives, sn, specificity, etc.).

Usage

classres.getPerformance(c.ref, c.pred)

Arguments

Details

The function is called automatically when a classification result with reference values is created, for example when applying a plsda or simca models.

Value

Returns a list with following fields:

Confidence intervals for regression coefficients

Description

returns matrix with confidence intervals for regression coeffocoents for given response number and number of components.

Usage

## S3 method for class 'regcoeffs'
confint(object, parm = NULL, level = 0.95, ncomp = 1, ny = 1, ...)

Arguments

Class for MCR-ALS constraint

Description

Class for MCR-ALS constraint

Usage

constraint(name, params = NULL, method = NULL)

Arguments

Details

Use this class to create constraints and add them to a list for MCR-ALS curve resuliton (see mcrals). Either provide name and parameters to one of the existing constraint implementations or make your own. See the list of implemented constraints by running constraints()

For your own constraint you need to create a method, which takes matrix with values (either spectra or contributions being resolved) as the first argument, does something and then return a matrix with the same dimension as the result. The method can have any number of optional parameters.

See help for mcrals or Bookdown tutorial for details.

Method for angle constraint

Description

Adds a small portion of mean to contributions or spectra to increase contrast

Usage

constraintAngle(x, d, weight = 0.05)

Arguments

Method for closure constraint

Description

Force rows of data sum up to given value

Usage

constraintClosure(x, d, sum = 1)

Arguments

Method for non-negativity constraint

Description

Set all negative values in the matrix to 0

Usage

constraintNonNegativity(x, d)

Arguments

Method for normalization constraint

Description

Normalize rows of matrix to unit length or area

Usage

constraintNorm(x, d, type = "length")

Arguments

Method for unimodality constraint

Description

forces column of matrix to have one maximum each

Usage

constraintUnimod(x, d, tol = 0)

Arguments

Shows information about all implemented constraints

Description

Shows information about all implemented constraints

Usage

constraints.list()

Generate sequence of indices for cross-validation

Description

Generates and returns sequence of object indices for each segment in random segmented cross-validation

Usage

crossval(cv = 1, nobj = NULL, resp = NULL)

Arguments

Value

matrix with object indices for each segment

Define parameters based on 'cv' value

Description

Define parameters based on 'cv' value

Usage

crossval.getParams(cv, nobj)

Arguments

Cross-validation of a regression model

Description

Does cross-validation of a regression model

Usage

crossval.regmodel(obj, x, y, cv, cal.fun, pred.fun, cv.scope = "local")

Arguments

Value

object of class plsres with results of cross-validation

Function 'pred.fun' must take four agruments: autoscaled x-values, array with regression coefficients, vectors for centring and scaling of y-values (if used). The function must return predicted y-values in original units (unscaled and uncentered).

Cross-validation of a SIMCA model

Description

Does the cross-validation of a SIMCA model

Usage

crossval.simca(obj, x, cv)

Arguments

Value

object of class simcares with results of cross-validation

String with description of cross-validation method

Description

String with description of cross-validation method

Usage

crossval.str(cv)

Arguments

Value

a string with the description text

Calculates critical limits for distance values using Data Driven moments approach

Description

Calculates critical limits for distance values using Data Driven moments approach

Usage

dd.crit(paramQ, paramT2, alpha = 0.05, gamma = 0.01)

Arguments

Calculates critical limits for distance values using Data Driven moments approach

Description

Calculates critical limits for distance values using Data Driven moments approach

Usage

ddmoments.param(U)

Arguments

Calculates critical limits for distance values using Data Driven robust approach

Description

Calculates critical limits for distance values using Data Driven robust approach

Usage

ddrobust.param(U, ncomp, alpha, gamma)

Arguments

Create ellipse on the current plot

Description

Create ellipse on the current plot

Usage

ellipse(xc = 0, yc = 0, a, b, col = "black", lty = 1, ...)

Arguments

Applies constraint to a dataset

Description

Applies constraint to a dataset

Usage

employ.constraint(obj, x, d, ...)

Arguments

Applies a list with preprocessing methods to a dataset

Description

Applies a list with preprocessing methods to a dataset

Usage

employ.prep(obj, x, ...)

Arguments

Imitation of fprinf() function

Description

Imitation of fprinf() function

Usage

fprintf(...)

Arguments

Calibration data

Description

Calibration data

Usage

getCalibrationData(obj)

Arguments

Details

Generic function getting calibration data from a linear decomposition model (e.g. PCA)

Returns matrix with original calibration data

Description

Returns matrix with original calibration data

Usage

## S3 method for class 'pca'
getCalibrationData(obj)

Arguments

Get calibration data

Description

Get data, used for calibration of the SIMCAM individual models and combine to one dataset.

Usage

## S3 method for class 'simcam'
getCalibrationData(obj)

Arguments

Details

See examples in help for simcam function.

Compute confidence ellipse for a set of points

Description

Compute confidence ellipse for a set of points

Usage

getConfidenceEllipse(points, conf.level = 0.95, n = 100)

Arguments

Value

matrix with coordinates of the ellipse points (x and y)

Confusion matrix for classification results

Description

Confusion matrix for classification results

Usage

getConfusionMatrix(obj, ...)

Arguments

Details

Returns confusion matrix for classification results represented by the object.

Confusion matrix for classification results

Description

The columns of the matrix correspond to classification results, rows - to the real classes. In case of soft classification with multiple classes (e.g. SIMCAM) sum of values for every row will not correspond to the total number of class members as the same object can be classified as a member of several classes or non of them.

Usage

## S3 method for class 'classres'
getConfusionMatrix(obj, ncomp = obj$ncomp.selected, ...)

Arguments

Details

Returns confusion matrix for classification results represented by the object.

Compute coordinates of a closed convex hull for data points

Description

Compute coordinates of a closed convex hull for data points

Usage

getConvexHull(points)

Arguments

Create a vector with labels for plot series

Description

For scatter plots labels correspond to rows of the data (names, values, indices, etc.). For non-scatter plots labels correspond to the columns (names, indices or max value for each column)

Usage

getDataLabels(ps, labels = NULL)

Arguments

Shows a list with implemented constraints

Description

Shows a list with implemented constraints

Usage

getImplementedConstraints()

Shows a list with implemented preprocessing methods

Description

Shows a list with implemented preprocessing methods

Usage

getImplementedPrepMethods()

Create labels as column or row indices

Description

Create labels as column or row indices

Usage

getLabelsAsIndices(ps)

Arguments

Create labels from data values

Description

Create labels from data values

Usage

getLabelsAsValues(ps)

Arguments

Get main title

Description

returns main title for a plot depending on a user choice

Usage

getMainTitle(main, ncomp, default)

Arguments

Details

Depedning on a user choice it returns main title for a plot

Define colors for plot series

Description

Define colors for plot series

Usage

getPlotColors(ps, col, opacity, cgroup, colmap)

Arguments

Get class belonging probability

Description

Compute class belonging probabilities for classification results.

Usage

getProbabilities(obj, ...)

Arguments

Probabilities for residual distances

Description

Probabilities for residual distances

Usage

## S3 method for class 'pca'
getProbabilities(obj, ncomp, q, h, ...)

Arguments

Details

Computes p-value for every object being from the same populaion as calibration set based on its orthogonal and score distances.

Probabilities of class belonging for PCA/SIMCA results

Description

Probabilities of class belonging for PCA/SIMCA results

Usage

## S3 method for class 'simca'
getProbabilities(obj, ncomp, q, h, ...)

Arguments

Details

Computes p-value for every object being from the same populaion as calibration set based on its orthogonal and score distances.

Identifies pure variables

Description

The method identifies indices of pure variables using the SIMPLISMA algorithm.

Usage

getPureVariables(D, ncomp, purevars, offset)

Arguments

Value

The function returns a list with with following fields:

Get regression coefficients

Description

Generic function for getting regression coefficients from PLS model

Usage

getRegcoeffs(obj, ...)

Arguments

Regression coefficients for PLS model'

Description

Returns a matrix with regression coefficients for the PLS model which can be applied to a data directly

Usage

## S3 method for class 'regmodel'
getRegcoeffs(
  obj,
  ncomp = obj$ncomp.selected,
  ny = 1,
  full = FALSE,
  alpha = 0.05,
  ...
)

Arguments

Details

The method recalculates the regression coefficients found by the PLS algorithm taking into account centering and scaling of predictors and responses, so the matrix with coefficients can be applied directly to original data (yp = Xb).

If number of components is not specified, the optimal number, selected by user or identified by a model will be used.

If Jack-knifing method was used to get statistics for the coefficient the method returns all statistics as well (p-value, t-value, confidence interval). In this case user has to specified a number of y-variable (if there are many) to get the statistics and the coefficients for. The confidence interval is computed for unstandardized coefficients.

Value

A matrix with regression coefficients and (optinally) statistics.

Return list with valid results

Description

Return list with valid results

Usage

getRes(res, classname = "ldecomp")

Arguments

Get selected components

Description

returns number of components depending on a user choice

Usage

getSelectedComponents(obj, ncomp = NULL)

Arguments

Details

Depedning on a user choice it returns optimal number of component for the model (if use did not provide any value) or check the user choice for correctness and returns it back

Selectivity ratio

Description

Generic function for returning selectivity ratio values for regression model (PCR, PLS, etc)

Usage

getSelectivityRatio(obj, ...)

Arguments

Selectivity ratio for PLS model

Description

Returns vector with Selectivity ratio values. This function is a proxy for selratio and will be removed in future releases.

Usage

## S3 method for class 'pls'
getSelectivityRatio(obj, ncomp = obj$ncomp.selected, ...)

Arguments

Value

vector with selectivity ratio values

References

[1] Tarja Rajalahti et al. Chemometrics and Laboratory Systems, 95 (2009), pp. 35-48.

VIP scores

Description

Generic function for returning VIP scores values for regression model (PCR, PLS, etc)

Usage

getVIPScores(obj, ...)

Arguments

VIP scores for PLS model

Description

Returns vector with VIP scores values. This function is a proxy for vipscores and will be removed in future releases.

Usage

## S3 method for class 'pls'
getVIPScores(obj, ncomp = obj$ncomp.selected, ...)

Arguments

Value

matrix nvar x 1 with VIP score values

Compute explained variance for MCR case

Description

Compute explained variance for MCR case

Usage

getVariance.mcr(obj, x)

Arguments

Calculate critical limits for distance values using Hotelling T2 distribution

Description

Calculate critical limits for distance values using Hotelling T2 distribution

Usage

hotelling.crit(nobj, ncomp, alpha = 0.05, gamma = 0.01)

Arguments

Value

vector with four values: critical limits for given alpha and gamma, mean distance and DoF.

Calculate probabilities for distance values and given parameters using Hotelling T2 distribution

Description

Calculate probabilities for distance values and given parameters using Hotelling T2 distribution

Usage

hotelling.prob(u, ncomp, nobj)

Arguments

show image data as an image

Description

show image data as an image

Usage

imshow(
  data,
  channels = 1,
  show.excluded = FALSE,
  main = paste0(" ", colnames(data)[channels]),
  colmap = "jet"
)

Arguments

Variable selection with interval PLS

Description

Applies iPLS algorithm to find variable intervals most important for prediction.

Usage

ipls(
  x,
  y,
  glob.ncomp = 10,
  center = TRUE,
  scale = FALSE,
  cv = list("ven", 10),
  exclcols = NULL,
  exclrows = NULL,
  int.ncomp = glob.ncomp,
  int.num = NULL,
  int.width = NULL,
  int.limits = NULL,
  int.niter = NULL,
  ncomp.selcrit = "min",
  method = "forward",
  x.test = NULL,
  y.test = NULL,
  silent = FALSE,
  full = FALSE,
  cv.scope = "local"
)

Arguments

Details

The algorithm splits the predictors into several intervals and tries to find a combination of the intervals, which gives best prediction performance. There are two selection methods: "forward" when the intervals are successively included, and "backward" when the intervals are successively excluded from a model. On the first step the algorithm finds the best (forward) or the worst (backward) individual interval. Then it tests the others to find the one which gives the best model in a combination with the already selected/excluded one. The procedure continues until no improvements is observed or the maximum number of iteration is reached.

There are several ways to specify the intervals. First of all either number of intervals (int.num) or width of the intervals (int.width) can be provided. Alternatively one can specify the limits (first and last variable number) of the intervals manually with int.limits.

Cross-validation settings, cv, can be a number or a list. If cv is a number, it will be used as a number of segments for random cross-validation (if cv = 1, full cross-validation will be preformed). If it is a list, the following syntax can be used: cv = list('rand', nseg, nrep) for random repeated cross-validation with nseg segments and nrep repetitions or cv = list('ven', nseg) for systematic splits to nseg segments ('venetian blinds').

Value

object of 'ipls' class with several fields, including:

References

[1] Lars Noergaard at al. Interval partial least-squares regression (iPLS): a comparative chemometric study with an example from near-infrared spectroscopy. Appl.Spec. 2000; 54: 413-419

Examples

library(mdatools)

## forward selection for simdata

data(simdata)
Xc = simdata$spectra.c
yc = simdata$conc.c[, 3, drop = FALSE]

# run iPLS and show results
im = ipls(Xc, yc, int.ncomp = 5, int.num = 10, cv = 4, method = "forward")
summary(im)
plot(im)

# show "developing" of RMSECV during the algorithm execution
plotRMSE(im)

# plot predictions before and after selection
par(mfrow = c(1, 2))
plotPredictions(im$gm)
plotPredictions(im$om)

# show selected intervals on spectral plot
ind = im$var.selected
mspectrum = apply(Xc, 2, mean)
plot(simdata$wavelength, mspectrum, type = 'l', col = 'lightblue')
points(simdata$wavelength[ind], mspectrum[ind], pch = 16, col = 'blue')

Runs the backward iPLS algorithm

Description

Runs the backward iPLS algorithm

Usage

ipls.backward(x, y, obj, int.stat, glob.stat, full, cv.scope)

Arguments

Runs the forward iPLS algorithm

Description

Runs the forward iPLS algorithm

Usage

ipls.forward(x, y, obj, int.stat, glob.stat, full, cv.scope)

Arguments

Calculate critical limits for distance values using Jackson-Mudholkar approach

Description

Calculate critical limits for distance values using Jackson-Mudholkar approach

Usage

jm.crit(residuals, eigenvals, alpha = 0.05, gamma = 0.01)

Arguments

Value

vector with four values: critical limits for given alpha and gamma, mean distance and DoF.

Calculate probabilities for distance values and given parameters using Hotelling T2 distribution

Description

Calculate probabilities for distance values and given parameters using Hotelling T2 distribution

Usage

jm.prob(u, eigenvals, ncomp)

Arguments

Class for storing and visualising linear decomposition of dataset (X = TP' + E)

Description

Creates an object of ldecomp class.

Usage

ldecomp(scores, loadings, residuals, eigenvals, ncomp.selected = ncol(scores))

Arguments

Details

ldecomp is a general class for storing results of decomposition of dataset in form X = TP' + E. Here, X is a data matrix, T - matrix with scores, P - matrix with loadings and E - matrix with residuals. It is used, for example, for PCA results (pcares), in PLS and other methods. The class also includes methods for calculation of residual distances and explained variance.

There is no need to use the ldecomp manually. For example, when build PCA model with pca or apply it to a new data, the results will automatically inherit all methods of ldecomp.

Value

Returns an object (list) of ldecomp class with following fields:

Compute score and residual distances

Description

Compute orthogonal Euclidean distance from object to PC space (Q, q) and Mahalanobis squared distance between projection of the object to the space and its origin (T2, h).

Usage

ldecomp.getDistances(scores, loadings, residuals, eigenvals)

Arguments

Details

The distances are calculated for every 1:n components, where n goes from 1 to ncomp (number of columns in scores and loadings).

Value

Returns a list with Q, T2 and tnorm values for each component.

Compute parameters for critical limits based on calibration results

Description

Compute parameters for critical limits based on calibration results

Usage

ldecomp.getLimParams(U)

Arguments

Compute coordinates of lines or curves with critical limits

Description

Compute coordinates of lines or curves with critical limits

Usage

ldecomp.getLimitsCoordinates(
  Qlim,
  T2lim,
  ncomp,
  norm,
  log,
  show.limits = c(TRUE, TRUE)
)

Arguments

Value

list with two matrices (x and y coordinates of corresponding limits)

Compute critical limits for orthogonal distances (Q)

Description

Compute critical limits for orthogonal distances (Q)

Usage

ldecomp.getQLimits(lim.type, alpha, gamma, params, residuals, eigenvals)

Arguments

Compute critical limits for score distances (T2)

Description

Compute critical limits for score distances (T2)

Usage

ldecomp.getT2Limits(lim.type, alpha, gamma, params)

Arguments

Compute explained variance

Description

Computes explained variance and cumulative explained variance for data decomposition.

Usage

ldecomp.getVariances(scores, loadings, residuals, Q)

Arguments

Value

Returns a list with two vectors.

Residuals distance plot for a set of ldecomp objects

Description

Shows a plot with score (T2, h) vs orthogonal (Q, q) distances and corresponding critical limits for given number of components.

Usage

ldecomp.plotResiduals(
  res,
  Qlim,
  T2lim,
  ncomp,
  log = FALSE,
  norm = FALSE,
  cgroup = NULL,
  xlim = NULL,
  ylim = NULL,
  show.limits = c(TRUE, TRUE),
  lim.col = c("darkgray", "darkgray"),
  lim.lwd = c(1, 1),
  lim.lty = c(2, 3),
  show.legend = TRUE,
  legend.position = "topright",
  show.excluded = FALSE,
  ...
)

Arguments

Details

The function is a bit more advanced version of plotResiduals.ldecomp. It allows to show distance values for several result objects (e.g. calibration and test set or calibration and new prediction set) as well as display the correspondng critical limits in form of lines or curves.

Depending on how many result objects your model has or how many you specified manually, using the res parameter, the plot behaves in a bit different way.

If only one result object is provided, then it allows to colorise the points using cgroup parameter. If two or more result objects are provided, then the function show distances in groups, and adds corresponding legend.

The function can show distance values normalised (h/h0 and q/q0) as well as with log transformation (log(1 + h/h0), log(1 + q/q0)). The latter is useful if distribution of the points is skewed and most of them are densely located around bottom left corner.

General class for Multivariate Curve Resolution model

Description

mcr is used to store and visualise general MCR data and results.

Usage

mcr(x, ncomp, method, exclrows = NULL, exclcols = NULL, info = "", ...)

Arguments

Multivariate curve resolution using Alternating Least Squares

Description

mcralls allows to resolve spectroscopic data to linear combination of individual spectra and contributions using the alternating least squares (ALS) algorithm with constraints.

Usage

mcrals(
  x,
  ncomp,
  cont.constraints = list(),
  spec.constraints = list(),
  spec.ini = matrix(runif(ncol(x) * ncomp), ncol(x), ncomp),
  cont.forced = matrix(NA, nrow(x), ncomp),
  spec.forced = matrix(NA, ncol(x), ncomp),
  cont.solver = mcrals.nnls,
  spec.solver = mcrals.nnls,
  exclrows = NULL,
  exclcols = NULL,
  verbose = FALSE,
  max.niter = 100,
  tol = 10^-6,
  info = ""
)

Arguments

Details

The method implements the iterative ALS algorithm, where, at each iteration, spectra and contributions of each chemical component are estimated and then a set of constraints is applied to each. The method is well described in [1, 2].

The method assumes that the spectra (D) is a linear combination of pure components spectra (S) and pure component concentrations (C):

D = CS' + E

So the task is to get C and S by knowing D. In order to do that you need to provide:

1. Constraints for spectra and contributions. The constraints should be provided as a list with name of the constraint and all necessary parameters. You can see which constraints and parameters are currently supported by running constraintList(). See the code examples below or a Bookdown tutorial for more details.

2. Initial estimation of the pure components spectra, S. By default method uses a matrix with random numbers but you can provide a better guess (for example by running mcrpure) as a first step.

3. Which solver to use for resolving spectra and concentrations. There are two built in solvers: mcrals.nnls (default) and mcrals.ols. The first implements non-negative least squares method which gives non-negative (thus physically meaningful) solutions. The second is ordinary least squares and if you want to get non-negative spectra and/or contributions in this case you need to provide a non-negativity constraint.

The algorithm iteratively resolves C and S and checks how well CS' is to D. The iterations stop either when number exceeds value in max.niter or when improvements (difference between explained variance on current and previous steps) is smaller than tol value.

Parameters cont.force and spec.force allows you to force some parts of the contributions or the spectra to be equal to particular pre-defined values. In this case you need to provide the parameters (or just one of them) in form of a matrix. For example cont.force should have as many rows as many you have in the original spectral data x and as many columns as many pure components you want to resolve. Feel all values of this matrix with NA and the values you want to force with real numbers. For example if you know that in the first measurement concentration of 2 and 3 components was zero, set the corresponding values of cont.force to zero. See also the last case in the examples section.

Value

Returns an object of mcrpure class with the following fields:

More details and examples can be found in the Bookdown tutorial.

Author(s)

Sergey Kucheryavskiy (svkucheryavski@gmail.com)

References

1. J. Jaumot, R. Gargallo, A. de Juan, and R. Tauler, "A graphical user-friendly interface for MCR-ALS: a new tool for multivariate curve resolution in MATLAB", Chemometrics and Intelligent #' Laboratory Systems 76, 101-110 (2005).

See Also

Methods for mcrals objects:

Plotting methods for mcrals objects:

Examples

library(mdatools)

# resolve mixture of carbonhydrates Raman spectra

data(carbs)

# define constraints for contributions
cc <- list(
   constraint("nonneg")
)

# define constraints for spectra
cs <- list(
   constraint("nonneg"),
   constraint("norm", params = list(type = "area"))
)

# because by default initial approximation is made by using random numbers
# we need to seed the generator in order to get reproducable results
set.seed(6)

# run ALS
m <- mcrals(carbs$D, ncomp = 3, cont.constraints = cc, spec.constraints = cs)
summary(m)

# plot cumulative and individual explained variance
par(mfrow = c(1, 2))
plotVariance(m)
plotCumVariance(m)

# plot resolved spectra (all of them or individually)
par(mfrow = c(2, 1))
plotSpectra(m)
plotSpectra(m, comp = 2:3)

# plot resolved contributions (all of them or individually)
par(mfrow = c(2, 1))
plotContributions(m)
plotContributions(m, comp = 2:3)

# of course you can do this manually as well, e.g. show original
# and resolved spectra
par(mfrow = c(1, 1))
mdaplotg(
   list(
      "original" = prep.norm(carbs$D, "area"),
      "resolved" = prep.norm(mda.subset(mda.t(m$resspec), 1), "area")
   ), col = c("gray", "red"), type = "l"
)

# in case if you have reference spectra of components you can compare them with
# the resolved ones:
par(mfrow = c(3, 1))
for (i in 1:3) {
   mdaplotg(
      list(
         "pure" = prep.norm(mda.subset(mda.t(carbs$S), 1), "area"),
         "resolved" = prep.norm(mda.subset(mda.t(m$resspec), 1), "area")
      ), col = c("gray", "red"), type = "l", lwd = c(3, 1)
   )
}

# This example shows how to force some of the contribution values
# First of all we combine the matrix with mixtures and the pure spectra, so the pure
# spectra are on top of the combined matrix
Dplus <- mda.rbind(mda.t(carbs$S), carbs$D)

# since we know that concentration of C2 and C3 is zero in the first row (it is a pure
# spectrum of first component), we can force them to be zero in the optimization procedure.
# Similarly we can do this for second and third rows.

cont.forced <- matrix(NA, nrow(Dplus), 3)
cont.forced[1, ] <- c(NA, 0, 0)
cont.forced[2, ] <- c(0, NA, 0)
cont.forced[3, ] <- c(0, 0, NA)

m <- mcrals(Dplus, 3, cont.forced = cont.forced, cont.constraints = cc, spec.constraints = cs)
plot(m)

# See bookdown tutorial for more details.

Identifies pure variables

Description

The method identifies indices of pure variables using the SIMPLISMA algorithm.

Usage

mcrals.cal(
  D,
  ncomp,
  cont.constraints,
  spec.constraints,
  spec.ini,
  cont.forced,
  spec.forced,
  cont.solver,
  spec.solver,
  max.niter,
  tol,
  verbose
)

Arguments

Value

The function returns a list with with following fields:

Fast combinatorial non-negative least squares

Description

Fast combinatorial non-negative least squares

Usage

mcrals.fcnnls(
  D,
  A,
  tol = 10 * .Machine$double.eps * as.numeric(sqrt(crossprod(A[, 1]))) * nrow(A)
)

Arguments

Details

Computes Fast combinatorial NNLS solution for B: D = AB' subject to B >= 0. Implements the method described in [1].

References

1. Van Benthem, M.H. and Keenan, M.R. (2004), Fast algorithm for the solution of large scale non-negativity-constrained least squares problems. J. Chemometrics, 18: 441-450. doi:10.1002/cem.889

Non-negative least squares

Description

Non-negative least squares

Usage

mcrals.nnls(
  D,
  A,
  tol = 10 * .Machine$double.eps * as.numeric(sqrt(crossprod(A[, 1]))) * nrow(A)
)

Arguments

Details

Computes NNLS solution for B: D = AB' subject to B >= 0. Implements the active-set based algorithm proposed by Lawson and Hanson [1].

References

1. Lawson, Charles L.; Hanson, Richard J. (1995). Solving Least Squares Problems. SIAM.

Ordinary least squares

Description

Ordinary least squares

Usage

mcrals.ols(D, A)

Arguments

Details

Computes OLS solution for D = AB' (or D' = AB'), where D, A are known

Multivariate curve resolution based on pure variables

Description

mcrpure allows to resolve spectroscopic data to linear combination of individual spectra and contributions using the pure variables approach.

Usage

mcrpure(
  x,
  ncomp,
  purevars = NULL,
  offset = 0.05,
  exclrows = NULL,
  exclcols = NULL,
  info = ""
)

Arguments

Details

The method estimates purity of each variable and then uses the purest ones to decompose the spectral data into spectra ('resspec') and contributions ('rescont') of individual chemical components by ordinary least squares.

The pure variabes are identified using stepwise maximum angle calculations and described in detail in [1]. So the purity of a spectral variable (wavelength, wavenumber) is actually an angle (measured in degrees) between the variable and vector of ones for the first component; and between the variable and space formed by previously found pure variables for the other components.

Value

Returns an object of mcrpure class with the following fields:

More details and examples can be found in the Bookdown tutorial.

Author(s)

Sergey Kucheryavskiy (svkucheryavski@gmail.com)

References

1. Willem Windig, Neal B. Gallagher, Jeremy M. Shaver, Barry M. Wise. A new approach for interactive self-modeling mixture analysis. Chemometrics and Intelligent Laboratory Systems, 77 (2005) 85–96. DOI: 10.1016/j.chemolab.2004.06.009

See Also

Methods for mcrpure objects:

Plotting methods for mcrpure objects:

Examples

library(mdatools)

# resolve mixture of carbonhydrates Raman spectra

data(carbs)
m = mcrpure(carbs$D, ncomp = 3)

# examples for purity spectra plot (you can select which components to show)
par(mfrow = c(2, 1))
plotPuritySpectra(m)
plotPuritySpectra(m, comp = 2:3)

# you can do it manually and combine e.g. with original spectra
par(mfrow = c(1, 1))
mdaplotg(
   list(
      "spectra" = prep.norm(carbs$D, "area"),
      "purity" = prep.norm(mda.subset(mda.t(m$resspec), 1), "area")
   ), col = c("gray", "red"), type = "l"
)

# show the maximum purity for each component
par(mfrow = c(1, 1))
plotPurity(m)

# plot cumulative and individual explained variance
par(mfrow = c(1, 2))
plotVariance(m)
plotCumVariance(m)

# plot resolved spectra (all of them or individually)
par(mfrow = c(2, 1))
plotSpectra(m)
plotSpectra(m, comp = 2:3)

# plot resolved contributions (all of them or individually)
par(mfrow = c(2, 1))
plotContributions(m)
plotContributions(m, comp = 2:3)

# of course you can do this manually as well, e.g. show original
# and resolved spectra
par(mfrow = c(1, 1))
mdaplotg(
   list(
      "original" = prep.norm(carbs$D, "area"),
      "resolved" = prep.norm(mda.subset(mda.t(m$resspec), 1), "area")
   ), col = c("gray", "red"), type = "l"
)

# in case if you have reference spectra of components you can compare them with
# the resolved ones:
par(mfrow = c(3, 1))
for (i in 1:3) {
   mdaplotg(
      list(
         "pure" = prep.norm(mda.subset(mda.t(carbs$S), 1), "area"),
         "resolved" = prep.norm(mda.subset(mda.t(m$resspec), 1), "area")
      ), col = c("gray", "red"), type = "l", lwd = c(3, 1)
   )
}

# See bookdown tutorial for more details.

A wrapper for cbind() method with proper set of attributes

Description

A wrapper for cbind() method with proper set of attributes

Usage

mda.cbind(...)

Arguments

Value

the merged datasets

Convert data matrix to an image

Description

Convert data matrix to an image

Usage

mda.data2im(data)

Arguments

Convert data frame to a matrix

Description

The function converts data frame to a numeric matrix.

Usage

mda.df2mat(x, full = FALSE)

Arguments

Details

If one or several columns of the data frame are factors they will be converted to a set of dummy variables. If any columns/rows were hidden in the data frame they will remain hidden in the matrix. If there are factors among the hidden columns, the corresponding dummy variables will be hidden as well.

All other attributes (names, axis names, etc.) will be inherited.

Value

a numeric matrix

Exclude/hide columns in a dataset

Description

Exclude/hide columns in a dataset

Usage

mda.exclcols(x, ind)

Arguments

Details

The method assign attribute 'exclcols', which contains number of columns, which should be excluded/hidden from calculations and plots (without removing them physically). The argument ind should contain column numbers (excluding already hidden), names or logical values.

Value

dataset with excluded columns

Exclude/hide rows in a dataset

Description

Exclude/hide rows in a dataset

Usage

mda.exclrows(x, ind)

Arguments

Details

The method assign attribute 'exclrows', which contains number of rows, which should be excluded/hidden from calculations and plots (without removing them physically). The argument ind should contain rows numbers (excluding already hidden), names or logical values.

Value

dataset with excluded rows

Get data attributes

Description

Returns a list with important data attributes (name, xvalues, excluded rows and columns, etc.)

Usage

mda.getattr(x)

Arguments

Get indices of excluded rows or columns

Description

Get indices of excluded rows or columns

Usage

mda.getexclind(excl, names, n)

Arguments

Convert image to data matrix

Description

Convert image to data matrix

Usage

mda.im2data(img)

Arguments

Include/unhide the excluded columns

Description

include colmns specified by user (earlier excluded using mda.exclcols)

Usage

mda.inclcols(x, ind)

Arguments

Value

dataset with included columns.

include/unhide the excluded rows

Description

include rows specified by user (earlier excluded using mda.exclrows)

Usage

mda.inclrows(x, ind)

Arguments

Value

dataset with included rows

Removes excluded (hidden) rows and colmns from data

Description

Removes excluded (hidden) rows and colmns from data

Usage

mda.purge(data)

Arguments

Removes excluded (hidden) colmns from data

Description

Removes excluded (hidden) colmns from data

Usage

mda.purgeCols(data)

Arguments

Removes excluded (hidden) rows from data

Description

Removes excluded (hidden) rows from data

Usage

mda.purgeRows(data)

Arguments

A wrapper for rbind() method with proper set of attributes

Description

A wrapper for rbind() method with proper set of attributes

Usage

mda.rbind(...)

Arguments

Value

the merged datasets

Set data attributes

Description

Set most important data attributes (name, xvalues, excluded rows and columns, etc.) to a dataset

Usage

mda.setattr(x, attrs, type = "all")

Arguments

Remove background pixels from image data

Description

Remove background pixels from image data

Usage

mda.setimbg(data, bgpixels)

Arguments

Wrapper for show() method

Description

Wrapper for show() method

Usage

mda.show(x, n = 50)

Arguments

A wrapper for subset() method with proper set of attributed

Description

A wrapper for subset() method with proper set of attributed

Usage

mda.subset(x, subset = NULL, select = NULL)

Arguments

Details

The method works similar to the standard subset() method, with minor differences. First of all it keeps (and correct, if necessary) all important attributes. If only columns are selected, it keeps all excluded rows as excluded. If only rows are selected, it keeps all excluded columns. If both rows and columns are selected it removed all excluded elements first and then makes the subset.

The parameters subset and select may each be a vector with numbers or nanes without excluded elements, or a logical expression.

Value

a data with the subset

A wrapper for t() method with proper set of attributes

Description

A wrapper for t() method with proper set of attributes

Usage

mda.t(x)

Arguments

Value

the transposed dataset

Plotting function for a single set of objects

Description

mdaplot is used to make different kinds of plot for one set of data objects.

Usage

mdaplot(
  data = NULL,
  ps = NULL,
  type = "p",
  pch = 16,
  col = NULL,
  bg = par("bg"),
  bwd = 0.8,
  border = NA,
  lty = 1,
  lwd = 1,
  cex = 1,
  cgroup = NULL,
  xlim = NULL,
  ylim = NULL,
  colmap = "default",
  labels = NULL,
  main = NULL,
  xlab = NULL,
  ylab = NULL,
  show.labels = FALSE,
  show.colorbar = !is.null(cgroup),
  show.lines = FALSE,
  show.grid = TRUE,
  grid.lwd = 0.5,
  grid.col = "lightgray",
  show.axes = TRUE,
  xticks = NULL,
  yticks = NULL,
  xticklabels = NULL,
  yticklabels = NULL,
  xlas = 0,
  ylas = 0,
  lab.col = "darkgray",
  lab.cex = 0.65,
  show.excluded = FALSE,
  col.excluded = "#C0C0C0",
  nbins = 60,
  force.x.values = NA,
  opacity = 1,
  pch.colinv = FALSE,
  ...
)

Arguments

Details

Most of the parameters are similar to what are used with standard plot function. The differences are described below.

The function makes a plot of one set of objects. It can be a set of points (scatter plot), bars, lines, scatter-lines, errorbars og an image. The data is organized as a data frame, matrix or vector. For scatter and only first two columns will be used, for bar plot only values from the first row. It is recommended to use mda.subset method if plot should be made only for a subset of the data, especially if you have any excluded rows or columns or other special attributed, described in the Bookdown tutorial.

If data is a data frame and contains one or more factors, they will be converted to a dummy variables (using function mda.df2mat) and appears at the end (last columns) if line or bar plot is selected.

The function allows to colorize lines and points according to values of a parameter cgroup. The parameter must be a vector with the same elements as number of objects (rows) in the data. The values are divided into up to eight intervals and for each interval a particular color from a selected color scheme is assigned. Parameter show.colorbar allows to turn off and on a color bar legend for this option.

The used color scheme is defined by the colmap parameter. The default scheme is based on color brewer (colorbrewer2.org) diverging scheme with eight colors. There is also a gray scheme (colmap = "gray") and user can define its own just by specifing the needed sequence of colors (e.g. colmap = c("red", "yellow", "green"), two colors is minimum). The scheme will then be generated automatically as a gradient among the colors.

Besides that the function allows to change tick values and corresponding tick labels for x and y axis, see Bookdown tutorial for more details.

Author(s)

Sergey Kucheryavskiy (svkucheryavski@gmail.com)

See Also

mdaplotg - to make plots for several sets of data objects (groups of objects).

Examples

# See all examples in the tutorial.

Check color values

Description

Checks if elements of argument are valid color values

Usage

mdaplot.areColors(palette)

Arguments

Format vector with numeric values

Description

Format vector with values, so only significant decimal numbers are left.

Usage

mdaplot.formatValues(data, round.only = FALSE, digits = 3)

Arguments

Details

Function takes into accound difference between values and the values themselves.

Value

matrix with formatted values

Color values for plot elements

Description

Generate vector with color values for plot objects (lines, points, bars), depending on number of groups for the objects.

Usage

mdaplot.getColors(
  ngroups = NULL,
  cgroup = NULL,
  colmap = "default",
  opacity = 1,
  maxsplits = 64
)

Arguments

Value

Returns vector with generated color values

Calculate limits for x-axis.

Description

Calculates limits for x-axis depending on data values that have to be plotted, extra plot elements that have to be shown and margins.

Usage

mdaplot.getXAxisLim(
  ps,
  xlim,
  show.labels = FALSE,
  show.lines = FALSE,
  show.excluded = FALSE,
  bwd = 0.8
)

Arguments

Value

Returns a vector with two limits.

Prepare xticklabels for plot

Description

Prepare xticklabels for plot

Usage

mdaplot.getXTickLabels(xticklabels, xticks, excluded_cols)

Arguments

Prepare xticks for plot

Description

Prepare xticks for plot

Usage

mdaplot.getXTicks(xticks, xlim, x_values = NULL, type = NULL)

Arguments

Calculate limits for y-axis.

Description

Calculates limits for y-axis depending on data values that have to be plotted, extra plot elements that have to be shown and margins.

Usage

mdaplot.getYAxisLim(
  ps,
  ylim,
  show.lines = FALSE,
  show.excluded = FALSE,
  show.labels = FALSE,
  show.colorbar = FALSE
)

Arguments

Value

Returns a vector with two limits.

Prepare yticklabels for plot

Description

Prepare yticklabels for plot

Usage

mdaplot.getYTickLabels(yticklabels, yticks, excluded_rows)

Arguments

Prepare yticks for plot

Description

Prepare yticks for plot

Usage

mdaplot.getYTicks(yticks, ylim, y_values = NULL, type = NULL)

Arguments

Create axes plane

Description

Creates an empty axes plane for given parameters

Usage

mdaplot.plotAxes(
  xticklabels = NULL,
  yticklabels = NULL,
  xlim = xlim,
  ylim = ylim,
  xticks = NULL,
  yticks = NULL,
  main = NULL,
  xlab = NULL,
  ylab = NULL,
  xlas = 0,
  ylas = 0,
  show.grid = TRUE,
  grid.lwd = 0.5,
  grid.col = "lightgray"
)

Arguments

Prepare colors based on palette and opacity value

Description

Prepare colors based on palette and opacity value

Usage

mdaplot.prepareColors(palette, ncolors, opacity)

Arguments

Value

vector with colors

Plot colorbar

Description

Shows a colorbar if plot has color grouping of elements (points or lines).

Usage

mdaplot.showColorbar(
  cgroup,
  colmap = "default",
  lab.col = "darkgray",
  lab.cex = 0.65
)

Arguments

Plot lines

Description

Shows horisontal and vertical lines on a plot.

Usage

mdaplot.showLines(point, lty = 2, lwd = 0.75, col = rgb(0.2, 0.2, 0.2))

Arguments

Details

If it is needed to show only one line, the other coordinate shall be set to NA.

Plotting function for several plot series

Description

mdaplotg is used to make different kinds of plots or their combination for several sets of objects.

Usage

mdaplotg(
  data,
  groupby = NULL,
  type = "p",
  pch = 16,
  lty = 1,
  lwd = 1,
  cex = 1,
  col = NULL,
  bwd = 0.8,
  legend = NULL,
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  labels = NULL,
  ylim = NULL,
  xlim = NULL,
  colmap = "default",
  legend.position = "topright",
  show.legend = TRUE,
  show.labels = FALSE,
  show.lines = FALSE,
  show.grid = TRUE,
  grid.lwd = 0.5,
  grid.col = "lightgray",
  xticks = NULL,
  xticklabels = NULL,
  yticks = NULL,
  yticklabels = NULL,
  show.excluded = FALSE,
  lab.col = "darkgray",
  lab.cex = 0.65,
  xlas = 1,
  ylas = 1,
  opacity = 1,
  ...
)

Arguments

Details

The mdaplotg function is used to make a plot with several sets of objects. Simply speaking, use it when you need a plot with legend. For example to show line plot with spectra from calibration and test set, scatter plot with height and weight values for women and men, and so on.

Most of the parameters are similar to mdaplot, the difference is described below.

The data should be organized as a list, every item is a matrix (or data frame) with data for one set of objects. Alternatively you can provide data as a matrix and use parameter groupby to create the groups. See tutorial for more details.

There is no color grouping option, because color is used to separate the sets. Marker symbol, line style and type, etc. can be defined as a single value (one for all sets) and as a vector with one value for each set.

Author(s)

Sergey Kucheryavskiy (svkucheryavski@gmail.com)

Create and return vector with legend values

Description

Create and return vector with legend values

Usage

mdaplotg.getLegend(ps, data.names, legend = NULL)

Arguments

Value

vector of text values for the legend

Compute x-axis limits for mdaplotg

Description

Compute x-axis limits for mdaplotg

Usage

mdaplotg.getXLim(
  ps,
  xlim,
  show.excluded,
  show.legend,
  show.labels,
  legend.position,
  bwd = NULL
)

Arguments

Value

vector with two values

Compute y-axis limits for mdaplotg

Description

Compute y-axis limits for mdaplotg

Usage

mdaplotg.getYLim(
  ps,
  ylim,
  show.excluded,
  show.legend,
  legend.position,
  show.labels
)

Arguments

Value

vector with two values

Prepare data for mdaplotg

Description

Prepare data for mdaplotg

Usage

mdaplotg.prepareData(data, type, groupby)

Arguments

Value

list of datasets

The method should prepare data as a list of datasets (matrices or data frames). One list element will be used to create one plot series.

If 'data' is matrix or data frame and not 'groupby' parameter is provided, then every row will be taken as separate set. This option is available only for line or bar plots.

Check mdaplotg parameters and replicate them if necessary

Description

Check mdaplotg parameters and replicate them if necessary

Usage

mdaplotg.processParam(param, name, is.type, ngroups)

Arguments

Show legend for mdaplotg

Description

Shows a legend for plot elements or their groups.

Usage

mdaplotg.showLegend(
  legend,
  col,
  pt.bg = NA,
  pch = NULL,
  lty = NULL,
  lwd = NULL,
  cex = 1,
  bty = "o",
  position = "topright",
  plot = TRUE,
  ...
)

Arguments

Create line plot with double y-axis

Description

mdaplotyy create line plot for two plot series and uses separate y-axis for each.

Usage

mdaplotyy(
  data,
  type = "l",
  col = mdaplot.getColors(2),
  lty = c(1, 1),
  lwd = c(1, 1),
  pch = (if (type == "b") c(16, 16) else c(NA, NA)),
  cex = 1,
  xlim = NULL,
  ylim = NULL,
  main = attr(data, "name"),
  xlab = attr(data, "xaxis.name"),
  ylab = rownames(data),
  labels = "values",
  show.labels = FALSE,
  lab.cex = 0.65,
  lab.col = "darkgray",
  show.grid = TRUE,
  grid.lwd = 0.5,
  grid.col = "lightgray",
  xticks = NULL,
  xticklabels = NULL,
  xlas = 0,
  ylas = 0,
  show.legend = TRUE,
  legend.position = "topright",
  legend = ylab,
  ...
)

Arguments

Details

This plot has properties both mdaplot and mdaplotg, so when you specify color, line properties etc. you have to do it for both plot series.

Author(s)

Sergey Kucheryavskiy (svkucheryavski@gmail.com)

See Also

mdaplotg - to make plots for several sets of data objects (groups of objects).

Examples

# See all examples in the tutorial.

Package for Multivariate Data Analysis (Chemometrics)

Description

This package contains classes and functions for most common methods used in Chemometrics. For a complete list of functions, use library(help = 'mdatools').

Details

The project is hosted on GitHub (https://svkucheryavski.github.io/mdatools/), there you can also find a Bookdown user tutorial explaining most important features of the package. There is also a dedicated YouTube channel (https://www.youtube.com/channel/UCox0H4utfMq4FIu2kymuyTA) with introductory Chemometric course with examples based on mdatools functionality.

Every method is represented by two classes: a model class for keeping all parameters and information about the model, and a class for keeping and visualising results of applying the model to particular data values.

Every model class, e.g. pls, has all needed functionality implemented as class methods, including model calibration, validation (test set and cross-validation), visualisation of the calibration and validation results with various plots and summary statistics.

So far the following modelling and validation methods are implemented:

Methods for data preprocessing:

All plotting methods are based on two functions, mdaplot and mdaplotg. The functions extend the basic functionality of R plots and allow to make automatic legend and color grouping of data points or lines with colorbar legend, automatically adjust axes limits when several data groups are plotted and so on.

Author(s)

Sergey Kucheryavskiy (svkucheryavski@gmail.com)

Principal Component Analysis

Description

pca is used to build and explore a principal component analysis (PCA) model.

Usage

pca(
  x,
  ncomp = min(nrow(x) - 1, ncol(x), 20),
  center = TRUE,
  scale = FALSE,
  exclrows = NULL,
  exclcols = NULL,
  x.test = NULL,
  method = "svd",
  rand = NULL,
  lim.type = "ddmoments",
  alpha = 0.05,
  gamma = 0.01,
  info = ""
)

Arguments

Details

Note, that from v. 0.10.0 cross-validation is no more supported in PCA.

If number of components is not specified, a minimum of number of objects - 1 and number of variables in calibration set is used. One can also specified an optimal number of component, once model is calibrated (ncomp.selected). The optimal number of components is used to build a residuals distance plot, as well as for SIMCA classification.

If some of rows of calibration set should be excluded from calculations (e.g. because they are outliers) you can provide row numbers, names, or logical values as parameter exclrows. In this case they will be completely ignored we model is calibrated. However, score and residuls distances will be computed for these rows as well and then hidden. You can show them on corresponding plots by using parameter show.excluded = TRUE.

It is also possible to exclude selected columns from calculations by provideing parameter exclcols in form of column numbers, names or logical values. In this case loading matrix will have zeros for these columns. This allows to compute PCA models for selected variables without removing them physically from a dataset.

Take into account that if you see other packages to make plots (e.g. ggplot2) you will not be able to distinguish between hidden and normal objects.

By default loadings are computed for the original dataset using either SVD or NIPALS algorithm. However, for datasets with large number of rows (e.g. hyperspectral images), there is a possibility to run algorithms based on random permutations [1, 2]. In this case you have to define parameter rand as a vector with two values: p - oversampling parameter and k - number of iterations. Usually rand = c(15, 0) or rand = c(5, 1) are good options, which give quite almost precise solution but much faster.

There are several ways to calculate critical limits for orthogonal (Q, q) and score (T2, h) distances. In mdatools you can specify one of the following methods via parameter lim.type: "jm" Jackson-Mudholkar approach [3], "chisq" - method based on chi-square distribution [4], "ddmoments" and "ddrobust" - related to data driven method proposed in [5]. The "ddmoments" is based on method of moments for estimation of distribution parameters (also known as "classical" approach) while "ddrobust" is based in robust estimation.

If lim.type="chisq" or lim.type="jm" is used, only limits for Q-distances are computed based on corresponding approach, limits for T2-distances are computed using Hotelling's T-squared distribution. The methods utilizing the data driven approach calculate limits for combination of the distances bases on chi-square distribution and parameters estimated from the calibration data.

The critical limits are calculated for a significance level defined by parameter 'alpha'. You can also specify another parameter, 'gamma', which is used to calculate acceptance limit for outliers (shown as dashed line on residual distance plot).

You can also recalculate the limits for existent model by using different values for alpha and gamme, without recomputing the model itself. In this case use the following code (it is assumed that you current PCA/SIMCA model is stored in variable m): m = setDistanceLimits(m, lim.type, alpha, gamma).

In case of PCA the critical limits are just shown on residual plot as lines and can be used for detection of extreme objects (solid line) and outliers (dashed line). When PCA model is used for classification in SIMCA (see simca) the limits are also employed for classification of objects.

Value

Returns an object of pca class with following fields:

More details and examples can be found in the Bookdown tutorial.

Author(s)

Sergey Kucheryavskiy (svkucheryavski@gmail.com)

References

1. N. Halko, P.G. Martinsson, J.A. Tropp. Finding structure with randomness: probabilistic algorithms for constructing approximate matrix decompositions. SIAM Review, 53 (2010) pp. 217-288.

2. S. Kucheryavskiy, Blessing of randomness against the curse of dimensionality, Journal of Chemometrics, 32 (2018).

3. J.E. Jackson, A User's Guide to Principal Components, John Wiley & Sons, New York, NY (1991).

4. A.L. Pomerantsev, Acceptance areas for multivariate classification derived by projection methods, Journal of Chemometrics, 22 (2008) pp. 601-609.

5. A.L. Pomerantsev, O.Ye. Rodionova, Concept and role of extreme objects in PCA/SIMCA, Journal of Chemometrics, 28 (2014) pp. 429-438.

See Also

Methods for pca objects:

Plotting methods for pca objects:

Most of the methods for plotting data are also available for PCA results (pcares) objects. Also check pca.mvreplace, which replaces missing values in a data matrix with approximated using iterative PCA decomposition.

Examples

library(mdatools)
### Examples for PCA class

## 1. Make PCA model for People data with autoscaling

data(people)
model = pca(people, scale = TRUE, info = "Simple PCA model")
model = selectCompNum(model, 4)
summary(model)
plot(model, show.labels = TRUE)

## 2. Show scores and loadings plots for the model

par(mfrow = c(2, 2))
plotScores(model, comp = c(1, 3), show.labels = TRUE)
plotScores(model, comp = 2, type = "h", show.labels = TRUE)
plotLoadings(model, comp = c(1, 3), show.labels = TRUE)
plotLoadings(model, comp = c(1, 2), type = "h", show.labels = TRUE)
par(mfrow = c(1, 1))

## 3. Show residual distance and variance plots for the model
par(mfrow = c(2, 2))
plotVariance(model, type = "h")
plotCumVariance(model, show.labels = TRUE, legend.position = "bottomright")
plotResiduals(model, show.labels = TRUE)
plotResiduals(model, ncomp = 2, show.labels = TRUE)
par(mfrow = c(1, 1))

PCA model calibration

Description

Calibrates (builds) a PCA model for given data and parameters

Usage

pca.cal(x, ncomp, center, scale, method, rand = NULL)

Arguments

Value

an object with calibrated PCA model

Low-dimensional approximation of data matrix X

Description

Low-dimensional approximation of data matrix X

Usage

pca.getB(X, k = NULL, rand = NULL, dist = "unif")

Arguments

Replace missing values in data

Description

pca.mvreplace is used to replace missing values in a data matrix with approximated by iterative PCA decomposition.

Usage

pca.mvreplace(
  x,
  center = TRUE,
  scale = FALSE,
  maxncomp = 10,
  expvarlim = 0.95,
  covlim = 10^-6,
  maxiter = 100
)

Arguments

Details

The function uses iterative PCA modeling of the data to approximate and impute missing values. The result is most optimal for data sets with low or moderate level of noise and with number of missing values less than 10% for small dataset and up to 20% for large data.

Value

Returns the same matrix x where missing values are replaced with approximated.

Author(s)

Sergey Kucheryavskiy (svkucheryavski@gmail.com)

References

Philip R.C. Nelson, Paul A. Taylor, John F. MacGregor. Missing data methods in PCA and PLS: Score calculations with incomplete observations. Chemometrics and Intelligent Laboratory Systems, 35 (1), 1996.

Examples

library(mdatools)

## A very simple example of imputing missing values in a data with no noise

# generate a matrix with values
s = 1:6
odata = cbind(s, 2*s, 4*s)

# make a matrix with missing values
mdata = odata
mdata[5, 2] = mdata[2, 3] = NA

# replace missing values with approximated
rdata = pca.mvreplace(mdata, scale = TRUE)

# show all matrices together
show(cbind(odata, mdata, round(rdata, 2)))

NIPALS based PCA algorithm

Description

Calculates principal component space using non-linear iterative partial least squares algorithm (NIPALS)

Usage

pca.nipals(x, ncomp = min(ncol(x), nrow(x) - 1), tol = 10^-10)

Arguments

Value

a list with scores, loadings and eigenvalues for the components

References

Geladi, Paul; Kowalski, Bruce (1986), "Partial Least Squares Regression:A Tutorial", Analytica Chimica Acta 185: 1-17

Runs one of the selected PCA methods

Description

Runs one of the selected PCA methods

Usage

pca.run(x, ncomp, method, rand = NULL)

Arguments

Singular Values Decomposition based PCA algorithm

Description

Computes principal component space using Singular Values Decomposition

Usage

pca.svd(x, ncomp = min(ncol(x), nrow(x) - 1))

Arguments

Value

a list with scores, loadings and eigenvalues for the components

Results of PCA decomposition

Description

pcares is used to store and visualise results for PCA decomposition.

Usage

pcares(...)

Arguments

Details

In fact pcares is a wrapper for ldecomp - general class for storing results for linear decomposition X = TP' + E. So, most of the methods, arguments and returned values are inherited from ldecomp.

There is no need to create a pcares object manually, it is created automatically when build a PCA model (see pca) or apply the model to a new data (see predict.pca). The object can be used to show summary and plots for the results.

It is assumed that data is a matrix or data frame with I rows and J columns.

Value

Returns an object (list) of class pcares and ldecomp with following fields:

See Also

Methods for pcares objects:

Methods, inherited from ldecomp class:

Check also pca and ldecomp.

Examples

### Examples for PCA results class

library(mdatools)

## 1. Make a model for every odd row of People data
## and apply it to the objects from every even row

data(people)
x = people[seq(1, 32, 2), ]
x.new = people[seq(1, 32, 2), ]

model = pca(people, scale = TRUE, info = "Simple PCA model")
model = selectCompNum(model, 4)

res = predict(model, x.new)
summary(res)
plot(res)

## 1. Make PCA model for People data with autoscaling
## and full cross-validation and get calibration results

data(people)
model = pca(people, scale = TRUE, info = "Simple PCA model")
model = selectCompNum(model, 4)

res = model$calres
summary(res)
plot(res)

## 2. Show scores plots for the results
par(mfrow = c(2, 2))
plotScores(res)
plotScores(res, cgroup = people[, "Beer"], show.labels = TRUE)
plotScores(res, comp = c(1, 3), show.labels = TRUE)
plotScores(res, comp = 2, type = "h", show.labels = TRUE)
par(mfrow = c(1, 1))

## 3. Show residuals and variance plots for the results
par(mfrow = c(2, 2))
plotVariance(res, type = "h")
plotCumVariance(res, show.labels = TRUE)
plotResiduals(res, show.labels = TRUE, cgroup = people[, "Sex"])
plotResiduals(res, ncomp = 2, show.labels = TRUE)
par(mfrow = c(1, 1))

Image data

Description

Dataset for showing how mdatools works with images. It is an RGB image represented as 3-way array.

Usage

data(people)

Format

a 3-way array (height x width x channels).

Details

This is an image with pellets of four different colours mixed in a glas volume.

People data

Description

Dataset for exploratory analysis with 32 objects (male and female persons) and 12 variables.

Usage

data(people)

Format

a matrix with 32 observations (persons) and 12 variables.

Details

The data was taken from the book [1] and is in fact a small subset of a pan-European demographic survey. It includes information about 32 persons, 16 represent northern Europe (Scandinavians) and 16 are from the Mediterranean regions. In both groups there are 8 male and 8 female persons. The data includes both quantitative and qualitative variables and is particularly useful for benchmarking exploratory data analysis methods.

Source

1. K. Esbensen. Multivariate Data Analysis in Practice. Camo, 2002.

Pseudo-inverse matrix

Description

Computes pseudo-inverse matrix using SVD

Usage

pinv(data)

Arguments

Plot function for classification results

Description

Generic plot function for classification results. Alias for plotPredictions.classres.

Usage

## S3 method for class 'classres'
plot(x, ...)

Arguments

Overview plot for iPLS results

Description

Shows a plot for iPLS results.

Usage

## S3 method for class 'ipls'
plot(x, ...)

Arguments

Details

See details for plotSelection.ipls.

Plot summary for MCR model

Description

Plot summary for MCR model

Usage

## S3 method for class 'mcr'
plot(x, ...)

Arguments

Model overview plot for PCA

Description

Shows a set of plots (scores, loadings, residuals and explained variance) for PCA model.

Usage

## S3 method for class 'pca'
plot(
  x,
  comp = c(1, 2),
  ncomp = x$ncomp.selected,
  show.labels = FALSE,
  show.legend = TRUE,
  ...
)

Arguments

Details

See examples in help for pca function.

Plot method for PCA results object

Description

Show several plots to give an overview about the PCA results

Usage

## S3 method for class 'pcares'
plot(x, comp = c(1, 2), ncomp = x$ncomp.selected, show.labels = TRUE, ...)

Arguments

Model overview plot for PLS

Description

Shows a set of plots (x residuals, regression coefficients, RMSE and predictions) for PLS model.

Usage

## S3 method for class 'pls'
plot(x, ncomp = x$ncomp.selected, ny = 1, show.legend = TRUE, ...)

Arguments

Details

See examples in help for pls function.

Model overview plot for PLS-DA

Description

Shows a set of plots (x residuals, regression coefficients, misclassification ratio and predictions) for PLS-DA model.

Usage

## S3 method for class 'plsda'
plot(x, ncomp = x$ncomp.selected, nc = 1, show.legend = TRUE, ...)

Arguments

Details

See examples in help for plsda function.

Overview plot for PLS-DA results

Description

Shows a set of plots (x residuals, y variance, classification performance and predictions) for PLS-DA results.

Usage

## S3 method for class 'plsdares'
plot(x, nc = 1, ncomp = x$ncomp.selected, show.labels = FALSE, ...)

Arguments

Details

See examples in help for pls function.

Overview plot for PLS results

Description

Shows a set of plots for PLS results.

Usage

## S3 method for class 'plsres'
plot(x, ncomp = x$ncomp.selected, ny = 1, show.labels = FALSE, ...)

Arguments

Details

See examples in help for plsres function.

Plot for randomization test results

Description

Makes a bar plot with alpha values for each component.

Usage

## S3 method for class 'randtest'
plot(x, main = "Alpha", xlab = "Components", ylab = "", ...)

Arguments

Details

See examples in help for randtest function.

Regression coefficients plot

Description

Shows plot with regression coefficient values for every predictor variable (x)

Usage

## S3 method for class 'regcoeffs'
plot(
  x,
  ncomp = 1,
  ny = 1,
  type = (if (x$nvar > 30) "l" else "h"),
  col = c(mdaplot.getColors(1), "lightgray"),
  show.lines = c(NA, 0),
  show.ci = FALSE,
  alpha = 0.05,
  ylab = paste0("Coefficients (", x$respnames[ny], ")"),
  ...
)

Arguments

Plot method for regression results

Description

Plot method for regression results

Usage

## S3 method for class 'regres'
plot(x, ...)

Arguments

Details

This is a shortcut for plotPredictions.regres

Model overview plot for SIMCA

Description

Shows a set of plots for SIMCA model.

Usage

## S3 method for class 'simca'
plot(x, comp = c(1, 2), ncomp = x$ncomp.selected, ...)

Arguments

Details

See examples in help for simcam function.

Model overview plot for SIMCAM

Description

Shows a set of plots for SIMCAM model.

Usage

## S3 method for class 'simcam'
plot(x, nc = c(1, 2), ...)

Arguments

Details

See examples in help for simcam function.

Model overview plot for SIMCAM results

Description

Just shows a prediction plot for SIMCAM results.

Usage

## S3 method for class 'simcamres'
plot(x, ...)

Arguments

Details

See examples in help for simcamres function.

Show plot series as bars

Description

First row of the data matrix is taken for creating the bar series. In case of barplot color grouping is made based on columns (not rows as for all other plots).

Usage

plotBars(ps, col = ps$col, bwd = 0.8, border = NA, force.x.values = NA)

Arguments

Biplot

Description

Biplot

Usage

plotBiplot(obj, ...)

Arguments

Details

Generic function for biplot

PCA biplot

Description

Shows a biplot for selected components.

Usage

## S3 method for class 'pca'
plotBiplot(
  obj,
  comp = c(1, 2),
  pch = c(16, NA),
  col = mdaplot.getColors(2),
  main = "Biplot",
  lty = 1,
  lwd = 1,
  show.labels = FALSE,
  show.axes = TRUE,
  show.excluded = FALSE,
  lab.col = adjustcolor(col, alpha.f = 0.5),
  ...
)

Arguments

Add confidence ellipse for groups of points on scatter plot

Description

The method shows confidence ellipse for groups of points on a scatter plot made using 'mdaplot()' function with 'cgroup' parameter. It will work only if 'cgroup' is a factor.

Usage

plotConfidenceEllipse(p, conf.level = 0.95, lwd = 1, lty = 1, opacity = 0)

Arguments

Examples

# adds 90% confidence ellipse with semi-transparent area over two clusters of points

library(mdatools)
data(people)
group <- factor(people[, "Sex"], labels = c("Male", "Female"))

# first make plot and then add confidence ellipse
p <- mdaplot(people, type = "p", cgroup = group)
plotConfidenceEllipse(p, conf.level = 0.90, opacity = 0.2)

Plot resolved contributions

Description

Plot resolved contributions

Usage

plotContributions(obj, ...)

Arguments

Show plot with resolved contributions

Description

Show plot with resolved contributions

Usage

## S3 method for class 'mcr'
plotContributions(
  obj,
  comp = seq_len(obj$ncomp),
  type = "l",
  col = mdaplot.getColors(obj$ncomp),
  ...
)

Arguments

Add convex hull for groups of points on scatter plot

Description

The method shows convex hull for groups of points on a scatter plot made using 'mdaplot()' function with 'cgroup' parameter. It will work only if 'cgroup' is a factor.

Usage

plotConvexHull(p, lwd = 1, lty = 1, opacity = 0)

Arguments

Examples

# adds convex hull with semi-transparent area over two clusters of points

library(mdatools)
data(people)
group <- factor(people[, "Sex"], labels = c("Male", "Female"))

p <- mdaplot(people, type = "p", cgroup = group)
plotConvexHull(p)

Cooman's plot

Description

Cooman's plot

Usage

plotCooman(obj, ...)

Arguments

Details

Generic function for Cooman's plot

Cooman's plot for SIMCAM model

Description

Shows a Cooman's plot for a pair of SIMCA models

Usage

## S3 method for class 'simcam'
plotCooman(
  obj,
  nc = c(1, 2),
  res = list(cal = obj$res[["cal"]]),
  groupby = res[[1]]$c.ref,
  main = "Cooman's plot",
  show.limits = TRUE,
  ...
)

Arguments

Details

Cooman's plot shows squared orthogonal distance from data points to two selected SIMCA models as well as critical limits for the distance (optional). In case if critical limits must be shown they are computed using chi-square distribution regardless which type of limits is employed for classification.

If only one result object is provided (e.g. results for calibration set or new predictions), then the points can be color grouped using 'groupby' parameter (by default reference class values are used to make the groups). In case of multiple result objects, the points are color grouped according to the objects (e.g. calibration set and test set).

Cooman's plot for SIMCAM results

Description

Shows a Cooman's plot for a pair of SIMCA models

Usage

## S3 method for class 'simcamres'
plotCooman(
  obj,
  nc = c(1, 2),
  main = "Cooman's plot",
  cgroup = obj$c.ref,
  show.plot = TRUE,
  ...
)

Arguments

Details

The plot is similar to plotCooman.simcam but shows points only for this result object and does not show critical limits (which are part of a model).

Correlation plot

Description

Correlation plot

Usage

plotCorr(obj, ...)

Arguments

Details

Generic function for correlation plot

Correlation plot for randomization test results

Description

Makes a plot with statistic values vs. coefficient of determination between permuted and reference y-values.

Usage

## S3 method for class 'randtest'
plotCorr(
  obj,
  ncomp = obj$ncomp.selected,
  ylim = NULL,
  xlab = expression(r^2),
  ylab = "Test statistic",
  ...
)

Arguments

Details

See examples in help for randtest function.

Variance plot

Description

Variance plot

Usage

plotCumVariance(obj, ...)

Arguments

Details

Generic function for plotting explained variance for data decomposition

Cumulative explained variance plot

Description

Shows a plot with cumulative explained variance vs. number of components.

Usage

## S3 method for class 'ldecomp'
plotCumVariance(obj, type = "b", labels = "values", show.plot = TRUE, ...)

Arguments

Show plot with cumulative explained variance

Description

Show plot with cumulative explained variance

Usage

## S3 method for class 'mcr'
plotCumVariance(
  obj,
  type = "b",
  labels = "values",
  main = "Cumulative variance",
  xticks = seq_len(obj$ncomp),
  ...
)

Arguments

Cumulative explained variance plot for PCA model

Description

Shows a plot with cumulative explained variance for components.

Usage

## S3 method for class 'pca'
plotCumVariance(obj, legend.position = "bottomright", ...)

Arguments

Details

See examples in help for pca function.

Show plot series as density plot (using hex binning)

Description

Show plot series as density plot (using hex binning)

Usage

plotDensity(ps, nbins = 60, colmap = ps$colmap)

Arguments

Discrimination power plot

Description

Discrimination power plot

Usage

plotDiscriminationPower(obj, ...)

Arguments

Details

Generic function for plotting discrimination power values for classification model

Discrimination power plot for SIMCAM model

Description

Shows a plot with discrimination power of predictors for a pair of SIMCA models

Usage

## S3 method for class 'simcam'
plotDiscriminationPower(
  obj,
  nc = c(1, 2),
  type = "h",
  main = paste0("Discrimination power: ", obj$classnames[nc[1]], " vs. ",
    obj$classname[nc[2]]),
  xlab = attr(obj$dispower, "xaxis.name"),
  ylab = "",
  ...
)

Arguments

Details

Discrimination power shows an ability of variables to separate classes. The power is computed similar to model distance, using variance of residuals. However in this case instead of sum the variance across all variables, we take the ratio separately for individual variables.

Discrimination power equal or above 3 is considered as high.

Degrees of freedom plot for both distances

Description

Shows a plot with degrees of freedom computed for score and orthogonal distances at given number of components using data driven approach ("ddmoments" or "ddrobust").

Usage

plotDistDoF(
  obj,
  type = "b",
  labels = "values",
  xticks = seq_len(obj$ncomp),
  ...
)

Arguments

Details

Work only if parameter lim.type equal to "ddmoments" or "ddrobust".

Show plot series as error bars

Description

It is assumed that first row of dataset contains the y-coordinates of points, second rows contains size of lower error bar and third - size for upper error bar. If only two rows are provided it is assumed that error bars are symmetric.

Usage

plotErrorbars(ps, col = ps$col, pch = 16, lwd = 1, cex = 1, ...)

Arguments

Shows extreme plot for SIMCA model

Description

Generic function for creating extreme plot for SIMCA model

Usage

plotExtreme(obj, ...)

Arguments

Extreme plot

Description

Shows a plot with number of expected vs. number of observed extreme objects for different significance levels (alpha values)

Usage

## S3 method for class 'pca'
plotExtreme(
  obj,
  res = obj$res[["cal"]],
  comp = obj$ncomp.selected,
  main = "Extreme plot",
  xlab = "Expected",
  ylab = "Observed",
  pch = rep(21, length(comp)),
  bg = mdaplot.getColors(length(comp)),
  col = rep("white", length(comp)),
  lwd = ifelse(pch %in% 21:25, 0.25, 1),
  cex = rep(1.2, length(comp)),
  ellipse.col = "#cceeff",
  legend.position = "bottomright",
  ...
)

Arguments

Statistic histogram

Description

Statistic histogram

Usage

plotHist(obj, ...)

Arguments

Details

Generic function for plotting statistic histogram plot

Histogram plot for randomization test results

Description

Makes a histogram for statistic values distribution for particular component, also show critical value as a vertical line.

Usage

## S3 method for class 'randtest'
plotHist(obj, ncomp = obj$ncomp.selected, bwd = 0.9, ...)

Arguments

Details

See examples in help for randtest function.

Hotelling ellipse

Description

Add Hotelling ellipse to a scatter plot

Usage

plotHotellingEllipse(p, conf.lim = 0.95, col = "#a0a0a0", lty = 3, ...)

Arguments

Details

The method is created to be used with PCA and PLS scores plots, so it shows the statistical limits computed using Hotelling T^2 distribution in form of ellipse. The function works similar to plotConvexHull and plotConfidenceEllipse but does not require grouping of data points. Can be used together with functions plotScores.pca, plotScores.ldecomp, plotXScores.pls, plotXScores.plsres.

See examples for more details.

Examples

# create PCA model for People data
data(people)
m <- pca(people, 4, scale = TRUE)

# make scores plot and show Hotelling ellipse with default settings
p <- plotScores(m, xlim = c(-8, 8), ylim = c(-8, 8))
plotHotellingEllipse(p)

# make scores plot and show Hotelling ellipse with manual settings
p <- plotScores(m, xlim = c(-8, 8), ylim = c(-8, 8))
plotHotellingEllipse(p, conf.lim = 0.99, col = "red")

# in case if you have both calibration and test set, 'plotScores()' returns
# plot series data for both, so you have to subset it and take the first series
# (calibration set) as shown below.
ind <- seq(1, 32, by = 4)
xc <- people[-ind, , drop = FALSE]
xt <- people[ind, , drop = FALSE]
m <- pca(xc, 4, scale = TRUE, x.test = xt)

p <- plotScores(m, xlim = c(-8, 8), ylim = c(-8, 8))
plotHotellingEllipse(p[[1]])

Show plot series as set of lines

Description

Show plot series as set of lines

Usage

plotLines(
  ps,
  col = ps$col,
  lty = 1,
  lwd = 1,
  cex = 1,
  col.excluded = "darkgray",
  show.excluded = FALSE,
  ...
)

Arguments

Loadings plot

Description

Loadings plot

Usage

plotLoadings(obj, ...)

Arguments

Details

Generic function for plotting loadings values for data decomposition

Loadings plot for PCA model

Description

Shows a loadings plot for selected components.

Usage

## S3 method for class 'pca'
plotLoadings(
  obj,
  comp = if (obj$ncomp > 1) c(1, 2) else 1,
  type = (if (length(comp == 2)) "p" else "l"),
  show.legend = TRUE,
  show.axes = TRUE,
  ...
)

Arguments

Details

See examples in help for pca function.

Misclassification ratio plot

Description

Misclassification ratio plot

Usage

plotMisclassified(obj, ...)

Arguments

Details

Generic function for plotting missclassification values for classification model or results

Misclassified ratio plot for classification model

Description

Makes a plot with misclassified ratio values vs. model complexity (e.g. number of components)

Usage

## S3 method for class 'classmodel'
plotMisclassified(obj, ...)

Arguments

Details

See examples in description of plsda, simca or simcam.

Misclassified ratio plot for classification results

Description

Makes a plot with ms ratio values vs. model complexity (e.g. number of components) for classification results.

Usage

## S3 method for class 'classres'
plotMisclassified(obj, ...)

Arguments

Details

See examples in description of plsdares, simcamres, etc.

Model distance plot

Description

Model distance plot

Usage

plotModelDistance(obj, ...)

Arguments

Details

Generic function for plotting distance from object to a multivariate model

Model distance plot for SIMCAM model

Description

Shows a plot with distance between one SIMCA model to others.

Usage

## S3 method for class 'simcam'
plotModelDistance(
  obj,
  nc = 1,
  type = "h",
  xticks = seq_len(obj$nclasses),
  xticklabels = obj$classnames,
  main = paste0("Model distance (", obj$classnames[nc], ")"),
  xlab = "Models",
  ylab = "",
  ...
)

Arguments

Details

The plot shows similarity between a selected model and the others as a ratio of residual variance using the following algorithm. Let's take two SIMCA/PCA models, m1 and m2, which have optimal number of components A1 and A2. The models have been calibrated using calibration sets X1 and X2 with number of rows n1 and n2. Then we do the following:

1. Project X2 to model m1 and compute residuals, E12

2. Compute variance of the residuals as s12 = sum(E12^2) / n1

3. Project X1 to model m2 and compute residuals, E21

4. Compute variance of the residuals as s21 = sum(E21^2) / n2

5. Compute variance of residuals for m1 as s1 = sum(E1^2) / (n1 - A1 - 1)

6. Compute variance of residuals for m2 as s2 = sum(E2^2) / (n2 - A2 - 1)

The model distance then can be computed as: d = sqrt((s12 + s21) / (s1 + s2))

As one can see, if the two models and corresponding calibration sets are identical, then the distance will be sqrt((n - A - 1) / n). For example, if n = 25 and A = 2, then the distance between the model and itself is sqrt(22/25) = sqrt(0.88) = 0.938. This case is demonstrated in the example section.

In general, if distance between models is below one classes are overlapping. If it is above 3 the classes are well separated.

Examples

# create two calibration sets with n = 25 objects in each
data(iris)
x1 <- iris[1:25, 1:4]
x2 <- iris[51:75, 1:4]

# create to SIMCA models with A = 2
m1 <- simca(x1, 'setosa', ncomp = 2)
m2 <- simca(x2, 'versicolor', ncomp = 2)

# combine the models into SIMCAM class
m <- simcam(list(m1, m2))

# show the model distance plot with distance values as labels
# note, that distance between setosa and setosa is 0.938
plotModelDistance(m, show.labels = TRUE, labels = "values")

Modelling power plot

Description

Modelling power plot

Usage

plotModellingPower(obj, ...)

Arguments

Details

Generic function for plotting modelling power values for classification model

Classification performance plot

Description

Classification performance plot

Usage

plotPerformance(obj, ...)

Arguments

Details

Generic function for plotting classification performance for model or results

Performance plot for classification model

Description

Makes a plot with sensitivity values vs. model complexity (e.g. number of components)

Usage

## S3 method for class 'classmodel'
plotPerformance(
  obj,
  nc = 1,
  param = "misclassified",
  type = "b",
  labels = "values",
  ylab = "",
  ylim = c(0, 1.15),
  xticks = seq_len(dim(obj$res$cal$c.pred)[2]),
  res = obj$res,
  ...
)

Arguments

Performance plot for classification results

Description

Makes a plot with classification performance parameters vs. model complexity (e.g. number of components) for classification results.

Usage

## S3 method for class 'classres'
plotPerformance(
  obj,
  nc = 1,
  type = "b",
  param = c("sensitivity", "specificity", "misclassified"),
  labels = "values",
  ylab = "",
  ylim = c(0, 1.1),
  xticks = seq_len(obj$ncomp),
  show.plot = TRUE,
  ...
)

Arguments