var.def.ncdf {ncdf} | R Documentation |
Defines a netCDF variable. This variable initially only exists in memory.
It is written to disk using create.ncdf()
.
var.def.ncdf( name, units, dim, missval, longname=name, prec="single")
name |
Name of the variable to be created (character string). |
units |
The variable's units (character string). |
dim |
The variable's dimension(s) (one or a list of "dim.netcdf" class objects). |
missval |
The variable's missing value. |
longname |
Optional longer name for the variable, which is assigned to the variables "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' 'single' 'double' 'char'. |
This routine creates a netCDF variable in memory. The variable can then
be passed to the routine create.ncdf
when writing a file to disk.
Note that this interface to the netCDF library includes that 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.
After a variable is defined with this call, and created on disk using
create.ncdf
, then data values for the variable can be written
to disk using put.var.ncdf
.
This function returns a var.ncdf
object, which describes the newly-created
variable. However, the var.ncdf
object is used for more than just
creating new variables. The function open.ncdf
returns a ncdf
object that itself contains a list of var.ncdf
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 dim.ncdf
object instead.)
The var.ncdf
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 "dim.ncdf" (see dim.def.ncdf
), 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.
An object of class var.ncdf
that can later be passed to
create.ncdf()
.
David W. Pierce dpierce@ucsd.edu
http://www.unidata.ucar.edu/packages/netcdf/
dim.def.ncdf
, create.ncdf
,
put.var.ncdf
.
# Define an integer dimension dimState <- dim.def.ncdf( "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 <- var.def.ncdf("Pop", "count", dimState, -1, longname="Population", prec="integer") # Create a netCDF file with this variable ncnew <- create.ncdf( "states_population.nc", varPop ) # Write some values to this variable on disk. popAlabama <- 4447100 put.var.ncdf( ncnew, varPop, popAlabama, start=1, count=1 ) # Add source info metadata to file att.put.ncdf( ncnew, 0, "source", "Census 2000 from census bureau web site") close.ncdf(ncnew) # Now illustrate some manipulations of the var.ncdf object filename <- "states_population.nc" nc <- open.ncdf(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 <- dim.def.ncdf( "Time", "days", 1:3 ) missval <- -1 varShort <- var.def.ncdf( "varShort", "meters", dimt, missval, prec="short") varInt <- var.def.ncdf( "varInt", "meters", dimt, missval, prec="integer") varFloat <- var.def.ncdf( "varFloat", "meters", dimt, missval, prec="single") varDouble<- var.def.ncdf( "varDouble","meters", dimt, missval, prec="double") nctypes <- create.ncdf("vartypes.nc", list(varShort,varInt,varFloat,varDouble) ) close.ncdf(nctypes)