This routine creates a netCDF dimension in memory. The created dimension can then
later be passed to the routine ncvar_def()
when defining a variable. Note that this interface to the netCDF library by default includes that more than the
minimum required by the netCDF standard. I.e., the netCDF standard allows
dimensions with no units or values. This call encourages creating dimensions
that have units and values,
as it is useful to ensure that all dimensions have units and
values, and considerably easier to include them in this call than it is
to add them later. The units and values are implemented through "dimensional
variables," which are variables with the same name as the dimension. By default, these
dimensional variables are created automatically -- there is no need for the
user to create them explicitly. Dimensional variables are standard practice
in netCDF files. To suppress the creation of the dimensional variable for
the dimension, set passed parameter create_dimvar to FALSE. As a
check, if create_dimvar is FALSE, you must ALSO pass an empty string ('') as the unit, and the values
must be simple integers from 1 to the length of the dimension (e.g., 1:10 to
make a dimension of length 10).
This empahsizes that without a dimensional variable, a netCDF file cannot
store a dimension's units or values.
The dimensional variable is usually created as a double precision floating
point. The other possibility is to pass integer values (using as.integer
,
for example), in which case the dimensional variable with be integer.
The return value of this function is an object of class ncdim4
, which
describes the newly created dimension.
The ncdim
object is used for more than just creating a new
dimension, however.
When opening an existing file, function nc_open
returns a
ncdf4
class object, which itself has a list of ncdim
objects
that describe all the dimensions in that existing file.
The ncdim
object has the following fields, which are all read only:
1) name, which is a character string containing the name of the dimension;
2) units, which is a character string containing the units for the dimension,
if there are any (technically speaking, this is the "units" attribute of the
associated coordinate variable); 3) vals, which is a vector containing the
dimension's values (i.e., the values of the associated coordinate variable,
or, if there is none, an integer sequence from 1 to the length of the dimension);
3) len, which is the length of this dimension; 4) unlim, which is a boolean
indicating whether or not this is an unlimited dimension; 5) (optional) calendar,
which is set if and only if the on-disk dimvar had an attribute named
"calendar" (in which case, it is set to the value of that attribute).