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:
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 1SBack to Table of Contents
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
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.
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
DEFINE GRID/LIKE=sst[D=coads_climatology]/X=temp/Y=tempso that regridding occurs on the X and Y axes but the original grid structure is maintained with respect to depth and time.
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
SHADE SST[GX=175W:75W:10]Back to Table of Contents
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
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.
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
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.
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
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.
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.
! 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
In many cases the volume of input data needed to perform
climatological calculations is very large. In the example above the
command
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)
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
! 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
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,
PLOT SIN(T[T=1-jan-1950:1-jan-2050:`30*24`]/1000)Back to Table of Contents
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
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.
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/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.
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:
! 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 Contents
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
keyword=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=".
say `3/10,PRECISION=7`will result in
0.3instead of 0.3000000.
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
say `35501/100,P=-2`will result in
355.01instead of 355.
In the case of a negative precision value, Ferret will again drop terminating zeros to the right of the decimal point.
say `1/0,BAD=missing`will result in
missingor
say `1/0,B=-999`will result in
-999
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
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%)
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:
($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%)
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,
SET DATA coads_climatology LIST/L=1/FORMAT=tab sst[X=170e:180,Y=5s:5n]Back to Table of Contents
For example, the SHOW DATA/VAR output for the variable "TEMP" might appear as:
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:20Back to Table of Contents
The output of SHOW TRANSFORMS now displays
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
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.
SET VARIABLE/BAD=xxx.xxxwill 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).
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:
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) ! ==> 530x457Back to Table of Contents
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.
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 qualifiersInstead 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 qualifiersBack to Table of Contents
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.)
SHADE/LEVELS=20 sstIt is not advised to exceed /LEVELS=200.
SHADE/LEVELS=20C/PALETTE=light_centered UWNDwhich requests approximately 20 levels centered around zero.
SHADE/LEVELS=2.5D SSTThe "D" notation may be combined with the "C" notation as in
SHADE/LEVELS=2.5DC/PALETTE=light_centered uwndwhich requests levels centered around zero with a delta value of 2.5
Conflicting region information can be given to Ferret in obvious ways such as
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 AIn both examples Ferret would resolve the conflict by listing just the three values I=1:3.
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
LIST/I=11:13 I[I=1:10]will result in a warning message that invalid limits have been ignored.
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
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.
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 GO margins
.
Use
GO/HELP marginsfor special instructions regarding the PLOT command when plotting multiple variables.
GO/HELP stick_vectorsfor on-line help.