Package {prinsurf}

Contour reading error

Description

For each variable, the root-mean-square difference between the value read from the variable's contour lines at each sample's biplot position (as predict.prinsurf does) and the sample's actual value. This measures how accurately a variable can be recovered by reading its contours, combining the surface's lack of fit for that variable with the small loss from interpolating between contour lines; lower is better, in the units of the working data. Samples that fall outside the supported part of the contour grid cannot be read and are excluded; their number is returned as the attribute "n.unread".

Usage

contour_predictive_error(object)

Arguments

Value

A named numeric vector of per-variable RMS contour-reading errors, with the mean over all variables as the attribute "overall" and the number of unreadable samples as the attribute "n.unread".

See Also

predictivity for whole-sample reconstruction.

Fitted (reconstructed) values from a principal surface

Description

Returns the fitted surface values \hat f_j(\lambda_i) for every sample and variable: the point on the surface at which sample i sits, written back in the coordinates of the original variables. Row i is the surface's reconstruction of sample i – what the fit says the sample would be if it lay exactly on the surface – and the residual x_i - \hat f(\lambda_i) is the part of the sample the surface does not capture, which is what predictivity summarises.

Usage

## S3 method for class 'prinsurf'
fitted(object, ...)

Arguments

Details

Values are in the working units used for fitting: centred, and divided by each variable's standard deviation if the surface was fitted with scale = TRUE. This is the scale on which residuals and predictivity are computed. predict.prinsurf differs in two ways: it reads values off the plotted contour grid rather than evaluating the coordinate functions exactly, and it returns them on the variables' original scales.

Value

An n \times p matrix of fitted values, in working (centred, optionally scaled) units.

See Also

predictivity for the per-sample quality of this reconstruction, and predict.prinsurf for the values a reader obtains from the contours.

Plot a principal-surface biplot

Description

Draws the sample coordinates. If vars is given, draws one panel per named variable, each showing the sample coordinates together with that variable's contour lines - the surface's analogue of a biplot axis, read by interpolating between contour lines rather than by projection onto a single calibrated axis. With no vars, a single panel of sample coordinates is drawn with no contours.

Usage

## S3 method for class 'prinsurf'
plot(
  x,
  vars = NULL,
  group = NULL,
  col_contour = "grey40",
  nlevels = 6,
  pch = 16,
  cex = 0.7,
  asp = 1,
  main = NULL,
  outer_main = NULL,
  ...
)

Arguments

Value

Invisibly, vars.

Examples

set.seed(1)
s <- runif(120, -1, 1); t <- runif(120, -1, 1)
X <- cbind(x = s, y = t, z = 0.7 * s + 0.9 * t^2) +
     matrix(rnorm(360, 0, 0.03), 120, 3)
fit <- prinsurf(X, max.iter = 6)

## default: each panel is titled with its variable's name
plot(fit, vars = c("x", "z"))

## your own panel titles, and a title for the figure as a whole
plot(fit, vars = c("x", "z"),
     main = c("First coordinate", "Third coordinate"),
     outer_main = "Principal-surface biplot")

## a title on a single, contour-free panel
plot(fit, main = "Sample coordinates")

Predict all variables from the biplot contours

Description

Reads every variable's value for every sample off that variable's contour lines at the sample's biplot position \lambda_i – the same interpolation used to draw the contours in plot.prinsurf. Values come from the contour grid alone: a sample whose position is not covered by the supported part of the grid has no contours to read, and is returned as NA for every variable.

Usage

## S3 method for class 'prinsurf'
predict(object, ...)

Arguments

Value

An n \times p matrix of values read from the contours, on the variables' original scales, with NA rows where the biplot cannot be read.

See Also

contour_predictive_error to measure this reading against the variables' actual values, and fitted.prinsurf for the surface's own reconstruction of the data.

Sample predictivity of a principal-surface biplot

Description

For each sample, the proportion of its squared length reconstructed by the fitted surface, 1 - \lVert x_i - \hat f(\lambda_i) \rVert^2 / \lVert x_i \rVert^2. This is the principal-surface analogue of biplot sample predictivity and is read from the sample's position on the surface.

Usage

predictivity(object)

Arguments

Value

A numeric vector of per-sample predictivities (with the overall mean as the attribute "overall").

Fit a principal surface

Description

Fits a two-dimensional principal surface to a numeric data matrix using the iterative expectation / projection algorithm of Hastie and Stuetzle (1989), with the coordinate functions estimated by local regression (loess).

Usage

prinsurf(X, max.iter = 10, span = 0.6, scale = FALSE, verbose = FALSE)

Arguments

Value

An object of class "prinsurf": a list with elements lambda (the n \times 2 surface coordinates of the samples), fj.mat (the fitted surface coordinates of the samples in the working units), models (the per-variable loess coordinate functions), varnames, center, scale, span and iterations.

References

Hastie, T. and Stuetzle, W. (1989) Principal curves. Journal of the American Statistical Association 84, 502–516.

Examples

set.seed(1)
s <- runif(120, -1, 1); t <- runif(120, -1, 1)
X <- cbind(x = s, y = t, z = 0.7 * s + 0.9 * t^2) +
     matrix(rnorm(360, 0, 0.03), 120, 3)
fit <- prinsurf(X, max.iter = 6)
fit