% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sectionview3d.R
\name{sectionview3d.function}
\alias{sectionview3d.function}
\alias{sectionview3d,function,function-method}
\alias{sectionview3d.matrix}
\alias{sectionview3d,matrix,matrix-method}
\alias{sectionview3d.character}
\alias{sectionview3d,character,character-method}
\alias{sectionview3d.km}
\alias{sectionview3d,km,km-method}
\alias{sectionview3d.Kriging}
\alias{sectionview3d,Kriging,Kriging-method}
\alias{sectionview3d.WarpKriging}
\alias{sectionview3d,WarpKriging,WarpKriging-method}
\alias{sectionview3d.glm}
\alias{sectionview3d,glm,glm-method}
\alias{sectionview3d.list}
\alias{sectionview3d,list,list-method}
\alias{sectionview3d}
\title{Plot a contour view of a prediction model or function, including design points if available.}
\usage{
\method{sectionview3d}{`function`}(
  fun,
  vectorized = FALSE,
  center = NULL,
  axis = NULL,
  npoints = 21,
  col_fun = if (!is.null(col)) col else "blue",
  col = NULL,
  col_fading_interval = 0.5,
  mfrow = c(1, 1),
  Xlab = NULL,
  ylab = NULL,
  Xlim = if (!add) matrix(c(0, 1), 2, 2) else NULL,
  ylim = NULL,
  title = NULL,
  title_sep = " | ",
  add = FALSE,
  engine3d = NULL,
  ...
)

\method{sectionview3d}{matrix}(
  X,
  y,
  center = NULL,
  axis = NULL,
  col_points = if (!is.null(col)) col else "red",
  col = NULL,
  col_fading_interval = 0.5,
  bg_fading = 1,
  mfrow = c(1, 1),
  Xlab = NULL,
  ylab = NULL,
  Xlim = if (!add) matrix(c(0, 1), 2, 2) else NULL,
  ylim = NULL,
  title = NULL,
  title_sep = " | ",
  add = FALSE,
  engine3d = NULL,
  ...
)

\method{sectionview3d}{character}(eval_str, axis = NULL, mfrow = c(1, 1), ...)

\method{sectionview3d}{km}(
  km_model,
  type = "UK",
  center = NULL,
  axis = NULL,
  npoints = 21,
  col_points = if (!is.null(col)) col else "red",
  col_fun = if (!is.null(col)) col else "blue",
  col = NULL,
  conf_level = 0.95,
  conf_fading = 0.5,
  bg_fading = 1,
  mfrow = c(1, 1),
  Xlab = NULL,
  ylab = NULL,
  Xlim = NULL,
  ylim = NULL,
  title = NULL,
  title_sep = " | ",
  add = FALSE,
  engine3d = NULL,
  ...
)

\method{sectionview3d}{Kriging}(
  Kriging_model,
  center = NULL,
  axis = NULL,
  npoints = 21,
  col_points = if (!is.null(col)) col else "red",
  col_fun = if (!is.null(col)) col else "blue",
  col = NULL,
  conf_level = 0.95,
  conf_fading = 0.5,
  bg_fading = 1,
  mfrow = c(1, 1),
  Xlab = NULL,
  ylab = NULL,
  Xlim = NULL,
  ylim = NULL,
  title = NULL,
  title_sep = " | ",
  add = FALSE,
  engine3d = NULL,
  ...
)

\method{sectionview3d}{WarpKriging}(
  WarpKriging_model,
  center = NULL,
  axis = NULL,
  npoints = 21,
  col_points = if (!is.null(col)) col else "red",
  col_fun = if (!is.null(col)) col else "blue",
  col = NULL,
  conf_level = 0.95,
  conf_fading = 0.5,
  bg_fading = 1,
  mfrow = c(1, 1),
  Xlab = NULL,
  ylab = NULL,
  Xlim = NULL,
  ylim = NULL,
  title = NULL,
  title_sep = " | ",
  add = FALSE,
  engine3d = NULL,
  ...
)

\method{sectionview3d}{glm}(
  glm_model,
  center = NULL,
  axis = NULL,
  npoints = 21,
  col_points = if (!is.null(col)) col else "red",
  col_fun = if (!is.null(col)) col else "blue",
  col = NULL,
  conf_level = 0.95,
  conf_fading = 0.5,
  bg_fading = 1,
  mfrow = c(1, 1),
  Xlab = NULL,
  ylab = NULL,
  Xlim = NULL,
  ylim = NULL,
  title = NULL,
  title_sep = " | ",
  add = FALSE,
  engine3d = NULL,
  ...
)

\method{sectionview3d}{list}(
  modelFit_model,
  center = NULL,
  axis = NULL,
  npoints = 21,
  col_points = if (!is.null(col)) col else "red",
  col_fun = if (!is.null(col)) col else "blue",
  col = NULL,
  bg_fading = 1,
  mfrow = c(1, 1),
  Xlab = NULL,
  ylab = NULL,
  Xlim = NULL,
  ylim = NULL,
  title = NULL,
  title_sep = " | ",
  add = FALSE,
  engine3d = NULL,
  ...
)

sectionview3d(...)
}
\arguments{
\item{fun}{a function or 'predict()'-like function that returns a simple numeric, or an interval, or mean and standard error: list(mean=...,se=...).}

\item{vectorized}{is fun vectorized?}

\item{center}{optional coordinates (as a list or data frame) of the center of the section view if the model's dimension is > 2.}

\item{axis}{optional matrix of 2-axis combinations to plot, one by row. The value \code{NULL} leads to all possible combinations i.e. \code{choose(D, 2)}.}

\item{npoints}{an optional number of points to discretize plot of response  surface and uncertainties.}

\item{col_fun}{color of the function plot.}

\item{col}{color of the object (use col_* for specific objects).}

\item{col_fading_interval}{an optional factor of alpha (color channel) fading used to plot confidence intervals.}

\item{mfrow}{an optional list to force \code{par(mfrow = ...)} call. The default value  \code{NULL} is automatically set for compact view.}

\item{Xlab}{an optional list of string to overload names for X.}

\item{ylab}{an optional string to overload name for y.}

\item{Xlim}{an optional list to force x range for all plots. The default value \code{NULL} is automatically set to include all design points (and their 1-99 percentiles).}

\item{ylim}{an optional list to force y range for all plots. The default value \code{NULL} is automatically set to include all design points (and their 1-99 percentiles).}

\item{title}{an optional overload of main title.}

\item{title_sep}{customize subtitle with fixed input.}

\item{add}{to print graphics on an existing window.}

\item{engine3d}{3D view package to use. "rgl" if available, otherwise "scatterplot3d" by default.}

\item{...}{arguments of the \code{sectionview3d.km}, \code{sectionview3d.glm}, \code{sectionview3d.Kriging} or \code{sectionview3d.function} function}

\item{X}{the matrix of input design.}

\item{y}{the array of output values (two columns means an interval).}

\item{col_points}{color of points.}

\item{bg_fading}{an optional factor of alpha (color channel) fading used to plot design points outside from this section.}

\item{eval_str}{the expression to evaluate in each subplot.}

\item{km_model}{an object of class \code{"km"}.}

\item{type}{the kriging type to use for model prediction.}

\item{conf_level}{an optional list of confidence intervals to display.}

\item{conf_fading}{an optional factor of alpha (color channel) fading used to plot confidence intervals.}

\item{Kriging_model}{an object of class \code{"Kriging"}.}

\item{WarpKriging_model}{an object of class \code{"WarpKriging"}.}

\item{glm_model}{an object of class \code{"glm"}.}

\item{modelFit_model}{an object returned by DiceEval::modelFit.}
}
\description{
Plot a contour view of a prediction model or function, including design points if available.
}
\details{
If available, experimental points are plotted with fading colors. Points that fall in the specified section (if any) have the color specified \code{col_points} while points far away from the center have shaded versions of the same color. The amount of fading is determined using the Euclidean distance between the plotted point and \code{center}.
}
\examples{
x1 <- rnorm(15)
x2 <- rnorm(15)

y <- x1 + x2 + rnorm(15)
model <- lm(y ~ x1 + x2)

sectionview3d(function(x) sum(x),
                       Xlim=cbind(range(x1),range(x2)), col='black')
DiceView:::.plot3d(x1, x2, y)

sectionview3d(function(x) {
                      x = as.data.frame(x)
                      colnames(x) <- all.vars(model$call)[-1]
                      p = predict.lm(model, newdata=x, se.fit=TRUE)
                      list(mean=p$fit, se=p$se.fit)
                    }, vectorized=TRUE,
              add=TRUE)

X = matrix(runif(15*2),ncol=2)
y = apply(X,1,branin)

sectionview3d(X, y)

x1 <- rnorm(15)
x2 <- rnorm(15)

y <- x1 + x2^2 + rnorm(15)
model <- glm(y ~ x1 + I(x2^2))

sectionview3d(model)

sectionview3d("abline(h=0.25,col='red')")
if (requireNamespace("DiceKriging")) { library(DiceKriging)

X = matrix(runif(15*2),ncol=2)
y = apply(X,1,branin)

model <- km(design = X, response = y, covtype="matern3_2")

sectionview3d(model)

}

if (requireNamespace("rlibkriging")) { library(rlibkriging)

X = matrix(runif(15*2),ncol=2)
y = apply(X,1,branin)

model <- Kriging(X = X, y = y, kernel="matern3_2")

sectionview3d(model)

}

if (requireNamespace("rlibkriging")) { library(rlibkriging)

X = matrix(runif(15*2),ncol=2)
y = apply(X,1,branin) + 5*rnorm(15)

model <- WarpKriging(y = y, X = X, warping = c("affine","affine"), kernel="matern3_2")

sectionview3d(model)

}

x1 <- rnorm(15)
x2 <- rnorm(15)

y <- x1 + x2^2 + rnorm(15)
model <- glm(y ~ x1 + I(x2^2))

sectionview3d(model)

if (requireNamespace("DiceEval")) { library(DiceEval)

X = matrix(runif(15*2),ncol=2)
y = apply(X,1,branin)

model <- modelFit(X, y, type = "StepLinear")

sectionview3d(model)

}

## A 2D example - Branin-Hoo function
sectionview3d(branin, col='black')

\dontrun{
## a 16-points factorial design, and the corresponding response
d <- 2; n <- 16
design.fact <- expand.grid(seq(0, 1, length = 4), seq(0, 1, length = 4))
design.fact <- data.frame(design.fact); names(design.fact) <- c("x1", "x2")
y <- branin(design.fact); names(y) <- "y"

if (requireNamespace("DiceKriging")) { library(DiceKriging)
## model: km
model <- DiceKriging::km(design = design.fact, response = y)
sectionview3d(model)
sectionview3d(branin, col='red', add=TRUE)
}

if (requireNamespace("rlibkriging")) { library(rlibkriging)
## model: Kriging
model <- Kriging(X = as.matrix(design.fact), y = as.matrix(y), kernel="matern3_2")
sectionview3d(model)
sectionview3d(branin, col='red', add=TRUE)
}

## model: glm
model <- glm(y ~ 1+ x1 + x2 + I(x1^2) + I(x2^2) + x1*x2, data=cbind(y,design.fact))
sectionview3d(model)
sectionview3d(branin, col='red', add=TRUE)

if (requireNamespace("DiceEval")) { library(DiceEval)
## model: StepLinear
model <- modelFit(design.fact, y, type = "StepLinear")
sectionview3d(model)
sectionview3d(branin, col='red', add=TRUE)
}
}

}
\seealso{
\code{\link{sectionview.function}} for a section plot, and \code{\link{sectionview3d.function}} for a 2D section plot.

\code{\link{sectionview.matrix}} for a section plot, and \code{\link{sectionview3d.matrix}} for a 2D section plot.

\code{\link{sectionview3d.matrix}} for a section plot.

\code{\link{sectionview.km}} for a section plot, and \code{\link{sectionview3d.km}} for a 2D section plot.

\code{\link{sectionview.Kriging}} for a section plot, and \code{\link{sectionview3d.Kriging}} for a 2D section plot.

\code{\link{sectionview.WarpKriging}} for a section plot, and \code{\link{sectionview3d.WarpKriging}} for a 2D section plot.

\code{\link{sectionview.glm}} for a section plot, and \code{\link{sectionview3d.glm}} for a 2D section plot.

\code{\link{sectionview.glm}} for a section plot, and \code{\link{sectionview3d.glm}} for a 2D section plot.
}
\author{
Yann Richet, ASNR
}
