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=0, pack=FALSE)

### 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` or `missing_value` attribute, 1=accept only `_FillValue` attribute, 2=accept only `missing_value` attribute.
`pack` | Variables are packed if `pack=TRUE` and the attributes `add_offset` and `scale_factor` are defined. Default is `FALSE`.

### Details

This function writes values to a NetCDF variable. Type conversion is performed by the NetCDF library, so that numeric values in R are automatically converted to the correct type of NetCDF variable.

However, text represented by R types `raw` and `character` can only be written to NetCDF type `NC_CHAR`. The dimensions of R `raw` variables map directly to NetCDF dimensions, but `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.

Values of `NA` are supported in numeric variables if the variable's missing value attribute (as defined in `na.mode`) is set. They are converted to the corresponding value before writing to disk. If `na.mode=0` and both attributes are defined, the value of `_FillValue` is used.

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

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

### Examples

    ##  Create a new NetCDF dataset and define two dimensions
    nc <- create.nc("var.put.nc")

    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 missing_value attribute for temperature
    att.put.nc(nc, "temperature", "missing_value", "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)

[Package RNetCDF version 1.9-1 Index]