\documentclass[nogin,a4paper]{article}

\usepackage[colorlinks=true,urlcolor=blue]{hyperref}
\usepackage{Sweave}
\usepackage[utf8]{inputenc}
\newcommand{\code}[1]{{\tt #1}}

\title{\bf Subsetting of Spatio-Temporal Objects} 

\author{
\includegraphics[width=5cm]{ifgi-logo_int} \hspace{.5cm}
\includegraphics[width=4cm]{logo52n} \\
\href{mailto:ben.graeler@uni-muenster.de}{Benedikt Gr{\"a}ler}
}
\date{\small \today }

\begin{document}
%\VignetteIndexEntry{Subsetting of spacetime objects}
\maketitle

\begin{abstract}
This vignette briefly describes how the subsetting of ST\dots classes 
works and mentions some of the underlying assumptions and pitfalls to be aware of.
\end{abstract}

\tableofcontents

\section{Introduction}

The design of the spatio-temporal classes in \code{spacetime} tries to follow the usual \emph{look-and-feel} of a standard \code{R} structure such as matrices and data frames. However, the two indices used in the representation referring to space and time do have some implicit meaning to be taken care of. The following examples will use small toy data set to illustrate the differences in subsetting among different notations and classes. All presented code can be used for both structures with and without data slot.

<<fig=FALSE>>=
library(sp)
library(xts)
library(spacetime)

# spatial component
spObj <- data.frame(x=c(0,2,1,0,2), y=c(2,2,1,0,0))
coordinates(spObj) <- ~x+y
row.names(spObj) <- c("A","B","C","D","E")

# temporal component
timeObj = as.POSIXct("2010-08-05")+3600*24*(0:1)

# data slot
m = 1:5*10 # means for each of the 5 point locations
mydata = data.frame(smpl1=rnorm(10, mean=rep(m, 2)),
                    smpl2=rnorm(10, mean=rep(m, 2)))
mydata[c(2, 4, 6, 7),] <- NA

STFDFobj <- STFDF(spObj, timeObj, mydata)
STSDFobj <- as(STFDFobj, "STSDF")
STIDFobj <- as(STFDFobj, "STIDF")

STFobj <- geometry(STFDFobj)
STSobj <- geometry(STSDFobj)
STIobj <- geometry(STIDFobj)
@

\section{Selection over space}

Subsetting over space can be done in different ways. This includes indices of class \code{numeric} where we refer to each actual index of the spatial location, \code{logical} that must be of the same length as the spatial component, \code{character} referring to row names of the spatial object and \code{Spatial} initiating an overlay to retrieve selection indices. 

\subsection{Indices of class \code{numeric}}

Spatio-temporal objects with a \emph{full} outline represent the complete structure of $3\times2=6$ spatio-temporal locations:
<<>>=
STFobj[1:3,]
@

In case of the \emph{sparse} structure, only the observed locations are stored leading to an index of only 3 rows.
<<>>=
STSobj[1:3,]
@

The \emph{irregular} case stores for each spatio-temporal location a separate spatial and temporal entity with an own spatial and temporal index. Hence the same selection as above returns the first three entries, i.e. the first three locations at the same moment in time. Note that the spatial locations \code{"B"} and \code{"D"} are not observed at the first moment in time.
<<>>=
STIobj[1:3,]
@

Like-wise one might select the same station repeatedly,
<<>>=
STSobj[rep(3,3),]
@

or stations in a different order:
<<>>=
STFobj[3:1,]
@
This applies to all three structures.

\subsection{Indices of class \code{logical}}

Spatio-temporal objects with a \emph{full} and \emph{sparse} structure require a vector of the same length as the slot \code{sp}. The vector will be recycled if necessary. The \emph{full} structure refers to $3\times 2=6$ spatio-temporal locations
<<>>=
STFobj[c(TRUE,TRUE,FALSE,FALSE,TRUE),]
@

where the \emph{sparse} structure only provides an index with 3 rows:
<<>>=
STSobj[c(TRUE,TRUE,FALSE,FALSE,TRUE),]
@

The \emph{irregular} case will again provide the exact matches with observation, but needs a longer vector of size 6, as each observation has its own spatial entity in the slot \code{sp}.
<<>>=
STSobj[c(TRUE,TRUE,FALSE,FALSE,TRUE,FALSE),]
@

A repeated selection or changing the order is not possible for \code{logical} indices.

\subsection{Indices of class \code{character}}

The character provided as first argument in the subsetting brackets is matched against the row names of the spatial object.
Objects of type \emph{full} represent the complete structure of $2\times 2=4$ spatio-temporal locations:
<<>>=
STFobj[c("A","B"),]
@

In case of the \emph{sparse} structure, only a single spatio-temporal locations is returned, as \code{B} has actually never been observed:
<<>>=
STSobj[c("A","B"),]
@

The \emph{irregular} case might have the same location several times and will return all occurrences:
<<>>=
STIobj[c("C"),]
@

Like-wise one might select the same station repeatedly
<<>>=
STIobj[c("C","C"),]
@

or stations in a different order:
<<>>=
STFobj[c("E","A"),]
@
This applies to all three structures.

\subsection{Indices of class \code{Spatial}}

In this case, the function \code{over} is called to determine the spatial relationship. See the documentation \code{?over}  for further details.

\section{Selection over time}

The temporal dimension is realised as an \code{xts} object and subsetting along time is completely left to the routines in the \code{xts} package. Please see the corresponding documentation for further details. A special property of the temporal domain is its natural order. Hence, no reordering takes place even if explicitly asked for in the subsetting index. This is especially evident for the \code{STI\dots} classes, as these have only identical indices for space and time and a spatial reordering would  involve a temporal one as well. In these cases, the natural order of time is given preference.

\section{Selection over space and time}

Selection over space and time can be done in two general ways. Either providing two separate vectors or as a two-column matrix. Just as for simple matrices, these two possibilities imply two distinct metaphors. The vectors will return all selected spatial entities combined with all temporal ones (where possible) respecting the ordering of the spatial index. The matrix notation selects pairs of indices. The vector notation accepts all formats indicated above while the matrix only supports \code{numeric} values. 

As this type of selection is typically done to select a sparse subset from the data, the object returned from a \code{STF\dots} object will be of type \code{STS\dots}. Typically, the provided matrix reflects the \code{index} slot:
<<>>=
STFobj[cbind(1:3,c(1,2,2)),]
@

A \emph{sparse} structure will remain \emph{sparse}, but only existing pairs from the index will be returned.
<<>>=
STSobj[cbind(1:3,c(1,1,1))]
@

The \emph{irregular} structure only provides data for identical spatial and temporal indices:
<<>>=
STIobj[cbind(1:5,5:1)]
@

Multiple selection over space and time is in general possible, but re-ordering is only possible for the spatial domain.

\end{document}