ncdf4 (version 1.23)

ncvar_def: Define a netCDF Variable

Description

Defines a netCDF variable. This variable initially only exists in memory. It is later written to disk using nc_create().

Usage

ncvar_def( name, units, dim, missval=NULL, longname=name, prec="float", 
 shuffle=FALSE, compression=NA, chunksizes=NA, verbose=FALSE )

Value

An object of class ncvar4 that can later be passed to

nc_create().

Arguments

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 model3/run1/Temperature will define a group named model3, with a subgroup named run1, which will hold a variable named Temperature. Using groups forces a netcdf version 4 file to be written. Note that older software might not be able to read netcdf version 4 files.

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 ncdim_def). To create a variable with NO dimensions, pass an empty list ("list()").

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.

Author

David W. Pierce

Details

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.

After a variable is defined with this call, and created on disk using nc_create, then data values for the variable can be written to disk using ncvar_put.

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.

References

http://dwpierce.com/software

See Also

ncdim_def, nc_create, ncvar_put.

Examples

if (FALSE) {
# 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" )
}