Ref Sec29.
SAVE
The SAVE command is an alias for LIST/FORMAT=CDF. All qualifiers and restrictions are identical to LIST/FORMAT=CDF.
Example:
yes? SAVE temp, salt ! is identical to yes? LIST/FORMAT=CDF temp, salt
1) Gaps in netCDF outputs are filled with the missing value flag of the variable being written. (See the chapter "Variables and Expressions", section "Missing value flags" . In the example below, if "temp" and "salt" share the same time axis then the L=2:4 values of salt will be so filled.
yes? SAVE/FILE=test.cdf temp[L=1:5], salt[L=1], salt[L=5]
2) Transformations that compress an axis to a point produce results that Ferret regards as time-independent. Thus, this 12-month average:
yes? SAVE/FILE=annual.cdf sst[L=1:12@AVE]
creates a netCDF file with no time axis. It would not be possible to append the average of the next 12 months as the next time step of this file. See the example on "Appending timesteps" for details on appending to netCDF files. However, a time location can be inherited from another variable by use of a "timestamp".
Timestamp: Inherit a time setting from another variable in order to create a time axis in a netCDF file. In this example, we inherit the time axis of "timestamp" in order to create a time axis in the netCDF file.
yes? DEFINE AXIS/T="1-JUL-1980":"1-JUL-1985":1/UNIT=year tannual yes? DEFINE GRID/T=tannual gannual yes? LET timestamp = T[G=gannual] * 0 !always 0 yes? LET sst_ave = sst[L=1:12@AVE] + timestamp yes? SAVE/FILE=annual.cdf sst_ave[L=1] yes? LET sst_ave = sst[L=13:24@AVE] + timestamp yes? SAVE/FILE=annual.cdf/APPEND sst_ave[L=2]
3) Background documentation about the definition and data set of origin for a variable are saved in the "history" attribute of a variable when it is first saved in the netCDF file. If the definition of the variable is then changed, and more values are inserted into the file using SAVE/APPEND, the modified definition will NOT be documented in the output file. If the new definition changes the defining grid for the variable the results will be unpredictable.
4) If you have created a data file with variables that you DEFINE, you will need to cancel those previous definitions of the variables before you USE the new data set. If you USE the data file while the DEFINE VARIABLE definition still exists in Ferret then the one that you defined is the one that you will see with LIST and other commands. Either CANCEL VARIABLE, or QUIT and start a new Ferret session where you access your new data set.
. . . yes? SAVE/FILE=annual.cdf/APPEND sst_ave[L=2] . . . yes? CANCEL VAR sst_ave yes? USE annual.cdf
yes? SHOW DATA
5) To write packed data to a netCDF file, make sure the variable has add_offset and scale_factor attributes and that these attributes have the /OUTPUT flag set. Then the data and its missing value flag will have this scaling applied on output. See NetCDF attributes for packing data.
6) The data type of the variables written to netCDF files are determined as follows: Coordinate data is always written in double precision. For file variables read in from a netCDF file, their output type will be the same as the type in the input file. For user-defined variables and variables from non-NetCDF files, the data type is double precision (prior to Ferret v6.8 it was single-precision float). For any variable you can set the precision using SET VARIABLE/OUTTYPE=. When writing data to netCDF files 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.
Beginning with Ferret v6.83, these additional command qualifiers are available:
will cause all subsequent SAVE statements to use that type. This allows a single setting for the entire Ferret session. The command could be placed in a .ferret startup file or a settings script run at startup.
CANCEL/LIST/OUTTYPE will restore the default behavior.
SAVE/OUTTYPE= overrides all other settings, for this SAVE command only. The specified type is applied to all the variables given in the SAVE command.
The output types are the netCDF types DOUBLE, FLOAT, INT, SHORT, BYTE. INT is INT4 and SHORT is INT2.
7) 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. When /RIGID is specifed, the time axis is NOT appendable, and so is not marked as being the record axis.
If a coordinate is irregular it is output to the netCDF file with a bounds attribute (beginning with Ferret v5.70). To require that all axes be written with bounds attributes, use the /BOUNDS qualifier:
yes? SAVE/BOUNDS v1,v2
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.
Examples:
yes? USE climatological_axes yes? LET v = L[GT=month_irreg] ! variable with an irregular axis yes? SAVE/FILE=mnth.nc/L=1:4 v ! bounds attribute on time axis.
We will be able to append more time steps to the file.
yes? SAVE/APPEND/FILE=mnth.nc/L=5:6 v
If there is a gap between time steps in the file and the first time step being appended, Ferret inserts a void point whose bounds are the upper bound of the last time in the file, and the lower bound of the first time step being appended. Append steps 10:12 to the file, and then look at the variable and its coordinates:
yes? SAVE/APPEND/FILE=mnth.nc/L=10:12 v yes? CANCEL VAR v yes? USE mnth.nc yes? LIST v, TBOXLO[gt=v], TBOXHI[gt=v], TBOX[gt=v] DATA SET: ./mnth.nc TIME: 01-JAN 00:00 to 31-DEC 05:49 Column 1: V is L[GT=MONTH_IRREG] Column 2: TBOXLO is TBOXLO (axis MONTH_IRREG1) Column 3: TBOXHI is TBOXHI (axis MONTH_IRREG1) Column 4: TBOX is TBOX (axis MONTH_IRREG1) V TBOXLO TBOXHI TBOX 16-JAN 12 / 1: 1.00 0.0 31.0 31.00 15-FEB 02 / 2: 2.00 31.0 59.2 28.24 15-MAR 17 / 3: 3.00 59.2 90.2 31.00 15-APR 05 / 4: 4.00 90.2 120.2 30.00 15-MAY 17 / 5: 5.00 120.2 151.2 31.00 15-JUN 05 / 6: 6.00 151.2 181.2 30.00 15-AUG 05 / 7: .... 181.2 273.2 92.00 15-OCT 17 / 8: 10.00 273.2 304.2 31.00 15-NOV 05 / 9: 11.00 304.2 334.2 30.00 15-DEC 17 / 10: 12.00 334.2 365.2 31.00
If appending data to a file which has a regular time axis and no bounds, if there is a gap between the time steps in the file and those being appended, older versions of Ferret had always written an axis which is irregular and which has large box sizes at the gap. Now, Ferret will issue a note suggesting that bounds would define the time axis more accurately.
yes? use coads_climatology ! Has a regular time axis yes? save/l=1:4/clobber/file=b.nc sst[x=180,y=0] yes? save/append/L=6:9/file=b.nc sst[x=180,y=0] *** NOTE: Appending to NetCDF record axis which has no bounds attribute. *** NOTE: This will result in incorrect box sizes on record axis: TIME *** NOTE: Write the data initially with the /BOUNDS qualifier
In version 6.0 of Ferret, a number of features were added to allow control over attributes written to NetCDF files. In particular you can SET ATTRIBUTE/OUTPUT to force attributes to be written to files. See "Output attributes to NetCDF fies" for a complete description. Also see "MODE UPCASE_OUTPUT" for control over whether variable and attribute names are converted to uppercase.
Starting with version 6.6, Ferret is linked with NetCDF-4 libraries. See the section on NetCDF-4 for details of the command syntax to control writing NetCDF-4 formatted files.