1\name{Coef.qrrvglm}
2\alias{Coef.qrrvglm}
3%- Also NEED an '\alias' for EACH other topic documented here.
4\title{ Returns Important Matrices etc. of a QO Object }
5\description{
6  This methods function returns important matrices etc. of a
7  QO object.
8
9
10}
11\usage{
12Coef.qrrvglm(object, varI.latvar = FALSE, refResponse = NULL, ...)
13}
14%- maybe also 'usage' for other objects documented here.
15\arguments{
16  \item{object}{
17% A CQO or UQO object.
18  A CQO object.
19  The former has class \code{"qrrvglm"}.
20
21
22  }
23
24
25  \item{varI.latvar}{
26  Logical indicating whether to scale the site scores (latent variables)
27  to have variance-covariance matrix equal to the rank-\eqn{R} identity
28  matrix. All models have uncorrelated site scores (latent variables),
29  and this option stretches or shrinks the ordination axes if \code{TRUE}.
30  See below for further details.
31
32
33
34  }
35  \item{refResponse}{
36    Integer or character.
37    Specifies the \emph{reference response} or \emph{reference species}.
38    By default, the reference
39    species is found by searching sequentially starting from the first
40    species until a positive-definite tolerance matrix is found. Then
41    this tolerance matrix is transformed to the identity matrix. Then
42    the sites scores (latent variables) are made uncorrelated.
43    See below for further details.
44
45
46%   If \code{eq.tolerances=FALSE}, then transformations occur so that
47%   the reference species has a tolerance matrix equal to the rank-\eqn{R}
48%   identity matrix.
49
50
51  }
52  \item{\dots}{ Currently unused. }
53}
54\details{
55
56  If \code{I.tolerances=TRUE} or \code{eq.tolerances=TRUE} (and its
57  estimated tolerance matrix is positive-definite) then all species'
58  tolerances are unity by transformation or by definition, and the spread
59  of the site scores can be compared to them. Vice versa, if one wishes
60  to compare the tolerances with the sites score variability then setting
61  \code{varI.latvar=TRUE} is more appropriate.
62
63
64  For rank-2 QRR-VGLMs, one of the species can be chosen so that the
65  angle of its major axis and minor axis is zero, i.e., parallel to
66  the ordination axes.  This means the effect on the latent vars is
67  independent on that species, and that its tolerance matrix is diagonal.
68  The argument \code{refResponse} allows one to choose which is the reference
69  species, which must have a positive-definite tolerance matrix, i.e.,
70  is bell-shaped.  If \code{refResponse} is not specified, then the code will
71  try to choose some reference species starting from the first species.
72  Although the \code{refResponse} argument could possibly be offered as
73  an option when fitting the model, it is currently available after
74  fitting the model, e.g., in the functions \code{\link{Coef.qrrvglm}} and
75  \code{\link{lvplot.qrrvglm}}.
76
77
78}
79\value{
80  The \bold{A}, \bold{B1}, \bold{C},  \bold{T},  \bold{D} matrices/arrays
81  are returned, along with other slots.
82  The returned object has class \code{"Coef.qrrvglm"}
83  (see \code{\link{Coef.qrrvglm-class}}).
84
85
86% For UQO, \bold{C} is undefined.
87
88
89
90}
91\references{
92Yee, T. W. (2004).
93A new technique for maximum-likelihood
94canonical Gaussian ordination.
95\emph{Ecological Monographs},
96\bold{74}, 685--701.
97
98
99Yee, T. W. (2006).
100Constrained additive ordination.
101\emph{Ecology}, \bold{87}, 203--213.
102
103
104}
105\author{ Thomas W. Yee }
106\note{
107Consider an equal-tolerances Poisson/binomial CQO model with \code{noRRR = ~ 1}.
108For \eqn{R=1} it has about \eqn{2S+p_2}{2*S+p2} parameters.
109For \eqn{R=2} it has about \eqn{3S+2 p_2}{3*S+2*p_2} parameters.
110Here, \eqn{S} is the number of species, and \eqn{p_2=p-1}{p2=p-1} is
111the number of environmental variables making up the latent variable.
112For an unequal-tolerances Poisson/binomial CQO model with
113\code{noRRR = ~ 1}, it has about \eqn{3S -1 +p_2}{3*S-1+p2} parameters
114for \eqn{R=1}, and about \eqn{6S -3 +2p_2}{6*S -3 +2*p2} parameters
115for \eqn{R=2}.
116Since the total number of data points is \eqn{nS}{n*S}, where
117\eqn{n} is the number of sites, it pays to divide the number
118of data points by the number of parameters to get some idea
119about how much information the parameters contain.
120
121
122}
123
124% ~Make other sections like Warning with \section{Warning }{....} ~
125\seealso{
126\code{\link{cqo}},
127\code{\link{Coef.qrrvglm-class}},
128\code{print.Coef.qrrvglm},
129\code{\link{lvplot.qrrvglm}}.
130
131
132}
133
134\examples{
135set.seed(123)
136x2 <- rnorm(n <- 100)
137x3 <- rnorm(n)
138x4 <- rnorm(n)
139latvar1 <- 0 + x3 - 2*x4
140lambda1 <- exp(3 - 0.5 * ( latvar1-0)^2)
141lambda2 <- exp(2 - 0.5 * ( latvar1-1)^2)
142lambda3 <- exp(2 - 0.5 * ((latvar1+4)/2)^2)  # Unequal tolerances
143y1 <- rpois(n, lambda1)
144y2 <- rpois(n, lambda2)
145y3 <- rpois(n, lambda3)
146set.seed(111)
147# vvv p1 <- cqo(cbind(y1, y2, y3) ~ x2 + x3 + x4, poissonff, trace = FALSE)
148\dontrun{ lvplot(p1, y = TRUE, lcol = 1:3, pch = 1:3, pcol = 1:3)
149}
150# vvv Coef(p1)
151# vvv print(Coef(p1), digits=3)
152}
153\keyword{models}
154\keyword{regression}
155
156
157