RNetCDF (version 2.4-2)

type.def.nc: Define a NetCDF Type

Description

Define complex data structures based on existing NetCDF data types.

Usage

type.def.nc(ncfile, typename, class, size=NULL, basetype=NULL,
            names=NULL, values=NULL, subtypes=NULL, dimsizes=NULL)

Arguments

ncfile

Object of class "NetCDF" which points to the NetCDF dataset (as returned from open.nc).

typename

Name to identify the new data type. Must begin with an alphabetic character, followed by zero or more alphanumeric characters including the underscore ("_"). Case is significant.

class

One of the keywords "compound", "enum", "opaque" or "vlen".

size

("opaque") Size in bytes of a single item of the opaque type.

basetype

("enum" or "vlen") Base type, given as the name or identifier of an existing NetCDF type. Only built-in integer types (e.g. "NC_INT") are allowed for class "enum".

names

("compound" or "enum") Name of each field or member (character vector).

values

("enum") Numeric value of each member (numeric vector).

subtypes

("compound") NetCDF type of each field, given by name (character vector) or identifier (numeric vector).

dimsizes

("compound") Array dimensions of each field, specified as a list of numeric vectors. Dimensions are given in R order (leftmost index varies fastest; opposite to CDL conventions). If a list item is NULL, the corresponding field is a scalar.

Value

NetCDF type identifier, returned invisibly.

Details

User-defined types are supported by files in "netcdf4" format. This function creates a new NetCDF data type, which can be used in definitions of NetCDF variables and attributes.

Several varieties of data type are supported, as specified by argument class:

"compound"	Combines atomic and user-defined types into C-like structs.
"enum"	Set of named integer values, similar to an R factor.
"opaque"	Blobs of arbitrary data with a given size.
"vlen"	Variable length vectors of a given base type.

type.def.nc may be repeated to insert additional members of an "enum" type or fields of a "compound" type. However, the size of a "compound" type is calculated from the fields specified when it is first defined, and later insertion of fields will only succeed if there is sufficient free space after the last field. Existing fields/members cannot be modified, and types cannot be removed from a dataset.

References

https://www.unidata.ucar.edu/software/netcdf/

Examples

# NOT RUN {
##  Create a new NetCDF4 dataset and define types
file1 <- tempfile("type.def_", fileext=".nc")
nc <- create.nc(file1, format="netcdf4")

# Compound type:
type.def.nc(nc, "astruct", "compound",
            names=c("siteid", "height", "colour"),
            subtypes=c("NC_INT", "NC_DOUBLE", "NC_SHORT"),
            dimsizes=list(NULL, NULL, c(3)))

# Enum type:
type.def.nc(nc, "afactor", "enum", basetype="NC_INT",
            names=c("peanut butter", "jelly"),
            values=c(101,102))

# Opaque type:
type.def.nc(nc, "ablob", "opaque", size=128)

# Vlen type:
type.def.nc(nc, "avector", "vlen", basetype="NC_FLOAT")

close.nc(nc)
unlink(file1)
# }