% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/CENTROIDS-shape-extraction.R
\name{shape_extraction}
\alias{shape_extraction}
\title{Shape average of several time series}
\usage{
shape_extraction(X, centroid = NULL, znorm = FALSE, ..., error.check = TRUE)
}
\arguments{
\item{X}{A matrix or data frame where each row is a time series, or a list where each element is
a time series. Multivariate series should be provided as a list of matrices where time spans
the rows and the variables span the columns.}

\item{centroid}{Optionally, a time series to use as reference. Defaults to a random series of \code{X}
if \code{NULL}. For multivariate series, this should be a matrix with the same characteristics as
the matrices in \code{X}. \strong{It will be z-normalized}.}

\item{znorm}{Logical flag. Should z-scores be calculated for \code{X} before processing?}

\item{...}{Further arguments for \code{\link[=zscore]{zscore()}}.}

\item{error.check}{Logical indicating whether the function should try to detect inconsistencies
and give more informative errors messages. Also used internally to avoid repeating checks.}
}
\value{
Centroid time series (z-normalized).
}
\description{
Time-series shape extraction based on optimal alignments as proposed by Paparrizos and Gravano
(2015) for the k-Shape clustering algorithm.
}
\details{
This works only if the series are \emph{z-normalized}, since the output will also have this
normalization.

The resulting centroid will have the same length as \code{centroid} if provided. Otherwise, there are
two possibilities: if all series from \code{X} have the same length, all of them will be used as-is,
and the output will have the same length as the series; if series have different lengths, a
series will be chosen at random and used as reference. The output series will then have the same
length as the chosen series.

This centroid computation is cast as an optimization problem called maximization of Rayleigh
Quotient. It depends on the \code{\link[=SBD]{SBD()}} algorithm. See the cited article for more details.
}
\examples{

# Sample data
data(uciCT)

# Normalize desired subset
X <- zscore(CharTraj[1:5])

# Obtain centroid series
C <- shape_extraction(X)

# Result
matplot(do.call(cbind, X),
        type = "l", col = 1:5)
points(C)

}
\references{
Paparrizos J and Gravano L (2015). ``k-Shape: Efficient and Accurate Clustering of Time Series.''
In \emph{Proceedings of the 2015 ACM SIGMOD International Conference on Management of Data}, series
SIGMOD '15, pp. 1855-1870. ISBN 978-1-4503-2758-9, \doi{10.1145/2723372.2737793}.
}
\seealso{
\code{\link[=SBD]{SBD()}}, \code{\link[=zscore]{zscore()}}
}
