\section{Usage}

This section descibes how to use {\CDO}.
The syntax is:
\begin{verbatim}
   cdo  [ Options ] Operator1 [ -Operator2 [ -OperatorN ] ]
\end{verbatim}


\subsection{Options}

All options have to be placed before the first operator.
The following options are available for all operators:

\begin{tabbing}
\makebox[1.5in][l]{\hspace*{1cm}\sl -a}
         \= Generate an absolute time axis. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -b $<$nbits$>$}
         \> Set the number of bits for the output precision. The valid precisions depend \\
         \> on the file format:\\
         \> \parbox[r]{3in}{
              \vspace*{1mm}
              \hspace*{0cm}\begin{tabular}{|l|l|}
              \hline
              \rowcolor{pcolor2}
                \sl $<$format$>$ & \sl $<$nbits$>$ \\
                {\tt grb, grb2}           & {\tt P1 - P24}              \\
                {\tt nc, nc2, nc4, nc4c}  & {\tt I8/I16/I32/F32/F64}  \\
                {\tt grb2, srv, ext, ieg}       & {\tt F32/F64}             \\
              \hline
              \end{tabular}
              \vspace*{1mm}
            } \\
         \> For {\tt srv}, {\tt ext} and {\tt ieg} format the letter {\tt L} or {\tt B} can be added to set the byteorder \\
         \> to {\tt L}ittle or {\tt B}ig endian. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -\,-cmor}
         \> CMOR conform NetCDF output. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -f $<$format$>$}
         \> Set the output file format. The valid file formats are: \\
         \> \parbox[r]{3in}{
              \vspace*{1mm}
              \hspace*{0cm}\begin{tabular}{|l|l|}
              \hline
              \rowcolor{pcolor2}
              {\bf File format}          & \sl $<$format$>$ \\
               GRIB version 1            & {\tt grb}  \\
               GRIB version 2            & {\tt grb2} \\
               NetCDF                    & {\tt nc}   \\
               NetCDF version 2 (64-bit) & {\tt nc2}  \\
               NetCDF-4 (HDF5)           & {\tt nc4}  \\
               NetCDF-4 classic          & {\tt nc4c} \\
               SERVICE                   & {\tt srv}  \\
               EXTRA                     & {\tt ext}  \\
               IEG                       & {\tt ieg}  \\
              \hline
              \end{tabular}
              \vspace*{1mm}
            } \\
         \> GRIB2 is only available if {\CDO} was compiled with GRIB\_API support and all \\
         \> NetCDF file types are only available if {\CDO} was compiled with NetCDF support! \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -g $<$grid$>$}
         \> Define the default grid description by name or from file (see chapter 1.3 on page \pageref{GRID_DESCRIPTION}). \\
         \> Available grid names are: {\tt r<NX>x<NY>}, {\tt lon=<LON>/lat=<LAT>}, {\tt n<N>}, {\tt gme<NI>} \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -h, -\,-help}
         \> Help information for the operators. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -\,-no\_history}
         \> Do not append to NetCDF {\it history} global attribute. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -\,-netcdf\_hdr\_pad, -\,-hdr\_pad, -\,-header\_pad $<$nbr$>$}
         \> \\
\makebox[1.5in][l]{\hspace*{1cm}}
         \> Pad NetCDF output header with {\it nbr} bytes. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -k $<$chunktype$>$}
         \> NetCDF4 chunk type: auto, grid or lines. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -L}
         \> Lock I/O (sequential access). \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -M}
         \> Switch to indicate that the I/O streams have missing values. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -m $<$missval$>$}
         \> Set the missing value of non NetCDF files (default: {\tt-9e+33}). \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -O}
         \> Overwrite existing output file, if checked. \\
         \> Existing output file is checked only for: {\tt ens<STAT>}, {\tt merge}, {\tt mergetime} \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -\,-operators}
         \> List of all operators. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -P $<$nthreads$>$}
         \> Set number of OpenMP threads (Only available if OpenMP support was compiled in). \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -\,-percentile $<$method$>$}
         \> \\
\makebox[1.5in][l]{\hspace*{1cm}}
         \> Percentile method: {\tt nrank nist numpy numpy\_lower numpy\_higher numpy\_nearest} \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -Q}
         \> Alphanumeric sorting of NetCDF parameter names. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -\,-reduce\_dim}
         \> Reduce NetCDF dimensions (module: TIMSTAT, FLDSTAT). \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -R, -\,-regular}
         \> Convert GRIB1 data from reduced to regular grid (only with cgribex lib). \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -r}
         \> Generate a relative time axis. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -S}
         \> Create an extra output stream for the module TIMSTAT. This stream contains  \\
         \> the number of non missing values for each output period. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -s, -\,-silent}
         \> Silent mode. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -t $<$partab$>$}
         \> Set the GRIB1 (cgribex) default parameter table name or file (see chapter 1.6 on page \pageref{PARAMETER_TABLE}).\\
         \> Predefined tables are:  {\tt echam4 echam5 echam6 mpiom1 ecmwf remo}\\
\makebox[1.5in][l]{\hspace*{1cm}\sl -\,-timestat\_date $<$srcdate$>$}
         \> \\
\makebox[1.5in][l]{\hspace*{1cm}}
         \> Target timestamp (time statistics): {\tt first, middle, midhigh} or {\tt last} source timestep. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -V, -\,-version}
         \> Print the version number. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -v, -\,-verbose}
         \> Print extra details for some operators. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -W}
         \> Print extra warning messages. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -z szip}
         \> SZIP compression of GRIB1 records. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl \ \ jpeg}
         \> JPEG compression of GRIB2 records. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl \ \ zip[\_1-9]}
         \> Deflate compression of NetCDF4 variables. \\
\end{tabbing}
%\footnotemark
%\footnotetext{Needs szip support compiled in}

\subsection{Environment variables}

There are some environment variables which influence the behavior of {\CDO}. 
An incomplete list can be found in \htmlref{Appendix A}{environment}.

Here is an example to set the envrionment variable CDO\_RESET\_HISTORY for different shells:

\begin{tabular}[b]{ll}
Bourne shell (sh): & CDO\_RESET\_HISTORY=1 ; export CDO\_RESET\_HISTORY \\
Korn shell (ksh):   & export CDO\_RESET\_HISTORY=1 \\
C shell (csh):        & setenv CDO\_RESET\_HISTORY 1 \\
\end{tabular}


\subsection{Operators}

There are more than 700 operators available.
% See section {\bf \htmlref{Operator catalog}{opercat}} for a short overview of all operators.
A detailed description of all operators can be found in the
{\bf \htmlref{Reference Manual}{refman}} section.


\subsection{Operator chaining}

All operators with a fixed number of input streams and one output stream
can pipe the result directly to an other operator.
The operator must begin with "--", in order to combine it with others.
This can improve the performance by:
\begin{itemize}
\item reducing unnecessary disk I/O
\item parallel processing
\end{itemize}
Use
\begin{verbatim}
   cdo sub -dayavg ifile2 -timavg ifile1 ofile
\end{verbatim}
instead of
\begin{verbatim}
   cdo timavg ifile1 tmp1
   cdo dayavg ifile2 tmp2
   cdo sub tmp2 tmp1 ofile
   rm tmp1 tmp2
\end{verbatim}

{\bf Note:}
Operator chaining is implemented over POSIX Threads (pthreads).
Therefore this {\CDO} feature is not available on operating systems without POSIX Threads support!

All operators with an arbitrary number of input streams ({\tt ifiles})
can't be combined with other operators if these operators are used
with more than one input stream. Here is an incomplete list of
these operators:
{\bf \htmlref{copy}{copy}},
{\bf \htmlref{cat}{cat}},
{\bf \htmlref{merge}{merge}},
{\bf \htmlref{mergetime}{mergetime}},
{\bf \htmlref{select}{select}},
{\bf \htmlref{ens$<\!STAT\!>$}{ENSSTAT}} \\
Use single quotes if the input stream names are generated with
wildcards. In this case CDO will do the pattern matching and the
output can be combined with other operators. Here is an example for
this feature:
\begin{verbatim}
   cdo timavg -select,name=temperature 'ifile?' ofile
\end{verbatim}

The CDO internal wildcard expansion is using the {\it glob()} function. 
Therefore internal wildcard expansion is not available on operating systems without the {\it glob()} function!

All operators with one input stream will process only one input
stream! You need to take care when mixing those operators with
operator with an arbitrary number of input streams. 
The following examples illustrate this problem.
\begin{enumerate}
\item {\tt cdo info -timavg ifile?}
\item {\tt cdo info -timavg ifile1 ifile2}
\item {\tt cdo timavg ifile1 tmpfile} \\
{\tt cdo info tmpfile ifile2}
\end{enumerate}
 All three examples produce identical results. 
The time average will be computed only on the first input file. 
\subsection{Parallelized operators}

Some of the {\CDO} operators are shared memory parallelized with OpenMP.
An OpenMP-enabled C compiler is needed to use this feature.
Users may request a specific number of OpenMP threads {\tt nthreads} with the '{\tt -P}' switch.

Here is an example to distribute the bilinear interpolation on 8 OpenMP threads:
\begin{lstlisting}[frame=single, backgroundcolor=\color{pcolor2}, basicstyle=\ttfamily, columns=flexible]
   cdo -P 8  remapbil,targetgrid  ifile  ofile
\end{lstlisting}

Many {\CDO} operators are I/O-bound. This means most of the time is spend in reading and writing the data. 
Only compute intensive {\CDO} operators are parallelized. 
An incomplete list of OpenMP parallelized operators can be found in \htmlref{Appendix B}{openmp}.

\subsection{Operator parameter}

Some operators need one or more parameter. A list of parameter is indicated by the seperator ','.

\begin{itemize}
\item STRING

Unquoted characters without blanks and tabs.
The following command select variables with the name {\tt pressure} and {\tt tsurf}:
\begin{verbatim}
   cdo selvar,pressure,tsurf ifile ofile
\end{verbatim}

\item FLOAT

Floating point number in any representation.
The following command sets the range between {\tt 0} and {\tt 273.15}
of all fields to missing value:
\begin{verbatim}
   cdo setrtomiss,0,273.15 ifile ofile
\end{verbatim}

\item INTEGER

A range of integer parameter can be specified by {\it first}/{\it last}[/{\it inc}].
To select the days 5, 6, 7, 8 and 9 use:
\begin{verbatim}
   cdo selday,5/9 ifile ofile
\end{verbatim}
The result is the same as:
\begin{verbatim}
   cdo selday,5,6,7,8,9 ifile ofile
\end{verbatim}
\end{itemize}

\subsection{CMOR compliant NetCDF output}

The {\CDO} NetCDF output is almost conform to the \href{http://cfconventions.org}{CF convention}.
The "Climate Model Output Rewriter" (\href{http://cfconventions.org}{CMOR}) library can be used to produce 
CF-compliant NetCDF files that fulfill the requirements of many of the climate community's standard model experiments.

\subsubsection{cmor operator}
The  {\CDO} operator cmor can be used to write NetCDF output with the CMOR library.
To enable this feature  {\CDO} needs to be compiled with CMOR support:
\begin{verbatim}
./configure  --with-netcdf=<NetCDF root directory> --with-cmor=<CMOR root directory> ...
make
\end{verbatim}

\subsubsection{cmor option}
The {\CDO} option -\,-cmor can be used to make the regular NetCDF output more CMOR conform.
This feature is independent from the CMOR library and can be used with all {\CDO} operators, except the operator cmor.
This option:
\begin{itemize}
\item Converts single value vertical coordinate to scalar coordinate variable
\item Stores hybrid sigma pressure level conform to the CF convention
\item Generates new {\tt tracking\_id} attribute
\item Generates new {\tt creation\_date} attribute
\end{itemize}
