% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/CVE.R
\name{cve.call}
\alias{cve.call}
\title{Conditional Variance Estimator (CVE).}
\usage{
cve.call(X, Y, method = "simple", nObs = sqrt(nrow(X)), h = NULL,
  min.dim = 1L, max.dim = 10L, k = NULL, momentum = 0, tau = 1,
  tol = 0.001, slack = 0, gamma = 0.5, V.init = NULL,
  max.iter = 50L, attempts = 10L, logger = NULL)
}
\arguments{
\item{X}{Design matrix with dimension \eqn{n\times p}{n x p}.}

\item{Y}{numeric array of length \eqn{n} of Responses.}

\item{method}{specifies the CVE method variation as one of
\itemize{
     \item "simple" exact implementation as described in the paper listed 
         below.
     \item "weighted" variation with addaptive weighting of slices.
}}

\item{nObs}{parameter for choosing bandwidth \code{h} using
\code{\link{estimate.bandwidth}} (ignored if \code{h} is supplied).}

\item{h}{bandwidth or function to estimate bandwidth, defaults to internaly
estimated bandwidth.}

\item{min.dim}{lower bounds for \code{k}, (ignored if \code{k} is supplied).}

\item{max.dim}{upper bounds for \code{k}, (ignored if \code{k} is supplied).}

\item{k}{Dimension of lower dimensional projection, if \code{k} is given
only the specified dimension \code{B} matrix is estimated.}

\item{momentum}{number of \eqn{[0, 1)} giving the ration of momentum for
eucledian gradient update with a momentum term. \code{momentum = 0}
corresponds to normal gradient descend.}

\item{tau}{Initial step-size.}

\item{tol}{Tolerance for break condition.}

\item{slack}{Positive scaling to allow small increases of the loss while
optimizing, i.e. \code{slack = 0.1} allows the target function to
increase up to \eqn{10 \%} in one optimization step.}

\item{gamma}{step-size reduction multiple. If gradient step with step size
\code{tau} is not accepted \code{gamma * tau} is set to the next step
size.}

\item{V.init}{Semi-orthogonal matrix of dimensions `(ncol(X), ncol(X) - k)
used as starting value in the optimization. (If supplied,
\code{attempts} is set to 0 and \code{k} to match dimension).}

\item{max.iter}{maximum number of optimization steps.}

\item{attempts}{If \code{V.init} not supplied, the optimization is carried
out \code{attempts} times with starting values drawn from the invariant
measure on the Stiefel manifold (see \code{\link{rStiefel}}).}

\item{logger}{a logger function (only for advanced user, slows down the
computation).}
}
\value{
an S3 object of class \code{cve} with components:
\describe{
   \item{X}{design matrix of predictor vector used for calculating
     cve-estimate,}
   \item{Y}{\eqn{n}-dimensional vector of responses used for calculating
       cve-estimate,}
   \item{method}{Name of used method,}
   \item{call}{the matched call,}
   \item{res}{list of components \code{V, L, B, loss, h} for
      each \code{k = min.dim, ..., max.dim}. If \code{k} was supplied in the
      call \code{min.dim = max.dim = k}.
      \itemize{
          \item \code{B} is the cve-estimate with dimension
              \eqn{p\times k}{p x k}.
          \item \code{V} is the orthogonal complement of \eqn{B}.
          \item \code{L} is the loss for each sample seperatels such that
              it's mean is \code{loss}.
          \item \code{loss} is the value of the target function that is 
              minimized, evaluated at \eqn{V}.
          \item \code{h} bandwidth parameter used to calculate
              \code{B, V, loss, L}.
      }
   }
}
}
\description{
Conditional Variance Estimation (CVE) is a novel sufficient dimension
reduction (SDR) method for regressions satisfying \eqn{E(Y|X) = E(Y|B'X)},
where \eqn{B'X} is a lower dimensional projection of the predictors. CVE,
similarly to its main competitor, the mean average variance estimation
(MAVE), is not based on inverse regression, and does not require the
restrictive linearity and constant variance conditions of moment based SDR
methods. CVE is data-driven and applies to additive error regressions with
continuous predictors and link function. The effectiveness and accuracy of 
CVE compared to MAVE and other SDR techniques is demonstrated in simulation
studies. CVE is shown to outperform MAVE in some model set-ups, while it
remains largely on par under most others.
Let \eqn{Y} be real denotes a univariate response and \eqn{X} a real
\eqn{p}-dimensional covariate vector. We assume that the dependence of
\eqn{Y} and \eqn{X} is modelled by
\deqn{Y = g(B'X) + \epsilon}
where \eqn{X} is independent of \eqn{\epsilon} with positive definite
variance-covariance matrix \eqn{Var(X) = \Sigma_X}. \eqn{\epsilon} is a mean
zero random variable with finite \eqn{Var(\epsilon) = E(\epsilon^2)}, \eqn{g}
is an unknown, continuous non-constant function,
and \eqn{B = (b_1, ..., b_k)} is
a real \eqn{p \times k}{p x k} of rank \eqn{k \leq p}{k <= p}. 
Without loss of generality \eqn{B} is assumed to be orthonormal.
}
\examples{
# create B for simulation (k = 1)
B <- rep(1, 5) / sqrt(5)

set.seed(21)
# creat predictor data X ~ N(0, I_p)
X <- matrix(rnorm(500), 100, 5)
# simulate response variable
#     Y = f(B'X) + err
# with f(x1) = x1 and err ~ N(0, 0.25^2)
Y <- X \%*\% B + 0.25 * rnorm(100)

# calculate cve with method 'simple' for k = 1
set.seed(21)
cve.obj.simple1 <- cve(Y ~ X, k = 1)

# same as
set.seed(21)
cve.obj.simple2 <- cve.call(X, Y, k = 1)

# extract estimated B's.
coef(cve.obj.simple1, k = 1)
coef(cve.obj.simple2, k = 1)
}