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

Notes:

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. 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) 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 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.