Define a netCDF Variable
Defines a netCDF variable. This variable initially only exists in memory.
It is later written to disk using nc_create().
ncvar_def( name, units, dim, missval, longname=name, prec="float", shuffle=FALSE, compression=NA, chunksizes=NA, verbose=FALSE )
name |
Name of the variable to be created (character string).
The name can
optionally have forward slashes in it, in which case the variable will be defined
in the indicated group. For example, a variable
named |
units |
The variable's units (character string). Or, pass a zero length string (”) to have no units attribute. |
dim |
The variable's dimension(s) (one or a list of "ncdim4" class objects, as returned by |
missval |
The variable's missing value. If NO missing value is desired, pass a NULL, or omit this argument entirely. If a NaN missing value is desired, pass an NA. |
longname |
Optional longer name for the variable, which is assigned to the variable's "long_name" attribute. For example, a variable named "TS" might have the longname "Surface Temperature" |
prec |
Precision of the created variable. Valid options: 'short' 'integer' 'float' 'double' 'char' 'byte'. See the special note below for how to create a character variable (strings). |
shuffle |
Turns on (if TRUE) or off (if FALSE, the default) the shuffle filter. According to netcdf docs, turning the shuffle filter on can improve compression for integer variables. Turning the shuffle filter on forces the created file to be in netcdf version 4 format, which will not be compatible with older software that only reads netcdf version 3 files. |
compression |
If set to an integer between 1 (least compression) and 9 (most compression), this enables compression for the variable as it is written to the file. Turning compression on forces the created file to be in netcdf version 4 format, which will not be compatible with older software that only reads netcdf version 3 files. |
chunksizes |
If set, this must be a vector of integers with a length equal to the number of dimensions in the variable. When data from this variable is written to the file, it will be buffered in blocks as indicated by the chunksize. The order of dimensions in this vector is the standard R ordering of XYZT. In some instances, setting a chunksize that reflects how the variable's data will be read or written can greatly reduce read or write times. See the netcdf documentation for more detail on how to set this parameter. Enabling this feature forces the created file to be in netcdf version 4 format, which will not be compatible with older software that only reads netcdf version 3 files. |
verbose |
Print debugging information. |
This routine creates a netCDF variable in memory. The variable can then
be passed to the routine nc_create when writing a file to disk.
Note that this interface to the netCDF library includes more than the minimum required by the netCDF standard. I.e., the netCDF standard allows variables with no units or missing values. This call requires units and a missing value, as it is useful to ensure that all variables have units and missing values, and considerably easier to include them in this call than it is to add them later. The units and missing value are implemented through attributes to the variable, named "units" and "missing_value", respectively. This is standard practice in netCDF files.
This function returns a ncvar object, which describes the newly-created
variable. However, the ncvar object is used for more than just
creating new variables. The function nc_open returns a ncdf4
class object that itself contains a list of ncvar4 objects that describe
the variables in an existing, on-disk netCDF file. (Note that coordinate
variables are NOT included in this list. Attributes of the coordinate variables
are kept in the ncdim4 class object instead.)
The ncvar4 class object has the following fields, which are all read-only:
1) name, which is a character string containing the name of the variable;
2) units, which is a character string containing the contents of the
variable's "units" attribute; 3) missval, which contains the contents of the
variable's "missing_value" attribute; 4) longname, which is the
contents of the variable's "long_name" attribute, or defaults to the name
of the variable if there is no "long_name" attribute; 5) ndims, which is the
number of dimensions this variable has; 6) dim, which is a list of objects of
class "ncdim4" (see ncdim_def), and describe this
variable's dimensions; 7) unlim, which is TRUE if this variable has an unlimited
dimension and FALSE otherwise; 8) varsize, which is a convenience array
that gives the shape of the variable (in XYZT ordering).
Note that the missval attribute does not need to be used much in R, because R's special value NA is fully supported. I.e., when data is read in from an existing file, any values equal to the "missing" value are set to NA. When data is written out, any NAs are set equal to the missing value. If not explicitly set by the user, a default value of 1.e30 is used for the missing value.
CHARACTER VARIABLES: Character-type variables (i.e., strings) are supported using the
original netcdf library approach, which is used because it is backwards compatible with
the older version 3 of the netcdf library. This approach uses fixed-size
strings, which should be declared to be the maximum length of the string
that will be stored. If the maximum string size is N, then an auxiliary
dimension is first defined, with values
running from 1 to N. For example, if N=12 and we call the new
auxiliary dimension "nchar", then the code could look like this:
dimnchar <- ncdim_def("nchar", "", 1:12, create_dimvar=FALSE ). The
character type variable is then defined with the first dimension being
this new auxiliary variable: varcolors <- ncvar_def("colors", "", list(dimnchar, dimcolorno),
prec="char" ). See the manual page for ncvar_put for a worked example.
An object of class ncvar4 that can later be passed to
nc_create().
David W. Pierce dpierce@ucsd.edu
http://dwpierce.com/software
# Define an integer dimension
dimState <- ncdim_def( "StateNo", "count", 1:50 )
# Make an integer variable. Note that an integer variable can have
# a double precision dimension, or vice versa; there is no fixed
# relationship between the precision of the dimension and that of the
# associated variable. We just make an integer variable here for
# illustration purposes.
varPop <- ncvar_def("Pop", "count", dimState, -1,
longname="Population", prec="integer")
# Create a netCDF file with this variable
ncnew <- nc_create( "states_population.nc", varPop )
# Write some values to this variable on disk.
popAlabama <- 4447100
ncvar_put( ncnew, varPop, popAlabama, start=1, count=1 )
# Add source info metadata to file
ncatt_put( ncnew, 0, "source", "Census 2000 from census bureau web site")
nc_close(ncnew)
# Now illustrate some manipulations of the var.ncdf object
filename <- "states_population.nc"
nc <- nc_open(filename)
print(paste("File",nc$filename,"contains",nc$nvars,"variables"))
for( i in 1:nc$nvars ) {
v <- nc$var[[i]]
print(paste("Here is information on variable number",i))
print(paste(" Name: ",v$name))
print(paste(" Units:",v$units))
print(paste(" Missing value:",v$missval))
print(paste(" # dimensions :",v$ndims))
print(paste(" Variable size:",v$varsize))
}
# Illustrate creating variables of various types. You will find
# that the type of the missing_value attribute automatically follows
# the type of the variable.
dimt <- ncdim_def( "Time", "days", 1:3 )
missval <- -1
varShort <- ncvar_def( "varShort", "meters", dimt, missval, prec="short")
varInt <- ncvar_def( "varInt", "meters", dimt, missval, prec="integer")
varFloat <- ncvar_def( "varFloat", "meters", dimt, missval, prec="single")
varDouble<- ncvar_def( "varDouble","meters", dimt, missval, prec="double")
nctypes <- nc_create("vartypes.nc", list(varShort,varInt,varFloat,varDouble) )
nc_close(nctypes)
# Clean up example
file.remove( filename )
file.remove( "vartypes.nc" )Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.