\name{fbplot}
\Rdversion{1.1}
\alias{fbplot}
\alias{boxplot.fd}
\alias{boxplot.fdPar}
\alias{boxplot.fdSmooth}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Functional Boxplots
}
\description{
Produces functional boxplots or enhanced functional boxplots of the
given functional data. It can also be used to carry out functional
data ordering based on band depth.
%% ~~ A concise (1-5 lines) description of what the function does. ~~
}
\usage{
fbplot(fit, x = NULL, method = "MBD", depth = NULL, plot = TRUE,
prob = 0.5, color = 6, outliercol = 2, barcol = 4,
fullout=FALSE, factor=1.5,xlim=c(1,nrow(fit)),
ylim=c(min(fit)-.5*diff(range(fit)),max(fit)+.5*diff(range(fit))),...)
\method{boxplot}{fd}(x, z=NULL, ...)
\method{boxplot}{fdPar}(x, z=NULL, ...)
\method{boxplot}{fdSmooth}(x, z=NULL, ...)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{fit}{
a p-by-n functional data matrix where n is the number of curves, and
p is defined below.
}
\item{x}{
For \code{fbplot}, \code{x} is the x coordinates of curves. Defaults
to 1:p where p is the number of x coodinates.
For \code{boxplot.fd}, \code{boxplot.fdPar} and
\code{boxplot.fdSmooth}, \code{x} is an object of class \code{fd},
\code{fdPar} or \code{fdSmooth}, respectively.
}
\item{z}{
The coordinate of the curves, labeled \code{x} for \code{fdplot}.
For \code{boxplot.fd}, \code{boxplot.fdPar} and
\code{boxplot.fdSmooth}, this cannot be \code{x}, because that would
clash with the generic \code{boxplot(x, ...)} standard.
}
\item{method}{
the method to be used to compute band depth. Can be one of "BD2",
"MBD" or "Both" with a default of "MBD". See also details.
}
\item{depth}{
a vector giving band depths of curves. If missing, band depth
computation is conducted.
}
\item{plot}{
logical. If TRUE (the default) then a functional boxplot is
produced. If not, band depth and outliers are returned.
}
\item{prob}{
a vector giving the probabilities of central regions in a decreasing
order, then an enhanced functional boxplot is produced. Defaults to
be 0.5 and a functional boxplot is plotted.
}
\item{color}{
a vector giving the colors of central regions from light to dark for
an enhanced functional boxplot. Defaults to be magenta for a
functional boxplot.
}
\item{outliercol}{
color of outlying curves. Defaults to be red.
}
\item{barcol}{
color of bars in a functional boxplot. Defaults to be blue.
}
\item{fullout}{
logical for plotting outlying curves. If FALSE (the default) then
only the part outside the box is plotted. If TRUE, complete outling
curves are plotted.
}
\item{factor}{
the constant factor to inflate the middle box and determine fences
for outliers. Defaults to be 1.5 as in a classical boxplot.
}
\item{xlim}{ x-axis limits }
\item{ylim}{ y-axis limits }
\item{...}{
For \code{fbplot}, optional arguments for \code{plot}.
For \code{boxplot.fd}, \code{boxplot.fdPar}, or
\code{boxplot.fdSmooth}, optional arguments for \code{fbplot}.
}
}
\details{
For functional data, the band depth (BD) or modifed band depth (MBD)
allows for ordering a sample of curves from the center outwards and,
thus, introduces a measure to define functional quantiles and the
centrality or outlyingness of an observation. A smaller rank is
associated with a more central position with respect to the sample
curves. BD usually provides many ties (curves have the same depth
values), but MBD does not. "BD2" uses two curves to determine a
band. The method "Both" uses "BD2" first and then uses "MBD" to break
ties. The method "Both" uses BD2 first and then uses MBD to break
ties. The computation is carried out by the fast algorithm proposed
by Sun et al. (2012).
%% ~~ If necessary, more details than the description above ~~
}
\value{
\item{depth }{band depths of given curves.}
\item{outpoint }{column indices of detected outliers.}
%% ~Describe the value returned
%% If it is a LIST, use
%% \item{comp1 }{Description of 'comp1'}
%% \item{comp2 }{Description of 'comp2'}
%% ...
}
\references{
Sun, Y., Genton, M. G. and Nychka, D. (2012), "Exact fast computation
of band depth for large functional datasets: How quickly can one
million curves be ranked?" Stat, 1, 68-74.
Sun, Y. and Genton, M. G. (2011), "Functional Boxplots," Journal of
Computational and Graphical Statistics, 20, 316-334.
Lopez-Pintado, S. and Romo, J. (2009), "On the concept of depth for
functional data," Journal of the American Statistical Association,
104, 718-734.
%% ~put references to the literature/web site here ~
}
\author{
Ying Sun \email{sunwards@stat.osu.edu}
Marc G. Genton \email{marc.genton@kaust.edu.sa}
%% ~~who you are~~
}
%\note{
%% ~~further notes~~
%}
%% ~Make other sections like Warning with \section{Warning }{....} ~
%\seealso{
%% ~~objects to See Also as \code{\link{help}}, ~~~
%}
\examples{
##
## 1. generate 50 random curves with some covariance structure
## model 1 without outliers
##
cov.fun=function(d,k,c,mu){
k*exp(-c*d^mu)
}
n=50
p=30
t=seq(0,1,len=p)
d=dist(t,upper=TRUE,diag=TRUE)
d.matrix=as.matrix(d)
#covariance function in time
t.cov=cov.fun(d.matrix,1,1,1)
# Cholesky Decomposition
L=chol(t.cov)
mu=4*t
e=matrix(rnorm(n*p),p,n)
y=mu+t(L)\%*\%e
#functional boxplot
fbplot(y,method='MBD',ylim=c(-11,15))
# The same using boxplot.fd
boxplot.fd(y, method='MBD', ylim=c(-11, 15))
# same with default ylim
boxplot.fd(y)
##
## 2. as an fd object
##
Y <- Data2fd(y)
boxplot(Y)
##
## 3. as an fdPar object
##
Ypar <- fdPar(Y)
boxplot(Ypar)
##
## 4. Smoothed version
##
Ysmooth <- smooth.fdPar(Y)
boxplot(Ysmooth)
##
## 5. model 2 with outliers
##
#magnitude
k=6
#randomly introduce outliers
C=rbinom(n,1,0.1)
s=2*rbinom(n,1,0.5)-1
cs.m=matrix(C*s,p,n,byrow=TRUE)
e=matrix(rnorm(n*p),p,n)
y=mu+t(L)\%*\%e+k*cs.m
#functional boxplot
fbplot(y,method='MBD',ylim=c(-11,15))
}
\keyword{ ~Functional Boxplots }
%\keyword{ ~kwd2 }% __ONLY ONE__ keyword per line