# Fit Co-Correspondence Analysis Ordination Models

### Description

`coca`

is used to fit Co-Correspondence Analysis (CoCA)
models. It can fit predictive or symmetric models to two community
data matrices containing species abundance data.

### Usage

1 2 3 4 5 6 7 8 9 10 11 | ```
coca(y, ...)
## Default S3 method:
coca(y, x, method = c("predictive", "symmetric"),
reg.method = c("simpls", "eigen"), weights = NULL,
n.axes = NULL, symmetric = FALSE, ...)
## S3 method for class 'formula'
coca(formula, data, method = c("predictive", "symmetric"),
reg.method = c("simpls", "eigen"), weights = NULL,
n.axes = NULL, symmetric = FALSE, ...)
``` |

### Arguments

`y` |
a data frame containing the response community data matrix. |

`x` |
a data frame containing the predictor community data matrix. |

`formula` |
a symbolic description of the model to be fit. The details of model specification are given below. |

`data` |
an optional data frame containing the variables in the model.
If not found in |

`method` |
a character string indicating which co-correspondence
analysis method to use. One of |

`reg.method` |
One of |

`weights` |
a vector of length |

`n.axes` |
the number of CoCA axes to extract. If missing (default)
the
. |

`symmetric` |
if |

`...` |
additional arguments to be passed to lower level methods. |

### Details

`coca`

is the main user-callable function.

A typical model has the form `response ~ terms`

where
`response`

is the (numeric) response data frame and `terms`

is a series of terms which specifies a linear predictor for
`response`

. A typical form for `terms`

is `.`

,
which is shorthand for "all variables" in `data`

. If `.`

is
used, `data`

must also be provided. If specific species
(variables) are required then `terms`

should take the form
`spp1 + spp2 + spp3`

.

The default is to fit a predictive CoCA model using SIMPLS via a
modified version of `simpls.fit`

from package
`pls`

. Alternatively, `reg.method = "eigen"`

fits the model
using an older, slower eigen analysis version of the SIMPLS
algorithm. `reg.method = "eigen"`

is about 100% slower than
`reg.method = "simpls"`

.

### Value

`coca`

returns a list with `method`

and `reg.method`

determining the actual components returned.

`nam.dat` |
list with components |

`call` |
the matched call. |

`method` |
the CoCA method used, one of |

`scores` |
the species and site scores of the fitted model. |

`loadings` |
the site loadings of the fitted model for the response and the predictor. (Predictive CoCA via SIMPLS only.) |

`fitted` |
the fitted values for the response. A list with 2
components |

`varianceExp` |
list with components |

`totalVar` |
list with components |

`lambda` |
the Eigenvalues of the analysis. |

`n.axes` |
the number of fitted axes |

`Ychi` |
a list containing the mean-centered chi-square matrices
for the response ( |

`R0` |
the (possibly user-supplied) row weights used in the analysis. |

`X` |
X-Matrix (symmetric CoCA only). |

`residuals` |
Residuals of a symmetric model (symmetric CoCA only). |

`inertia` |
list with components |

`rowsum` |
a list with the row sums for the response
( |

`colsum` |
a list with the column sums for the response
( |

### Author(s)

Original Matlab code by C.J.F. ter Braak and A.P. Schaffers. R
port by Gavin L. Simpson. Formula method for `coca`

uses a
modified version of `ordiParseFormula`

by Jari
Oksanen to handle formulea.

### References

ter Braak, C.J.F and Schaffers, A.P. (2004) Co-Correspondence
Analysis: a new ordination method to relate two community
compositions. *Ecology* **85(3)**, 834–846

### See Also

`crossval`

for cross-validation and
`permutest.coca`

for permutation test to determine the
number of PLS axes to retain in for predictive CoCA.

`summary.predcoca`

and `summary.symcoca`

for
summary methods.

### Examples

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 | ```
## symmetric CoCA
data(beetles)
## log transform the bettle data
beetles <- log(beetles + 1)
data(plants)
## fit the model
bp.sym <- coca(beetles ~ ., data = plants, method = "symmetric")
bp.sym
summary(bp.sym)
plot(bp.sym)
## predictive CoCA using SIMPLS and formula interface
bp.pred <- coca(beetles ~ ., data = plants)
## should retain only the useful PLS components for a parsimonious model
## Leave-one-out crossvalidation - this takes a while
## Not run:
crossval(beetles, plants)
## so 2 axes are sufficient
## permutation test to assess significant PLS components - takes a while
bp.perm <- permutest(bp.pred, permutations = 99)
bp.perm
## End(Not run)
## agrees with the Leave-one-out cross-validation
## refit the model with only 2 PLS components
bp.pred <- coca(beetles ~ ., data = plants, n.axes = 2)
bp.pred
summary(bp.pred)
plot(bp.pred)
## predictive CoCA using Eigen-analysis
data(bryophyte)
data(vascular)
carp.pred <- coca(y = bryophyte, x = vascular, reg.method = "eigen")
carp.pred
## determine important PLS components - takes a while
## Not run:
crossval(bryophyte, vascular)
(carp.perm <- permutest(carp.pred, permutations = 99))
## End(Not run)
## 2 components again, refit
carp.pred <- coca(y = bryophyte, x = vascular,
reg.method = "eigen", n.axes = 2)
carp.pred
## plot
plot(carp.pred)
``` |