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", "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, ...)

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

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

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 `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 `NA`s. 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` 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.

### 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 `NA`s 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`.

### Author(s)

Gavin L. Simpson and Jari Oksanen

`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)

```

[Package analogue version 0.17-6 Index]