@BeginModule
@NewPage
@Name      = EOFs
@Title     = Empirical Orthogonal Functions
@Section   = EOFs
@Class     = EOF calculation
@Arguments = ifile ofile1 ofile2
@Operators = eof eoftime eofspatial eof3d

@BeginDescription
This module calculates empirical orthogonal functions of the data in @file{ifile} 
as the eigen values of the scatter matrix (covariance matrix) @math{S} of the data
sample @math{z(t)}. A more detailed description can be found above.

@bold{Please note, that the input data are assumed to be anomalies.}

If operator @mod{eof} is chosen, the EOFs are computed in either time or spatial
space, whichever is the fastest. If the user already knows, which computation
is faster, the module can be forced to perform a computation in time- or gridspace
by using the operators @mod{eoftime} or @mod{eofspatial}, respectively. This can enhance 
performance, especially for very long time series, where the number of timesteps
is larger than the number of grid-points. Data in @file{ifile} are assumed to be anomalies.
If they are not, the behavior of this module is @bold{not well defined}. 
After execution @file{ofile1} will contain all eigen-values and @file{ofile2} the
eigenvectors @math{e_j}. All EOFs and eigen-values are computed. However, only the first 
@math{neof} EOFs are written to @file{ofile2}. Nonetheless, @file{ofile1} contains all eigen-values. 
Note, thate the resulting EOF in @file{ofile2} is @math{e_j} and thus @bold{not weighted} for consistency.

Missing values are not fully supported. Support is only checked for non-changing
masks of missing values in time. Although there still will be results, they are
not trustworthy, and a warning will occur. In the latter case we suggest to 
replace missing values by 0 in @file{ifile}. 
@EndModule


@BeginOperator_eof
@Title     = Calculate EOFs in spatial or time space
@Parameter = neof
@EndOperator

@BeginOperator_eof3d
@Title     = Calculate 3-Dimensional EOFs in time space
@Parameter = neof
@EndOperator

@BeginOperator_eof3dtime
@Title     = Same as eof3d
@Parameter = neof
@EndOperator

@BeginOperator_eoftime

@Title     = Calculate EOFs in time space
@Parameter = neof
@EndOperator

@BeginOperator_eofspatial
@Title     = Calculate EOFs in spatial space
@Parameter = neof
@EndOperator
@EndDescription


@BeginParameter neof
@Item = neof
INTEGER  Number of eigen functions
@EndParameter


@BeginEnvironment
@Item = CDO_SVD_MODE
Is used to choose the algorithm for eigenvalue calculation. Options are 'jacobi' for 
a one-sided parallel jacobi-algorithm (only executed in parallel if -P flag is set)
and  'danielson_lanczos' for a non-parallel d/l algorithm. The default setting is 'jacobi'.

@Item = MAX_JACOBI_ITER
Is the maximum integer number of annihilation sweeps that is executed if the 
jacobi-algorithm is used to compute the eigen values. The default value is 12.

@Item = FNORM_PRECISION
Is the Frobenius norm of the matrix consisting of an annihilation pair
of eigenvectors that is used to determine if the eigenvectors have reached 
a sufficient level of convergence. If all annihilation-pairs of vectors have 
a norm below this value, the computation is considered to have converged 
properly. Otherwise, a warning will occur. The default value 1e-12.
@EndEnvironment


@BeginExample
To calculate the first 40 EOFs of a data-set containing anomalies use:
@BeginVerbatim
   cdo eof,40 ifile ofile1 ofile2
@EndVerbatim

If the dataset does not containt anomalies, process them first,
and use:
@BeginVerbatim
   cdo sub ifile1 -timmean ifile1 anom_file	
   cdo eof,40 anom_file ofile1 ofile2	
@EndVerbatim
@EndExample
