my_var[GX=new_xaxis]
my_var[GX=175w:75w:10]
PLOT SIN(X[GX=0:3.14:.1])
my_time_series[GT=annual_axis@MOD]
my_time_series[GT=annual_axis@MODVAR]
LET/D=levitus_climatology sst = temp[Z=0]
SAY `1/300,BAD=-999,PRECISION=1`
0.003
" instead of "0.0033333"
SAY `U[Z=@AVE,L=1],RETURN=SHAPE`
XY
"
($shape%|X|Y|Z|T|<Error: not 1-dimensional%)
LIST/PRECISION=5 sst[d=coads_climatology]
LIST/FORMAT=tab-delimited SST[d=coads_climatology]
SET VARIABLE/TITLE="My own title" sst[D=coads_climatology]
($PPL$XPIXEL) ($PPL$YPIXEL)
MESSAGE Incredible\! What a message\! ! with a comment
SHADE/LEVELS=20C uwnd[D=coads_climatology,T=15-jan]
LIST/I=1:3 I[I=1:10]
will list just 3 values
Fprint -X my_metafile.plt
STAT/BRIEF
GO margins 1 .8 .5 1
SHADE/PALETTE=light_centered/LEVELS=C my_anomalies
New regridding transformations expand upon the style that has been available using G=@AVE. The G=@AVE transformation is most commonly used for regridding closely-spaced points to more widely spaced points. It computes the weighted average of the source points that lie fully or partially within the grid box of each destination grid point. Weighting is based on the relative span of source axis that lies within each destination grid box.
The new transformations compute the statistics of this regridding:
The new transformations are qualitatively different from previous
regridding transformations (G=@LIN, G=@AVE, ...) in that they compute
statistical attributes of the original field which may have differing
units and differing character from the original. For example, G=@VAR
will produce a result with units that are the squared units from the
source variable; G=@NGD will produce a dimensionless (no units) count
of numbers of points. Essentially these transformations provide a
means to perform a given calculation over a limited span of
coordinates and repeat that calculation for a series of contiguous
spans. For example, if we wish to compute the variance the variable
sst over 10 degree longitude range from 180 to 170w we
could use the syntax sst[X=180:170w@VAR]. Now, if we wish
to perform the same operation 10 times in 10-degree wide bands from
180 to 80w we could instead use G=@VAR regridding as in (see Dynamic
Grids in these release notes for an explanation of the "GX="
syntax):
DEFINE AXIS/X=175w:85w:10/UNITS=degrees x10deg LET sst10 = sst[GX=x10deg@VAR]Note that the variance (G=@VAR), sum (G=@SUM), and number of valid points (G=@NGD) are computed using the identical weighting scheme to G=@AVE whereas the minimum and maximum (G=@MIN and G=@MAX) are discrete (unweighted). For the unweighted calculations each source point contributes 100% to the destination point in whose grid box it lies. If the source point falls identically on the boundary between two destination grid cells it contributes 100% to the destination grid box to its right - the next higher coordinate value.
Interpolation in past versions of Ferret has been controlled
exclusively via a mode: SET MODE INTERPOLATE caused all data accesses
(all variables and all axes) to be interpolated when world coordinates
did not lie exactly on axis points. In Ferret version 4.20
interpolation can be applied on an axis by axis and variable by
variable basis like any other transformation. To apply interpolation
use the transformation "@ITP" in the same way as, say, @SBX,
specifying the desired location to which to interpolate. For example,
on a Z axis with grid points at Z=10 and Z=20 the syntax
my_var[Z=14@ITP] would interpolate to Z=14 with the computation
0.6*my_var[Z=10]+0.4*my_var[Z=20].
The example which follows illustrates the interpolation control
that is possible using @ITP:
In Ferret version 4.20 it is often possible to avoid explicitly
defining grids. Ferret will create the grids dynamically provided the
clues provided are unambiguous. This is useful in two common
situations:
Syntax: G*=name@transform where
Suppose the variable SST is defined on a 2x2 degree
grid in latitude/longitude (e.g. SET DATA coads_climatology).
If we wish to regrid to 10 degree spacing in longitude over a range
from 175W to 75W we could use the commands
The command SHOW GRID SST10 will show the dynamically created
grid. The names of dynamic grids will always be displayed in
parentheses.
Note that the transformation method to be used for regridding may also
be specified, so LET SST10 = SST[GX=x10deg@ave] would create a
10-degree spaced result in which each grid point was computed as the
weighted sum of the source points that fell within its grid box. As usual
the default method for regridding is linear interpolation.
Syntax: G=name@transform where
If two variables are defined on grids that are mutually
non-conformable because axes exist in one grid but do not exist (are
NORMAL) in another Ferret will now create a dynamic grid to
resolve the non-conformabilities. This means that an expression of the
form VAR1[G=VAR2] will be meaningful as long as the grid domains
overlap.
For example, TEMP[d=levitus_climatology] is defined on an XYZ
(time-independent) grid whereas SST[d=coads_climatology] is defined on
an XYT grid. So to evaluate the expression
SST[d=coads_climatology,G=TEMP[d=levitus_climatology]] Ferret will
create a dynamic intermediate grid equivalent to
Again, the command SHOW GRID will reveal the resulting dynamically
created grid structure.
The syntax "GX=lo:hi:delta" can now be used in square brackets
modifying a variable name to indicate the dynamic creation of an axis
with the indicated range and spacing and the immediate regridding of
the variable to a grid containing that axis. For example
SST[GX=175W:75W:10] will create a dynamic axis of 10 degree regular
point spacing, will create a dynamic grid incorporating this axis (see
previous section), and will regrid the variable SST to this grid.
Similarly, by referring to the grid indices rather than their world
coordinates the expression SST[GI=1:100:5] will create a dynamic axis
which subsamples every 5th longitude point from SST. In this case the
points of the resulting axis may be irregularly spaced if the points
of the original axis were also irregular.
As with the dynamic regridding described above, transformations can be
specified to indicate the regridding technique. Thus SST[GI=1:100:5@AVE]
will use averaging instead of the default linear interpolation to
perform the regridding.
As a notational convenience the "G" may be dropped when referring to a
dynamic axes. Thus SST[X=175W:75W:10] is equivalent to SST[GX=175W:75W:10]
and SST[I=1:100:5@AVE] is equivalent to SST[GI=1:100:5@AVE]. When using
this notational convenience keep in mind that a regridding is taking place
so the transformation which is applied (if any) must be a regridding
transformation (see SHOW TRANSFORMS).
The lower figure of this comparison plot illustrates the effect of dynamic
axes in the command
The same notation used for dynamic axes may also be applied to
pseudo-variables providing a simple means for creating arrays of values. For
example X[GX=0.2:1:0.2] is a vector of 5 points from 0.2 to 1 at a
regular spacing of 0.2 units. The vector is oriented in the X
direction.
An example of using such a vector is
As a notational convenience the "G" may be dropped when referring to a
dynamic pseudo-variables. Thus X[X=0.2:1:0.2] is equivalent to
X[GX=0.2:1:0.2].
Ferret version 4.20 can create climatologies from time series simply
by regridding to a climatological axis with a modulo regridding
transformation. For example, if the axis named month_reg is a
12 point monthly climatological axis then the expression
To generate a climatology based on a restricted range of input data
simply define an intermediate variable with the desired points. For
example a monthly climatological time series based on data from the
1960s could be computed
using
This example shows the entire sequence necessary to generate a plot of
climatological SST at 40N, 40W based on the January 1982 to December 1992
Fleet Numerical wind data set.
In many cases the volume of input data needed to perform
climatological calculations is very large. In the example above the
command
Unlike other transformations and regridding modulo regridding is
performed as an **unweighted** axerage: each non-missing source point
contributes 100% of its weight to the destination grid box within
which it falls. If the source and destination axes are not properly
aligned this can lead to apparent shifts in the data. For example, if
a monthly time series has data points at the first of each month and a
climatological axis is defined at midmonths then unweighted modulo
averaging will lead to an apparent 1/2 month shift. To avoid
situations of this type simply regrid to the climatological axis using
linear interpolation prior to the modulo regridding.
Here is an example that illustrates the situation and the use of
linear interpolation to repair it
In addition to the modulo averaging calculation performed by @MOD other
statistics of the regridding are also provided. All modulo regridding
calculations are unweighted as discussed under @MOD.
Try for example,
Previous to version 4.2 of Ferret the command LET (alias for DEFINE
VARIABLE) defined only global variable names. That is, the command
"LET varname = expression" defined "varname" such that it superseded
any other variables by that name in data sets. The qualifier
"Dataset=" (LET/Dataset=...) now allows you detailed control over the
multiple use of the same name.
If the name or number of a data set is supplied then the /dataset
qualifier indicates that this variable name is to be defined only in
the specified data set. For example
If the /dataset qualifier is applied without
specifying a data set name then the interpretation is different. In
this case the named variable becomes a default definition -- one which
applies only if a data-set specific variable of the same name does not
exist. For example, if the command
Let/D is especially useful for editing data sets because it gives a
ready way to distinguish between the pre-edit and post-edit versions
of the variable. In this example we edit the data set etopo60,
replacing a small rectangle in the Pacific Ocean:
Previously Ferret always formatted valid immediate mode results
using 5 significant digits and formatted invalid immediate mode results
as "bad". New controls allow you to specify the formatting of
immediate mode results in both valid and invalid cases.
The syntax to achieve this control is to include
If the #digits given is negative Ferret will interpret this as the
desired number of decimal places rather than the number of significant
digits. Thus
In the case of a negative precision value, Ferret will again drop
terminating zeros to the right of the decimal point.
The immediate mode syntax can reveal the size and shape of
the result
The keyword RETURN=, used in the syntax
(described immediately above) that controls the formatting of
immediate mode results, can reveal the size and shape of the
result. RETURN= may take arguments
Symbols may be edited and checked using the same controls that
apply to journal file arguments
The Ferret version 3.2 Users Guide contains a section called
Arguments to GO tools which describes the
syntax for checking and editing arguments. The same syntax now applies
to symbols defined by DEFINE SYMBOL. As with the GO tool arguments, all string manipulations are case insensitive.
In brief the capabilities include:
Using the qualifier /PRECISION=# the output precision of the LIST
command may be easily controlled. This qualifier functions exactly as
does the SET LIST/PRECISION= command but it applies only to the
current command.
Tab and commma-delimited output format suitable to ingest into
spreadsheets is now available from the LIST command. By default the
listing will also contain an explanatory header. Use the /NOHEAD
qualifier to suppress the header. Use /PRECISION= (see above) to
control the number of significant digit in the output. Use /ORDER= as
usual to permute the order of the output axes. Only the first 3
characters of the format specified are significant so
"LIST/FORMAT=comma-delimited" may be shortened to "LIST/FORMAT=com"
and similarly "tab-delimited" may be shortened to "tab".
Example,
For example, the SHOW DATA/VAR output for the variable "TEMP" might
appear as:
The output of SHOW TRANSFORMS now displays
The command SET VARIABLE, which previous to version 4.2 could be
applied only to user-defined variables (defined with LET) of "EZ"
variables (ASCII and IEEE binary files) can now be applied to NetCDF
and GT files. The modified titles, units, and bad data flags do not
effect the data files -- they effect only the current session. All
outputs - plots, listings, and data files created - will be effected
by the changes.
Note that Ferret maintains 2 missing data flags for
each variable though typically only one of the flags is used.
The symbols PPL$XPIXEL and PPL$YPIXEL will not appear in the output of
SHOW SYMBOLS/ALL because they are created on the fly in the proper
context of the current putput window. An example of usage:
The backslash character can be used to embed syntax elements that
might otherwise lead to inappropriate interpretation. This is
especially useful with the SPAWN command (to permit the full range of
characters for Unix commands). A backslash immediately preceding an
exclamation mark ("\!") will suppress the interpretation of the
exclamation mark as the end of the line. A backslash immediately
preceding a grave accent ("\`") will suppress the interpretation of
the grave accent as enclosing an immediate mode expression. A
backslash immediately preceding a semicolon ("\;") will suppress the
interpretation of the semicolon as a delimiter between commands.
Each of these lines would cause errors if the back slashes were omitted.
A number of easy shorcuts are now available to specify contour limits
in a general way. (All of the previous detailed controls still exist
and their function is unchanged.)
Conflicting region information can be given to Ferret in obvious ways such as
Internally, Ferret uses the region closest to the
variable to perform the calculation. Thus, in both of the
examples above Ferret will perform the calculation on I=1:10, since
the "[I=1:10]" directly modifies the variable name. If Ferret sees
conflicting regions it attempts to use the regions further from the
variable to clip the calculation. Thus 10 points are clipped to 3 in
the above examples.
Unresolvable conflicts such as
The Ferret utility Fprint now supports screen previews of Ferret metafiles,
with the -X option. The help functions in both Fprint and its underlying
utility gksm2ps provide instructions on obtaining a preview of a metafile.
For example
The output of STAT/BRIEF excludes the header information (data set, title,
units and region) and omits the computation of variance.
Note that you must use this script after
SET VIEWPORT and SET WINDOW/ASPECT as those commands will
override the effects of
SET DATA coads_climatology
! with modal interpolation
SET MODE INTERPOLATE
LIST/L=1/X=180/Y=0 sst ! interpolates both lat and long
! with no interpolation
CANCEL MODE INTERPOLATE
LIST/L=1/X=180/Y=0 sst ! gives value at 179E, 1S
! using @ITP to interpolate in longitude, only
LIST/L=1/Y=0 sst[X=180@ITP] ! latitude remains 1S
Back to Table of Contents
Back to Table of Contents
Regridding to specified axes without defining the destination grid.
DEFINE AXIS/X=175w:75w:10/UNITS=degrees x10deg
LET sst10 = sst[GX=x10deg]
Ferret will dynamically create a grid equivalent to new_grid in
DEFINE GRID/LIKE=sst/X=x10deg new_grid.
This figure shows the effects of
regridding the 2x2 degree COADS data to a 10 degree spacing in
longitude using (default) linear interpolation.
Automatic reconciliation of incompatible grid shapes
DEFINE GRID/LIKE=sst[D=coads_climatology]/X=temp/Y=temp
so that regridding
occurs on the X and Y axes but the original grid structure is
maintained with respect to depth and time.
SHADE SST[GX=175W:75W:10]
Back to Table of Contents
PLOT SIN(X[GX=0:3.14:.1])
Note that when the lo:high:delta notation is applied to T or L
expressed as calendar dates the units of the delta value will be hours
so that, for example, L[GT=1-jan-1980:1-feb-1980:24] is 32 integer
spaced at regular 24 hour intervals.
LET sst_climatology = sst[D=coads,GT=month_reg@MOD]
is a 12 month climatology computed by averaging the full time domain
of the input variable (576 points for coads) modulo fashion into the
12 points of the climatological axis.
LET sst_1960s = sst[D=coads,T=1-jan-1960:31-dec-1969]
PLOT sst_1960s[GT=month_reg@MOD]
In a similar fashion intermediate variables can be defined that mask out
only certain input points.
! use the predefined climatological axes
USE climatological_axes
CANC DATA climatological_axes
! use the Fleet Numerical winds
SET DATA monthly_navy_winds
! plot the raw data
SET REGION/X=40w/Y=40n
plot uwnd
! plot the 12 month climatology
LET uwnd_clim = uwnd[GT=month_reg@MOD]
PLOT uwnd_clim
! since uwnd_clim is on a climatological axis
! Ferret can also plot it on the calendar axis with the raw data
PLOT/T=16-jan-1982:17-dec-1992 uwnd,uwnd_clim
CONTOUR/X=0:360/Y=90s:90n sst_climatology[L=1]
to plot January from the climatology would require
Nx*Ny*Nt=72*72*576=3 Megawords of data. Such calculations may be too
large to fit into memory. However, if the region is fully specified
(as shown for the X and Y limits in the example) Ferret's internal
memory manager will break up the calculation as needed to produce the
result. (See Memory Use in the Ferret Users Guide for further details)
! define test_var, an illustrative variable with 1 year periodicity
! Note: test_var points are at the **beginnings** of months
DEFINE AXIS/T=1-jan-1970:1-jan-1974:`365.25/12`/UNITS=days t10years
DEFINE GRID/T=t10years gg
LET test_var = SIN(L[G=gg]*2*3.14/12)
! plot 4 years of the cycle
PLOT test_var
! define climatological axes at the midpoints of months
USE climatological_axes
CANC DATA climatological_axes
! notice that modulo regridding appears to shift the data
! (due to mis-aligned source and destination axes)
PLOT/OVER/T=1-jan-1970:1-jan-1974 test_var[GT=month_reg@MOD]
! to avoid the shift we can first regrid test_var to mid-month
! points using linear interpolation (the default regridding method)
! notice that the function test_var is largely unchanged by this
LET test_var_centered = test_var[GT=month_reg]
PLOT/OVER/T=1-jan-1970:1-jan-1974 test_var_centered
! finally perform a modulo regridding on well-aligned data
! notice that the shift is gone
PLOT/OVER/T=1-jan-1970:1-jan-1974 test_var_centered[GT=month_reg]
Back to Table of Contents
Back to Table of Contents
PLOT SIN(T[T=1-jan-1950:1-jan-2050:`30*24`]/1000)
Back to Table of Contents
LET/dataset=coads_climatology V_geostrophic = SLP[X=@DDC]/(F*RHO)
defined V_geostrophic only in data set coads_climatology. In other
data sets the name V_geostrophic may refer to file variables or it may
be given different definitions or it may be undefined. The data set
may be specified either by name as in this example or by number as
shown by SHOW DATA. Note that variables defined using
LET/dataset=[name_or_number] will be shown in the SHOW DATA output for
that data set as well as in SHOW VARIABLES.
LET/DATASET sst = temp[Z=0]
is issued then sst[D=levitus_climatology] will evaluate to
temp[D=levitus_climatology,Z=0] because the variable
sst does not exist in levitus_climatology, but
sst[D=coads_climatology] will refer to the file variable
name sst within the coads_climatology data set.
! Do not use memory-cached data when editing.
! Always reread the most recent version from the file.
SET MODE STUPID
! Save an exact copy of the original data for editing.
! We will call our edited file "new_etopo.cdf"
SET DATA etopo60
LET/D=etopo60 depth = rose
SET VARIABLE/TITLE="edited etopo depth"/UNITS=meters depth
SAVE/FILE=new_etopo.cdf depth
USE new_etopo.cdf
! "rose[d=etopo60]" is the original.
! "depth[d=new_etopo]" is the edited version.
! Redefine "depth[d=etopo60]" as a tool for for selective editing.
LET/D=etopo60 depth = rose[D=etopo60]-rose[D=etopo60] + correction
! An example edit: replace a small region with the value 500
LET correction = 500
SAVE/APPEND/FILE=new_etopo.cdf depth[D=etopo60,X=180:175w,Y=0:2n]
PLOT/X=160e:160w/Y=1n rose[D=etopo60], depth[D=new_etopo]
Back to Table of Contentskeyword=value
pairs inside the grave
accents following the immediate mode expression and set off by commas.
The recognized keywords are "BAD=" and
"PRECISION=". Only the first character of the keyword
is significant so they may be abbreviated as short as
"B=" and "P=".
PRECISION=, BAD= and
RESULT= may be specified simultaneously, in any order,
separated by commas. If RESULT= is included, however,
the other keywords will be ignored.
say `3/10,PRECISION=7`
will result in
0.3
instead of 0.3000000.
say `35501/100,P=-2`
will result in
355.01
instead of 355.
say `1/0,BAD=missing`
will result in
missing
or
say `1/0,B=-999`
will result in
-999
The size and shape information revealed by RESULT= is
useful in creating sophisticated scripts. For example, these lines
could be used to verify that the user has passed a 1-dimensional field
as the first argument to a script
say `SST[T=1-JAN-1983],RETURN=SHAPE`
will result in
XY
CAST
is a vertical profile with points
every 10 meters of depth starting at 10 meters then
say `CAST[Z=100:200],RETURN=KSTART`
will result in
10
say `CAST[Z=100:200],RETURN=KEND`
will result in
20
LET my_expr = $1
DEFINE SYMBOL SHAPE `my_expr,RESULT=SHAPE`
QUERY/IGNORE ($SHAPE%|X|Y|Z|T|<Expression must be 1-dimensional%)
Back to Table of Contents
($SHAPE%XY%)
($SHAPE%|X|Y|Z|T|%)
($SHAPE%|X>I|Y>J|Z>K|T>L|%)
($SHAPE%|X|Y|Z|T|*>other%)
will always result in "X","Y","Z","T", or "other".
($SHAPE%|*>The shape is *|%)
($SHAPE%|X|Y|Z|T|<Not a 1-dimensional shape%)
SET DATA coads_climatology
LIST/L=1/FORMAT=tab sst[X=170e:180,Y=5s:5n]
Back to Table of Contents
name title I J K L
TEMP TEMPERATURE 1:160 4:98 1:2 1:480
deg. C on grid PS3DT1 with -1.E+34 & 0 for missing data
X=130E:70W Y=23.2S:44.3N Z=0:20
Back to Table of Contents
yes? SHOW TRANSFORMS
variable transforms e.g.SST[T=1-jan:15-mar@DDC]
code description code description
---- ----------- ---- -----------
@ITP interpolated @SBX box smoothed
@AVE averaged @SBN binomial smoothed
@VAR variance @SWL Welch smoothed
@SUM summed @SHN Hanning smoothed
@RSU running sum @SPZ Parzen smoothed
@SHF shifted @FAV ave-filled
@MIN minimum @FLN linear-filled
@MAX maximum @FNR nearest-filled
@DDC centered derivative @NGD number of valid
@DDF forward derivative @NBD number flagged bad
@DDB backwards derivative @LOC location
@DIN integrated @WEQ weighted equal
@IIN indef. integ.
regridding transforms e.g.SST[GX=x5deg@AVE]
code description code description
---- ----------- ---- -----------
@LIN lin. interp. @NGD # gd pts
@AVE box avgd @MOD modulo ave
@NRS nearest @MODVAR modulo var
@ASN 1 to 1 @MODNGD # gd mod pts
@VAR variance @MODSUM modulo sum
@MIN minimum @MODMIN modulo min
@MAX maximum @MODMAX modulo min
@SUM sum
SET VARIABLE/BAD=xxx.xxx
will effect only the second of these, generally
having the effect of masking additional data without effecting the
original mask. Use SHOW DATA/VARIABLES to query the missing data
flag(s).
PLOT SIN(X[X=0:3.14:.1])
SAY ($PPL$XPIXEL)x($PPL$YPIXEL) ! ==> 809x698
SET WIND/NEW/SIZE=.3
SAY ($PPL$XPIXEL)x($PPL$YPIXEL) ! ==> 530x457
Back to Table of Contents
SAY Incredible\! What a message\! ! with a comment
SPAWN echo \`date\`
SAY Here is one line\; and here is another.
SAY \/qualifier is the syntax for command qualifiers
Instead the output of these commands looks like
Incredible! What a message!
Tue Feb 6 14:08:53 PST 1996
Here is one line; and here is another.
/qualifier is the syntax for command qualifiers
Back to Table of Contents
Back to Table of Contents SHADE/LEVELS=20 sst
It is not advised to exceed /LEVELS=200. SHADE/LEVELS=20C/PALETTE=light_centered UWND
which requests approximately 20 levels centered around zero. SHADE/LEVELS=2.5D SST
The "D" notation may be combined with the "C" notation as in
SHADE/LEVELS=2.5DC/PALETTE=light_centered uwnd
which requests levels centered around zero with a delta value
of 2.5
LIST/I=1:3 I[I=1:10]
in which it is not clear if the request is for 10 points or for 3,
or in subtler, disguised ways such as
LET A = I[I=1:10]
LIST/I=1:3 A
In both examples Ferret would resolve the conflict by listing just the
three values I=1:3.
LIST/I=11:13 I[I=1:10]
will result in a warning message that invalid limits have been ignored.
Fprint -X metafile.plt*
sequentially displays the metafiles with names matching "metafile.plt*",
pausing
after each for your decision to retain or delete the file. The default action
(upon carriage return) is to retain the displayed file. Enter 'y' to delete
it.
GO margins
.
Use
GO/HELP margins
for special instructions
regarding the PLOT command when plotting multiple variables.
GO/HELP stick_vectors
for on-line help.