Document Actions
LIST
Ref Sec17.
LIST
/I/J/K/L /X/Y/Z/T /D /ILIMITS /JLIMITS /KLIMITS /LLIMITS /XLIMITS /YLIMITS /ZLIMITS /TLIMIT /APPEND /FILE /FORMAT /HEADING /NOHEAD /TITLE /ORDER /RIGID /PRECISION /CLOBBER /SINGLE /QUIET /WIDTH /EDGES /BOUNDS /KEEP_AXISNAMES
Produces a listing of the indicated data.
LIST[/qualifiers] [expression_1 , expression_2 , ...]
Example:
yes? LIST/Z=10 u , v , u^2 + v^2
Lists the 3 quantities specified using the current default data set and region (at depth 10).
Parameters
Expressions may be any valid expression. See the chapter "Variables and Expressions", section "Expressions" for a definition of valid expressions. If multiple variables or expressions are specified they may be listed together in columns or in sequence depending on the /SINGLY qualifier. The expression(s) will be inferred from the current context if omitted from the command line.
If multiple expressions are given on the command line and /SINGLY is not specified, then the expressions must be conformable. See the chapter "Variables and Expressions", section "Multi-Dimensional Expressions" for a definition of conformable expressions. Degenerate or single point axis limits will be promoted up (values repeated) as needed.
Example:
yes? LIST/I=1:3/J=1:2 i+j, i
Command qualifiers for LIST:
LIST/I= /J= /K= /L=/X= /Y= /Z= /T=
Specifies value or range of axis subscripts (I, J, K, or L), or axis coordinates (X, Y, Z, or T) to be used when evaluating the expression(s) being listed.
LIST/ILIMITS=/JLIMITS=/KLIMITS=/LLIMITS=
Specifies the size of the desired netCDF output file independently from the actual data being saved. By specifying axis limits in excess of the saved expression's limits it is possible to /APPEND data later. See the chapter "Converting to NetCDF", section Simple Conversions Using Ferret, example 4.
LIST/XLIMITS=/YLIMITS=/ZLIMITS=/TLIMITS=
Specifies the size of the desired netCDF output file independently from the actual data being saved. By specifying axis limits in excess of the saved expression's limits it is possible to /APPEND data later. See the chapter "Converting to NetCDF", section Simple Conversions Using Ferret, example 4.
Specifies the default data set to be used when evaluating the expression(s) being listed.
Use this qualifier together with the /FILE qualifier to indicate that the listed data should be appended to a pre-existing file. If no file exists by the name indicated a new file is created. This qualifier is not applicable to /FORMAT=GT. When used with /FORMAT=CDF it permits any data in the file to be overwritten, new variables to be added to the file, and appending of new indices along the T axis of the variables in the file. To append slabs of data in other dimensions, see the example in the netCDF chapter, Appending Multiple Slabs). This qualifier overrides the command CANCEL LIST/APPEND.
Names a file to receive the listed data. If /FILE is specified with no name then the default name is used from the SET LIST/FILE command.
Example:
yes? LIST/FILE=my_file.dat sst[D=coads_climatology]
See command SET LIST/AUTO for further information on automatic filename generation.
Used with LIST/FILE. Indicates that any existing file with the name used is to be deleted, before writing. If CLOBBER is not specified and the file exists, and error message is given.
Example:
yes? LIST/FILE=my_file.dat/CLOBBER sst[D=coads_climatology]
Specifies an output format ( =format_choice) for the data to be listed.
yes? SET LIST/FORMAT=format_choice
or
yes? SET LIST/FORMAT (use format set by SET LIST/FORMAT)
|
FORTRAN format |
produces ASCII output |
|
"UNFORMATTED" |
produces unformatted (binary) output using FORTRAN record structure |
|
"CDF" |
produces netCDF format output |
|
"GT" |
produces TMAP GT format |
|
"STREAM" |
produces unstructured binary floating point (C-style) |
|
"tab" |
produces tab-delimited output |
|
"comma" |
produces comma-delimited output |
This command has the same function as SET LIST/FORMAT except that it does not affect future LIST commands. See command SET LIST/FORMAT for detailed documentation.
Notes for LIST/FORMAT:
1) All output values, regardless of the /FORMAT designation, will be of type single precision floating point. For FORTRAN output formats this means all numerical field specifiers must be "F", "E", or "G".
2) For FORTRAN-formatted and UNFORMATTED (binary) output, the contents of a single output "record" are determined by the /ORDER qualifier. For example, each record will be a line of Y values for LIST/ORDER=YX. If /ORDER is omitted, the records will be the first output axis of greater than unity length taken in the order X, Y, Z, then T. FORTRAN-formatted output records may be further split by the usual rules of FORTRAN output formatting.
3) FORTRAN formats must be enclosed in parentheses. If blanks are included in the format it must be enclosed in quotation marks. Output strings are permitted in the format.
Example:
yes? LIST/FORMAT=("The temperature is:", F6.3) sst[X=180, Y=0]
4) When FORTRAN formats are used, and more than one value per record is desired, the /ORDER qualifier must be used, even if the variable is defined along only one axis.
Example:
yes? LIST/FORMAT=(8F6.3)/ORDER=T sst[X=180, Y=0]
5) The default listing style includes labels for the rows and columns of the output. When a FORTRAN format is specified, these labels are omitted.
6) On Unix systems the /FORMAT=UNFORMATTED specifier produces FORTRAN-style variable-length records. On most implementations this means that a 4-byte field containing the record length begins and ends each record of data.
7) The command alias SAVE is provided for the commonly used LIST/FORMAT=CDF. netCDF outputs are self-documenting, including grid definitions. The output files can be used as input with the command USE—alias for SET DATA/FORMAT=CDF. See command SAVE for further notes about netCDF files.
8) For tab and comma foratted output, the coordinates are checked to see if the default format gives enough precision to distinguish all of the coordinates. For fine grids, the coordinates are output with enough digits to distinguish them. This may result in the coordinates not lining up with the columns of the variable values. If there is missing data, a tab or comma will be written as a placeholder.
Only valid for netCDF output (LIST/FORMAT=cdf). Outputs the data, including the bounds attribute on all of its axes. The bounds attribute is used by default on all irregular axes, for Ferret ersion 5.70 and later. See the comments under SAVE.
Only valid for netCDF output (LIST/FORMAT=cdf). Outputs the data, having the edges attribute on all of its axes.
For ASCII data listings this command determines whether to precede the listing with a heading describing data set, variable and region. This qualifier overrides the CANCEL LIST/HEAD command. Starting with Ferret version 5.4 the default heading output of the list command is expanded to include the filename, file path, and complete information on the subset of the data that's listed. See the example under LIST/WIDTH=.
For ASCII data listings this qualifier determines whether to precede the listing with a heading that describes the data set, variable, and region. This qualifier overrides the CANCEL LIST/HEAD command. When the argument /HEADING=ENHANCED is used a self-documenting heading is provided that includes the axis coordinates.
For netCDF output files (alias SAVE) the /HEADING=ENHANCED option causes the netCDF file structure to include extra coordinate information that describes how the particular data subset being written fits within the broader coordinate system of the grid from which it is extracted. When a netCDF file with an enhanced heading is accessed by Ferret (using SET DATA or USE) the index values will appear to be consistent with the parent data set. If /HEADING=ENHANCED is set for a netCDF output file, then /KEEP_AXISNAMES is ignored.
Does not precede listing with a heading describing data set, variable and region. This qualifier overrides the SET LIST/HEAD command.
Writes the original axis names to the output netCDF file. If a subset of the grid has been requested, by default the axes are renamed to reflect this, so that for instance,
yes? USE coads_climatology
yes? SAVE/file=my_subset.nc/X=180:200/Y=-10:20 sst
writes the axis names with the subset indicated by adding the indices that the subset represents; here the X and Y axes in the output file would be named COADSX81_90 and COADSY41_55. To keep the original axis names, COADSX and COADSY, use LIST/KEEP_AXISNAMES.
yes? USE coads_climatology
yes? SAVE/KEEP_AXISNAMES/file=my_subset.nc/X=180:200/Y=-10:20 sst
Specifies the order (ORDER=permutation) in which axes are to be laid out in the listing.
Examples:
yes? LIST/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. /ORDER is applicable only to /FORMAT=unf and FORTRAN formats.
Note that a 1-dimensional list will, by default, place only one value per record. The /ORDER qualifier can cause the 1-dimensional list to occur in a single record. For example,
LIST/I=1:5 I
will list as 5 records whereas
LIST/I=1:5 /ORDER=X I
will list 5 values on a single record.
Controls the digit precision of LIST output
Using the qualifier /PRECISION=#digits 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. 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.
Using the qualifier /QUIET will prevent the message "LISTing to file XXXX.XXXX" from being displayed.
Valid only with /FORMAT=CDF. Indicates that Ferret should not create a netCDF "record" axis as the time axis for any of the variables listed with this command. Time axes are, instead, of fixed length and the /APPEND qualifier is not usable to extend the listing.
This qualifier is relevant only when multiple expressions are specified in the LIST command. When the /SINGLY qualifier is specified the entire listing of each expression including (optional) heading and all data is completed before proceeding to the next expression.
By default the expressions are not listed singly—each line contains one value of each expression. The qualifier has no effect if only a single expression is specified. If the /FILE qualifier is specified to use automatic filename generation and /APPEND is not specified, then each expression is listed to a separate file.
Valid only with /FORMAT=CDF. Causes the global attribute "title" to be defined in a netCDF file, thereby setting its title.
For multi-column output, controls the width of the listing on the page so the output line is no longer than "columns" characters.
Example:
yes? USE coads_climatology
yes? LIST/L=1/WIDTH=50/Y=0:4 sst
VARIABLE : SEA SURFACE TEMPERATURE (Deg C)
DATA SET : COADS Monthly Climatology (1946-1989)
FILENAME : coads_climatology.des
FILEPATH : /home/ja9/tmap/fer_dsets/descr/
SUBSET : 180 by 2 points (LONGITUDE-LATITUDE)
TIME : 16-JAN 06:00
... listing every 36th point
21E 93E 165E 123W 51W
1 37 73 109 145
3N / 47: .... 28.30 29.04 25.36 27.49
1N / 46: .... 28.29 29.12 24.82 27.49
yes? list/l=1/wid=70/y=0:4 sst
VARIABLE : SEA SURFACE TEMPERATURE (Deg C)
DATA SET : COADS Monthly Climatology (1946-1989)
FILENAME : coads_climatology.des
FILEPATH : /home/ja9/tmap/fer_dsets/descr/
SUBSET : 180 by 2 points (LONGITUDE-LATITUDE)
TIME : 16-JAN 06:00
... listing every 23th point
21E 67E 113E 159E 155W 109W 63W 17W
1 24 47 70 93 116 139 162
3N / 47: .... 28.15 27.54 29.09 26.90 25.34 .... 27.58
1N / 46: .... 28.18 .... 29.24 26.49 24.90 .... 27.05v