\name{tsExtract}
\alias{tsExtract}

\title{Extract Dates and Values from a Time Series}

\description{
Converts a base R time series object of class \code{ts} into two
data frames --- one of \code{Date} values and one of numeric values ---
suitable for passing directly to \code{\link{XY}} as the \code{x} and
\code{y} arguments.

\code{\link{XY}} no longer accepts a \code{ts} object directly.
Use \code{tsExtract} to prepare the components first, then pass them
to \code{\link{XY}}. Because the extracted vectors exist in the global
environment rather than in a data frame, include \code{data=NULL} in
the \code{\link{XY}} call.
}

\usage{
tsExtract(y.ts, x.name=NULL)
}

\arguments{
  \item{y.ts}{A time series object of class \code{ts}, either univariate
       or multivariate.}
  \item{x.name}{Optional character string used to name the date column in
       the returned \code{x.dates} data frame. When \code{NULL}, the
       column is named \code{x.dates}.}
}

\details{
The function uses \code{\link{time}} to obtain the fractional-year time
index of each observation and converts it to a \code{\link{Date}} object.
Supported frequencies are:

\tabular{ll}{
  \code{365} or \code{366} \tab Daily \cr
  \code{52}                \tab Weekly \cr
  \code{12}                \tab Monthly \cr
  \code{4}                 \tab Quarterly \cr
  \code{1}                 \tab Yearly \cr
}

Monthly conversion maps each fractional-year index to the first day of
the corresponding calendar month, which sidesteps the uneven month
lengths that base R's \code{ts} indexing does not track.

For a multivariate \code{ts} object, the y component contains one column
per time series, named after the original column names.
}

\value{
A list with three components:

\item{x.dates}{A single-column data frame of class \code{Date}, one row
     per observation.}
\item{y}{A data frame of numeric values. One column for a univariate
     series; one column per series for a multivariate object.}
\item{y.name}{Character string giving the name of the y variable (or the
     name from the \code{yname} option for a univariate series).}
}

\author{David W. Gerbing (Portland State University; \email{gerbing@pdx.edu})}

\seealso{
\code{\link{XY}}, \code{\link{ts}}, \code{\link{time}}
}

\examples{
# Monthly airline passenger data (built-in R dataset)
pull <- tsExtract(AirPassengers)
x <- pull$x.dates
y <- pull$y
XY(x,y, data=NULL)

# Quarterly earnings data
pull <- tsExtract(JohnsonJohnson)
x <- pull$x.dates
y <- pull$y
XY(x, y, data=NULL)
}

\keyword{ts}
\keyword{manip}
