\name{xenv}
\alias{xenv}
\title{Fit the envelope based PLS.}
\description{
  This function fits the envelope model to the responses and predictors,
  using the maximum likelihood estimation.  When the dimension of the envelope is between 1 and p-1, we implemented the algorithm in Cook   et al (2013).  When the dimension is p, then the envelope model ddegenerates to
the standard multivariate linear regression.  When the dimension is 0,
  it means that X and Y are uncorrelated, and the fitting is different.
  }
\usage{
       ModelOutput = xenv(X, Y, u)
   }

\arguments{
  \item{X}{Predictors. An n by p matrix, p is the number of predictors. The predictors can be univariate or multivariate, discrete or continuous.}
  \item{Y}{Multivariate responses. An n by r matrix, r is the number of responses and n is number of observations. The responses must be continuous variables.}
  \item{u}{Dimension of the envelope. An integer between 0 and p.}
  \item{maxIter}{Maximum number of iterations.  Default value: 100.}
  \item{ftol}{Tolerance parameter for F.  Default value: 1e-3. }
  \item{verbose}{Flag for print out model fitting process, logical 0 or 1. Default value: 0.}
  \item{asym}{Flag for calculate compute the asyptotic covariance of vec(beta) and asymptotic standard error for elements in beta for a fiteed envelope model, logical 0 or 1. Default value: 0. }  
  \item{init}{The initial value for the envelope subspace. An p by u matrix. Default value is the one generated by function get_Init.}
}
%\details{}
\value{
  \item{mu}{The estimated intercept in the envelope model.  An r by 1 vector.}
  \item{beta}{The envelope estimator of the regression coefficients. An p by r matrix.}
  \item{Gamma}{The orthogonal basis of the envelope subspace. An p by u semi-orthogonal matrix.}
  \item{Gamma0}{The orthogonal basis of the complement of the envelope subspace.  An p by p-u semi-orthogonal matrix.}
  \item{eta}{The coordinates of beta with respect to Gamma. A u by r matrix.}
  \item{SigX}{The envelope estimator of the covariance matrix of X.  An p by p matrix.}
  \item{Omega}{The coordinates of Sigma with respect to Gamma. A u by u matrix.}
  \item{Omega0}{The coordinates of Sigma with respect to Gamma0. An p-u by p-u matrix.}

  \item{sigYcX}{The estimated conditional covariance matrix of Y given X. An r by r matrix.}
  \item{loglik}{The maximized log likelihood function.  A real number.}
  \item{covMatrix}{The asymptotic covariance of vec(beta). An pr by pr matrix. The covariance matrix returned are asymptotic.  For the actual standard errors, multiply by 1/n.}
  \item{asySE}{The asymptotic standard error for elements in beta under the envelope model.  An p by r matrix.  The standard errors returned are asymptotic, for actual standard errors, multiply by 1/sqrt(n).}
  \item{ratio}{The asymptotic standard error ratio of the standard multivariate linear regression estimator over the envelope estimator, for each element in beta.  An r by p matrix.}
  \item{paramNum}{The number of parameters in the envelope model.  A positive integer.}
  \item{n}{The number of observations in the data.  A positive integer.}
  \item{fit_time}{The time costs for fitting the envelope model.}
}
  
\references{
Cook, R. D., Helland, I. S. and Su, Z. (2013), Envelopes and Partial Least Squares Regression. \emph{Journal of the Royal Statistical Society: Series B}., 75, 851-877. 

The codes are implemented based on the algorithm in Cook, R. D., Forzani, L. and Su, Z. (2016), A Note on Fast Envelope Estimation. \emph{Journal of Multivariate Analysis.} 150, 42-54. 
}

\author{Guangyu Zhu and Zhihua Su\cr Maintainer: Guangyu Zhu \email{gzhu22@ufl.edu}}

\seealso{\code{choose_xenv} for choosing the dimension of envelope subspace.}

%\examples{
%# mussel
%data(AIS)
%m1 = xenv(AIS$X,AIS$Y,1)
%}