analogue (version 0.10-0)

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 class '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 class '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 class 'wa':
fitted(object, \dots)
## S3 method for class 'wa':
residuals(object, \dots)
## S3 method for class 'wa':
coef(object, \dots)
waFit(x, y, tol.dw, useN2, deshrink, na.tol, small.tol,
      min.tol, f)

Arguments

x

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.

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

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

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:

[object Object],[object Object],[object Object],[object Object]

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.

See Also

mat for an alternative transfer function method.

Examples

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)