Ferret

Appendix A: EXTERNAL FUNCTIONS

A number of external functions are included with the Ferret distribution. This number is expected to grow as Ferret developers and users contribute more functions. See the chapter "Writing External Functions" (p. 249) for how to adapt your Fortran code to a Ferret external function. Send your contributions to the Users Guide editor at ferret_ug@pmel.noaa.gov.

The functions are listed in the following sections. To see what functions are available to you, type

yes? SHOW FUNCTION/EXTERNAL

yes? SHOW FUNCTIONS/DETAILS/EXTERNAL function_name

gives further details on how the arguments influence the grid for the function's result.

Appendix A Sec1. COMPRESSI

COMPRESSI(DAT) Returns data, compressed along the I axis: Missing points moved to the end

Arguments:	DAT	DAT: variable to compress in I
Result Axes:	X	ABSTRACT, same length as DAT x-axis
	Y	Inherited from DAT
	Z	Inherited from DAT
	T	Inherited from DAT

Note:
It is generally advisable to include explicit limits when working with functions that replace axes. for example, consider the function compressi(v). The expression

list/i=6:10 compressi(v)

is not equivalent to

list compressi(v[i=6:10])

The former will list the 6th through 10th compressed indices from the entire i range of variable v. the latter will list all of the indices that result from compressing v[i=6:10].

Appendix A Sec2. COMPRESSJ

COMPRESSJ(DAT) Returns data, compressed along the J axis: Missing points moved to the end

Arguments:	DAT	DAT: variable to compress in J
Result Axes:	X	Inherited from DAT
	Y	ABSTRACT, same length as DAT y-axis
	Z	Inherited from DAT
	T	Inherited from DAT

Note: see the note under COMPRESSI on specifying axis limits (p. 69)

Appendix A Sec3. COMPRESSK

COMPRESSK(DAT) Returns data, compressed along the I axis: Missing points moved to the end

Arguments:	DAT	DAT: variable to compress in K
Result Axes:	X	Inherited from DAT
	Y	Inherited from DAT
	Z	ABSTRACT, same length as DAT z-axis
	T	Inherited from DAT

Note: see the note under COMPRESSI on specifying axis limits (p. 69)

Appendix A Sec4. COMPRESSL

COMPRESSL(DAT) Returns data, compressed along the L axis: Missing points moved to the end

Arguments:	DAT	DAT: variable to compress in L
Result Axes:	X	Inherited from DAT
	Y	Inherited from DAT
	Z	Inherited from DAT
	T	ABSTRACT, same length as DAT t-axis

Note: see the note under COMPRESSI on specifying axis limits (p. 69)

Appendix A Sec5. COMPRESSI_BY

COMPRESSI_BY (var, mask), Compress data according to a mask

Arguments:	VAR	Variable to compress according to MASK
	MASK	mask to use in compressing the data
Result Axes:	X	Abstract
	Y	Inherited from VAR and MASK
	Z	Inherited from VAR and MASK
	T	Inherited from VAR and MASK

Compress variable "dat" along its I axis using the (multi-dimensional) mask supplied in the second argument.

For example:

yes? LET mask = {1,,1,,1} + 0*L[l=101:102] + 0*K[k=10:11]
yes? LIST mask
               {1,,1,,1} + 0*L[L=101:102] + 0*K[K=10:11]
                   1      2      3      4      5
                   1      2      3      4      5
     ---- L:101 T:   101
     10   / 10: 1.000   .... 1.000   .... 1.000
     11   / 11: 1.000   .... 1.000   .... 1.000
     ---- L:102 T:   102
     10   / 10: 1.000   .... 1.000   .... 1.000
     11   / 11: 1.000   .... 1.000   .... 1.000

yes? LIST compressi_by({11,22,33,44,55},mask)
                 COMPRESSI_BY({11,22,33,44,55},MASK)
                   1      2      3      4      5
                   1      2      3      4      5
     ---- L:101 T:   101
     10   / 10: 11.00 33.00 55.00   ....   ....
     11   / 11: 11.00 33.00 55.00   ....   ....
     ---- L:102 T:   102
     10   / 10: 11.00 33.00 55.00   ....   ....
     11   / 11: 11.00 33.00 55.00   ....   ....

Appendix A Sec6. COMPRESSJ_BY

COMPRESSJ_BY (var, mask), Compress data according to a mask

Arguments:	VAR	Variable to compress according to MASK
	MASK	mask to use in compressing the data
Result Axes:	X	Inherited from VAR and MASK
	Y	Abstract
	Z	Inherited from VAR and MASK
	T	Inherited from VAR and MASK

Compress variable "dat" along its J axis using the (multi-dimensional) mask supplied in the second argument. See the example under COMPRESSI_by.

Appendix A Sec7. COMPRESSK_BY

COMPRESSK_BY (var, mask), Compress data according to a mask

Arguments:	VAR	Variable to compress according to MASK
	MASK	mask to use in compressing the data
Result Axes:	X	Inherited from VAR and MASK
	Y	Inherited from VAR and MASK
	Z	Abstract
	T	Inherited from VAR and MASK

Compress variable "dat" along its K axis using the (multi-dimensional) mask supplied in the second argument. See the example under COMPRESSI_by.

Appendix A Sec8. COMPRESSL_BY

COMPRESSL_BY (var, mask), Compress data according to a mask

Arguments:	VAR	Variable to compress according to MASK
	MASK	mask to use in compressing the data
Result Axes:	X	Inherited from VAR and MASK
	Y	Inherited from VAR and MASK
	Z	Inherited from VAR and MASK
	T	Abstract

Compress variable "dat" along its L axis using the (multi-dimensional) mask supplied in the second argument. See the example under COMPRESSI_by.

Appendix A Sec9. CONVOLVEI

CONVOLVEI (VAR, WEIGHT), CONVOLVEJ (VAR, WEIGHT) ,
CONVOLVEK (VAR, WEIGHT), CONVOLVE L (VAR, WEIGHT)
Convolve I (J,K,or L)component of variable with weight function

Arguments:	VAR	COM: variable to convolve
	WEIGHT	Weight function
Result Axes:	X	Inherited from VAR
	Y	Inherited from VAR
	Z	Inherited from VAR
	T	Inherited from VAR

This function (and likewise CONVOLVEJ, CONVOLVEK, and CONVOLVEL) convolves the variable VAR, with the weight function, wt along the X axis. Note that the variable's context may not be of adequate size for the full calculation. Missing data flags will be inserted where computation is impossible.

When bad data points are encountered in the component data all result data depending on it are flagged as bad, too.

The weight function is applied at each point from i-hlen to i+hlen, where hlen is half the length of the weight function. If the function is of even length, a zero weight is used at the upper end. Thus if the weights were {0.1, 0.4, 0.4, 0.1} the result at point I would be computed as the sum 0.1* COM(i-2) + 0.4* com(i-1) + 0.4* COM(i) + 0.1* COM(i+1) + 0.* COM(i+2)

Example:

Use the function to smooth a function. ()

yes? LET weight = {0.25, 0.5, 0.25}
yes? LET c = SIN(x[x=0:10:.1]) + RANDU(X[X=0:10:.1])/5
yes? PLOT c
yes? PLOT/OVER/TITLE="convolvei" CONVOLVEI(c,weight)

Appendix A Sec10. EOF_SPACE

EOF_SPACE(A, FRAC_TIMESER) Returns EOF (Empirical Orthogonal Function) spacial fields(eigenfunctions) from x-y-time field

Arguments:	A	Variable in x, y, t; may be a function of z
	FRAC_ TIMESER	Use only those time series with this fraction valid data, e.g. 0.8 to require that 80% of the data be present to use the data at a location.
Result Axes:	X	Inherited from A
	Y	Inherited from A
	Z	Inherited from A
	T	ABSTRACT 1 to NEOF

The EOF functions all make the same computations, returning different portions of the results. EOF_SPACE returns the eigenfunctions, normalized so that they have the units of data, while time amplitude functions (TAF's) are dimensionless. Thus the sum of the values of a given EOF = sqrt(eigenvalue), and the mean of a given TAF = 1. EOF_STAT returns some useful statistics: the number of EOF's which were computed and normalized for the parameters given; the %variation explained for each eigenfunction, and the eigenvalues.

Specifying the context of the input variable explicitly e.g.

EOF_SPACE(A[x=20:40,y=2s:40n,l=1:58],FRAC_TIMESER)

will prevent any confusion about the region. See the note in chapter 3 (p.63 )on the context of variables passed to functions.

The method is an implementation of Chelton's '82 method for finding EOFs of gappy time series. If there are no gaps, it reduces to ordinary EOFs.

The EOF analysis solves a matrix problem where the matrix is dimensioned (NX*NY) by NT, which can quickly become quite large. The EOF functions use other workspace as well which demands even more memory, and often memory must be increased with the SET MEMORY command. Regridding to a coarser grid or restricting the region may be necessary.

See the example under EOF_STAT for more on the input parameters, and see the demonstration ef_eof_demo.jnl for examples of this function.

Note: Earlier versions of the EOF functions had one more parameter. Check the version you have by saying

yes? SHOW FUNCTION eof*

The PCT_CUTOFF argument let you specify a minimum percent variance explained, and only scaled and returned N EOF's, up to the point where the EOF explained at least that variance. The current version is equivalent to setting PCT_CUTOFF = 0; e.g. all EOF's are scaled and returned in the result.

Appendix A Sec11. EOF_STAT

EOF_STAT(A,FRAC_TIMESER) Used with EOF_SPACE and/or EOF_TFUNC. Return statistics related to an EOF solution for a given set of parameters. Results are on the x-axis j = 1: # EOFscomputed and scaled, j = 2: % percentage of total variance accounted for by each eigenvector, j = 3: the eigenvalues.

Arguments:	A	Variable in x, y, t; may be a function of z
	FRAC_ TIMESER	Use only those time series with this fraction valid data, e.g. 0.8 to require that 80% of the data be present to use the data at a location.
Result Axes:	X	ABSTRACT: 1 to NEOF
	Y	ABSTRACT: 1 through 3 as outlined in the description.
	Z	NORMAL (no axis)
	T	NORMAL (no axis)

Please see the discussion under EOF_SPACE, and see the demonstration ef_eof_demo.jnl for examples of this function.

Example results:

For a simple sample function, eof_stat called to decompose it into eigenfunctions. We allow data to be used if the time series at the point has at least 80% valid data.

Request the number of eigenvalues computed for this choice of parameters.

yes? list/i=1/j=1 eofstat
            VARIABLE : EOF_STAT(SST[X=67W:1W,Y=11S:11N], 0.8)0
            DATA SET : COADS Monthly Climatology (1946-1989)
            FILENAME : coads_climatology.des
            FILEPATH : /home/ja9/tmap/fer_dsets/descr/
            X        : 1
            Y        : 1
         284.0

Now get the percent variance explained by the eigenfunctions which were computed.

yes? list/i=1:10/j=2 eofstat
            VARIABLE : EOF_STAT(SST[X=67W:1W,Y=11S:11N], 0.8)
            DATA SET : COADS Monthly Climatology (1946-1989)
            FILENAME : coads_climatology.des
            FILEPATH : /home/ja9/tmap/fer_dsets/descr/
            SUBSET   : 10 points (X)
            Y        : 2
              2
              2
1    / 1: 86.95
2    / 2:   5.82
3    / 3:   3.87
4    / 4:   1.51
5    / 5:   0.56
6    / 6:   0.38
7    / 7:   0.31
8    / 8:   0.23
9    / 9:   0.15
10   / 10:   0.11

And finally the eigenvalues associated with these eigenfunctions.

yes? list/i=1:10/j=3 eofstat
            VARIABLE : EOF_STAT(SST[X=67W:1W,Y=11S:11N], 0.8)
            DATA SET : COADS Monthly Climatology (1946-1989)
            FILENAME : coads_climatology.des
            FILEPATH : /home/ja9/tmap/fer_dsets/descr/
            SUBSET   : 10 points (X)
            Y        : 3
              3
              3
1    / 1: 249.4
2    / 2:   16.7
3    / 3:   11.1
4    / 4:    4.3
5    / 5:    1.6
6    / 6:    1.1
7    / 7:    0.9
8    / 8:    0.7
9    / 9:    0.4
10   / 10:    0.3

Appendix A Sec12. EOF_TFUNC

EOF_TFUNC(A, FRAC_TIMESER) Compute EOF time amplitude functions from x-y-time field w/gaps.

Arguments:	A	Variable in x, y, t; may be a function of z
	FRAC_ TIMESER	Use only those time series with this fraction valid data, e.g. 0.8 to require that 80% of the data be present to use the data at a location.
Result Axes:	X	ABSTRACT: 1 to NEOF
	Y	NORMAL (no axis)
	Z	Inherited from A
	T	Inherited from A

Please see the discussion under EOF_SPACE, and see the demonstration ef_eof_demo.jnl for examples of this function.

The time amplitude functions (TAF's) are dimension less; and the mean of a given TAF = 1. They are returned as follows: For x=1, time amplitude function corresponding to the first eigenfunction is the time series with t=1:NT.

Appendix A Sec13. FINDHI

FINDHI(A,XRANGE,YRANGE) Find local maxima of a variable.

Arguments:	A	Variable in x and y, may be a function of z and/or t
	XRANGE	Range in data units of the X radius in which the function looks for maxima
	YRANGE	Range in data units of the Y radius in which the function looks for maxima
Result Axes:	X	ABSTRACT
	Y	ABSTRACT: j=1:3
	Z	Inherited from A
	T	Inherited from A

The maxima are listed along the X axis: j=1 contains the X locations of the points, j=2 contains the Y coordinates of the points, and j=3 contains the function values at the maxima.

This function looks for the maximumm gridded value in the neighborhood x+/- XRANGE, Y+/- YRANGE. It returns only values in the interior of the region, not on boundaries. It is an implementaion of the NCAR graphics routine "minmax"

The GO script label_lo_hi.jnl makes it easy to call this function and label and label low's and high's with either their numerical value or the letters L and H. See the demonstration script minmax_label_demo.jnl

Appendix A Sec14. FINDLO

FINDLO(A,XRANGE,YRANGE) Find local minima of a variable.

Arguments:	A	Variable in x and y, may be a function of z and/or t
	XRANGE	Range in data units of the X radius in which the function looks for minima
	YRANGE	Range in data units of the Y radius in which the function looks for minima
Result Axes:	X	ABSTRACT
	Y	ABSTRACT: j=1:3
	Z	Inherited from A
	T	Inherited from A

The minima are listed along the X axis: j=1 contains the X locations of the points, j=2 contains the Y coordinates of the points, and j=3 contains the function values at the minima.

This function looks for the minimumm gridded value in the neighborhood x+/- XRANGE, Y+/- YRANGE. It returns only values in the interior of the region, not on boundaries. It is an implementaion of the NCAR graphics routine "minmax".

Appendix A Sec15. FFT_IM

FFT_RE(A) computes the imaginary part of Fast Fourier Transform of time series in variable A

Arguments:	A	Variable with a regular time axis; may be a function of x, y, and/or z
Result Axes:	X	Inherited from A
	Y	Inherited from A
	Z	Inherited from A
	T	Generated by the function: frequency in cyc/(time units from A)

The units of the returned time axis are "cycles/Dt" where Dt is the time increment.

Even and odd N's are allowed. N need not be a power of 2. FFT_RE and FFTP_IM assume f(1)=f(N+1), and the user gives the routines the first N pts.

The code is based on the FFT routines in Swarztrauber's FFTPACK available at www.netlib.org.

Specifying the context of the input variable explicitly e.g.

LIST FFT_RE(A[l=1:58])

will prevent any confusion about the region. See the note in chapter 3 (p. 63)on the context of variables passed to functions.

Appendix A Sec16. FFT_RE

FFT_RE(A) computes the real part of Fast Fourier Transform of time series in variable A

Arguments:	A	Variable with a regular time axis; may be a function of x, y, and/or z
Result Axes:	X	Inherited from A
	Y	Inherited from A
	Z	Inherited from A
	T	Generated by the function: frequency in cyc/(time units from A)

The units of the returned time axis are "cycles/Dt" where Dt is the time increment.

Even and odd N's are allowed. N need not be a power of 2. FFT_RE and FFT_IM assume f(1)=f(N+1), and the user gives the routines the first N pts.

The code is based on the FFT routines in Swarztrauber's FFTPACK available at www.netlib.org.

Specifying the context of the input variable explicitly e.g.

LIST FFT_RE(A[l=1:58])

will prevent any confusion about the region. See the note in chapter 3 (p. 63)on the context of variables passed to functions.

Appendix A Sec17. FFT_INVERSE

FFT_INVERSE(AR, AI) computes inverse Fast Fourier Transform of the two frequency series in AR and AI

Arguments:	AR	Real part of an FFT transform. Variable with a frequency axis; may be a function of x, y, and/or z
	AI	Imaginary part of an FFT transform. Variable with a frequency axis; may be a function of x, y, and/or z
Result Axes:	X	Inherited from AR, AI
	Y	Inherited from AR, AI
	Z	Inherited from AR, AI
	T	Abstract axis: 2*length of input frequency axes of AR and AI

The returned time axis is abstract; the user will need to regrid it to the appropriate time axis.

See also the functions FFTA and FFTP for the amplitude and phase of the transforms.

The code is based on the FFT routines in Swarztrauber's FFTPACK available at

www.netlib.org.

Appendix A Sec18. WRITEV5D

WRITEV5D(V1,V2,V3,V4,V5,V6,V7,V8,FILENAME) Write up to 8 variables to a Vis5D-formatted file V5.1

Arguments:	V1
	V2
	V3	Up to 8 variables to write to the file
	V4
	V5
	V6
	V7
	V8
	FILENAME	Name of the file to write: file type for Vis5d files is .v5d
Result Axes:	X	Inherited from variables: all variables must have the same x and y axes
	Y	Inherited from variables: all variables must have the same x and y axes
	Z	Inherited from variables; the result grid will contain the union of all the levels that are present in the variables.
	T	Inherited from variables: all variables must have the same time axis

This function calls utility functions from the Vis5D distribution to write a Vis5D-formatted file containing Ferret variables. TheVis5D tool is a system for interactive visualization of large 5-D gridded data sets. It was developed by Bill Hibbard and others at the University of Wisconsin, and can be found at

http://www.ssec.wisc.edu/~billh/vis5d.html

There are limits in Vis5D on the size of the grid and the number of timesteps. The function will issue an error if these limits are exceeded.

To make it more convenient to call the writev5d function, to open Vis5D from Ferret, and to append to a Vis5D file, GO tools are available: vis5d_write.jnl, vis5d_start.jnl, and vis5d_append.jnl. These have the filename first in their argument lists, and do not require the user to specify all 8 arguments to the function.

Write 3 variables to a file, then append to some of the variables. The times in this example have a gap in them; this will show up in the Vis5d tool as a gap in time. Last, start Vis5d and open the file.

Yes? SET REGION/I=55:180/J=30:60
yes? GO vis5d_write tm_1.v5d sst[L=20:30], airt[L=20:30], fcn_1
yes? GO vis5d_append t_1.v5d sst[l=34,50], airt[l=34,50]
yes? GO vis5d_start temper_1.v5d

See the demonstration ef_wv5d_demo.jnl for examples of this function.

Appendix A Sec19. ZAXREPLACE_AVG

ZAXREPLACE_AVG(V,ZVALS,ZAX)

Use weighted averaging to convert between alternative monotonic Zaxes. The weighting is done according to the portion of the source box that lies within the destination grid cell.

The mapping between the source and destination Z axes is a function of X,Y, and or T. Typical applications in the field of oceanography include converting from a Z axis of layer number to a Z axis in units of depth (e.g., for sigma coordinate fields) and converting from a Z axes of depth to one of density (for a stably stratified fluid).

Argument 1, V, is the field of data values, say temperature on the "source" Z-axis, say, layer number. The second argument, ZVALS, contains values in units of the desired destination Z axis (ZAX) on the Z axis as V — for example, depth values associated with each vertical layer. The third argument, ZAX, is any variable defined on the destination Z axis, often "Z[gz=zaxis_name]" is used. For an example of the ZAXREPLACE family of functions see ZAXREPLACE (p. 70)

Arguments:	V	A function of depth and perhaps, x, y, and time.
	ZVALS	Destination Z axis values as a fcn of source Z axis
	ZAX	Variable with desired z (depth) axis points
Result Axes:	X	Inherited from V
	Y	Inherited from V
	Z	Inherited from ZAX
	T	Inherited from V

Appendix A Sec20. ZAXREPLACE_BIN

ZAXREPLACE_BIN(V,ZVALS,ZAX)

Use unweighted averaging to convert between alternative monotonic Zaxes. The function finds the source points within each destination box and averages them.

Arguments:	V	A function of depth and perhaps, x, y, and time.
	ZVALS	Destination Z axis values as a fcn of source Z axis
	ZAX	Variable with desired z (depth) axis points
Result Axes:	X	Inherited from V
	Y	Inherited from V
	Z	Inherited from ZAX
	T	Inherited from V