wa: 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, …)
# S3 method for default
wa(x, env,
   deshrink = c("inverse", "classical", "expanded", "none", "monotonic"),
   tol.dw = FALSE, useN2 = TRUE,
   na.tol = c("min","mean","max"),
   small.tol = c("min","mean","fraction","absolute"),
   min.tol = NULL, f = 0.1, ...)
# S3 method for formula
wa(formula, data, subset, na.action,
   deshrink = c("inverse", "classical", "expanded", "none", "monotonic"),
   tol.dw = FALSE, useN2 = TRUE, na.tol = c("min","mean","max"),
   small.tol = c("min","mean","fraction","absolute"), min.tol = NULL,
   f = 0.1,..., model = FALSE)
# S3 method for wa
fitted(object, …)
# S3 method for wa
residuals(object, …)
# S3 method for wa
coef(object, …)
waFit(x, y, tol.dw, useN2, deshrink, na.tol, small.tol,
      min.tol, f)

Arguments

The species training set data

env, y

The response vector

deshrink

Which deshrinking method to use? One of "inverse" or "classical", "expanded", "none", or "monotonic".

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’. Default is not to replace small tolerances.

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.

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. Note that in the case of deshrink = "monotonic" this is a list with components sm (the representation of the smooth term as returned by smoothCon) and p (solutions to the least squares fit with monotonic constraints, the result of a call to pcls).

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.

options.tol

A list, containing the values of the arguments useN2, na.tol, small.tol, min.tol, and f.

terms, model

Model terms and model.frame components. Only returned by the formula method of wa.

Details

A typical model has the form response ~ terms where response 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. The default is to not replace small tolerances, and the user needs to specify suitable values of min.tol. Function tolerance may be of use in computing tolerances before fitting the WA model.

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.
mean: small tolerances are replaced by the average observed tolerance from the set that are greater than, or equal to, min.tol.
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.

Function waFit is the workhorse implementing the actual WA computations. It performs no checks on the input data and returns a simple list containing the optima, tolernances, model tolerances, fitted values, coefficients and the numbers of samples and species. See Value below for details of each component.

Examples

Run this code

# NOT RUN {
data(ImbrieKipp)
data(SumSST)

## fit the WA model
mod <- wa(SumSST ~., data = ImbrieKipp)
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))

## caterpillar plot of optima and tolerances
caterpillarPlot(mod)                 ## observed tolerances
caterpillarPlot(mod, type = "model") ## with tolerances used in WA model

## plot diagnostics for the WA model
par(mfrow = c(1,2))
plot(mod)
par(mfrow = c(1,1))

## tolerance DW
mod2 <- wa(SumSST ~ ., data = ImbrieKipp, tol.dw = TRUE,
           min.tol = 2, small.tol = "min")
mod2

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

## tolerance DW
mod3 <- wa(SumSST ~ ., data = ImbrieKipp, tol.dw = TRUE,
           min.tol = 2, small.tol = "mean")
mod3

## fit a WA model with monotonic deshrinking
mod4 <- wa(SumSST ~., data = ImbrieKipp, deshrink = "monotonic")
mod4

## extract the fitted values
fitted(mod4)

## residuals for the training set
residuals(mod4)

# }