The ncvar Package. October 8, 2004

Transcription

1 The ncvar Package October 8, 2004 Version Date Title High-level R Interface to NetCDF Datasets Author Maintainer <juerg.schmidli@env.ethz.ch> Depends R (>= 1.7), RNetCDF This package provides a high-level R interface to Unidata s NetCDF data files. Using this package netcdf datasets, and all their associated metadata, can be read and written in one go. It is also easy to create datasets including lots of metadata. This package supports both the CF and default NetCDF metadata conventions. This package supports more general NetCDF files and conventions than the ncdf package by David Pierce. It requires the low-level NetCDF package RNetCDF by Pavel Michna. License GPL version 2 or newer R topics documented: ncvar att.def.ncv coord.def.ncv dim.def.ncv examples.ncv print.ncv var.def.ncv var.get.ncv var.put.ncv att.get.ncv att.put.ncv att.val.ncv dim.get.ncv dim.put.ncv dim.val.ncv xtype.ncv ncvar-internal.ncv Index 18 1

2 2 att.def.ncv ncvar High-level R Interface to NetCDF Datasets Note This package provides a high-level R interface to Unidata s NetCDF data files. Using this package NetCDF datasets, and all their associated metadata, can be read and written in one go. It is also easy to create datasets including lots of metadata. This package supports both the CF and the default NetCDF (user guide) metadata conventions. This package supports more general NetCDF files and conventions than the ncdf package by David Pierce. It uses the low-level NetCDF package RNetCDF by Pavel Michna. NetCDF is an abstraction that supports a view of data as a collection of self-describing, portable objects that can be accessed through a simple interface. Array values may be accessed directly, without knowing details of how the data are stored. Auxiliary information about the data, such as what units are used, may be stored with the data. Generic utilities and application programs can access NetCDF datasets and transform, combine, analyze, or display specified fields of the data. The NetCDF Climate and Forecast (CF) Metadata Conventions are designed to promote the processing and sharing of files created with the NetCDF API. The conventions define metadata that provide a definitive description of what the data in each variable represents, and of the spatial and temporal properties of the data. This enables users of data from different sources to decide which quantities are comparable, and facilitates building applications with powerful extraction, regridding, and display capabilities. The CF conventions generalize and extend the COARDS conventions. See examples for some examples of using the package. This package requires the RNetCDF package by Pavel Michna. References att.def.ncv Define NetCDF Attribute(s) Defines an attribute object containing one or more attributes. att.def.ncv(name, value, xtype=null, attlist=null)

3 coord.def.ncv 3 name value xtype attlist The name of the attribute. The attribute value. This can be either a single numeric value or a vector of numeric values, or a character string. One of the predefined NetCDF external data types (NC_BYTE, NC_CHAR, NC_SHORT, NC_INT, NC_FLOAT, NC_DOUBLE). If no type is provided, NC_CHAR, NC_INT, or NC_FLOAT is chosen depending on the type of value. A list of attributes in the format name, value, name, value, etc. The attribute s external type is determined from its value. This function defines a new attribute object. This function is normally not called by the user. Object or list of objects of class att.ncv ## Define some attributes att1 <- att.def.ncv(attlist=list("long_name", "precipitation", "units", "mm d-1", "_Fill", , "grid_mapping", "rotated_pole") ) att2 <- att.def.ncv("_fill", , xtype = "NC_DOUBLE") att3 <- att.def.ncv(attlist=list("long_name", "precipitation", "units", "mm d-1") ) ## Add an attribute object to a list of attribute objects att4 <- append(att3, list(att2)) print.ncv(att1) print.ncv(att4) coord.def.ncv Define a NetCDF Coordinate Define a new NetCDF coordinate variable object. coord.def.ncv(name, data=null, xtype=null, att=null, mvar=null, unlim=false)

4 4 coord.def.ncv name data xtype unlim att mvar Variable name. Must begin with an alphabetic character, followed by zero or more alphanumeric characters including the underscore ( _ ). Case is significant. The (onedimensional) array containing the coordinate values. One of the predefined numeric NetCDF external data types (NC_BYTE, NC_SHORT, NC_INT, NC_FLOAT, NC_DOUBLE). If none is provided, the type is determined automatically from value to one of the follwoing NC_INT, or NC_FLOAT. Set to TRUE if an unlimited dimension should be created, otherwise to FALSE. A list of attribute objects (class att.ncv ), as returned from att.def.ncv. A list of variable objects (class var.ncv ) as returned from var.def.ncv. This function creates a new NetCDF coordinate variable, that is an object of class coord.ncv. A NetCDF coordinate variable is a one-dimensional variable with the same name as its dimension. See var.def.ncv for further information on NetCDF variables. An object of class coord.ncv. ## define some coordinate variables lon <- coord.def.ncv("lon", seq(1,10), xtype="nc_float", att=list("axis", "X", "long_name", "longitude", "units", "degrees_east") ) lat <- coord.def.ncv("lat", 1.*seq(1,5), att=list("axis", "Y", "long_name", "latitude", "units", "degrees_north") ) hgt <- coord.def.ncv("hgt", 0., att=list("axis", "Z", "long_name", "altitude", "units", "metre", "positive", "up") ) time <- coord.def.ncv("time", 0., att=list("axis", "T", "calendar", "standard", "long_name", "time", "units", "days since :00:00.0"), unlim=true) ## define data variable pre <- var.def.ncv("precip", array(1,dim=c(10,5,1,1)), xtype="nc_float", dim=list(lon, lat, hgt, time), att=list("long_name", "precipitation", "units", "mm d-1", "_Fill", ) ) ## write to file var.put.ncv(paste(tempdir(),"/foo.nc",sep=""), pre, new=true)

5 dim.def.ncv 5 dim.def.ncv Define NetCDF Dimension(s) Defines a dimension object containing one or more dimensions. dim.def.ncv(name, value, unlim=false, dimlist=null) name value unlim dimlist The name of the dimension. The dimension length. That is the number of values along this dimension. This must be a positive integer. Set to TRUE if an unlimited dimension should be created, otherwise FALSE. A list of dimensions in the format name, value, name, value, etc. This function defines a new dimension object. This function is normally not called by the user. Object or list of objects of class dim.ncv. ## Define some dimensions dims <- dim.def.ncv(dimlist=list("dimx", 10, "dimy", 20, "time", 2, "max_string_length", 30) ) time <- dim.def.ncv(name="time", unlim=true) dims[[3]] <- time

6 6 print.ncv examples.ncv Executes the example functions. example() Executes the example functions. The examples provide further illustration of how to use this package. To see the code enter the example name without parenthesis, e.g. foo.ncv. List of example functions. foo.ncv() ex.cf5.1.ncv() ex.cf5.2.ncv() ex.cf5.6.ncv() ex.cf7.2.ncv() # default example, used for the help pages # example 5.1 from the CF-conventions # example 5.2 from the CF-conventions # example 5.6 from the CF-conventions # example 7.2 from the CF-conventions print.ncv Print Summary Information About a NetCDF Dataset Print summary information about a NetCDF dataset. print.ncv(x,...) x Object of class var.ncv or att.ncv.... passed to or from other methods (not used)

7 var.def.ncv 7 This function prints information about a NetCDF dataset. This includes a list of all dimensions and their length, a list of all variables and their attributes (including their values) and a list of all global attributes (including their values). The output of this function is almost identical with a "ncdump -h" call. References ## Create example file foo.ncv() ## Read variable temp <- var.get.ncv(paste(tempdir(),"/foo.nc",sep=""), "temperature") print.ncv(temp) var.def.ncv Define a NetCDF Variable Define a new NetCDF variable object. var.def.ncv(name, data=null, xtype=null, start=na, count=na, dim=null, att=null, mvar=null, gatt=null, coord=false, unlim=false) name data xtype start Variable name. Must begin with an alphabetic character, followed by zero or more alphanumeric characters including the underscore ( _ ). Case is significant. The (multidimensional) array containing the data to write. One of the predefined NetCDF external data types (NC_BYTE, NC_CHAR, NC_SHORT, NC_INT, NC_FLOAT, NC_DOUBLE). If none is provided, NC_CHAR, NC_INT, or NC_FLOAT is chosen depending on the type of value. A vector of indices (1-based) indicating where to start writing the passed data. The length of this vector must equal the number of dimensions of the variable.

8 8 var.def.ncv count dim att mvar gatt coord unlim A vector of integers indicating the number of values to write along each dimension. The length of this vector must equal the number of dimensions of the variable. A list of dimension/coordinate objects (class dim.ncv or coord.ncv ), as returned from dim.def.ncv or coord.def.ncv, respectively. A list of attribute objects (class att.ncv ), as returned from att.def.ncv. A list of variable objects (class var.ncv ) as returned from dim.def.ncv. A list of attribute objects (class att.ncv ), as returned from att.def.ncv. For internal use only. For internal use only. This function creates a new variable object including all its associated metadata. Apart from the mandatory dimensions and coordinates, the variables metadata may include attributes and further NetCDF variables such as grid mappings, labels, auxillary coordinate variables, cell boundaries, cell measures, and cell methods. An object of class var.ncv. References ## define coordinate variables rlon <- coord.def.ncv("rlon", seq(1,10), xtype="nc_float", att=list("axis", "X", "standard_name", "grid_longitude", "long_name", "longitude in rotated pole grid", "units", "degrees") ) rlat <- coord.def.ncv("rlat", 1.*seq(1,5), att=list("axis", "Y", "standard_name", "grid_latitude", "long_name", "latitude in rotated pole grid", "units", "degrees") ) hgt <- coord.def.ncv("hgt", 0., att=list("axis", "Z", "long_name", "altitude", "units", "metre", "positive", "up") ) time <- coord.def.ncv("time", 0., att=list("axis", "T", "calendar", "standard", "long_name", "time", "units", "days since :00:00.0"), unlim=true) ## define grid mapping variable #gmap <- var.def.ncv("rotated_pole", 0., # att=list("grid_mapping_name", "rotated_latitude_longitude",

9 var.get.ncv 9 # "grid_north_pole_longitude", -170., # "grid_north_pole_latitude", 32.5) ) ## define data variable pre <- var.def.ncv("precip", array(1., dim=c(10,5,1,1)), xtype="nc_float", dim=list(rlon, rlat, hgt, time), att=list("long_name", "precipitation", "units", "mm d-1", "_Fill", , "grid_mapping", "rotated_pole")) ## write to file var.put.ncv(paste(tempdir(),"/foo.nc",sep=""), pre) var.get.ncv Get a NetCDF Variable Get data and associated metadata of a NetCDF variable. var.get.ncv(path, name, start=na, count=na, mode="attonly", data=true, gatts=false, coord=false, recursion=0, verbose=false) path name start count mode data gatts coord recursion verbose Filename of the NetCDF file to be opened. Name of the variable. A vector of indices indicating where to start reading the values (beginning at 1). The length of this vector must equal the number of dimensions the variable. If not specified (start=na), the entire variable is read. A vector of integers indicating the number of values to read along each dimension. The length of this vector must equal the number of dimensions the variable. If not specified (count=na), the entire variable is read. the read mode, determines which metadata is read. Currently the following modes are supported: nometa, no additional metadata is returned; attonly, the variables attributes are returned; netcdf, the coordinate variables as defined by the NetCDF user guide and associated attributes are returned; cf, all coordinate related variables and associated attributes are returned (coordinate and auxillary coordinate variables, grid mapping variables); cf-full, all metadata associated with the variable as defined in the CF-conventions is returned. Set to FALSE, if only metadata should be read. Set to TRUE, if global attributes should be read. For internal use only. For internal use only. For internal use only.

10 10 var.put.ncv This function returns the data and associated metadata of a variable. If the read procedure fails (e.g., no variable with the corresponding name), NULL is returned. Returned data are either of type R integer or R double precision. s of NA are supported; values in the data file that match the variable s missing value attribute (_FillValule) are automatically converted to NA before being returned to the user. Data in a NetCDF file is conceived as being a multi-dimensional array. The number and length of dimensions is determined when the variable is created. The start and count indices that this routine takes indicate where the reading starts along each dimension, and the count of values along each dimension to read. Note that the order of dimensions is consistent with the R conventions (the first dimension varies fastest), but opposite to the CDL conventions. An object of class var.ncv, including the variables data and metadata. References ## Reads a variable and associated metadata from the file created with ## foo.ncv() foo.ncv() pre <- var.get.ncv(paste(tempdir(),"/foo.nc",sep=""), "temperature") var.put.ncv Put a NetCDF Variable Put data and associated metadata of a NetCDF variable. var.put.ncv(path, var, new=true, define=true, data=true, recursion=0, verbose=false)

11 var.put.ncv 11 path var new define data recursion verbose Filename of the NetCDF file to be created/opened. The variable object (class var.ncv ), as returned from var.def.ncv. Set to TRUE if a new file should be created, otherwise an exisiting file will be opened for writing. If TRUE, define the data and associated metadata (NetCDF define mode). Set to FALSE, if the variables already have been defined. If TRUE, write the data to the file (NetCDF data mode). Set to FALSE, if no data should be written. For internal use only. For internal use only. This function writes the data and and associated metadata of a variable to a NetCDF file. Type conversion is done by the NetCDF library itself. Special treatment is necessary for the R type character. When writing values of type NC_CHAR, it is mandatory that the first element of count contains the value of this dimension s length (usually max_string_length), the maximum string length is given by this value. R arrays of type character need therefore one additional dimension when written to a NetCDF dataset. s of NA are supported if the variable s missing value attribute (missing_value or _Fill) is set. They are converted to the corresponding value before written to disk. Data in a NetCDF file is conceived as being a multi-dimensional array. The number and length of dimensions is determined when the variable is created. The start and count indices that this routine takes indicate where the writing starts along each dimension, and the count of values along each dimension to write. Note that the order of dimensions is consistent with the R conventions (the first dimension varies fastest), but opposite to the CDL conventions. Note NC_BYTE is always interpreted as signed. References ## Copy data from one file to another foo.ncv() temp <- var.get.ncv(paste(tempdir(),"/foo.nc",sep=""), "temperature", mode="cf") var.put.ncv(paste(tempdir(),"/foo2.nc",sep=""), temp)

12 12 att.get.ncv att.get.ncv Get NetCDF Attributes (internal) Get all attributes for a given variable. For internal use only. att.get.ncv(ncfile, variable, natts) ncfile variable natts Object of class NetCDF, returned from open.nc. ID or name of the variable from which the attribute will be read, or NC_GLOBAL for the global attributes. The number of attributes to be read. Get all attributes for a given variable. For internal use only. List of objects of class att.ncv. An empty list if no attributes exist. ## Create example file foo.ncv() ## Open file nc <- open.nc(paste(tempdir(),"/foo.nc",sep="")) ## Get attribute att <- att.get.ncv(nc, "temperature", 1) close.nc(nc)

13 att.put.ncv 13 att.put.ncv Put NetCDF Attributes (internal) Writes all attributes for a given variable. For internal use only. att.put.ncv(ncfile, variable, att) ncfile variable att Object of class NetCDF, returned from open.nc. ID or name of the variable for which the attributes will be written, or NC_GLOBAL for the global attributes. List of objects of class att.ncv. Writes all attributes for a given variable. For internal use only. att.val.ncv Get NetCDF Attributes (internal) Get the value of an attribute. For internal use only. att.val.ncv(att, name) att name A list of objects of class att.ncv. The name of the attribute.

14 14 dim.get.ncv Get the value of an attribute. For internal use only. The attribute value. NULL if the attributes does not exist. ## Create example file foo.ncv() ## Open file nc <- open.nc(paste(tempdir(),"/foo.nc",sep="")) ## Get attribute att <- att.get.ncv(nc, "temperature", 1) att.val.ncv(att, "missing_value") close.nc(nc) dim.get.ncv Get NetCDF Dimensions (internal) Get a dimension of a given variable. For internal use only. dim.get.ncv(ncfile, dimension) ncfile dimension Object of class NetCDF, returned from open.nc. ID or name of the dimension. Get a dimension of a given variable. For internal use only. Object of class dim.ncv. NULL for a scalar variable.

15 dim.put.ncv 15 ## Create example file foo.ncv() ## Open file nc <- open.nc(paste(tempdir(),"/foo.nc",sep="")) ## Get dimension (id=0) dim <- dim.get.ncv(nc, 0) close.nc(nc) dim.put.ncv Put NetCDF Dimension (internal) Create a NetCDF dimension on file. For internal use only. dim.put.ncv(ncfile, dim) ncfile dim Object of class NetCDF, returned from open.nc. Object of class dim.ncv. Create a NetCDF dimension on file. For internal use only. ## Create example file foo.ncv() ## Open file nc <- open.nc(paste(tempdir(),"/foo.nc",sep=""), write=true) ## Get dimension (id=0) dim <- dim.get.ncv(nc, 0) ## Write new dimension

16 16 dim.val.ncv dim$name <- "newdim" dim.put.ncv(nc, dim) close.nc(nc) dim.val.ncv Get NetCDF Dimension Lengths (internal) Get the lengths of all NetCDF dimensions for a given variable. For internal use only. dim.val.ncv(dim) dim Object of class dim.ncv. Return a vector containing the lengths of all NetCDF dimensions for a given variable. For internal use only. A vector of dimension lengths. ## Define some dimensions dim <- dim.def.ncv(dimlist=list("lon", 5, "lat", 10, "height", 30) ) len <- dim.val.ncv(dim)

17 xtype.ncv 17 xtype.ncv External NetCDF Data Type (internal) Determine the default external NetCDF data type. For internal use only. xtype.ncv(value) value An R object. Determine the default external NetCDF data type. The default types are NC_INT, NC_FLOAT, and NC_CHAR. For internal use only. A string specifying the external data type. val <- vector(1, mode="integer") print(xtype.ncv(val)) val <- vector(2, mode="numeric") print(xtype.ncv(val)) val <- vector(3, mode="character") print(xtype.ncv(val)) ncvar-internal.ncv Further internal ncvar functions Further internal ncvar functions. These are not to be called by the user.

18 Index Topic file att.def.ncv, 2 coord.def.ncv, 3 dim.def.ncv, 4 examples.ncv, 5 ncvar, 1 print.ncv, 6 var.def.ncv, 7 var.get.ncv, 8 var.put.ncv, 10 Topic internal att.get.ncv, 11 att.put.ncv, 12 att.val.ncv, 13 dim.get.ncv, 14 dim.put.ncv, 15 dim.val.ncv, 16 ncvar-internal.ncv, 17 xtype.ncv, 16 open.nc, 11, 12, 14, 15 print.ncv, 6 print.var.ncv (ncvar-internal.ncv), 17 var.def.ncv, 3, 4, 7, 10 var.get.ncv, 8 var.inq.ncv (ncvar-internal.ncv), 17 var.put.ncv, 10 xtype.ncv, 16 xtype2str.ncv (ncvar-internal.ncv), 17 att.def.ncv, 2, 3, 7 att.get.ncv, 11 att.inq.ncv (ncvar-internal.ncv), 17 att.put.ncv, 12 att.val.ncv, 13 coord.def.ncv, 3, 7 dim.def.ncv, 4, 7 dim.get.ncv, 14 dim.put.ncv, 15 dim.val.ncv, 16 ex.cf5.1.ncv (examples.ncv), 5 ex.cf5.2.ncv (examples.ncv), 5 ex.cf5.6.ncv (examples.ncv), 5 ex.cf7.2.ncv (examples.ncv), 5 ex.pavel.ncv (examples.ncv), 5 examples, 2 examples.ncv, 5 foo.ncv (examples.ncv), 5 ncvar, 1 ncvar-internal.ncv, 17 18