wa {analogue}R Documentation

Weighted averaging transfer functions

Description

Implements the weighted averaging transfer function methodology. Tolerance down-weighting and inverse and classicial deshrinking are supported.

Usage

wa(x, ...)

## Default S3 method:
wa(x, env, deshrink = c("inverse", "classical", "expanded", "none"),
   tol.dw = FALSE, useN2 = TRUE,
   na.tol = c("min","mean","max"),
   small.tol = c("min","fraction","absolute"),
   min.tol = NULL, f = 0.1, ...)

## S3 method for class 'formula':
wa(formula, data, subset, na.action,
   deshrink = c("inverse", "classical", "expanded", "none"),
   tol.dw = FALSE, ..., model = FALSE)

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

## S3 method for class 'wa':
residuals(object, ...)

## S3 method for class 'wa':
coef(object, ...)

Arguments

x The species training set data
env The response vector
deshrink Which deshrinking method to use? One of "inverse" or "classical", "expanded" or "none"
tol.dw logical; should species with wider tolerances be given lower weight?
useN2 logical; should Hill's N2 values be used to produce un-biased tolerances?
na.tol character; method to use to replace missing (NA) tolerances in WA computations. Missing values are replaced with the minimum, average or maximum tolerance observed that is not missing.
small.tol character; method to replace small tolerances. See Details.
min.tol numeric; threshold below which tolerances are treated as being ‘small’.
f numeric, 0 < f < 1; fraction of environmental gradient env to replace small tolerances with if small.tol = "fraction" is specified.
formula a model formula
data an optional data frame, list or environment (or object coercible by as.data.frame to a data frame) containing the variables specified on the RHS of the model formula. If not found in data, the variables are taken from environment(formula), typically the environment from which wa is called.
subset an optional vector specifying a subset of observations to be used in the fitting process.
na.action a function which indicates what should happen when the data contain NAs. The default is set by the na.action setting of options, and is na.fail if that is unset. The 'factory-fresh' default is na.omit. Another possible value is NULL, no action. Value na.exclude can be useful.
model logical. If TRUE the model frame is returned.
object an Object of class "wa", the result of a call to wa.
... arguments to other methods.

Details

A typical model has the form response ~ terms whereresponse is the (numeric) response vector (the variable to be predicted) and terms is a series of terms which specifies a linear predictor for response. A terms specification of the form first + second indicates all the terms in first together with all the terms in second with duplicates removed. A specification of . is shorthand for all terms in data not already included in the model.

Species that have very small tolerances can dominate reconstructed values if tolerance down-weighting is used. In wa, small tolerances are defined as a tolerance that is < min.tol. These small tolerances can be adjusted in several ways:

min
small tolerances are replaced by the smallest observed tolerance that is greater than, or equal to, min.tol. With this method, the replaced values will be no smaller than any other observed tolerance. This is the default in analogue.
fraction
small tolerances are replaced by the fraction, f, of the observed environmental gradient in the training set, env.
absolute
small tolerances are replaced by min.tol.

Value

An object of class "wa", a list with the following components:

wa.optima The WA optima for each species in the model.
tolerances The actual tolerances calculated (these are weighted standard deviations).
model.tol The tolerances used in the WA model computations. These will be similar to tol, but will no contain any NAs and any small tolerances will have been replaced with the appropriate value.
fitted.values The fitted values of the response for each of the training set samples.
residuals Model residuals.
coefficients Deshrinking coefficients.
rmse The RMSE of the model.
r.squared The coefficient of determination of the observed and fitted values of the response.
avg.bias, max.bias The average and maximum bias statistics.
n.samp, n.spp The number of samples and species in the training set.
deshrink The deshrinking regression method used.
tol.dw logical; was tolerance down-weighting applied?
call The matched function call.
orig.x The training set species data.
orig.env The response data for the training set.
terms, model Model terms and model.frame components. Only returned by the formula method of wa.

Author(s)

Gavin L. Simpson and Jari Oksanen

See Also

mat for an alternative transfer function method.

Examples

data(swapdiat)
data(swappH)
swapdiat <- swapdiat / 100

## fit the WA model
mod <- wa(swappH ~., data = swapdiat)
mod

## extract the fitted values
fitted(mod)

## residuals for the training set
residuals(mod)

## deshrinking coefficients
coef(mod)

## diagnostics plots
par(mfrow = c(1,2))
plot(mod)
par(mfrow = c(1,1))

## tolerance DW
mod2 <- wa(swappH ~., data = swapdiat, tol.dw = TRUE)

## tolerances
with(mod2, tolerances)

## Imbrie and Kipp
data(ImbrieKipp)
data(SumSST)
ik.wa <- wa(SumSST ~ ., data = ImbrieKipp, tol.dw = TRUE,
            min.tol = 2, small.tol = "min")
ik.wa

## compare actual tolerances to working values
with(ik.wa, rbind(tolerances, model.tol))

[Package analogue version 0.6-6 Index]