EOFGRADS

Version 0.155

A tool to compute Empirical Orthogonal Functions (EOFs) within GrADS.

Installation

Download a suitable gzipped tar file
Unpack script eof.gs and binary eofudf from the tar archive:
gunzip -c eofgrads_*tar.gz | tar -xvf -
Move eof.gs to your GrADS script directory.
If you never used a User Defined Function (UDF), set your environment variable GAUDFT to point to your UDF table file, for example:

csh:
$ setenv GAUDFT $HOME/grads/udft.txt
sh:
$ export GAUDFT=$HOME/grads/udft.txt

You may like to add these lines to your .login (csh) and/or .profile (sh) files.

Add an eofudf entry to your UDF table file:

eofudf 2 6 expr value value value value char
sequential
/your/path/to/eofudf <-- Your path to the eofudf executable
eofudf.in
eofudf.out

(Only for Linux): The Linux eofudf binary requires a run-time library libcxa.so.3 which is included in the Linux tar-file. Eofudf will only work if you either install libcxa.so.3 in one of the standard search directories for libraries, e.g., /usr/lib, or if you set the environment variable LD_LIBRARY_PATH to include the directory where you stored libcxa.so.3, e.g., if you stored libcxa.so.3 in $HOME/lib and you are using the bash shell,
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/lib
You may like to add this to your environment setup to your .profile file.

Usage

ga-> eof [options] fld

with

fld Input field (GrADS expression).

Options:

-neof <# eof>	 Number of EOFs (default: 12)
-npc <# pc>	 Number of PCs (default: # eof)
-tinc tinc;	 Time increment (default: 1)
-nper nper;	 Minimal percent of defined data values required
	for a grid point to be considered in the EOF calculation
-o <prefix>	 Prefix for output files: (default: first 6 characters of  <fld>)

Notes

Normalization: Variance(PCs)=1
Be carefull not to include spaces in the input field expression.
The data are not weighted. Use sqrt(cos(lat*3.141/180)) for a simple area weight.
The program is not well tested for inputs with data gaps.
Avoid GrADS's cyclic continuation for global data; otherwise the cyclic points will be weighted twice.
You must have write permission to the current working directory.

Examples

Compute EOFs of field u using the current GrADS dimensions:

   ga-> eof u

Compute the first 20 area weighted EOF's and the first 10 PCs of "p" over land assuming a land mask "mask". The output files shall get the prefix "pland". At least 50% of data shall exist at each grid point to be included in the EOF analysis. Analyze data in the northern mid-latitude (35N to 60N).
```
ga-> set lat 35 60
ga-> set time jan1980 dec2000
ga-> eof -o pland -neof 20 -npc 10 -nper 50 maskout(p,mask)*sqrt(cos(lat*3.141/180))
```

How it works

To circumvent the Grads's UDF limitation to up to 2 dimensions eofgrads consists of a GrADS script eof.gs and a UDF eofudf. The script eof.gs uses the current GrADS dimension (lon,lat,lev,time) to write the data for the EOF analysis to a file eof_in.gad. It then sets time to the first time step and executes the UDF eofudf via a GrADS display command. Eofudf uses EISPACK routines to compute the eigenvalues and eigenvectors (EOFs) of the covariance matrix of the data in eof_in.gad The Principal Component (PCs) are obtained by projection of the original data onto the EOFs.

The EOFs and PCs are written to two GrADS data descriptor file/data file pairs:xxxx_eof.ctl/xxxx_eof.gad and xxxx_pc.ctl/xxxx_pc.gad The eigenvalues and the accounted ("explained") variances are written to a text file xxxx_eval.txt. Finally, a second call of eofudf with a time series input is used to obtain the time information needed for TDEF records in the output control files.

Copyright

As usual, anything free comes with

                            NO WARRANTY

  BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.

Source code
The source code can be downloaded here. Go into the src directory and run "make" to compile eofudf.
Remarks

You may need to adjust "resz" in the eofudf.f file. It specifies the units for "REAL"s in Fortran "ACCESS='DIRECT'" open commands and depends on the Fortran compiler you are using. Most likely values for "resz" are 1, 4 or 8.
You may also have to edit the Makefile to specify your Fortran compiler and options.

Matthias Münnich