\name{spxenv}
\alias{spxenv}
\title{Fit the envelope based sparse partial least squares model}
\description{
  This function fits the sparse envelope model to the predictor using
the maximum likelihood estimation.  When the dimension of the
  envelope is between 1 and p-1, we implemented the algorithm in G. Zhu and Z. Su 
  (2017).  When the dimension is p, then the envelope model degenerates 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 = spxenv(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{lambda1}{A user supplied lambda sequence for first stage.}
  \item{lambda2}{A user supplied lambda sequence for second stage.}
  \item{maxiter}{Maximum number of iterations.  Default value: 100.}
  \item{ftol}{Tolerance parameter for F.  Default value: 1e-4. } 
  \item{init}{The initial value for the envelope subspace. An r by u matrix. Default value is the one generated by function initial_value.}
  \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{verbose}{Flag for print out model fitting process, logical 0 or 1. Default value: 0.}
}
%\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 beta. A p by r matrix.} 
  \item{Gamma}{The orthogonal basis of the envelope subspace. A 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. A 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{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{q}{The number of active response variables.  A positive integer.}
  \item{iternum}{The number iteration. A positive integer.}
  \item{lambda}{The tuning parameters choosed by BIC.}
  \item{where_1}{The active responses chosen by the sparse envelope model.}
  \item{where_0}{The inactive responses chosen by the sparse envelope model.}
  \item{BIC_seq1}{The sequence of BIC in the first stage.}
  \item{BIC_seq2}{The sequence of BIC in the second stage.}
  \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{fit_time}{The time costs for fitting the envelope model.}
}
  
\references{
The codes are implemented based on the algorithm in Guangyu Zhu and Zhihua Su (2017). 'Envelope-based Sparse Partial Least Squares', Manuscript submitted for publication. 
}

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

\seealso{\code{choose_spxenv} for choosing the dimension of envelope subspace and the tuning parameter.}

%\examples{}