trend.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/trend.R
\name{trend}
\alias{trend}
\title{Trend Component from a \code{km} Object}
\usage{
trend(object, X, deriv = 0, diagOnly = FALSE)
}
\arguments{
\item{object}{A \code{km} object.}

\item{X}{A "design": a numeric matrix or data frame wih numeric
columns compatible with \code{object}.}

\item{deriv}{Logical. If \code{TRUE} the derivative will be
returned as the \code{"deriv"} attribute of the result.  This
will be an array with dimension either \code{c(n, p, n, d)} or
\code{c(n, p, d)} depending on the value of \code{diagOnly}.}

\item{diagOnly}{Logical. If \code{TRUE} the structure of the
result takes into account the fact that the row \eqn{i} of the
trend matrix \eqn{\mathbf{F}}{F} depends only on the row
\eqn{i} of the design matrix \eqn{\mathbf{X}}{X} so some
elements in the Jacobian array are structural zeroes and can
be omitted. See \bold{Details}.}
}
\value{
The trend matrix, possibly with the Jacobian array
    attached as an attribute named \code{"deriv"}.
}
\description{
Evaluate the trend component of a \code{km} object on the
given design \code{X}.
}
\details{
The derivatives are stored in a "Jacobian array" say
\eqn{\mathbf{J}}{J}. Let \eqn{n} be the number of rows in \code{X},

\itemize{

 \item{

   If \code{diagOnly} is \code{FALSE}; The array is
   four-dimensional with dimension \eqn{(n \times p) \times (n \times
   d)}{(n * p) * (n * d)} where the first parenthese encloses the
   dimension of the "trend" matrix \eqn{\mathbf{F}}{F} and the
   second one encloses the dimension of the "design" matrix
   \eqn{\mathbf{X}}{X}.  The general element is
   \deqn{J_{i,\,j,\,k,\,\ell} =
   \frac{\partial F_{i,j}}{\partial X_{k,\ell}}.}{J[i, j, k, l] =
   dF[i, j] / dX[k, l].} Note that this value is zero when \eqn{i
   \neq k}{i != k}.

 }

\item{

   If \code{diagOnly} is \code{TRUE}, the Jacobian array is
   3-dimensional with dimension \eqn{n \times p \times d)}{n * p *
   d} and its element is \deqn{J_{i,\,j,\,\ell} = \frac{\partial
   F_{i,j}}{\partial X_{i,\ell}}.}{J[i, j, l] = dF[i, j] / dX[i,
   l].} So the structural zeroes of the previous array are
   omitted. This is especially useful if \eqn{n} is large.

}
}
}
\examples{
library(DiceKriging)
# a 16-points factorial design, and the corresponding response
d <- 2; n <- 16
design.fact <- expand.grid(x1 = seq(0, 1, length = 4),
                           x2 = seq(0, 1, length = 4))
y <- apply(design.fact, 1, branin)

## kriging model 1 : matern5_2 covariance structure, no trend, no
## nugget effect
fit <- km(~ x1 + x2, design = design.fact, response = y)
X <- matrix(runif(n = 40), ncol = 2,
            dimnames = list(NULL, c("x1", "x2")))
fitTrend <- trend(fit, X = X, deriv = 1)
fitTrend <- trend(fit, X = X[1, ], deriv = 1)
}