R: Define a NetCDF Type

type.def.nc {RNetCDF} | R Documentation

## 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.

### 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.

### Value

NetCDF type identifier, returned invisibly.

### Author(s)

Pavel Michna, Milton Woods

### References

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

### Examples

    ##  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)

[Package RNetCDF version 2.4-2 Index]