Ref Sec17.
LIST
/I/J/K/L/M/N /X/Y/Z/T/E/F /D /ILIMITS /JLIMITS /KLIMITS /LLIMITS /XLIMITS /YLIMITS /ZLIMITS /TLIMITS /APPEND /FILE /FORMAT /HEADING /NOHEAD /TITLE /ORDER /RIGID /PRECISION /CLOBBER /SINGLE /QUIET /WIDTH /EDGES /BOUNDS /NOROWLAB /KEEP_AXISNAMES /OUTTYPE /NCFORMAT /XCHUNK/YCHUNK/ZCHUNK/TCHUNK/DEFLATE/SHUFFLE/ENDIAN/ASGLOBAL
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.
Note:
If the data is in a DSG (Discrete Sampling Geometries) dataset, the listing includes the requested variables and all their associated coordinate values.
- LIST/FORMAT=comma or LIST/FORMAT=tab will make a comma-or tab-delimited listing, including formatted location and time coordinates.
- LIST/NOROWLAB wil remove the coordinate and feature information from the lines for a simple listing.
- LIST/PRECISION= may be used to control precision of the variables listed. It does not apply to the coordinates, however coordinate variables may be requested in the listing: "list/prec=8 longitude, latitude".
For DSG data, Features can be picked out with a range in /M or /E. List the first 2 timeseries with
yes? list/M=1:2 temp
Coordinate ranges are applied to the data to list a subset in space or time. To list data for only a subset of stations, and a range of depths,
yes? list/X=310:320/y=-4:7/Z=0:30 temp, sal
For DSG data, index ranges /I= /J= /K= /L= are not allowed, as the indices do not correspond to coordiate ranges. Use coordinate ranges, or try a command such as
LIST/i=1:5 XSEQUENCE(var)
Example:
yes? LIST/I=1:3/J=1:2 i+j, i
Command qualifiers for LIST:
LIST/I= /J= /K= /L= /M= /N= /X= /Y= /Z= /T= /E= /F=
Specifies value or range of axis subscripts (I, J, K, L, M, N), or axis coordinates (X, Y, Z, T, E, or F) to be used when evaluating the expression(s) being listed.
LIST/ILIMITS=/JLIMITS=/KLIMITS=/LLIMITS=/MLIMITS=/NLIMITS=
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=/ELIMITS=/FLIMITS=
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.
If writing to a DSG file, e.g. a subset of data from an existing DSG file, new variables may be appended if they are of the same size and shape as the existing data in the file being written.
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 SET LIST/FILE=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.
Note that for text formats (default LIST to the terminal, or LIST/FORMAT=comma, LIST/FORMAT=tab), the format of time-strings can be changed to ISO 8601 time formatting, by using the MODE DATE_FORMAT:iso setting.
Notes for LIST/FORMAT:
1) For FORTRAN output formats, floating-point numerical field specifiers must be "F", "E", or "G". Fortran output formats are not implemented for DSG datasets at this time. Use LIST/PRECISION
Beginning with Ferret v7.4, limited use of A and I formats are allowed for listing strings and numeric data output as integers. When A or I is included, the formats must be simple lists of one specifier per variable listed.
Examples:
yes? let date_strings = TAX_DATESTRING(t[g=airt],t[g=airt],"month")
yes? list/nohead/l=1:5/format=(a,f6.2) date_strings, airt[x=-135,y=0]
DEC-2010 25.38
DEC-2010 25.37
DEC-2010 26.83
DEC-2010 26.51
DEC-2010 26.52
yes? let num = L[gx=date_strings]
yes? list/nohead/l=1:5/format=(i6, a10,f6.2) num, date_strings, airt[x=-135,y=0]
1 DEC-2010 25.38
2 DEC-2010 25.37
3 DEC-2010 26.83
4 DEC-2010 26.51
5 DEC-2010 26.52
yes? list/nohead/format=(a6, a8, a2, a5) {"Abcde"}, {"Abcdefg"}, {"A"}, {"Abcd"}
Abcde Abcdefg A Abcd
yes? list/nohead/format=(a5, a7, a1, a4) {"Abcde"}, {"Abcdefg"}, {"A"}, {"Abcd"}
AbcdeAbcdefgAAbcd
yes? list/nohead/format=(a2, a2, a2, a2) {"Abcde"}, {"Abcdefg"}, {"A"}, {"Abcd"}
AbAb AAb
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. For writing string data, if a single variable is being written, the format LIST/FORMAT=(A) may be used. Listing multiple string variables or string and numeric variables cannot be done with a Fortran format. (But try /FORMAT=comma or /FORMAT=tab). See Chapter 7 for examples.
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 formatted 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. The missing-value flags are written in the header lines and if there is missing data, the missing value for each variable is written. This makes the data work when imported into other applications.
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.
LIST/DEFLATE[=deflate_level]
For writing NetCDF-4 formatted files, sets the level of HDF5 compression. (Ferret version 6.6 and higher). Only valid with LIST/FORMAT=CDF (alias SAVE), and for NetCDF-4 formatted files. DEFLATE=0 turns off compression, DEFLATE=1 sets a deflate level of 1. The setting may be between 0 and 9; however levels greater than 1 are not recommended by the HDF5 documentation. Specifying SET LIST/DEFLATE with no value turns on the compression and sets the level to 1. See the NetCDF and HDF5 documentation for details of HDF5 compression. LIST/DEFLATE with no argument turns on compression and sets the level to 1.
yes? SAVE/FILE=new.nc/CLOBBER/NCFORMAT=4/DEFLATE temp
NetCDF-4 topics are furher discussed in Chapter 2, section netCDF4.
Please see the full NetCDF documentation and descriptions of the use of HDF5 with netcdf-4 at the Unidata NetCDF pages,
http://www.unidata.ucar.edu/software/netcdf/
LIST/EDGES
Only valid for netCDF output (LIST/FORMAT=cdf). Outputs the data, having the edges attribute on all of its axes.
LIST/ENDIAN=
For writing NetCDF files, sets the endianness. (Ferret v6.6 and higher.) Only valid with LIST/FORMAT=CDF (alias SAVE), and for NetCDF-4 formatted files. In netCDF classic format, the problem of endianness is solved by writing all data in big-endian order. The HDF5 library allows data to be written as either big or little endian, and automatically reorders the data when it is read, if necessary.
By default, netCDF uses the native types on the machine which writes the data. Users may change the endianness of a variable (before any data are written). In that case the specified endian type will be used in HDF5 (for example, a H5T_STD_I16LE will be used for NC_SHORT, if little-endian has been specified for that variable.)
Please see the full NetCDF documentation and descriptions of the use of HDF5 with netcdf-4 at the Unidata NetCDF pages,
http://www.unidata.ucar.edu/software/netcdf/
Arguments to /ENDIAN are big, little, and native. The default is native.
yes? SAVE/NCFORMAT=4/ENDIAN=big/FILE=newfile.nc my_var
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.
LIST/NCFORMAT=
For writing NetCDF files, (Ferret v6.6 and higher), specifies that the output file will be of one of the output formats that the NetCDF-4 library writes. Only valid with LIST/FORMAT=CDF (alias SAVE).
SAVE/NCFORMAT=netcdf4/FILE=a.nc var !write a NetCDF-4 formatted file, using HDF5 SAVE/NCFORMAT=classic/FILE=a.nc var !write a Netcdf-4 Classic Model Formatted file. SAVE/NCFORMAT=64bit_offset/FILE=a.nc var ! Writes the 64-bit offset formated file.
LIST/NCFORMAT=netcdf4 may be abbreveiated as LIST/NCFORMAT=4 and LIST/NCFORMAT=classic may be abbreviated as LIST/NCFORMAT=3. The classic model files are compatible with software that uses NetCDF-3. The 64-bit offset formated files are a variation on the classic format.
Other qualifiers on the LIST command for making settings for NetCDF-4 formatted files are /DEFLATE /ENDIAN /SHUFFLE /XCHUNK /YCHUNK /ZCHUNK /TCHUNK
The NetCDF documentation describes these formats. Please see the full NetCDF documentation and descriptions of the use of HDF5 with netcdf-4 at the Unidata NetCDF pages,
http://www.unidata.ucar.edu/software/netcdf/
Does not precede listing with a heading describing dataset, variable and region. This qualifier overrides the SET LIST/HEAD command.
Leaves off the coordinate labels at the start of each row of the listing.
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
Additionally, if an axis in a dataset has the same name as another axis already defined in the Ferret session, the axis is given a new internal name. For instance if there is an axis called TIME in some grid, and we open a file with a name TIME but different coordinates, this second axis is given the name TIME1. In this case, saving data with /KEEP_AXISNAMES will attempt to use the original name, if that can be done unambiguously.
Only for netCDF files. Saves the variable to the file as a global attribute. This command is arbitrarily limited to writing 1-D variables of length 100 elements or less. The variable may be of type char or a numeric variable.
yes? cancel mode upcase ! optional yes? let instrument_type = "General Widgets Company model 3.b" yes? save/append/asglobal/file=my_2017_data.nc instrument_type yes? let instrument_number = 133 yes? save/append/asglobal/file=my_2017_data.nc instrument_number
To define and attributes on variables, use DEFINE ATTRIBUTE.
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 data type for writing to NetCDF files. The types are the NetCDF types DOUBLE, FLOAT, INT, SHORT, and BYTE. See the documentation of the SAVE command for details about output data types.
Beginning with Ferret/PyFerret v7.45 LIST/OUTTYPE may also be used for stream binary files with LIST/FORMAT=STREAM. The types are the same as for netCDF files, DOUBLE, FLOAT, INT, SHORT, and BYTE.
Note that the output type of the missing_value and _FillValue attributes must match the type of the data being written. for instance if the data is being written as INT, then the missing value flag must also be a value that can be represented as an INT.
/OUTTYPE is not implemented for data from DSG files. The output type will be the same as the type in the source dataset.
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. (Previous to Ferret v6.8, note that in fact at most 7 digits were significant since Ferret calculations are performed in single precision.)
If the value specified for #digits is zero or negative Ferret will interpret this as the desired number of decimal places rather than the number of significant digits. (Ferret v7.5 and higher)
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.
LIST/SHUFFLE=
For writing NetCDF-4 formatted files, turns on or off HDF5 shuffle. (Ferret version 6.6 and higher). Only valid with LIST/FORMAT=CDF (alias SAVE), and with NetCDF-4 formatted files. Settings for HDF5 shuffle=0 turns shuffle off and =1 turns it on. See the NetCDF and HDF5 documentation for details. /SHUFFLE often reduces file size.
SAVE/SHUFFLE/NCFORMAT=4/FILE=out.nc var ! Turns on HDF5 shuffle SAVE/SHUFFLE=1/NCFORMAT=4/FILE=out.nc var ! same as the above command SAVE/SHUFFLE=0/NCFORMAT=4/FILE=out.nc var ! turns off shuffle
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
LIST/XCHUNK=/YCHUNK=/ZCHUNK=/TCHUNK=/ECHUNK=/FCHUNK=
For writing NetCDF-4 formatted files (Ferret version 6.6 and higher), sets chunk sizes in each coordinate direction. Only valid with LIST/FORMAT=CDF (alias SAVE), and with NetCDF-4 formatted files. The values are given as integers and must be less than or equal to the size of the dimension. If these are not specified, the compression will use the defaultchunk-size scheme of the NetCDF-4 library. If you specify a chunk sizefor any dimension, you must specify it for all of the dimensions present in the grid.
yes? SAVE/FILE=deflate.nc/CLOBBER/NCFORMAT=4/DEFLATE=1/SHUFFLE=1\
/XCHUNK=30/YCHUNK=30/ZCHUNK=1/TCHUNK=1 tempThis document discusses improving performance with Chunking: http://www.unidata.ucar.edu/software/netcdf/docs/netcdf_perf_chunking.html
Please see the full NetCDF documentation and descriptions of the use of HDF5 with netcdf-4 at the Unidata NetCDF pages,
http://www.unidata.ucar.edu/software/netcdf/