R: Write Data to a NetCDF Variable

var.put.nc {RNetCDF} | R Documentation

## Write Data to a NetCDF Variable

### Description

Write the contents of a NetCDF variable.

### Usage

    var.put.nc(ncfile, variable, data, start=NA, count=NA, na.mode=4, pack=FALSE,
      cache_bytes=NA, cache_slots=NA, cache_preemption=NA)

### Arguments

`ncfile` | Object of class "`NetCDF`" which points to the NetCDF dataset (as returned from `open.nc`).
`variable` | ID or name of the NetCDF variable.
`data` | An R vector or array of data to be written to the NetCDF variable. Values are taken from `data` in the order of R vector elements, so that leftmost indices vary fastest over an array.
`start` | A vector of indices specifying the element where writing starts along each dimension of `variable`. Indices are numbered from 1 onwards, and the order of dimensions is shown by `print.nc` (array elements are stored sequentially with leftmost indices varying fastest). By default (`start=NA`), all dimensions of `variable` are written from the first element onwards. Otherwise, `start` must be a vector whose length is not less than the number of dimensions in `variable` (excess elements are ignored). Any `NA` values in vector `start` are set to 1.
`count` | A vector of integers specifying the number of values to write along each dimension of `variable`. The order of dimensions is the same as for `start`. By default (`count=NA`), `count` is set to `dim(data)` for an array or `length(data)` for a vector. Otherwise, `count` must be a vector whose length is not less than the number of dimensions in `variable` (excess elements are ignored). Any `NA` value in vector `count` indicates that the corresponding dimension should be written from the `start` index to the end of the dimension. Note that an unlimited dimension initially has zero length, and the dimension is extended by setting the corresponding element of `count` greater than the current length.
`na.mode` | Set the mode for handling missing values (`NA`) in numeric variables: 0=accept `_FillValue`, then `missing_value` attribute; 1=accept only `_FillValue` attribute; 2=accept only `missing_value` attribute; 3=no missing value conversion; 4=valid range from valid_min and valid_max or valid_range, fill value from _FillValue, with defaults for each type except `NC_BYTE` and `NC_UBYTE` (see https://www.unidata.ucar.edu/software/netcdf/docs/attribute_conventions.html).
`pack` | Variables are packed if `pack=TRUE` and the attributes `add_offset` and `scale_factor` are defined. Default is `FALSE`.

The arguments below apply only to datasets in "netcdf4" format. Reading and writing of variables involves a "chunk cache", and default cache settings are defined by the NetCDF library. Performance may be improved in some applications by adjusting the cache settings through the following options:

`cache_bytes` | Size of chunk cache in bytes. Value of `NA` (default) implies no change.
`cache_slots` | Number of slots in chunk cache. Value of `NA` (default) implies no change.
`cache_preemption` | Value between 0 and 1 (inclusive) that biases the cache scheme towards eviction of chunks that have been fully read. Value of `NA` (default) implies no change.

### Details

This function writes values to a NetCDF variable. Data values in R are automatically converted to the correct type of NetCDF variable.

Text represented by R type `character` can be written to NetCDF types `NC_CHAR` and `NC_STRING`, and R type `raw` can be written to NetCDF type `NC_CHAR`. When writing to `NC_CHAR` variables, `character` variables have an implied dimension corresponding to the string length. This implied dimension must be defined explicitly as the fastest-varying dimension of the `NC_CHAR` variable, and it must be included as the first element of arguments `start` and `count` taken by this function.

Due to the lack of native support for 64-bit integers in R, NetCDF types `NC_INT64` and `NC_UINT64` require special attention. This function accepts the usual R `integer` (signed 32-bit) and `numeric` (double precision) types, but to represent integers larger than about 53-bits without truncation, \codeinteger64 vectors are also supported.

NetCDF numeric variables cannot portably represent `NA` values from R. NetCDF does allow attributes to be defined for variables, and several conventions exist for attributes that define missing values and valid ranges. The convention in use can be specified by argument `na.mode`. Values of `NA` in argument `data` are converted to a missing or fill value before writing to the NetCDF variable. Unusual cases can be handled directly in user code by setting `na.mode=3`.

Variables of user-defined types are supported, subject to conditions on the corresponding data structures in R. "compound" arrays must be stored in R as lists, with items named for the compound fields; items of base NetCDF data types are stored as R arrays, with leading dimensions from the field dimensions (if any) and trailing dimensions from the NetCDF variable. "enum" arrays are stored in R as factor arrays. "opaque" arrays are stored in R as raw (byte) arrays, with a leading dimension for bytes of the opaque type and trailing dimensions from the NetCDF variable. "vlen" arrays are stored in R as a list with dimensions of the NetCDF variable; items in the list may have different lengths; base NetCDF data types are stored as R vectors.

To reduce the storage space required by a NetCDF file, numeric variables can be "packed" into types of lower precision. The packing operation involves subtraction of attribute `add_offset` before division by attribute `scale_factor`. This packing operation is performed automatically for variables defined with the two attributes `add_offset` and `scale_factor` if argument `pack` is set to `TRUE`. If `pack` is `FALSE`, `data` values are assumed to be packed correctly and are written to the variable without alteration.

Data in a NetCDF variable is represented as a multi-dimensional array. The number and length of dimensions is determined when the variable is created. The `start` and `count` arguments of this routine indicate where the writing starts and the number of values to write along each dimension.

Awkwardness arises mainly from one thing: NetCDF data are written with the last dimension varying fastest, whereas R works opposite. Thus, the order of the dimensions according to the CDL conventions (e.g., time, latitude, longitude) is reversed in the R array (e.g., longitude, latitude, time).

### Note

`NC_BYTE` is always interpreted as signed. For best performance, it is recommended that the definition of dimensions, variables and attributes is completed before variables are read or written.

### Author(s)

Pavel Michna, Milton Woods

### References

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

### Examples

    ##  Create a new NetCDF dataset and define two dimensions
    file1 <- tempfile("var.put_", fileext=".nc")
    nc <- create.nc(file1)

    dim.def.nc(nc, "station", 5)
    dim.def.nc(nc, "time", unlim=TRUE)
    dim.def.nc(nc, "max_string_length", 32)

    ##  Create three variables, one as coordinate variable
    var.def.nc(nc, "time", "NC_INT", "time")
    var.def.nc(nc, "temperature", "NC_DOUBLE", c(0,1))
    var.def.nc(nc, "name", "NC_CHAR", c("max_string_length", "station"))

    ##  Put some _FillValue attribute for temperature
    att.put.nc(nc, "temperature", "_FillValue", "NC_DOUBLE", -99999.9)

    ##  Define variable values
    mytime        <- c(1:2)
    mytemperature <- c(1.1, 2.2, 3.3, 4.4, 5.5, 6.6, 7.7, NA, NA, 9.9)
    myname        <- c("alfa", "bravo", "charlie", "delta", "echo")

    dim(mytemperature) <- c(5,2)

    ##  Put subsets of the data:
    var.put.nc(nc, "time", mytime, start=2, count=1)
    var.put.nc(nc, "temperature", mytemperature[3:4,2], start=c(3,2), count=c(2,1))
    var.put.nc(nc, "name", myname[3:4], start=c(NA,3), count=c(NA,2))
    sync.nc(nc)

    ##  Put all of the data:
    var.put.nc(nc, "time", mytime)
    var.put.nc(nc, "temperature", mytemperature)
    var.put.nc(nc, "name", myname)

    close.nc(nc)
    unlink(file1)

[Package RNetCDF version 2.4-2 Index]