Document Actions
SET
Ref Sec31.
SET
Sets features of the operating environment for program Ferret.
Generally, features may be toggled on and off with SET and CANCEL. Features affected by SET may be examined with SHOW (See also CANCEL, and SHOW).
Ref Sec31.1.
/TYPE /OUTPUT /LIKE
Set or reset attribute characteristics for a variable and/or attribute. (See the section on access to dataset and variable attributes)
SET ATTRIBUTE/ TYPE=[float or string] varname.attname
yes? SET ATTRIBUTE/TYPE=float varname.attname
SET ATTRIBUTE/OUTPUT= varname[.attname] sets a flag for each attribute which determines whether it is written to output netCDF files. It can turn on writing of all or none of the attributes, or /OUTPUT=default gives the standard set of Ferret output attributes. It is applied as follows.
|
SET ATT/OUTPUT varname.attname |
Sets an individual attribute to be written when the variable is written |
|
SET ATT/OUTPUT=all varname |
Output all attributes that have been defined for a variable |
|
SET ATT/OUTPUT=default varname |
Write only the outputs that Ferret typically writes by default |
|
SET ATT/OUTPUT=none varname |
Output no attributes for the variable |
This causes all of the attributes from var2 to be copied to var1, removing all of the attributes of var1, and replacing them with the attributes and the output flags from var2.
Ref Sec31.2.
/MODULO /DEPTH /CALENDAR /T0 /UNITS /STRIDE /OFFSET
Set or resets characteristics of an existing axis.
Indicates that an axis is to be treated as a depth axis (graphics made with positive down).
yes? SET AXIS/DEPTH z_ax
Resets the calendar definition for a time axis.The allowed calendars are GREGORIAN, NOLEAP, JULIAN, 360_DAY, and ALL_LEAP. This qualifier is ignored if it is applied to a non-time axis. Applying this qualifier does not change the coordinates of the axis, but only their interpretation. For example, create an axis which is by default a Gregorian calendar axis, containing a leap day. Then reset it to a NOLEAP calendar. The coordinate values are the same but their interpretation as dates is changed.
yes? DEFINE AXIS/T=0:100:1/T0="1-JAN-2004 00:00:00"/UNITS=days tax
yes? LIST/L=58:62 T[GT=tax]
VARIABLE : T
axis TAX
SUBSET : 5 points (TIME)
27-FEB-2004 00 / 58: 57.00
28-FEB-2004 00 / 59: 58.00
29-FEB-2004 00 / 60: 59.00
01-MAR-2004 00 / 61: 60.00
02-MAR-2004 00 / 62: 61.00
yes? SET AXIS/CALENDAR=noleap tax
yes? LIST/L=58:62 T[GT=tax]
VARIABLE : T
axis TAX
SUBSET : 5 points (TIME)
CALENDAR : NOLEAP
27-FEB-2004 00 / 58: 57.00
28-FEB-2004 00 / 59: 58.00
01-MAR-2004 00 / 60: 59.00
02-MAR-2004 00 / 61: 60.00
03-MAR-2004 00 / 62: 61.00
Indicates that an axis is to be treated as a modulo axis (the first point "wraps" and follows the last point, as in a longitude axis). The optional modulo length is the length in axis units of the modulo repeat. If a length is specified, it may be longer than the axis span, so that the axis is treated as a subspan modulo axis. If it is not specified, the axis length is used as the modulo length. See the sections on modulo axes and subspan modulo axes for more information.
yes? SET AXIS/MODULO x_ax
yes? SET AXIS/MODULO/len=365.2425 days_axis
Indicates that the axis is to be treated everywhere it is used, with the stride specified. The stride value directs Ferret to use every nth point along the axis. If variables and grids from different data sets have this exact same axis, then the striding is applied for all those variables and grids. The striding may be cancelled with CANCEL AXIS/STRIDE. See the discussion of netCDF strides.
This qualifier is valid only if /STRIDE= is also specified. Otherwise it is ignored. The value of the offset the delta from the first index value, so that /OFFSET=0 means start at index=1, and
yes? SET AXIS/STRIDE=5/OFFSET=2 my_x_axis
is equivalent to this old stride syntax
yes? LET new_var = old_var[i=3:1000:5]
The stride syntax var[i=start:end:delta] is also still valid.
Example:
! Open a dataset with the time axis representing monthly data starting in January
! Set strides so that we pick out every December.
yes? use my_monthly_data
yes? SET AXIS/STRIDE=12/OFFSET=11 `var,RETURN=taxis`
yes? LIST/L=1:10 var
VARIABLE : SST[X=300:330@AVE,Y=10:20@AVE]
DATA SET : COADS 2x2 Degree Monthly Average Surface Marine Observations
FILENAME : coads.cdf
FILEPATH : /home/shiva/data/
SUBSET : 10 points (TIME)
LONGITUDE: 60W to 30W
LATITUDE : 10N to 20N
DEC-1946 / 1: 26.73
DEC-1947 / 2: 26.06
DEC-1948 / 3: 26.13
DEC-1949 / 4: 26.26
DEC-1950 / 5: 26.62
DEC-1951 / 6: 26.30
DEC-1952 / 7: 26.85
DEC-1953 / 8: 26.53
DEC-1954 / 9: 25.58
DEC-1955 / 10: 26.64
Sets, or resets, the time origin of a time axis.
yes? SET AXIS/T0="1-JAN-1990" t_ax
yes? SET AXIS/T0="15-MAR-1950 12:00:00" timeax
If the axis is not a time axis, this qualifier is ignored. Applying this qualifier does not change the coordinates of the axis, but only their interpretation. If /T0 is applied to an axis that did not previously have a time origin, the axis will become a calendar-formatted axis, with time coordinates automatically translated into date/time strings on listings, and formatted time axes on plots.
Sets, or resets, the units of an axis.
yes? SET AXIS/UNITS=days t_ax
yes? SET AXIS/UNITS=meters xax
Applying this qualifier does not change the coordinates of the axis, but only their interpretation. UNITS are expressed as a string and are converted according to the usual rules for Ferret axes, see the description of units under DEFINE AXIS
Ref Sec31.3.
/EZ /VARIABLE /TITLE /FORMAT /GRID /SKIP /COLUMNS /SAVE /RESTORE /ORDER /TYPE /SWAP /REGULART/DELIMITED
SET DATA/EZ /COLUMNS /FORMAT /GRID /SKIP /TITLE /VARIABLE
Specifies ASCII, binary, netCDF, GT, or TS-formatted data set(s) to be analyzed.
1) ASCII or binary:
yes? SET DATA/EZ[/qualifiers] data_set1, data_set2, …
or equivalently, with alias FILE:
yes? FILE[/qualifiers] data_set1, data_set2, ...
2) netCDF:
yes? SET DATA/FORMAT=cdf netCDF_file
or equivalently, with alias USE
yes? USE netCDF_file
or for a netCDF dataset on a DODS server,
yes? use "http://www.ferret.noaa.gov/cgi-bin/nph-nc/data/coads_climatology.nc"
3) GT or TS-formatted:
yes? SET DATA data_set1, data_set2, ...
In the case of GT or TS-formatted files, an extension of .des is assumed. A previously SET data set can be SET by its reference number, as shown by SHOW DATA, rather than by name.
If a Unix filename includes a path (with slashes) then the full path plus name must be enclosed in double quotation marks.
yes? use "/home/mydirectory/mydata/new_salinity.cdf"
If the filename begins with a numeric character, Ferret does not recognize the file, but it can be specified using the Unix pathname, e.g.
yes? use "./123"
or
yes? file/var=a "./45N_180W.dat"
Note: Maximum simultaneous data sets: 30 (as of Ferret ver. 5.41). Use CANCEL DATA if the limit is reached.
Command qualifiers for SET DATA_SET:
Specifies the format of the data set(s) being SET. Allowable values for "file_format" are "cdf", "delimited", "free", "stream", "unformatted", or a FORTRAN format in quotation marks and parentheses.
yes? SET DATA/FORMAT=file_format [data_set_name_or_number]
Valid arguments for /FORMAT=
1) SET DATA/FORMAT=free (default for SET DATA/EZ)
To use the format "free" a file must consist entirely of numerical data separated by commas, blanks or tabs.
2) SET DATA/FORMAT=cdf
If SET DATA/FORMAT=cdf (alias USE) is used, the data file must be in CDF format. The default filename extension is ".cdf", or ".nc"
Example:
yes? SET DATA/FORMAT=CDF my_netcdf
or equivalently,
yes? USE my_netcdf
See the chapter "Data Set Basics", section "NetCDF data."
Command qualifiers for SET DATA_SET/FORMAT=CDF:
SET DATA /FORMAT=CDF /ORDER=<permutation> /REGULART
The permutation argument contains information both about the order of the axes in the file and the direction.
The order indicated through the /ORDER qualifier should always be exactly the reverse of the order in which the dimensions of variables as revealed by the netCDF ncdump -h command are declared. (This ambiguity reflects the linguistic difference between "C ordering" and "FORTRAN ordering". The default X-Y-Z-T ordering used in the COARDS standard and in Ferret documentation would be referred to as T-Z-Y-X ordering if we used C terminology.)
Thus, to USE a file in Ferret in which the data on disk transposes the X and Y axes we would specify
USE/ORDER=YX my_file.nc
To use a file in which the data were laid down in XZ "slabs", such as might occur in model outpus we would specify
USE/ORDER=XZYT my_model.nc
To indicate that the coordinates along a particular axis are reversed from the "right hand rule" ordering, for example a Y axis which runs north to south (not uncommon in image data), we would precede that axis by a minus sign. For example
USE/ORDER=X-Y my_flipped_images.nc
The minus sign should be applied to the axis position **after** transposition. Thus if a file both transposed the XY axis ordering and used north-to-south ordering in latitude one would access the file with
USE/ORDER=Y-X my_transposed_flipped_images.nc
NetCDF files, while in principle self-documenting, may be contain axis ambiguities. For example, a file which is supposed to contain a time series, but lacks units on the coordinate variable in the file may appear to be a line of data on the X axis. The /ORDER qualifier can be used to resolve these ambiguities. For this example, one would initialize the file with the command
USE/ORDER=T my_ambiguous_time_series.nc
Notes for USE/ORDER:
a) Note that specifying USE/ORDER=XYZT is not always equivalent to specifying default ordering. For example, if a netCDF file contained variables on an XYT grid, the /ORDER=XYZT specifaction would tell Ferret to interpret it as an XYZ grid.
b) Also note, the /ORDER qualifier will be ignored if either the file is not netCDF, or the file is netCDF but has an "enhanced" header (see SAVE/HEADING=enhanced)
Speeds initialization of large netCDF data sets with known regular time axes. When Ferret initializes a netCDF file (the SET DATA/FORMAT=cdf command or the USE command alias), it checks for the attribute point_spacing = "even" on the time axis. If found, Ferret knows that the coordinates are evenly spaced and reads only the first and last coordinate on the axis to obtain a complete description. If not found, Ferret must read the full list of coordinates -- a time-consuming procedure for very large files. After reading the coordinates, Ferret determines if they are regular. The /REGULART qualifier instructs Ferret to treat the time axis as regular regardless of the presence or absence of a point_spacing attribute in the file, speeding up the initialization time on files lacking point_spacing, but known to be regular. If the file happens to contain a bounds attribute on the time axis, and /REGULART is specified, then the bounds are ignored.
Note that when writing netCDF files Ferret, by default, does NOT include the point_spacing attribute. This is because Ferret's default file characteristic is to be append-able, with no guarantees that the appended time steps will be regularly spaced. For output files of fixed length with regular time steps it is advisable to use the SAVE/RIGID qualifier. This allows Ferret to include the point_spacing="even" attribute. If the files will be very large (too large for the full time range to be in memory), then use the /RIGID/TLIMITS= qualifiers to specify the full, ultimate fixed size and use SAVE/APPEND to insert data into the file piecemeal.
If the file has the bounds attribute for the record axis (files written with Ferret version 5.70 and after include the bounds attribute for all irregular axes), then we can append further timesteps to the file and keep the correct point spacing. If there is a gap between the last time in the existing file and the first time being appended, Ferret adds a void point, consisting of missing data, centered on the interval between the upper cell bound of the time axis in the file and the lower cell bound of the new data being written.
3) SET DATA/FORMAT=UNFORMATTED
To use the format "unformatted" the data must be floating point, binary, FORTRAN-style records with all of the desired data beginning on 4-byte boundaries. This option expects 4 bytes of record length information at the beginning and again at the end of each record. The "-" designator ( /VARIABLES) can be used to skip over unwanted 4-byte quantities (variables) in each record. See the chapter "Data Set Basics", section Binary data.
4) SET DATA/FORMAT=FORTRAN format string
FORTRAN format specifications should be surrounded by parentheses and enclosed in quotation marks. Integer format is not supported by Ferret; to read integer data use, for instance, FILE/FORMAT=(f5.0). See also Reading "delimited" files for reading string data or data with dates which have mixed string and numeric information.
The format specified is for reading each record; it cannot be used to specify the total number of values read. That is determined by the grid for the variables. The grid is by default an abstract axis of length 20408, or it may be set explicitly using DEFINE AXIS, DEFINE GRID and SET DATA/GRID= commands.
Example:
yes? SET DATA/EZ/FORMAT="(5X,F12.0)" my_data_set ! or equivalently,
yes? FILE/FORMAT="(5X,F12.0)" my_data_set
5) SET DATA/FORMAT=STREAM
/FORMAT=stream is used to indicate that a file contains either unstructured binary output (typical of C program output) or fixed-length records suitable for direct access (all records of equal length, no record length information embedded in the file). With caution it is also possible to read FORTRAN variable-length record output. This sort of file is typically created by "quick and dirty" FORTRAN code which uses the simplest FORTRAN OPEN statement and outputs entire variables with a single WRITE statement.
This format specifier allows you to access any contiguous stretch of 4-byte values from the file. The /SKIP=n qualifier specifies how many values should be skipped at the file start. The /GRID=name qualifier specifies the grid onto which the data should be read and therefore the number of values to be read from the file (the number of points in the grid). Note that an attempt to read more data than the file contains, or to read record length information, will result in a fatal FORTRAN error on UNIX systems and will crash the Ferret program.
For multiple variables, use the /COLUMNS=n specifier to specify how many 4-byte values separate each variable in the file. Each variable is assumed to represent a contiguous stream of values within the file and all variables are assumed to possess the same number of points. (A "poor man's method" is to create multiple Unix soft links pointing to the same file and multiple SET DATA/EZ commands to specify one variable from each link name.)
See the chapter "Data Set Basics", section Binary data for further discussion and examples of binary types. Also see the section below under SET DATA/TYPE for a list of the data types that may be read using SET DATA/FORMAT=STREAM
SET DATA/FORMAT=DELIMITED[/DELIMITERS=][/TYPE=][/VAR=] filename
Initializes a file of mixed numerical, string, and date fields. If the data types are not specified the file will be analyzed automatically to determine data types. Using delimited files, the number of variables that can be read from a single file is increased from 20 to 100.
The alias COLUMNS stands for "SET DATA/FORMAT=DELIMITED"
/DELIMITER - list of field delimiters. Default is tab or comma. You can list any ascii character. For example, if fields are delimited with X and also with tabs and commas, use /DELIM="X,\t,\,". Special characters include
- \b - blank
- \t - tab
- \n - newline
- \nnn - decimal value from ASCII table
/TYPE is the list of data types of the fields. Field types may be any of
- "-" - skipped
- NUMERIC
- TEXT
- LATITUDE - e.g. 87S or 21.5N (interpreted as negative or positive, respectively)
- LONGITUDE - e.g. 160W or 30E (interpreted as negative or positive, respectively)
- DATE - e.g. mm/dd/yy or mm/dd/yyyy or yyyy-mm-dd or yyyymmdd - value returned is days from 1-jan-1900 (consistent with the DAYS1900 function)
- EURODATE - e.g. dd/mm/yy or dd/mm/yyyy or yyyy-mm-dd TIME - e.g. hh:mm or hh:mm:ss.s/
See the section on delimited files in the Data Set Basics chapter "Reading Delimited Data" for examples.
Restores the current default data set number that was saved with SET DATA/SAVE.
This is useful in creating GO files that perform their function and then restore Ferret to its previous state.
Saves the current default data set number so it can be restored with SET DATA/RESTORE.
This is useful in creating GO files that perform their function and then restore Ferret to its previous state.
Associates a title with the data set.
yes? SET DATA/EZ/TITLE="title string" file_name
yes? USE/TITLE="pmel data set" "http://www.ferret.noaa.gov/cgi-bin/nph-nc/data/coads_climatology.nc"
For EZ, netCDF, or DODS datasets, set a title. This title appears on plotted outputs at the top of the plot.
Accesses data from an ASCII or unformatted file that is not in a standardized format (TMAP or netCDF). The command FILE is an alias for SET DATA/EZ.
yes? SET DATA/EZ[/qualifiers] ASCII_or_binary_file ! or, equivalently,
yes? FILE[/qualifiers] ASCII_or_binary_file
Example:
yes? FILE/VARIABLE=my_var my_data.dat
See the chapter "Data Set Basics", section ASCII data for more information and examples. Used on its own, SET DATA/EZ/VAR= uses a default axis length which may be shorter than the size of your data. If this is the case, use DEFINE AXIS and DEFINE GRID commands, and FILE/GRID= to read your data, as discussed in the "Data Set Basics" chapter.
Command qualifiers for SET DATA_SET/EZ:
Specifies the number of columns in the EZ data file.
By default the number of columns is assumed to be equal to the number of variables (including "-"'s) specified by the /VARIABLES qualifier.
Specifies the defining grid for the data in the data set. The argument can be the name of a grid or the name of a variable that is already defined on the desired grid.
Example:
yes? SET DATA/EZ/GRID=sst[D=coads] snoopy
This is the mechanism by which the shape of the data (1D along T axis, 2D in the XY plane, etc.) is specified. See also the examples in the section Reading ASCII files. By default Ferret uses grid EZ, a line of up to 20480 points oriented along the X axis.
Specifies the number of records to skip at the start of a data set before beginning to read the data. By default, no records are skipped.
For ASCII files a "record" refers to a single line in the file (i.e., a newline character). If the FORMAT statement contains slash characters the "data record" may be multiple lines; the /SKIP qualifier is independent of this fact.
For FORTRAN-structured binary files the /SKIP argument refers to the number of binary records to be skipped.
For unstructured (stream) binary files (e.g., output of a C program) the /SKIP argument refers to the number of words (4-byte quantities) to skip before reading begins.
Stream files only. Change the byte ordering of numbers read from the file; big-endian numbers are converted to little-endian numbers and vice versa.
SET DATA/TYPE=
For ASCII delimited files, /TYPE specifies the type of each variable to be read (see SET DATA/FORMAT=DELIMITED). For unstructured (stream) binary files (see SET DATA/FORMAT=STREAM), /TYPE specifies the data type of a set of variables in the file. For stream files, the available values and their corresponding types are:
yes? SET DATA/EZ/FORMAT=STREAM/TYPE=14,R4/VAR=V1,V2 foobar.dat
will read a file containing INTEGER*4 and REAL*4 numbers into the variables v1 and v2.
Names the variables of interest in the file. Default is v1.
yes? FILE/VARIABLES="var1,var2,..." file_name
Except in the case of /FORMAT=stream, Ferret assumes that successive values in the data file represent successive variables. For example, if there are three variables in a file, the first value represents the first variable, the second represents the second variable, the third the third variable, and the fourth returns to representing the first variable. The maximum number of variables allowed in a single free-formatted data set is 20. See SET DATA/FORMAT=DELIMITED for reading from a delimited file.
Variable names may be 1 to 24 characters (letters, digits, $, and _) beginning with a letter. To indicate a column is not of interest use "-" for its name.
Example: (the third column of data will be ignored)
yes? SET DATA/VARIABLES="temp,salt,-,u,v" ocean_file.dat
Specifies the order (ORDER=permutation) in which axes are to be read. This qualifier does NOT work for delimited files (SET DATA/FORMAT=delimited). For netCDF files there are additional options for this qualifier; see SET DATA/FORMAT=CDF/ORDER.
Examples:
yes? FILE/ORDER=XY sst ! X varies fastest
yes? LIST/ORDER=YX sst ! Y varies fastest
The "permutation" string may be any permutation of the letters X, Y, Z, and T. If the /format=stream qualifier is used, the string may also contain V (for variable). This allows variables to be "interleaved."
Ref Sec31.4.
SET EXPRESSION
Specifies the default context expression. When Ferret's "action" commands (PLOT, CONTOUR, SHADE, VECTOR, WIRE, etc.) are issued with no argument, the default context expression is used. This is the expression last used as argument to an action command, or it may be set explicitly with SET EXPRESSION. See the chapter "Variables and Expressions", section Expressions for a full list of action commands.
yes? SET EXPRESSION expr1 , expr2 , ...
Examples:
1) yes? SET EXPRESSION temp
Sets the current expression to "temp".
2) yes? SET EXPRESSION u , v , u^2 + v^2
Set the current expressions to "u , v , u^2 + v^2"
Ref Sec31.5.
SET GRID
/RESTORE /SAVE
Specifies the default grid for abstract expressions. Type GO wire_frame_demo at the Ferret prompt for an example of usage.
yes? SET GRID[/qualifier] [grid_or_variable_name]
Examples:
yes? SET GRID sst[D=coads]
yes? SET GRID ! use grid from last data accessed
See the chapter "Grids and Regions", section Grids.
Command qualifiers for SET GRID:
Restores the current default grid last saved by SET GRID/SAVE. Useful together with SET GRID/SAVE to create GO files that restore the state of Ferret when they conclude.
Saves the current default grid to be restored later. Useful together with SET GRID/RESTORE to create GO files that restore the state of Ferret when they conclude.
When using curvilinear data, call the script mp_grid varnam.jnl" to associate the grid with the map region.
Example:
yes? use coads_climagoloty
yes? set region/x=40e:110e/y=60s:20s/L=6
yes? go mp_stereographic_north
yes? go mp_aspect
yes? go mp_grid
yes? shade/noaxes sst, x_page, y_page
Ref Sec31.6.
SET LIST
/APPEND /FILE /FORMAT /HEADING /PRECISION
Uses SET LIST to specify the default characteristics of listed output.
yes? SET LIST/qualifiers
The state of the list command may be examined with SHOW LIST. See commands "CANCEL LIST" and "LIST".
"Command qualifiers for SET LIST:
Specifies that by default the listed output is to be appended to a pre-existing file. Cancel this state with CANCEL LIST/APPEND.
Specifies a default file for the output of the LIST command.
yes? SET LIST/FILE=filename
The filename specified in this way is a default only. It will be used by the command
yes? LIST/FILE variable
but will be ignored in
yes? LIST/FILE=snoopy.dat variable
Ferret generates a filename based on the data set, variable, and region if the filename specified is "AUTO". The resulting name is often quite long but may be shortened by following "AUTO" with a minus sign and the name(s) of the axes to exclude from the filename.
Note: the region information is not used in automatic netCDF output filenames.
Examples:
yes? SET LIST/FILE=AUTO
yes? LIST/L=500/X=140W:110W/Y=2S:2N/FILE sst[D=coads]
Sends data to file WcoadsSST.X140W110WY2S2NL500.
yes? SET LIST/FILE=AUTO-XY
yes? LIST/L=500/X=140W:110W/Y=2S:2N/FILE sst[D=coads]
Sends data to file WcoadsSST.L500.
Specifies an output format for the LIST command. (When a FORTRAN format is specified the row and column headings are omitted from the output.)
yes? SET LIST/FORMAT=option
yes? SET LIST/FORMAT !reactivate previous format
|
Options |
|
|
FORTRAN format |
produces ASCII output |
|
"UNFORMATTED" |
produces unformatted (binary) output |
|
"CDF" |
produces netCDF output |
|
"GT" |
produces TMAP GT format |
Examples:
1) yes? SET LIST/FORMAT=(1X,12F6.1)
Specifies a FORTRAN format (without row or column headings).
2) yes? SET LIST/FORMAT=UNFORMATTED
Specifies binary output. (FORTRAN variable record length record structure.)
Notes:
- When using GT format all variables named in a single LIST command will be put into a single GT-formatted timestep.
- Very limited error checking will be done on FORTRAN formats.
- FORTRAN formats are reused as necessary to output full record.
- Latitude axes are listed south to north when /FORMAT is specified.
Specifies that ASCII output is to be preceded by a heading that documents data set, variable, and region. Cancel the heading with CANCEL LIST/HEAD.
Specifies the data precision (number of significant digits) of the output listings. This qualifier has no effect when /FORMAT= is specified.
yes? SET LIST/PRECISION=#_of_digits
Note that this controls only the output precision of the data. and that in fact at most 7 digits are significant since Ferret calculations are performed in single precision.
Ref Sec31.7.
SET MEMORY
/SIZE
yes? SET MEMORY/SIZE=megawords
The command SET MEMORY provides control over how much "physical" memory Ferret can use. (In reality the distinction between physical and virtual memory is invisible to Ferret. The SET MEMORY command merely dictates how much memory Ferret can attempt to allocate from the operating system.)
SET MEMORY controls only the size of Ferret's cache memory—memory used to hold intermediate results from computations that are in progress and used to hold the results of past file IO and computations for re-use. The default size of the memory cache is 25.6 megawords (equivalently,25.6×4=102.4 megabytes). Cache memory size can be set larger or smaller than this figure.
Example:
yes? SET MEMORY/SIZE=100
Sets the size of Ferret's memory cache to 100 million (4-byte) words.
Notes:
- As a practical matter memory size should not normally be set larger than the physical memory available on the system. If Ferret is unable to allocate the requested memory, it will return an error message.
- The effect of SET MEMORY/SIZE= is identical to the "-memsize" qualifier on the Ferret startup command line.
- See SET MODE DESPERATE and MEMORY USAGE in this users guide for further instructions on setting the memory cache size appropriately.
- Using the SET MEMORY command automatically resets the value of SET MODE DESPERATE to a default that is consistent with the memory size.
- The effects of SET MEMORY/SIZE last only for the current Ferret session. Exiting Ferret and restarting will reset the memory cache to its default size.
- If memory is severely limited on a system Ferret's default memory cache size may be too large to permit execution. In this case use the "-memsize" qualifier on the command line to specify a smaller cache.
- To set the amount of memory every time you start Ferret, add a SET MEMORY/SIZE= command to your .ferret startup file
Ref Sec31.8.
/LAST
Specifies special operating modes or states for program Ferret.
yes? SET MODE[/LAST] mode_name[:argument]
|
|
|
Default |
|
ASCII_FONT |
imposes PPLUS ASCII font types on plot labels |
set |
|
CALENDAR |
uses date strings for T axis (vs. time step values) |
set |
|
DEPTH_LABEL |
uses "DEPTH" as Z axis label |
set |
|
DESPERATE |
attempts calculations too large for memory |
canceled |
|
DIAGNOSTIC |
turns on internal program diagnostic output |
canceled |
|
GRATICULE |
sets drawing of graticule lines on all subsequent plots |
cancelled |
|
GUI |
unsupported; used in GUI development |
|
|
IGNORE_ERROR |
continues command file after errors. On an error, the |
canceled |
|
INTERPOLATE |
automatically interpolates data between planes |
canceled |
|
JOURNAL |
records keyboard commands in a journal file |
set |
|
LATIT_LABEL |
uses "N" "S" notation for labeling latitudes |
set |
|
LINECOLORS |
reset number of line colors from the default of 6 |
set |
|
LONG_LABEL |
uses "E" "W" notation for labeling longitudes |
set |
|
METAFILE |
captures graphics in GKS metafiles |
canceled |
|
NLEVELS |
reset default number of contour or color levels for contour, color fill or shade plots, default 30 |
set |
|
NODATA_LAB |
controls whether NO VALID DATA is written across plots. Cancel to leave such plots blank. |
set |
|
PPLLIST |
listed output from PPLUS is directed to the named file |
canceled |
|
REFRESH |
refreshes graphics on systems lacking "backing store" |
canceled |
|
SEGMENT |
utilizes GKS segment storage |
set |
|
STUPID |
controls cache hits in memory (diagnostic) |
canceled |
|
UPCASE_OUTPUT |
controls whether variable and axis names are upcased on output |
set |
|
VERIFY |
displays each command file line as it is executed |
set |
|
WAIT |
waits for carriage return after each plot |
canceled |
Command qualifiers for SET MODE:
Resets mode to its last state.
yes? SET MODE/LAST mode_name
Example: (a command file that will not alter Ferret modes)
yes? CANCEL SYMBOL fer_last_error ! we will check for any errors in this block of code
yes? SET MODE IGNORE_ERRORS ! 1st line of command file
.
!. ... code which may encounter errors
.
yes? SET MODE/LAST IGNORE_ERRORS ! last line of command file
yes? ! After a block of code, see the last error encountered, if any
yes? IF ($fer_last_error"0|*>1") THEN SHOW SYMBOL fer_last_error
Ref Sec31.8.1.
The SET MODE ASCII_FONT command causes program Ferret to precede plot labels with the PPLUS font descriptor "@AS" (ASCII SIMPLEX font). This assures that special characters (e.g., underscores) are faithfully reproduced. For special plots it may be desirable to use other fonts (e.g., to obtain subscripts). CANCEL MODE ASCII_FONT is for these cases.
default state: set
Ref Sec31.8.2.
SET MODE CALENDAR causes program Ferret to output times in date/time format (instead of time axis time step values). This affects both plotted and listed output.
This mode accepts an optional argument specifying the degree of precision for the output date. If the argument is omitted the precision is unchanged from its last value.
default state: set (argument: minutes)
Arguments
SET MODE CALENDAR accepts the following arguments:
|
Argument |
Equivalent precision |
|
SECONDS |
-6 |
|
MINUTES |
-5 (default) |
|
HOURS |
-4 |
|
DAYS |
-3 |
|
MONTHS |
-2 |
|
YEARS |
-1 |
The argument is uniquely identified by the first two characters.
Example:
yes? SET MODE CALENDAR:DAYS
Causes times to be displayed in the format dd-mmm-yyyy.
When CALENDAR mode is canceled the "equivalent" in the table above determines the precision of the time steps displayed exactly as in SET MODE LONGITUDE.
Ref Sec31.8.3. SET MODE DEPTH_LABEL
SET MODE DEPTH_LABEL causes Ferret to label Z coordinate information in the units of the Z axis. This affects both plotted and listed output. This mode accepts an optional argument specifying the degree of precision for the output. If the argument is omitted the precision is unchanged from its last value.
yes? SET MODE DEPTH:argument
default state: set (argument: -4)
Arguments
See the example under "SET MODE LONG" for a detailed description of precision control.
Ref Sec31.8.4.
Ferret checks the size of the component data required for a calculation in advance of performing the calculation. If the size of the component data exceeds the value of the MODE DESPERATE argument Ferret attempts to perform the calculation in pieces.
For example, the calculation "LIST/I=1/J=1 U[K=1:100,L=1:1000@AVE]" requires 100*1000=100,000 points of component data although the result is only a line of 100 points on the K axis. If 100,000 exceeds the current value of the MODE DESPERATE argument Ferret splits this calculation into smaller sized chunks along the K axis, say, K=1:50 in the first chunk and K=51:100 in the second.
Ferret is also sensitive to the performance penalties associated with reading data from the disk. Splitting the calculation along axis of the stored data records can require the data to be read many times in order to complete the calculation. Ferret attempts to split calculations along efficient axes, and will split along the axis of stored data only in desperation, if MODE DESPERATE is SET.
Example:
yes? SET MODE DESPERATE:5000
default state: canceled (default argument: 80000)
Note: Use MODE DIAGNOSTIC to see when splitting is occurring.
Arguments
Use SHOW MEMORY/FREE to see the total memory available (as set with SET MEMORY/SIZE).
Whenever the size of memory is set using SET MEMORY the MODE DESPERATE argument is reset at one tenth of memory size. For most purposes this will be an appropriate value. The user may at his discretion raise or lower the MODE DESPERATE value based on the nature of a calculation. A complex calculation, with many intermediate variables, may require a smaller value of MODE DESPERATE to avoid an "insufficient memory" error. A simple calculation, such as the averaging operation described above, will typically run faster with a larger MODE DESPERATE value. The upper bound for the argument is the size of memory. The lower bound is "memory block size."
Ref Sec31.8.5.
SET MODE DIAGNOSTIC
SET MODE DIAGNOSTIC causes Ferret to display diagnostic information in real time about its internal functioning. It is intended to help Ferret developers diagnose performance problems by displaying what the Ferret memory management subsystem is doing. The message "strip gathering on xxx axis" indicates that Ferret has broken up a calculation into smaller pieces. Subsequent "strip" and "gathering" messages indicate that sub-regions of the calculations are being processed and brought together.
default state: canceled
See the FAQ, How do I interpret the output of "SET MODE DIAGNOSTIC? for help interpreting the output.
Ref Sec31.8.6.
SET MODE GRATICULE
SET MODE GRATICULE turns on plotting of graticule lines at the tic marks of both the horizontal and vertical axes of all subsequent plots. In effect this is equivalent to specifying the GRATICULE qualifier for all plot commands. See documentation of the /GRATICULE qualifier with the various plot commands, for instance PLOT/GRATICULE. You may specify line types with SET MODE GRATICULE:(type) where type is color, dash, or thickness
Examples:
yes? SET MODE GRATICULE
yes? SET MODE GRATICULE:(color=red)
yes? SET MODE GRATICULE:(dash,color=blue)
yes? SET MODE GRAT:"LARGE(COLOR=blue),SMALL(COLOR=lightblue)"
Currently, dash types cannot be customized, as they can for PLOT/DASH. Look for this in a future release of Ferret.
Ref Sec31.8.7.
SET MODE IGNORE_ERROR
SET MODE IGNORE_ERROR causes Ferret to continue execution of a command file despite errors encountered. When an error is encountered (regardless of the setting of this mode) a symbol FER_LAST_ERROR is set containing the text that is output to standard error. See an example using MODE IGNORE_ERROR.
default state: canceled
Ref Sec31.8.8.
SET MODE INTERPOLATE
Note: The transformation @ITP provides the same functionality as MODE INTERPOLATE with a greater level of control.
SET MODE INTERPOLATE affects the interpretation of world coordinate specifiers (/X, /Y, /Z, and /T) in cases where the position is normal to the plane in which the data is being examined. When this mode is SET and a world coordinate is specified which does not lie exactly on a grid point, Ferret automatically interpolates from the surrounding grid point values. When this mode is canceled, the same world coordinate specification is shifted to the grid point of the grid box that contained it before computations were made (see examples).
default state: canceled
Example:
If the grid underlying the variable temp has points defined at Z=5 and at Z=15 (with the grid box boundary at Z=10) and data is requested at Z=12 then
yes? SET MODE INTERPOLATE
yes? LIST/T=18249/X=130W:125W/Y=0:3N/Z=12 temp
lists temperature data in the X-Y plane obtained by interpolating between the Z=5 and Z=15 planes. Whereas,
yes? CANCEL MODE INTERPOLATE
yes? LIST/T=18249/X=130W:125W/Y=0:3N/Z=12 temp
lists the data at Z=15. The output documentation always reflects the true location used.
Ref Sec31.8.9.
SET MODE LABELS
SET MODE LABELS restores the default behavior of labeling, if CANCEL MODE LABELS has been issued. CANCEL MODE LABELS implements the /NOLABELS qualifier for all plots after it has been set.
Ref Sec31.8.10.
SET MODE LOGO
SET MODE LOGO turns on the Ferret logo (three lines at the upper right of plots), if it has been turned off by CANCEL MODE LOGO
Ref Sec31.8.11.
SET MODE JOURNAL causes Ferret to record all commands issued in a journal file. Output echoed to this file may be turned on and off via mode JOURNAL at any time.
default state: set
Example:
yes? SET MODE JOURNAL:my_journal_file.jnl
The optional argument to MODE JOURNAL specifies the name of the output journal file—with no argument, the default name "ferret.jnl" is used. Journal files for successive Ferret sessions are handled by version number. See the chapter "Computing Environment", section "Output file naming".
Ref Sec31.8.12.
SET MODE LATIT_LABEL causes Ferret to output latitude coordinate information in degrees N/S format (instead of the internal latitude coordinate). This affects both plotted and listed output.
This mode accepts an optional argument specifying the degree of precision for the output. If the argument is omitted the precision is unchanged from its last value.
Example:
yes? SET MODE LAT:2
default state: set (argument: 1)
Arguments
See the example under "SET MODE LONG" for a detailed description of precision control.
Ref Sec31.8.13.
SET MODE LONG_LABEL causes Ferret to output longitude coordinate information in degrees E/W format (instead of the internal longitude coordinate). This will affect both plotted and listed output.
This mode accepts an optional argument specifying the degree of precision for the output. If the argument is omitted the precision will be unchanged from its last value.
Example:
yes? SET MODE LONG:2
default state: set (argument: 1)
Arguments
The argument of SET MODE LONG is an integer specifying the precision. If the argument is positive or zero it specifies the maximum number of decimal places to display. If the argument is negative it specifies the maximum number of significant digits to display.
Examples:
Suppose the longitude to be displayed is 165.23W. Then
yes? SET MODE LONG:1 will produce 165.2W
yes? SET MODE LONG:-3 will produce 165W
When LONG mode is canceled the argument still determines the output precision.
Ref Sec31.8.13b.
SET MODE LINECOLORS
SET MODE LINECOLORS allows for a new number of colors for plot lines to be set. The default is 6.
The new number of LINECOLORS will take effect on the next new plot window (or on the first window if no plots have been drawn yet in the session). If plots have already been drawn, Ferret will issue a NOTE indicating that the new number of colors will takes effect after the command SET WINDOW/NEW.
The first 6 colors are always defined. Further colors are initially grey; these colors as well as the first 6 may be redefined using the PPL COLOR command.
yes? SET MODE LINECOLORS:8
*** NOTE: New # of line colors will take effect on next new window: SET WIN/NEW then define pen colors
yes? SET WINDOW/NEW
yes? PPL COLOR,7,100,50,0 ! orange
yes? PPL COLOR,8,60,0,100 ! purple
See the example in the chapter on Customizing Plots.
Note that once you have defined new colors, they can be used for axes, text, and graticule lines as well as for plotting lines of data.
Example: Here we use a seventh color, leaving it defined as gray. Use this color for graticule lines.
yes? SET MODE LINECOLORS:7
yes? USE etopo60
yes? FILL/GRATICULE=[DASH,COLOR=7,THICKNESS=1] rose
MODE LINECOLORS cannot be canceled; issuing the command CANCEL MODE LINECOLORS will reset the number back to 6.
Ref Sec31.8.14.
SET MODE METAFILE causes Ferret to capture all graphics in metafiles. These metafiles can later be routed to various devices to obtain hard copy output or postscript files.
The optional argument to MODE METAFILE specifies the name of the output metafile—with no argument, the default name "metafile.plt" is used. Multiple output files (i.e., successive plots) are handled by version number. See the chapter "Computing Environment", section "Output file naming"
See the chapter "Computing Environment", section "Hard copy)" for details on generating graphics files and hard copy.
Example:
yes? SET MODE METAFILE:june_sst.plt
default state: canceled (default argument when set: "metafile.plt")
Ref Sec31.8.15.a
SET MODE NLEVELS
Sets the initial number of contour/color levels that will be used when computing automatic contour levels. Previously this value was always 10. If you are drawing just color plots without contour lines, 40 is a good value to use; if you often use contour lines or FILL/LINE, then a smaller number will look good.
Example:
yes? SET MODE NLEVELS 40
yes? SET MODE/LAST nlevels ! restores previous value
Ref Sec31.8.15.b
SET MODE NODATA_LAB
Sets or cancels the NO VALID LABEL that is placed on plots when all the data referenced by the plotting command is missing. Default is SET, so that this label DOES appear, in the middle of the plot for 2D plots, or as part of the labels at the bottom for line plots.
Sometimes it's convenient to plot all-missing data, as an underlay to set up plot axes. In this case, the NO VALID DATA label is not wanted. CANCEL MODE nodata_lab will remove that label.
Example:
yes? USE levitus_climatology
yes? ! This plot has NO VALID DATA across the middle.
yes? SHADE/K=1/X=50E:70E/Y=40:50/NOLAB temp
yes? ! This plot is just blank.
yes? CANCEL MODE nodata_lab
yes? SHADE/K=1/X=50E:70E/Y=40:50/NOLAB temp
Ref Sec31.8.15.
SET MODE PPLLIST
Directs listed output from PPLUS commands (e.g., PPL LIST LABS) to the specified file. This mode is useful for creating scripts that customize plots. The user can specify the name of the output file by giving it as an argument, otherwise file name "ppllist.out" is assigned.
Example:
yes? SET MODE PPLLIST:plot_symbols.txt
yes? PPL LISTSYM
yes? SPAWN grep "WIDTH" plot_symbols.txt
default state: canceled
Ref Sec31.8.16.
SET MODE REFRESH
The SET MODE REFRESH command causes Ferret to update windows following "occlusion" events on X-servers that lack a backing store (SGI workstations have been a case in point).
default state: canceled (except on SGI systems)
Ref Sec31.8.17.
SET MODE SEGMENTS causes Ferret to utilize GKS segments ("GKS" is the Graphical Kernel System—an international graphics standard). On some systems MODE SEGMENTS may be necessary to update windows following "occlusion" events or to resize window with the mouse.
Segments, however, make heavy demands on the system's virtual memory. If Ferret crashes during graphics output due to insufficient virtual memory try CANCEL MODE SEGMENTS.
default state: set
Ref Sec31.8.18.
SET MODE STUPID
Note: MODE STUPID is included for diagnostic purposes only.
SET MODE STUPID controls the ability of Ferret to reuse results left in memory from previous commands. It also effects its ability to reuse intermediate variables that are referenced multiple times during complex calculations. Given with no argument
yes? SET MODE STUPID
causes Ferret to forget data cached in memory. The result is that all requests for variables are read from disk and no intermediate calculations are reused. The program will be significantly slower as a result.
A lesser degree of cache limitation occurs with the command
yes? SET MODE STUPID: weak_cache
which causes Ferret to revert to the cache access strategy that it used previous to Ferret version 5.0. In this mode cache hits are unreliable unless the region of interest is fully specified. (Unspecified limits will typically default to the full range of the relevant axis.)
default state: canceled
Ref Sec31.8.19.
SET MODE UPCASE_OUTPUT
By default Ferret changes variable and attribute names to uppercase form, and they are written in uppercase to netCDF files. In order to keep the original lowercase or mixed-case spelling of variable and attribute names when they are written to netCDF files, issue the command
yes? CANCEL MODE UPCASE_OUTPUT
and the original upper- or lower-case spellings to be used.
default state: set
Ref Sec31.8.20.
SET MODE VERIFY
SET MODE VERIFY causes commands from a command file ("GO file") to be displayed on the screen as they are executed. Note that if MODE VERIFY is canceled, loop counting in the REPEAT command is turned off.
default state: SET, argument "default"
Note: Many GO files begin with CANCEL MODE VERIFY to inhibit output and end with SET MODE/LAST VERIFY to restore the previous state. Only if an error or interrupt occurs during the execution of such a command file will the state of MODE VERIFY be affected.
SET MODE VERIFY can accept arguments to further refine control over command echoing.
yes? SET MODE VERIFY: DEFAULT
- This will be the default state if no argument is given
- Ferret echos commands taken from GO scripts
- Ferret echos commands in which symbol substitutions occur or in which embedded expressions are evaluated
yes? SET MODE VERIFY: ALL
- In addition to the cases above Ferret also displays the individual commands that are generated by repeat loops and semicolon-separated command groups
- Ferret displays a REPEAT loop counter ("!-> REPEAT: ...")
yes? SET MODE VERIFY: ALWAYS
- Echoing behavior is the same as argument ALL but ALWAYS, in addition, causes CANCEL MODE VERIFY to be ignored when it is encountered in a GO file. This functionality is useful when debugging GO scripts. Entering CANCEL MODE VERIFY or SET MODE VERIFY:DEFAULT from the command line will cancel this state.
Ref Sec31.8.21.
SET MODE WAIT
SET MODE WAIT causes Ferret to wait for a keyboard keystroke from the user after each plotted output is completed. This is useful on graphics terminals that do not have a separate graphics plane; on these terminals SET MODE WAIT prevents the graphical output from being wiped off the screen until the user is ready to proceed.
default state: canceled
Ref Sec31.9.
SET MOVIE
/COMPRESS /FILE /LASER /START
Designates a file (specified or default) for storing graphical images as movie frames (in HDF Raster-8 format). Note that the FRAME/FILE=filename qualifier is generally preferable to the SET MOVIE command, as it is simpler and more flexible. See the chapter "Animations and GIF Images "HDF movies" for further explanation.
yes? SET MOVIE[/qualifiers]
Command qualifiers for SET MOVIE:
Turns on or off compression of HDF frames using run length compression.
yes? SET MOVIE/COMPRESS=OFF
The allowed arguments are "on" and "off" —CANCEL MOVIE does not affect this qualifier.
default state: on
Specify an output file to receive movie frames.
!specify a new filename
yes? SET MOVIE/FILE=filename
or
!reactivate a previously specified filename after CANCEL MOVIE
yes? SET MOVIE/FILE
The default movie filename extension is ".mgm"
The default movie filename is "ferret.mgm"
Output to Panasonic OMDR. Valid only on older VAX/VMS systems.
Only valid for use on older VAX/VMS systems with the Panasonic Optical Memory Disk Recorder (OMDR). Only valid with /LASER qualifier.
Ref Sec31.10.
/I/J/K/L /X/Y/Z/T /DI/DJ/DK/DL /DX/DY/DZ/DT
Specifies the default space-time region for the evaluation of expressions.
yes? SET REGION[/qualifiers] [ reg_name]
See the chapter "Grids and Regions", section Regions for further information.
Examples:
1) yes? SET REGION/X=140E
Sets X axis position in the default context.
2) yes? SET REGION/@N !N specifies X and Y but not Z or T
Sets only X and Y in the default context (since X and Y are defined in region N but Z and T are not).
3) yes? SET REGION N
Sets ALL AXES in the default region to be exactly the same as region N. Since Z and T are undefined in region N they will be set undefined in the default context.
4) yes? SET REGION/@N/Z=50:250
Sets X and Y in the default region to be exactly the same as region N and then sets Z to the range 50 to 250.
5) yes? SET REGION/DZ=-5
Set the region along the Z axis to be 5 units less than its current value.
6) yes? SET REGION/DJ=-10:10
Increases the current vertical axis range by 10 units on either end of the axis.
Command qualifiers for SET REGION:
SET REGION/I=/J=/K=/L=/X=/Y=/Z=/T=
Sets region bounds for specified axis subscript (I, J, K, or L) or axis coordinates (X, Y, Z, or T). See examples above.
SET REGION/DI=/DJ=/DK=/DL=/DX=/DY=/DZ=/DT=
Modifies current region information by the specified increment of an axis subscript (I, J, K, or L) or axis coordinate (X, Y, Z, or T). See examples above. Syntax: /D*=val, or /D*=lo:hi.
Ref Sec31.11.
/BAD /GRID /TITLE /UNIT /DATASET/NAME/OFFSET/SCALE/OUTTYPE
Modifies characteristics of a variable defined by DEFINE VARIABLE or SET DATA/EZ. This command permits variables within a single EZ data set to be defined on different grids and it allows the titles and units to be superseded for the duration of a session, only, on netCDF and GT data sets.
yes? SET VARIABLE/qualifiers variable_name
Parameters
The variable name can be a simple name or a name qualified by a data set.
Example:
yes? SET VAR/UNITS="CM" WIDTH[D=snoopy]
Command qualifiers for SET VARIABLE:
Ref Sec31.11.1.
SET VARIABLE/BAD=
Designates a value to be used as the missing data flag. The qualifier is applicable to EZ data set variables and to netCDF data sets. The bad value which is specified will be used in subsequent outputs and calculations involving this variable. It applies only for the duration of the current Ferret session. It does not alter the data files. It is not applicable to variables defined with DEFINE VARIABLE.
For netCDF files only, if the file contains Fortran NaN (not a number), the user may designate NaN as the bad value flag for a given variable in a netCDF dataset. SET VARIABLE/BAD=NAN.
When the command SET VARIABLE/BAD= is be used to set one of the two missing value flags of a file variable, the bad value which is specified will be used in subsequent outputs and calculations involving this variable.
Ferret is aware of up to two missing value flags for each variable in a netCDF file. Under most circumstances, netCDF file variables use only a single flag. With a command like
SET VARIABLE/BAD=-999 my_file_var
you can specify -999 as an additional missing value flag. It is this value which will be present in all subsequent SAVEs to files and calculations.
Note that if the netCDF file contains two distinct flag values specified by the netCDF attributes "missing_value" and "_FillValue", then this command will migrate the value specified by missing_value to the position previously occupied by _FillValue and replace the one specified by missing_value. Thus a double usage of this command allows you to control both flags. You can use the command "SHOW DATA/VARIABLES" to see both bad value flags.
Ref Sec31.11.2.
Sets the defining grid for a variable in an EZ data set. The argument may be an expression.
Example:
yes? SET VARIABLE/GRID=my_grid width[D=snoopy]
This is the mechanism by which the shape of the data (1D along T axis, 2D in the XY plane, etc.) is specified. By default Ferret will use grid EZ, a line of up to 20480 points oriented along the X axis. The qualifier is not applicable to variables defined with DEFINE VARIABLE.
SET VARIABLE/NAME=
This is effectively a RENAME command -- applies to all classes of variables (but not pseudo-variables). Useful for "repairing" variables whose definitions are inadequate as-is but whose variable names are significant. A common application of this is in creating output netCDF files in which contain modified versions of variables from input files.
yes? SET VARIABLE/NAME=new old
Example:
yes? SET VARIABLE/NAME=north_vel V[d=1]
Ref Sec31.11.3.
SET VARIABLE/TITLE=
Associates a title with the variable. This title appears on plotted outputs and listings. The qualifier is applicable to all variables.
yes? SET VARIABLE/TITLE="title string" var_name
SET VARIABLE/UNITS=
Associates units with the variable. The units appear on plotted outputs and listings. The qualifier is applicable to all variables.
yes? SET VARIABLE/UNITS="units string" var_name
Ref Sec31.11.4.
SET VARIABLE/OFFSET=
For variables in netCDF files only, set an offset which will always be applied when the data is read from the file. This offset is applied after any offset factor specified by an attribute in the file. For applying a scale and offset to data when writing data to a netCDF file see writing packed data to a netCDF file
An application of this is when we want to use a variable to define an axis, but the variations in the data aren't well represented by a single precision variable. This is described in the section on DEFINE AXIS/FROM_DATA.
Ref Sec31.11.5.
SET VARIABLE/SCALE=
For variables in netCDF files only, set a scale factor which will always be applied when the data is read from the file. This factor is applied after any scale factor specified by an attribute in the file. See also SET VARIABLE/OFFSET, above.
When a scale factor and offset are specified, the scale factor is applied first:
var = scale*var_in + offset
If scale and offset values have been set, with either netCDF attributes or with a SET VARIABLE/SCALE=/OFFSET=, they may be accessed with the RETURN= keyword.
Example:
yes? USE coads_climatology
yes? SAY `sst,RETURN=nc_scale`
!-> MESSAGE/CONTINUE 1
1
yes? SAY `sst,RETURN=nc_offset`
!-> MESSAGE/CONTINUE 0
0
yes? SET VAR/SCALE=10/OFF=50 sst
yes? SAY `sst,RETURN=user_off`
!-> MESSAGE/CONTINUE 50
50
yes? SAY `sst,RETURN=user_scale`
!-> MESSAGE/CONTINUE 10
10
Ref Sec31.11.6.
SET VARIABLE/OUTTYPE=
We can control the data type of variables written to output netCDF files, with SET VAR/OUTTYPE=. The netCDF library is used to convert the data type of a Ferret FLOAT value to the requested output type. The types allowed are FLOAT, INT, SHORT, and BYTE, or use SET VAR/OUTTYPE=INPUT to preserve the type the data had on input. To write integers, for instance,
yes? SET DATA etopo60
yes? SET VAR/OUTTYPE=int4 rose
yes? SAVE/X=180/FILE=r_int.nc rose
LISTing to file a.nc
*** NOTE: Converting data type of missing_value NC_FLOAT to match output type of variable NC_INT
** netCDF error:
data in attribute missing_value not representable in output type NC_INT
Here, the missing_value of the variable cannot be represented as an integer, and the variable was not written. Correct for this by assigning a new missing_value to the variable before writing:
yes? SET DATA etopo60
yes? SET VAR/OUTTYPE=int4/BAD=200000 rose
yes? SAVE/X=180/FILE=r_int.nc rose
LISTing to file a.nc
*** NOTE: Converting data type of missing_value NC_FLOAT to match output type of variable NC_INT
Note that not all data can be represented in all types. Also note that when data is written to DOUBLE (or any other type for that matter), it is always converted from the Ferret internal representation of single precision FLOAT data: Even if the original data was double precision, when it is read from the netCDF file it is always converted to single precision.
Ref Sec31.12. SET
VIEWPORT
Sets the rectangular region within the output window where output will be drawn.
yes? SET VIEWPORT view_name
Issuing the command SET VIEWPORT is best thought of as entering "viewport mode." While in viewport mode all previously drawn viewports remain on the screen until explicitly cleared with either SET WINDOW/CLEAR or CANCEL VIEWPORT. If multiple plots are drawn in a single viewport without the use of /OVERLAY the current plot will erase and replace the previous one; the graphics in other viewports will be affected only if the viewports overlap. If viewports overlap the most recently drawn graphics will always lie on top, possibly obscuring what is underneath. By default, the state of "viewport mode" is canceled.
Pre-defined viewports exist for dividing the window into four quadrants and for dividing the window in half horizontally and vertically. See the chapter "Customizing Plots", section 6.7, Pre-defined Viewports, for a list.
Ref Sec31.13.
SET WINDOW
/ASPECT /CLEAR /LOCATION /NEW /SIZE /TITLE
Creates, resizes, reshapes or moves graphics output windows.
yes? SET WINDOW[/qualifiers] [window_number]
Note: Multiple windows may be simultaneously viewable but only a single window receives output at any time.
See commands SHOW WINDOWS and CANCEL WINDOW for additional information.
Examples:
1) yes? SET WINDOW/NEW
Creates a new output window and sends subsequent graphics to it.
2) yes? SET WINDOW 3
Sends subsequent graphics to window 3.
3) yes? SET WINDOW/SIZE=.5
Resizes current window to ½ of full.
4) yes? SET WINDOW/ASPECT=.5
Reshapes current window with Y/X equal to 1:2. The effect of this command is not seen until a plot is sent to the window.
5) yes? SET WINDOW/LOCATION=0,.5
Puts the lower left corner of the current window at the left border of the display and half way up it.
6) yes? SET WINDOW/TITLE="new title"
On the next new window, changes the title in the top bar.
Command qualifiers for SET WINDOW:
SET WINDOW/ASPECT
Sets the aspect ratio of the output window and hard copy. Note the new ratio doesn't take effect until a plot command is issued in the window.
Examples:
1) yes? SET WINDOW/ASPECT=y_over_x n
Sets the overall aspect ratio of window n.
2) yes? SET WINDOW/ASPECT=y_over_x
Sets the overall aspect ratio of the current window.
3) yes? SET WINDOW/ASPECT=y_over_x:AXIS
Sets the axis length aspect ratio of the current window.
The total size (area) of the output window is not changed.
The default value for the overall window ratio is y/x = 8.8/10.2 ~ 0.86.
The default value for the axis length ratio is y/x = 6/8 = 0.75.
Use PPLUS/RESET or SET WINDOW/ASPECT=.75:AXIS to restore defaults.
The aspect ratio specified is a default for future SET WINDOW commands
The origin (lower left) is restored to its default values: 1.2, 1.4
When using "SET WINDOW n" to return to a previous window that differs from the current window in aspect ratio, it is necessary to re-specify its aspect ratio with /ASPECT, otherwise PPLUS will not be properly reset. If you return to a previous window, you cannot expect to make an overlay on the plot that is there. The PPLUS settings for axis lengths and other properties of the plot will have been overwritten.
SET WINDOW/CLEAR
Clears the image(s) in the current or specified window. Useful with viewports.
SET WINDOW/LOCATION
Sets the location for the lower left corner of named (or current) window. The coordinates x and y must be values between 0 and 1 and refer to distances from the lower left corner of the display screen (total length and width of which are each 1).
yes? SET WINDOW/LOCATION=x,y [window_number]
SET WINDOW/NEW
Causes future graphical output to be directed to a new window. The window will be created at the next graphics output.
yes? SET WINDOW/NEW
SET WINDOW/SIZE
Resizes a window to r times the area of the standard window. (The length of the sides changes by the square root of r.) If the window number is omitted the command will resize the currently active window. (The default window size is 0.7.)
yes? SET WINDOW/SIZE=r [window_number]
The actual size of the window is reset to fit on the output device.
SET WINDOW/TITLE[=title text]
On the next new window,
changes the title in the top bar. By default this title is
FERRET_n_date:time, where n is the window number, and the date and time are for the Ferret session (see the symbols SESSION_DATE and SESSION_TIME). The title is
saved in the symbol WIN_TITLE.
! After drawing a plot, the title at the top of the window is of the form
! FERRET_1_8-Aug-08:13:07
yes? PLOT/I=1:5 i
yes? SHOW SYMBOL win_title WIN_TITLE = "8-Aug-08:13:07"
yes? SET WINDOW/NEW/SIZE=0.3/TITLE="small window"
yes? SHOW SYMBOL win_title
WIN_TITLE = "small_window"
The title at the top of the window will be FERRET_2_small_window.