chap_OBS.tex

%\usepackage{framed}

%% =================================================================================================
\section{Standalone observation operator (\texttt{SAO})}
\label{sec:OBS_sao}

%% =================================================================================================
\subsection{Concept}

The observation operator maps model variables to observation space. This is normally done while the model is running, i.e. online, it is possible to apply this mapping offline without running the model with the \textbf{standalone observation operator} (SAO). The process is divided into an initialisation phase, an interpolation phase and an output phase.
During the interpolation phase the SAO populates the model arrays by
reading saved model fields from disk. The interpolation and the output phases use the same OBS code described in the preceding sections.

There are two ways of exploiting the standalone capacity.
The first is to mimic the behaviour of the online system by supplying model fields at
regular intervals between the start and the end of the run.
This approach results in a single model counterpart per observation.
This kind of usage produces feedback files the same file format as the online observation operator.
The second is to take advantage of the ability to run offline by calculating
multiple model counterparts for each observation.
In this case it is possible to consider all forecasts verifying at the same time.
By forecast, we mean any method which produces an estimate of physical reality which is not an observed value.

% sao.exe

%% =================================================================================================
\subsection{Using the standalone observation operator}

%% =================================================================================================
\subsubsection{Building}

In addition to \emph{OCE} the SAO requires the inclusion of the \emph{SAO} directory.
\emph{SAO} contains a replacement \mdl{nemogcm} which overwrites the resultant \textbf{nemo.exe}.
Note this a similar approach to that taken by the standalone surface scheme \emph{SAS} and the offline TOP model \emph{OFF}.

% Running
%% =================================================================================================
\subsubsection{Running}

The simplest way to use the executable is to edit and append the \nam{sao}{sao} namelist to
a full \NEMO\ namelist and then to run the executable as if it were nemo.exe.

% Configuration section
%% =================================================================================================
\subsection{Configuring the standalone observation operator}
The observation files and settings understood by \nam{obs}{obs} have been outlined in the online observation operator section.
In addition is a further namelist \nam{sao}{sao} which used to set the input model fields for the SAO

%% =================================================================================================
\subsubsection{Single field}

In the SAO the model arrays are populated at appropriate time steps via input files.
At present, \textbf{tsn} and \textbf{sshn} are populated by the default read routines.
These routines will be expanded upon in future versions to allow the specification of any model variable.
As such, input files must be global versions of the model domain with
\textbf{votemper}, \textbf{vosaline} and optionally \textbf{sshn} present.

For each field read there must be an entry in the \nam{sao}{sao} namelist specifying
the name of the file to read and the index along the \emph{time\_counter}.
For example, to read the second time counter from a single file the namelist would be.

\begin{listing}
  \begin{forlines}
!----------------------------------------------------------------------
!       namsao Standalone obs_oper namelist
!----------------------------------------------------------------------
!   sao_files    specifies the files containing the model counterpart
!   nn_sao_idx   specifies the time_counter index within the model file
&namsao
   sao_files = "foo.nc"
   nn_sao_idx = 2
/
  \end{forlines}
  \caption{\forcode{&namsao}}
  \label{lst:namsao}
\end{listing}

%% =================================================================================================
\subsubsection{Multiple fields per run}

Model field iteration is controlled via \textbf{nn\_sao\_freq} which
specifies the number of model steps at which the next field gets read.
For example, if 12 hourly fields are to be interpolated in a setup where 288 steps equals 24 hours.

\begin{forlines}
!----------------------------------------------------------------------
!       namsao Standalone obs_oper namelist
!----------------------------------------------------------------------
!   sao_files    specifies the files containing the model counterpart
!   nn_sao_idx   specifies the time_counter index within the model file
!   nn_sao_freq  specifies number of time steps between read operations
&namsao
   sao_files = "foo.nc" "foo.nc"
   nn_sao_idx = 1 2
   nn_sao_freq = 144
/
\end{forlines}

The above namelist will result in feedback files whose first 12 hours contain the first field of foo.nc and
the second 12 hours contain the second field.

%\begin{framed}
\textbf{Note} Missing files can be denoted as "nofile".
%\end{framed}

A collection of fields taken from a number of files at different indices can be combined at
a particular frequency in time to generate a pseudo model evolution.
If all that is needed is a single model counterpart at a regular interval then
the standard SAO is all that is required.
However, just to note, it is possible to extend this approach by comparing multiple forecasts, analyses, persisted analyses and
climatologies with the same set of observations.
This approach is referred to as \emph{Class 4} since it is the fourth metric defined by the GODAE intercomparison project. This requires multiple runs of the SAO and running an additional utility (not currently in the \NEMO\ repository) to combine the feedback files into one class 4 file.

%% =================================================================================================
\section{Observation utilities}
\label{sec:OBS_obsutils}

For convenience some tools for viewing and processing of observation and feedback files are provided in
the \NEMO\ repository.
These tools include OBSTOOLS which are a collection of \fortran\ programs which are helpful to deal with feedback files.
They do such tasks as observation file conversion, printing of file contents,
some basic statistical analysis of feedback files.
The other main tool is an IDL program called dataplot which uses a graphical interface to
visualise observations and feedback files.
OBSTOOLS and dataplot are described in more detail below.

%% =================================================================================================
\subsection{Obstools}

A series of \fortran\ utilities is provided with \NEMO\ called OBSTOOLS.
This are helpful in handling observation files and the feedback file output from the observation operator. A brief description of some of the utilities follows

%% =================================================================================================
\subsubsection{corio2fb}

The program corio2fb converts profile observation files from the Coriolis format to the standard feedback format.
It is called in the following way:

\begin{cmds}
corio2fb.exe outputfile inputfile1 inputfile2 ...
\end{cmds}

%% =================================================================================================
\subsubsection{enact2fb}

The program enact2fb converts profile observation files from the ENACT format to the standard feedback format.
It is called in the following way:

\begin{cmds}
enact2fb.exe outputfile inputfile1 inputfile2 ...
\end{cmds}

%% =================================================================================================
\subsubsection{fbcomb}

The program fbcomb combines multiple feedback files produced by individual processors in
an MPI run of \NEMO\ into a single feedback file.
It is called in the following way:

\begin{cmds}
fbcomb.exe outputfile inputfile1 inputfile2 ...
\end{cmds}

%% =================================================================================================
\subsubsection{fbmatchup}

The program fbmatchup will match observations from two feedback files.
It is called in the following way:

\begin{cmds}
fbmatchup.exe outputfile inputfile1 varname1 inputfile2 varname2 ...
\end{cmds}

%% =================================================================================================
\subsubsection{fbprint}

The program fbprint will print the contents of a feedback file or files to standard output.
Selected information can be output using optional arguments.
It is called in the following way:

\begin{cmds}
fbprint.exe [options] inputfile

options:
     -b            shorter output
     -q            Select observations based on QC flags
     -Q            Select observations based on QC flags
     -B            Select observations based on QC flags
     -u            unsorted
     -s ID         select station ID
     -t TYPE       select observation type
     -v NUM1-NUM2  select variable range to print by number
                      (default all)
     -a NUM1-NUM2  select additional variable range to print by number
                      (default all)
     -e NUM1-NUM2  select extra variable range to print by number
                      (default all)
     -d            output date range
     -D            print depths
     -z            use zipped files
\end{cmds}

%% =================================================================================================
\subsubsection{fbsel}

The program fbsel will select or subsample observations.
It is called in the following way:

\begin{cmds}
fbsel.exe <input filename> <output filename>
\end{cmds}

%% =================================================================================================
\subsubsection{fbstat}

The program fbstat will output summary statistics in different global areas into a number of files.
It is called in the following way:

\begin{cmds}
fbstat.exe [-nmlev] <filenames>
\end{cmds}

%% =================================================================================================
\subsubsection{fbthin}

The program fbthin will thin the data to 1 degree resolution.
The code could easily be modified to thin to a different resolution.
It is called in the following way:

\begin{cmds}
fbthin.exe inputfile outputfile
\end{cmds}

%% =================================================================================================
\subsubsection{sla2fb}

The program sla2fb will convert an AVISO SLA format file to feedback format.
It is called in the following way:

\begin{cmds}
sla2fb.exe [-s type] outputfile inputfile1 inputfile2 ...

Option:
     -s            Select altimeter data_source
\end{cmds}

%% =================================================================================================
\subsubsection{vel2fb}

The program vel2fb will convert TAO/PIRATA/RAMA currents files to feedback format.
It is called in the following way:

\begin{cmds}
vel2fb.exe outputfile inputfile1 inputfile2 ...
\end{cmds}

%% =================================================================================================
\subsection{Building the obstools}

To build the obstools use in the tools directory use ./maketools -n OBSTOOLS -m [ARCH].

%% =================================================================================================
\subsection{Dataplot}

An IDL program called dataplot is included which uses a graphical interface to
visualise observations and feedback files. Note a similar package has recently developed in python (also called dataplot) which does some of the same things that the IDL dataplot does. Please contact the authors of the this chapter if you are interested in this.

It is possible to zoom in, plot individual profiles and calculate some basic statistics.
To plot some data run IDL and then:

\begin{verbatim}
IDL> dataplot, "filename"
\end{verbatim}

To read multiple files into dataplot,
for example multiple feedback files from different processors or from different days,
the easiest method is to use the spawn command to generate a list of files which can then be passed to dataplot.

\begin{verbatim}
IDL> spawn, 'ls profb*.nc', files
IDL> dataplot, files
\end{verbatim}

\autoref{fig:OBS_dataplotmain} shows the main window which is launched when dataplot starts.
This is split into three parts.
At the top there is a menu bar which contains a variety of drop down menus.
Areas - zooms into prespecified regions;
plot - plots the data as a timeseries or a T-S diagram if appropriate;
Find - allows data to be searched;
Config - sets various configuration options.

The middle part is a plot of the geographical location of the observations.
This will plot the observation value, the model background value or observation minus background value depending on
the option selected in the radio button at the bottom of the window.
The plotting colour range can be changed by clicking on the colour bar.
The title of the plot gives some basic information about the date range and depth range shown,
the extreme values, and the mean and RMS values.
It is possible to zoom in using a drag-box.
You may also zoom in or out using the mouse wheel.

The bottom part of the window controls what is visible in the plot above.
There are two bars which select the level range plotted (for profile data).
The other bars below select the date range shown.
The bottom of the figure allows the option to plot the mean, root mean square, standard deviation or
mean square values.
As mentioned above you can choose to plot the observation value, the model background value or
observation minus background value.
The next group of radio buttons selects the map projection.
This can either be regular longitude latitude grid, or north or south polar stereographic.
The next group of radio buttons will plot bad observations, switch to salinity and
plot density for profile observations.
The rightmost group of buttons will print the plot window as a postscript, save it as png, or exit from dataplot.

\begin{figure}
  \centering
  \includegraphics[width=0.66\textwidth]{OBS_dataplot_main}
  \caption{Main window of dataplot}
  \label{fig:OBS_dataplotmain}
\end{figure}

If a profile point is clicked with the mouse button a plot of the observation and background values as
a function of depth (\autoref{fig:OBS_dataplotprofile}).

\begin{figure}
  \centering
  \includegraphics[width=0.66\textwidth]{OBS_dataplot_prof}
  \caption[Profile plot from dataplot]{
    Profile plot from dataplot produced by right clicking on a point in the main window}
  \label{fig:OBS_dataplotprofile}
\end{figure}

\subinc{\input{../../global/epilogue}}

\end{document}