\svnidlong
{$HeadURL: https://repos.deltares.nl/repos/openda/public/trunk/core/doc/usedoc/resultwriter.tex $}
{$LastChangedDate: 2014-03-17 11:09:23 +0100 (Mon, 17 Mar 2014) $}
{$LastChangedRevision: 4372 $}
{$LastChangedBy: vrielin $}

\odachapter{Generation of output with \oda}

\begin{tabular}{p{4cm}l}
%\textbf{Contributed by:} & ? \\
\textbf{Last update:}    & \svnfilemonth-\svnfileyear\\
\end{tabular}

\odasection{Concepts}

\oda has an advanced output processing system. The main concept can be
understood as a publisher-subscriber mechanism. In many places in the code of
\oda developers have identified pieces of information, that may be of
interest to users. Each piece of information gets an 'id', an 'outpuLevel' and
'context'. Separate from offering potentially useful items anywhere in the
code, you can configure one or more output-writers and filter the output that
you want to collect. The type of ResultWriter selected determines the output
format. Different writers, or multiple copies can be selected in one run, eg to
split your results in separate files that are easier to analyse.

The current implementation replaces an older one, that is still working for
compatibility of older configurations. You may encounter input files with the
old syntax. We suggest that you replace them with the new syntax described
here. If you really need to use the old format, please consult the xsd-file or
xsd-documentation on our website.

\odasection{Getting started}

We recommend that you start with following defaults at the end of your main
oda-file:
\begin{verbatim}
<resultWriters>
  <resultWriter className="org.openda.resultwriters.MatlabResultWriter">
    <workingDirectory>.</workingDirectory>
    <configFile>results_yourlabel.m</configFile>
    <selection>
      <resultItem outputLevel="Normal" maxSize="1000" />
    </selection>
  </resultWriter>

  <resultWriter className="org.openda.resultwriters.NetcdfResultWriter">
    <workingDirectory>.</workingDirectory>
    <configFile>results_yourlabel_.nc</configFile>
    <selection>
      <resultItem outputLevel="Normal" minSize="1000" />
    </selection>
  </resultWriter>
</resultWriters>
\end{verbatim}
This configures two resultwriters: all small items are written to matlab-ascii
and the larger items to netcdf. The default outputLevel should be good for a
start, but can easily be adapted if needed. Valid outputLevels are: None,
Essential, Normal, Verbose and All.

\odasection{Advanced filtering}

In some cases the simple approach above is not sufficient and more advanced
filtering is needed. You should keep in mind that multiple criteria for
selection will only select those items that match all criteria. For example:
\begin{verbatim}
<selection>
  <resultItem outputLevel="Normal" maxSize="1000" />
</selection>
\end{verbatim}
selects items that have outputLevel higher or equal to Normal and have a size
that is at most 1000. On the other hand selection in separate items are matched
if one applies. For example:
\begin{verbatim}
<selection>
  <resultItem outputLevel="Normal" maxSize="1000" />
  <resultItem outputLevel="Essential" minSize="1001" />
</selection>
\end{verbatim}
will add the most important large items compared to the previous example.

The most important section criteria are:
\begin{itemize}
\item outputLevel : Hint by the developer about the importance of the output.
Valid values are None, Essential, Normal, Verbose and All
\item minSize : only items of at least this size are selected
\item maxSize : only items of at most this size are selected
\item id : only id's matching this selection are written, eg "pred\_f". At the
moment you can only find out about the id's with a small trial run, where you
write all items, or by examining  the code.
\item context : The items are divided in groups that are intended to help you
suppress output or generate more output for parts of the algorithm. For example
the analysis-step of the EnKf used context="analysis step". One can also use
regular expressions here. For example to select inner-iteration 10 one uses
context="inner iteration 10", but to select all inner-iterations one can use
context="inner iteration (.*)".
\end{itemize}

\odasection{ResultWriters}

In addition to the two most common result-writers, several others exist for
more specific purposes. Moreover, you can implement your own result-writer to
format the output exactly to your needs. Some existing writers are:
\begin{itemize}
\item {\tt org.openda.resultwriters.MatlabResultWriter}: Most common output to
matlab ascii format (.m file). These files can be loaded into Matlab or Octave
for further analysis or plotting. Since the ascii format is very slow for large
data items, the default maximimum size is maxSize=1000.
\item {\tt org.openda.resultwriters.NetcdfResultWriter}: Writes to netcdf.
Very useful for larger data items, that do not fit well in the Matlab ascii
files.
\item {\tt org.openda.resultwriters.TextTableWriter}: Simple
comma-separated-value table with main results of a calibration run. Can eg be
used to load the main results into a spreadsheet program.
\item {\tt org.openda.resultwriters.CsvResultWriter}: TODO
\item {\tt org.openda.resultwriters.GlueCsvResultWriter}: TODO
\item {\tt org.openda.resultwriters.McCsvResultWriter}: TODO
\end{itemize}

\odasection{Finally}

Several nice examples can be found in the examples-directory\\
{\tt public/examples/core/simple\_resultwriters}.
