%        File: tiger.Swn
%     Created: Do Mär 26 11:00  2009 C
% Last Change: Do Mär 26 11:00  2009 C
%
\documentclass[a4paper]{article}
\usepackage[breaklinks=TRUE]{hyperref}
\usepackage{natbib}
\usepackage[utf8]{inputenc} 

\begin{document}
\title{Example on using the tiger-package (TIme series of Grouped
ERrors)}
\author{Dominik Reusser}
%\VignetteIndexEntry{Example to tiger-package}
\maketitle
\section{Introduction}
This document walks you step by step through the data analysis with
the TIGER package. The core idea of the method is to gain important
information about a model by a temporally resolved  evaluation of the
difference between model and observation. If similar patterns of this
difference occur repeatedly, the same
discrepancy between model and observation indicates that the
difference is due to
a structural problem in the model or a systematic errors in
the observation. We may improve our understanding of the system under
investigation, if the conditions leading to this pattern of
difference can be identified.   
 For more information on the method, please see
 \citep{Reusser2009a, Reusser2009}.

\section{Data}
In this example, we are looking at the difference between an observed
river discharge time series and the model output from a hydrological
model, simulating the river discharge from meteorological input data.
The data is provided in the package and is shown in
figure~\ref{fig:data} in two ways, once as a single best simulation
run and once as a number (25) of simulation runs with varying model parameters
representing the uncertainty in the estimation of those parameters.

<<>>=
library(tiger)
data(tiger.example)
measured.single <- tiger.single$measured
modelled.single <- tiger.single$modelled

measured.multi <- tiger.multi$measured
modelled.multi <- tiger.multi$modelled
@


<<label=fig1plot,include=FALSE>>=

par(mfrow=c(2,1))
plot(d.dates, measured.single, type="l", col="blue")
lines(d.dates, modelled.single)

legend("topright", legend=c("measured","modelled"), lty=1, col=c("blue", "black"))

plot(d.dates, measured.multi, type="l", col="blue")
for(i in 1:NROW(modelled.multi)){
	lines(d.dates, modelled.multi[i,])
}

lines(d.dates, measured.multi, col="blue")
@

\begin{figure}
\begin{center}
<<label=fig1,fig=TRUE,echo=FALSE>>=
<<fig1plot>>
@
\end{center}
\caption{Measured and modelled river discharge.}
\label{fig:data}
\end{figure}

\section{Doing the calculations}
First of all, we will generate our synthetic peak errors which will
help to better understand the error groups. The synthetic peak errors
are shown in figure~\ref{fig:peaks}.

<<>>=
peaks2 <- synth.peak.error(rise.factor=2, recession.const=0.02,
     rise.factor2=1.5, err1.factor=c(1.3,1.5,2.0),
     err2.factor = c(0.02,0.03,0.06), 
     err4.factor = c(9,22,40), 
     err5.factor = c(0.2,0.3,0.5),
     err6.factor =c(2,3,5),
     err9.factor=c(1.5,3,6)
   )
@

The synthetic peak error number 5 overestimates the peak, but the
total volume is kept correct. The recession constant is optimized to
obtain a correct volume and the package asks you to check whether the
optimization was successful.

The command bellow plots the synthetic peak errors.

<<label=fig2plot,include=FALSE>>=
    p.synth.peak.error(peaks2)
@

\begin{figure}
\begin{center}
<<label=fig2,fig=TRUE,echo=FALSE>>=
<<fig2plot>>
@
\end{center}
\caption{Synthetic peak errors.}
\label{fig:peaks}
\end{figure}

Then, we will call the function that does all the computation. The
objects returned (\verb@result.single@ and \verb@result.multi@) are 
equivalent to
\verb@tiger.single@ and \verb@tiger.multi@
provided in \verb@data(tiger.example)@. For the multi-run case we
calculate values for every tenth window only (\verb@step.size=10@) in
order to save memory and computation time. Note that
\citet{Reusser2009a} used \verb@step.size=1@ for their study. These result objects will then
be further processed by plotting and summarizing methods. Here, the
methods are shown for the \verb@tiger.multi@ object, but they work the
same way for the  \verb@tiger.single@ object.
<<eval=FALSE>>=
result.single <- tiger(modelled=modelled.single, measured=measured.single, window.size=240, synthetic.errors=peaks2)
result.multi <- tiger(modelled=modelled.multi, measured=measured.multi, window.size=240, synthetic.errors=peaks2)
@
<<echo=FALSE>>=
result.single <- tiger.single
result.multi <- tiger.multi
@

\section{Assessing performance measures used to build error groups}
About 50 performance measures are used to split the time series into
error groups. Some of these performance measures are highly correlated
and not of much interest for further interpretation. Therefore, we
will exclude those from further plots. Note that we want to keep the
CE and RMSE measures in any case. We will also create a scatter
plot of the remaining measures to get an impression of their
interdependence (Figure~\ref{fig:scatter} - here, we are only showing
the scatter plots for the first five measures).

<<label=fig3plot,include=FALSE>>=
 correlated <- correlated(result.multi, keep=c("CE","RMSE" ))
 print(scatterplot(result.multi$measures.uniform, 
            show.measures=correlated$measures.uniform$to.keep[c(1,2,3,5,6)]))
@

\begin{figure}
\begin{center}
<<label=fig3,fig=TRUE,echo=FALSE>>=
<<fig3plot>>
@
\end{center}
\caption{Scatter plots of the performance measures.}
\label{fig:scatter}
\end{figure}

To get an impression of how the performance measures react to the
synthetic peaks, we can create a number of plots (figure~\ref{fig:summary.peak}). Nine plots show
the response of some exemplary measures (y-axis) to the synthetic peak
errors, each of which is shown with a different symbol. On the x-axis, no
error would be in the centre and the severity of the error increases to each
side. The variable \verb@do.out@ determines whether to exclude outliers from
the plot.

<<label=fig4plot,include=FALSE>>=
show.measures <- which(names(result.multi$measures) %in% 
                       c("CE", "PDIFF", "ME", "MSDE", 
                         "SMSE",  "Rsqr","SMALE",
                         "lagtime", "NSC"))
peaks.measures(result.multi, show.measures=show.measures,
               mfrow=c(2,5), do.out=c(rep(FALSE, 4), TRUE,
                                      TRUE,rep(FALSE, 3)) )
@

\begin{figure}
\begin{center}
<<label=fig4,fig=TRUE,echo=FALSE>>=
<<fig4plot>>
@
\end{center}
\caption{Performance measures for synthetic peak errors.}
\label{fig:summary.peak}
\end{figure}

\section{How many clusters to use?}
In order to determine the optimum number of error groups during the
c-means clustering, we try to minimize the validity index
(figure~\ref{fig:validity}). 


<<label=fig5plot,include=FALSE>>=
par(mar=c(4,4,1,1)+0.1)
p.validityIndex(result.multi, validity.max=10)

@


\begin{figure}
\begin{center}
<<label=fig5,fig=TRUE,echo=FALSE>>=
<<fig5plot>>
@
\end{center}
\caption{Validity index for the identification of the optimal cluster number
for c-means clustering.}
\label{fig:validity}
\end{figure}

The 3
cluster solution combines clusters B and C  from the 5 cluster
solution in cluster B and clusters E and E in cluster C
 (figure~\ref{fig:numberClusters}).
Therefore the 5 cluster solution also represents the 
3 cluster solution. In this example, we are using the 5
group (cluster) solution. 

<<label=fig5aplot,include=FALSE>>=
par(mfrow=c(2,1),mar=c(2,4,1,2)+0.1)
errors.in.time(d.dates, result.multi, solution=3)
               #show.months=TRUE)
errors.in.time(d.dates, result.multi, solution=5,
                new.order=c(4,3,5,2,1))
               #show.months=TRUE, new.order=c(3,4,5,2,1))
solutions <- 5
@
\begin{figure}
\begin{center}
<<label=fig5a,fig=TRUE,echo=FALSE>>=
<<fig5aplot>>
@
\end{center}
\caption{Simulated and observed discharge series. The colour bars indicate
the error class during this time period. Plots are show for 3, and
5 classes.}
\label{fig:numberClusters}
\end{figure}


\section{Time pattern of error groups}
The temporal occurence of the error groups is shown in
figure~\ref{fig:errorsInTime}. 

<<label=fig6plot,include=FALSE>>=
#new.order <- c(4,5,2,1,3)
new.order=c(4,3,5,2,1)
par(mar=c(2,4,1,2)+0.1)
errors.in.time(d.dates, result.multi, solution=solutions,
               #show.months=TRUE, new.order=new.order)
               new.order=new.order)
@

\begin{figure}
\begin{center}
<<label=fig6,fig=TRUE,echo=FALSE>>=
<<fig6plot>>
@
\end{center}
\caption{Simulated and observed discharge series. The colour bars indicate
the error class during this time period.}
\label{fig:errorsInTime}
\end{figure}

\section{Characterizing the error groups}
In order to characterize the error groups, we can check which of the
synthetic peaks belong to which error groups and visualize the
assignment as shown in Figure~\ref{fig7}. Note that the output is
formated as \LaTeX tables with \& as the delimiter between columns and
$\backslash\backslash$ as end of line delimiter.
<<>>=
peak.cluster <- peaks.in.clusters(result.multi, solution=solutions, new.order=new.order)
@

<<label=fig7plot,include=FALSE>>=
p.synth.peak.error(peaks2, peak.cluster=peak.cluster,
peak.palette=rainbow(5) )
@

\begin{figure}
\begin{center}
<<label=fig7,fig=TRUE,echo=FALSE>>=
<<fig7plot>>
@
\end{center}
\caption{Synthetic peak errors with colors showing the corresponding
cluster.}
\label{fig:fig7}
\end{figure}

But also, we can check what the values of the performance measures in
each cluster are. This is done with box plots as shown in
figure~\ref{fig:boxPlots}. The plotting command also produces a
summary table of the findings as described by \citet{Reusser2009a}.

<<label=fig8plot,include=FALSE>>=
par(mfrow=c(4,6), mar=c(2,2,3,1)+0.1)
summary.table <- box.plots(result.multi, 
                           solution=solutions,
                           show.measures=correlated$measures.uniform$to.keep,
                           new.order=new.order)
@
<<>>=
print(summary.table)
@

\begin{figure}
\begin{center}
<<label=fig8,fig=TRUE,echo=FALSE>>=
<<fig8plot>>
@
\end{center}
\caption{Matrix of box plots comparing the normalized
performance measure values. The yellow line indicates the
``perfect fit'' for
each of the performance measures.Simulated and observed discharge series. The colour bars indicate
the error class during this time period.}
\label{fig:boxPlots}
\end{figure}

\bibliographystyle{plainnat}
\bibliography{tiger}
\end{document}
