Title: | Interface to 'NetCDF' Datasets |
---|---|
Description: | An interface to the 'NetCDF' file formats designed by Unidata for efficient storage of array-oriented scientific data and descriptions. Most capabilities of 'NetCDF' version 4 are supported. Optional conversions of time units are enabled by 'UDUNITS' version 2, also from Unidata. |
Authors: | Pavel Michna [aut], Milton Woods [aut, cre] |
Maintainer: | Milton Woods <[email protected]> |
License: | GPL (>= 2) | file LICENSE |
Version: | 2.9-2 |
Built: | 2024-08-27 04:51:53 UTC |
Source: | https://github.com/mjwoods/rnetcdf |
Copy attribute from one NetCDF to another.
att.copy.nc(ncfile.in, variable.in, attribute, ncfile.out, variable.out)
att.copy.nc(ncfile.in, variable.in, attribute, ncfile.out, variable.out)
ncfile.in |
Object of class |
variable.in |
ID or name of the variable in the input NetCDF dataset from which the attribute will be copied, or |
attribute |
Name or ID of the attribute in the input NetCDF dataset to be copied. |
ncfile.out |
Object of class |
variable.out |
ID or name of the variable in the output NetCDF dataset to which the attribute will be copied, or |
This function copies an attribute from one open NetCDF dataset to another. It can also be used to copy an attribute from one variable to another within the same NetCDF dataset.
Valid attribute ID numbers range from 0 to the number of attributes minus 1. The number of attributes of a file, group, or variable can be found using the relevant inquiry function (file.inq.nc
, grp.inq.nc
, or var.inq.nc
).
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## Create two new NetCDF datasets and define two dimensions file1 <- tempfile("att.copy_", fileext=".nc") file2 <- tempfile("att.copy_", fileext=".nc") nc.1 <- create.nc(file1) nc.2 <- create.nc(file2) dim.def.nc(nc.1, "station", 5) dim.def.nc(nc.1, "time", unlim=TRUE) dim.def.nc(nc.2, "station", 5) dim.def.nc(nc.2, "time", unlim=TRUE) ## Create two variables, one as coordinate variable var.def.nc(nc.1, "time", "NC_INT", "time") var.def.nc(nc.1, "temperature", "NC_DOUBLE", c(0,1)) var.def.nc(nc.2, "time", "NC_INT", "time") var.def.nc(nc.2, "temperature", "NC_DOUBLE", c(0,1)) ## Put some attributes to the first dataset att.put.nc(nc.1, "temperature", "_FillValue", "NC_DOUBLE", -99999.9) att.put.nc(nc.1, "NC_GLOBAL", "title", "NC_CHAR", "Data from Foo") ## Copy the attributes to the second dataset att.copy.nc(nc.1, 1, 0, nc.2, 1) att.copy.nc(nc.1, "NC_GLOBAL", "title", nc.2, "NC_GLOBAL") close.nc(nc.1) close.nc(nc.2) unlink(file1) unlink(file2)
## Create two new NetCDF datasets and define two dimensions file1 <- tempfile("att.copy_", fileext=".nc") file2 <- tempfile("att.copy_", fileext=".nc") nc.1 <- create.nc(file1) nc.2 <- create.nc(file2) dim.def.nc(nc.1, "station", 5) dim.def.nc(nc.1, "time", unlim=TRUE) dim.def.nc(nc.2, "station", 5) dim.def.nc(nc.2, "time", unlim=TRUE) ## Create two variables, one as coordinate variable var.def.nc(nc.1, "time", "NC_INT", "time") var.def.nc(nc.1, "temperature", "NC_DOUBLE", c(0,1)) var.def.nc(nc.2, "time", "NC_INT", "time") var.def.nc(nc.2, "temperature", "NC_DOUBLE", c(0,1)) ## Put some attributes to the first dataset att.put.nc(nc.1, "temperature", "_FillValue", "NC_DOUBLE", -99999.9) att.put.nc(nc.1, "NC_GLOBAL", "title", "NC_CHAR", "Data from Foo") ## Copy the attributes to the second dataset att.copy.nc(nc.1, 1, 0, nc.2, 1) att.copy.nc(nc.1, "NC_GLOBAL", "title", nc.2, "NC_GLOBAL") close.nc(nc.1) close.nc(nc.2) unlink(file1) unlink(file2)
Delete a NetCDF attribute.
att.delete.nc(ncfile, variable, attribute)
att.delete.nc(ncfile, variable, attribute)
ncfile |
Object of class |
variable |
ID or name of the attribute's variable, or |
attribute |
The name or ID of the attribute to be deleted. |
This function deletes a NetCDF attribute from a NetCDF dataset open for writing.
Valid attribute ID numbers range from 0 to the number of attributes minus 1. The number of attributes of a file, group, or variable can be found using the relevant inquiry function (file.inq.nc
, grp.inq.nc
, or var.inq.nc
).
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("att.delete_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Create two variables, one as coordinate variable var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(nc, "temperature", "NC_DOUBLE", c(0,1)) ## Put some attributes att.put.nc(nc, "temperature", "_FillValue", "NC_DOUBLE", -99999.9) att.put.nc(nc, "NC_GLOBAL", "title", "NC_CHAR", "Data from Foo") ## Delete these attributes att.delete.nc(nc, "temperature", "_FillValue") att.delete.nc(nc, "NC_GLOBAL", "title") close.nc(nc) unlink(file1)
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("att.delete_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Create two variables, one as coordinate variable var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(nc, "temperature", "NC_DOUBLE", c(0,1)) ## Put some attributes att.put.nc(nc, "temperature", "_FillValue", "NC_DOUBLE", -99999.9) att.put.nc(nc, "NC_GLOBAL", "title", "NC_CHAR", "Data from Foo") ## Delete these attributes att.delete.nc(nc, "temperature", "_FillValue") att.delete.nc(nc, "NC_GLOBAL", "title") close.nc(nc) unlink(file1)
Get an attribute from a NetCDF dataset.
att.get.nc(ncfile, variable, attribute, rawchar=FALSE, fitnum=FALSE)
att.get.nc(ncfile, variable, attribute, rawchar=FALSE, fitnum=FALSE)
ncfile |
Object of class |
|||||||||||||||||||||
variable |
ID or name of the variable from which the attribute will be read, or |
|||||||||||||||||||||
attribute |
Attribute name or ID. |
|||||||||||||||||||||
rawchar |
This option only relates to NetCDF attributes of type |
|||||||||||||||||||||
fitnum |
By default, all numeric variables are read into R as double precision values. When
|
This function returns the value of the attribute.
Vector with a data type that depends on the NetCDF variable. For NetCDF variables of type NC_CHAR
, the R type is either character
or raw
, as specified by argument rawchar
. For NC_STRING
, the R type is character
. Numeric variables are read as double precision by default, but the smallest R type that exactly represents each external type is used if fitnum
is TRUE
.
Valid attribute ID numbers range from 0 to the number of attributes minus 1. The number of attributes of a file, group, or variable can be found using the relevant inquiry function (file.inq.nc
, grp.inq.nc
, or var.inq.nc
).
NC_BYTE
is always interpreted as signed.
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("att.get_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Create two variables, one as coordinate variable var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(nc, "temperature", "NC_DOUBLE", c(0,1)) ## Put some attributes att.put.nc(nc, "temperature", "_FillValue", "NC_DOUBLE", -99999.9) att.put.nc(nc, "temperature", "long_name", "NC_CHAR", "air temperature") att.put.nc(nc, "NC_GLOBAL", "title", "NC_CHAR", "Data from Foo") att.put.nc(nc, "NC_GLOBAL", "history", "NC_CHAR", paste("Created on", date())) ## Get these attributes att.get.nc(nc, "temperature", "_FillValue") att.get.nc(nc, "temperature", "long_name") att.get.nc(nc, "NC_GLOBAL", "title") att.get.nc(nc, "NC_GLOBAL", "history") close.nc(nc) unlink(file1)
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("att.get_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Create two variables, one as coordinate variable var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(nc, "temperature", "NC_DOUBLE", c(0,1)) ## Put some attributes att.put.nc(nc, "temperature", "_FillValue", "NC_DOUBLE", -99999.9) att.put.nc(nc, "temperature", "long_name", "NC_CHAR", "air temperature") att.put.nc(nc, "NC_GLOBAL", "title", "NC_CHAR", "Data from Foo") att.put.nc(nc, "NC_GLOBAL", "history", "NC_CHAR", paste("Created on", date())) ## Get these attributes att.get.nc(nc, "temperature", "_FillValue") att.get.nc(nc, "temperature", "long_name") att.get.nc(nc, "NC_GLOBAL", "title") att.get.nc(nc, "NC_GLOBAL", "history") close.nc(nc) unlink(file1)
Inquire about a NetCDF attribute.
att.inq.nc(ncfile, variable, attribute)
att.inq.nc(ncfile, variable, attribute)
ncfile |
Object of class |
variable |
Either the ID or the name of the attribute's variable or |
attribute |
Either the ID or the name of the attribute to be inquired. |
This function returns information about a NetCDF attribute. Information about an attribute include its ID, its name, its type, and its length. In general, attributes are accessed by name rather than by their ID number because the attribute number is more volatile than the name, since it can change when other attributes of the same variable are deleted.
Valid attribute ID numbers range from 0 to the number of attributes minus 1. The number of attributes of a file, group, or variable can be found using the relevant inquiry function (file.inq.nc
, grp.inq.nc
, or var.inq.nc
).
A list containing the following components:
id |
Attribute ID. |
name |
Attribute name. |
type |
External NetCDF data type as one of the following labels: |
length |
Length of this attribute. |
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("att.inq_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Create two variables, one as coordinate variable var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(nc, "temperature", "NC_DOUBLE", c(0,1)) ## Put some attributes att.put.nc(nc, "temperature", "_FillValue", "NC_DOUBLE", -99999.9) att.put.nc(nc, "NC_GLOBAL", "title", "NC_CHAR", "Data from Foo") ## Inquire about these attributes att.inq.nc(nc, "temperature", "_FillValue") att.inq.nc(nc, "NC_GLOBAL", "title") close.nc(nc) unlink(file1)
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("att.inq_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Create two variables, one as coordinate variable var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(nc, "temperature", "NC_DOUBLE", c(0,1)) ## Put some attributes att.put.nc(nc, "temperature", "_FillValue", "NC_DOUBLE", -99999.9) att.put.nc(nc, "NC_GLOBAL", "title", "NC_CHAR", "Data from Foo") ## Inquire about these attributes att.inq.nc(nc, "temperature", "_FillValue") att.inq.nc(nc, "NC_GLOBAL", "title") close.nc(nc) unlink(file1)
Put an attribute to a NetCDF dataset.
att.put.nc(ncfile, variable, name, type, value)
att.put.nc(ncfile, variable, name, type, value)
ncfile |
Object of class |
variable |
ID or name of the variable to which the attribute will be assigned or |
name |
Attribute name. Must begin with an alphabetic character, followed by zero or more alphanumeric characters including the underscore ( |
type |
External NetCDF data type as one of the following labels: |
value |
Attribute value. This can be either a single numeric value or a vector of numeric values, or alternatively a character string. |
Names commencing with underscore ("_"
) are reserved for use by the NetCDF library. Most generic applications that process NetCDF datasets assume standard attribute conventions and it is strongly recommended that these be followed unless there are good reasons for not doing so.
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
.
R numeric
and integer
variables can be written to NetCDF numeric types. The NetCDF library handles type conversions, but conversions of values outside the range of a type will result in an error. Due to the lack of native support for 64-bit integers in R, this function accepts integer64
vectors.
NC_BYTE
is always interpreted as signed.
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("att.put_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Create two variables, one as coordinate variable var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(nc, "temperature", "NC_DOUBLE", c(0,1)) ## Put some attributes att.put.nc(nc, "temperature", "_FillValue", "NC_DOUBLE", -99999.9) att.put.nc(nc, "temperature", "long_name", "NC_CHAR", "air temperature") att.put.nc(nc, "NC_GLOBAL", "title", "NC_CHAR", "Data from Foo") att.put.nc(nc, "NC_GLOBAL", "history", "NC_CHAR", paste("Created on", date())) close.nc(nc) unlink(file1)
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("att.put_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Create two variables, one as coordinate variable var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(nc, "temperature", "NC_DOUBLE", c(0,1)) ## Put some attributes att.put.nc(nc, "temperature", "_FillValue", "NC_DOUBLE", -99999.9) att.put.nc(nc, "temperature", "long_name", "NC_CHAR", "air temperature") att.put.nc(nc, "NC_GLOBAL", "title", "NC_CHAR", "Data from Foo") att.put.nc(nc, "NC_GLOBAL", "history", "NC_CHAR", paste("Created on", date())) close.nc(nc) unlink(file1)
Rename a NetCDF attribute.
att.rename.nc(ncfile, variable, attribute, newname)
att.rename.nc(ncfile, variable, attribute, newname)
ncfile |
Object of class |
variable |
ID or name of the attribute's variable, or |
attribute |
The current attribute name or ID. |
newname |
The new name to be assigned to the specified attribute. |
This function changes the name of an existing attribute in a NetCDF dataset open for writing. An attribute cannot be renamed to have the same name as another attribute of the same variable.
Valid attribute ID numbers range from 0 to the number of attributes minus 1. The number of attributes of a file, group, or variable can be found using the relevant inquiry function (file.inq.nc
, grp.inq.nc
, or var.inq.nc
).
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("att.rename_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Create two variables, one as coordinate variable var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(nc, "temperature", "NC_DOUBLE", c(0,1)) ## Put some attributes att.put.nc(nc, "temperature", "_FillValue", "NC_DOUBLE", -99999.9) att.put.nc(nc, "NC_GLOBAL", "title", "NC_CHAR", "Data from Foo") ## Rename these attributes att.rename.nc(nc, "temperature", "_FillValue", "my__FillValue") att.rename.nc(nc, "NC_GLOBAL", "title", "my_title") close.nc(nc) unlink(file1)
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("att.rename_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Create two variables, one as coordinate variable var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(nc, "temperature", "NC_DOUBLE", c(0,1)) ## Put some attributes att.put.nc(nc, "temperature", "_FillValue", "NC_DOUBLE", -99999.9) att.put.nc(nc, "NC_GLOBAL", "title", "NC_CHAR", "Data from Foo") ## Rename these attributes att.rename.nc(nc, "temperature", "_FillValue", "my__FillValue") att.rename.nc(nc, "NC_GLOBAL", "title", "my_title") close.nc(nc) unlink(file1)
Close an open NetCDF dataset.
close.nc(con, ...)
close.nc(con, ...)
con |
Object of class |
... |
Arguments passed to or from other methods (not used). |
This function closes an open NetCDF dataset. After an open NetCDF dataset is closed, its NetCDF ID may be reassigned to the next NetCDF dataset that is opened or created. Therefore, the passed object (ncfile
) should be deleted by the user after calling this function.
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## Create a void NetCDF dataset file1 <- tempfile("close_", fileext=".nc") nc <- create.nc(file1) close.nc(nc) unlink(file1)
## Create a void NetCDF dataset file1 <- tempfile("close_", fileext=".nc") nc <- create.nc(file1) close.nc(nc) unlink(file1)
Find NetCDF options detected when installing RNetCDF.
config.nc()
config.nc()
This function is not intended for user code, and it is subject to change or removal without notice. It is currently needed for RNetCDF package tests, to determine expected behaviour of the NetCDF C library.
Unless otherwise documented, optional NetCDF features that are not detected when installing RNetCDF will raise an error when called from R code. If necessary, work arounds can be implemented by wrapping the relevant code in try
or tryCatch
.
Pavel Michna, Milton Woods
Create a new NetCDF dataset.
create.nc(filename, clobber=TRUE, share=FALSE, prefill=TRUE, format="classic", large=FALSE, diskless=FALSE, persist=FALSE, mpi_comm=NULL, mpi_info=NULL)
create.nc(filename, clobber=TRUE, share=FALSE, prefill=TRUE, format="classic", large=FALSE, diskless=FALSE, persist=FALSE, mpi_comm=NULL, mpi_info=NULL)
filename |
Filename for the NetCDF dataset to be created. |
clobber |
The creation mode. If |
share |
The buffer scheme. If |
prefill |
The prefill mode. If |
format |
The file format. One of |
large |
(Deprecated) |
diskless |
When |
persist |
When |
mpi_comm |
Fortran handle of MPI communicator for parallel I/O. The default of |
mpi_info |
Fortran handle of MPI Info object for parallel I/O. The default value |
This function creates a new NetCDF dataset, returning an object of class NetCDF
that can be used in R.
The file format is specified by the format
argument, which may take the following values:
"classic"
(default) Original netcdf file format, still widely used and recommended for maximum portability of datasets. Uses a signed 32-bit offset in its internal structures, so files larger than 2GB can only be created under limited conditions.
"offset64"
64-bit offset extension of original format, introduced by netcdf-3.6. Allows larger files and variables than "classic"
format, but there remain some restrictions on files larger than 2GB.
"data64"
Extension of "classic"
format to support large files (i.e. over 2GB) and large variables (over 2B array elements). This format was introduced in netcdf-4.4.0.
"netcdf4"
Netcdf in an HDF5 container, introduced by netcdf-4.0. Allows dataset sizes up to filesystem limits, and extends the feature set of the older formats.
"classic4"
Same file format as "netcdf4"
, but this option ensures that only classic netcdf data structures are stored in the file for compatibility with older software (when linked with the netcdf4 library).
Object of class NetCDF
which points to the NetCDF dataset, returned invisibly.
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## Create empty NetCDF datasets with different formats file1 <- tempfile("create3_", fileext=".nc") nc <- create.nc(file1) close.nc(nc) unlink(file1) file2 <- tempfile("create64_", fileext=".nc") nc2 <- create.nc(file2,format="offset64") close.nc(nc2) unlink(file2) file3 <- tempfile("create4_", fileext=".nc") nc3 <- create.nc(file3,format="netcdf4") close.nc(nc3) unlink(file3)
## Create empty NetCDF datasets with different formats file1 <- tempfile("create3_", fileext=".nc") nc <- create.nc(file1) close.nc(nc) unlink(file1) file2 <- tempfile("create64_", fileext=".nc") nc2 <- create.nc(file2,format="offset64") close.nc(nc2) unlink(file2) file3 <- tempfile("create4_", fileext=".nc") nc3 <- create.nc(file3,format="netcdf4") close.nc(nc3) unlink(file3)
Define a new NetCDF dimension.
dim.def.nc(ncfile, dimname, dimlength=1, unlim=FALSE)
dim.def.nc(ncfile, dimname, dimlength=1, unlim=FALSE)
ncfile |
Object of class |
dimname |
Dimension name. Must begin with an alphabetic character, followed by zero or more alphanumeric characters including the underscore ( |
dimlength |
Length of dimension, that is, number of values for this dimension as an index to variables that use it. This must be a positive integer. If an unlimited dimension is created ( |
unlim |
Set to |
This function creates a new NetCDF dimension. There is a suggested limit (100) to the number of dimensions. Ordinarily, the name and length of a dimension are fixed when the dimension is first defined. The name may be changed later, but the length of a dimension (other than the unlimited dimension) cannot be changed without copying all the data to a new NetCDF dataset with a redefined dimension length. A NetCDF dimension in an open NetCDF dataset is referred to by a small integer called a dimension ID. In the C interface, dimension IDs are 0, 1, 2, ..., in the order in which the dimensions were defined. At most one unlimited length dimension may be defined for each NetCDF dataset.
NetCDF variable identifier, returned invisibly.
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("dim.def_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) close.nc(nc) unlink(file1)
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("dim.def_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) close.nc(nc) unlink(file1)
Inquire about a NetCDF dimension.
dim.inq.nc(ncfile, dimension)
dim.inq.nc(ncfile, dimension)
ncfile |
Object of class |
dimension |
Either the ID or the name of the dimension to be inquired. |
This function returns information about a NetCDF dimension. Information about a dimension include its name, its ID, its length and a flag if it is the unlimited dimension of this NetCDF dataset, if any. The length of the unlimited dimension, if any, is the number of records written so far.
A list containing the following components:
id |
Dimension ID. |
name |
Dimension name. |
length |
Length of dimension. For the unlimited dimension, this is the number of records written so far. |
unlim |
|
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("dim.inq_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Inquire about the dimensions dim.inq.nc(nc, 0) dim.inq.nc(nc, "time") close.nc(nc) unlink(file1)
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("dim.inq_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Inquire about the dimensions dim.inq.nc(nc, 0) dim.inq.nc(nc, "time") close.nc(nc) unlink(file1)
Rename a NetCDF dimension.
dim.rename.nc(ncfile, dimension, newname)
dim.rename.nc(ncfile, dimension, newname)
ncfile |
Object of class |
dimension |
Either the ID or the name of the dimension to be renamed. |
newname |
The new dimension name. |
This function renames an existing dimension in a NetCDF dataset open for writing. A dimension cannot be renamed to have the same name as another dimension.
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("dim.rename_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Rename the dimensions dim.rename.nc(nc, 0, "mystation") dim.rename.nc(nc, "time", "mytime") close.nc(nc) unlink(file1)
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("dim.rename_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Rename the dimensions dim.rename.nc(nc, 0, "mystation") dim.rename.nc(nc, "time", "mytime") close.nc(nc) unlink(file1)
Inquire about a NetCDF dataset.
file.inq.nc(ncfile)
file.inq.nc(ncfile)
ncfile |
Object of class |
A list containing the following components:
ndims |
Number of dimensions defined for this NetCDF dataset. |
nvars |
Number of variables defined for this NetCDF dataset. |
ngatts |
Number of global attributes for this NetCDF dataset. |
unlimdimid |
ID of the unlimited dimension, if there is one for this NetCDF dataset. Otherwise |
format |
Format of file, typically |
libvers |
Version string of the NetCDF library in the current R session. |
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("file.inq_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Create two variables, one as coordinate variable var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(nc, "temperature", "NC_DOUBLE", c(0,1)) ## Put some attributes att.put.nc(nc, "temperature", "_FillValue", "NC_DOUBLE", -99999.9) att.put.nc(nc, "temperature", "long_name", "NC_CHAR", "air temperature") att.put.nc(nc, "NC_GLOBAL", "title", "NC_CHAR", "Data from Foo") att.put.nc(nc, "NC_GLOBAL", "history", "NC_CHAR", paste("Created on", date())) ## Inquire about the dataset file.inq.nc(nc) close.nc(nc) unlink(file1)
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("file.inq_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Create two variables, one as coordinate variable var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(nc, "temperature", "NC_DOUBLE", c(0,1)) ## Put some attributes att.put.nc(nc, "temperature", "_FillValue", "NC_DOUBLE", -99999.9) att.put.nc(nc, "temperature", "long_name", "NC_CHAR", "air temperature") att.put.nc(nc, "NC_GLOBAL", "title", "NC_CHAR", "Data from Foo") att.put.nc(nc, "NC_GLOBAL", "history", "NC_CHAR", paste("Created on", date())) ## Inquire about the dataset file.inq.nc(nc) close.nc(nc) unlink(file1)
Define a NetCDF Group.
grp.def.nc(ncid, grpname)
grp.def.nc(ncid, grpname)
ncid |
Object of class |
grpname |
Group name. Must begin with an alphabetic character, followed by zero or more alphanumeric characters including the underscore ( |
This function may only be used with datasets in netcdf4
format. It creates a new NetCDF group, which may be used as a container for other NetCDF objects, including groups, dimensions, variables and attributes.
Most NetCDF object types, including groups, variables and global attributes, are visible only in the group where they are defined. However, dimensions are visible in their groups and all child groups.
Object of class NetCDF
which points to the NetCDF group, returned invisibly.
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## Create a new NetCDF4 dataset file1 <- tempfile("grp.def_", fileext=".nc") nc <- create.nc(file1, format="netcdf4") ## Define dimensions, variables and attributes in the root group dim.def.nc(nc, "station", 5) var.def.nc(nc, "station", "NC_CHAR", c("station")) att.put.nc(nc, "NC_GLOBAL", "Description", "NC_CHAR", "Site-based measurements") ## Define a group grp <- grp.def.nc(nc, "time_series") ## Define dimensions and variables in the new group dim.def.nc(grp, "time", unlim=TRUE) var.def.nc(grp, "time", "NC_INT", "time") var.def.nc(grp, "temperature", "NC_DOUBLE", c("station","time")) att.put.nc(nc, "NC_GLOBAL", "Description", "NC_CHAR", "Time-series at sites") close.nc(nc) unlink(file1)
## Create a new NetCDF4 dataset file1 <- tempfile("grp.def_", fileext=".nc") nc <- create.nc(file1, format="netcdf4") ## Define dimensions, variables and attributes in the root group dim.def.nc(nc, "station", 5) var.def.nc(nc, "station", "NC_CHAR", c("station")) att.put.nc(nc, "NC_GLOBAL", "Description", "NC_CHAR", "Site-based measurements") ## Define a group grp <- grp.def.nc(nc, "time_series") ## Define dimensions and variables in the new group dim.def.nc(grp, "time", unlim=TRUE) var.def.nc(grp, "time", "NC_INT", "time") var.def.nc(grp, "temperature", "NC_DOUBLE", c("station","time")) att.put.nc(nc, "NC_GLOBAL", "Description", "NC_CHAR", "Time-series at sites") close.nc(nc) unlink(file1)
Inquire about a NetCDF group.
grp.inq.nc(ncid,grpname=NULL,ancestors=TRUE)
grp.inq.nc(ncid,grpname=NULL,ancestors=TRUE)
ncid |
Object of class |
grpname |
By default, the inquiry relates to the group represented by |
ancestors |
If |
This function provides information about the structure of a NetCDF group or dataset. The results allow programs to explore a dataset without prior knowledge of the contents.
A list containing the following components:
self |
Object of class |
parent |
Object of class |
grps |
List of objects of class |
name |
Name of the NetCDF group. |
fullname |
Full name of the NetCDF group, with ancestors listed in order from the root group of the dataset and separated by |
dimids |
Vector of dimension identifiers. If |
unlimids |
Vector of identifiers for unlimited dimensions. If |
varids |
Vector of identifiers for variables in the group. |
typeids |
Vector of identifiers for types in the group. |
ngatts |
Number of group attributes. |
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
# Create a new NetCDF dataset: file1 <- tempfile("grp.inq_", fileext=".nc") nc <- create.nc(file1, format="netcdf4") # Define groups in root group. # (Any names can be used; hierarchical numbers are used here for clarity) grp11 <- grp.def.nc(nc, "group1.1") grp12 <- grp.def.nc(nc, "group1.2") # Define group nested in group1.1: grp111 <- grp.def.nc(grp11, "group1.1.1") # Put some attributes in each group. # (We could also define dimensions, types, and variables). att.put.nc(nc, "NC_GLOBAL", "title", "NC_CHAR", "Group 1 (root)") att.put.nc(grp11, "NC_GLOBAL", "title", "NC_CHAR", "Group 1.1") att.put.nc(grp12, "NC_GLOBAL", "title", "NC_CHAR", "Group 1.2") att.put.nc(grp111, "NC_GLOBAL", "title", "NC_CHAR", "Group 1.1.1") ## Examine contents of a group directly using its hierarchical name ... mygrp <- grp.inq.nc(nc, "/group1.1/group1.1.1") att.get.nc(mygrp$self, "NC_GLOBAL", "title") ## Recursively examine contents of nested groups ... # (See also print.nc for a visual overview) get_global_atts <- function(ncid) { inq <- grp.inq.nc(ncid) atts <- character(inq$ngatts) for (ii in seq_len(inq$ngatts)) { atts[ii] <- att.get.nc(ncid, "NC_GLOBAL", ii-1) } ngrps <- length(inq$grps) grps <- vector("list", ngrps + 1) grps[[1]] <- atts for (ii in seq_len(ngrps)) { grps[[ii + 1]] <- get_global_atts(inq$grps[[ii]]) } return(grps) } get_global_atts(nc) ## Tidy up: close.nc(nc) unlink(file1)
# Create a new NetCDF dataset: file1 <- tempfile("grp.inq_", fileext=".nc") nc <- create.nc(file1, format="netcdf4") # Define groups in root group. # (Any names can be used; hierarchical numbers are used here for clarity) grp11 <- grp.def.nc(nc, "group1.1") grp12 <- grp.def.nc(nc, "group1.2") # Define group nested in group1.1: grp111 <- grp.def.nc(grp11, "group1.1.1") # Put some attributes in each group. # (We could also define dimensions, types, and variables). att.put.nc(nc, "NC_GLOBAL", "title", "NC_CHAR", "Group 1 (root)") att.put.nc(grp11, "NC_GLOBAL", "title", "NC_CHAR", "Group 1.1") att.put.nc(grp12, "NC_GLOBAL", "title", "NC_CHAR", "Group 1.2") att.put.nc(grp111, "NC_GLOBAL", "title", "NC_CHAR", "Group 1.1.1") ## Examine contents of a group directly using its hierarchical name ... mygrp <- grp.inq.nc(nc, "/group1.1/group1.1.1") att.get.nc(mygrp$self, "NC_GLOBAL", "title") ## Recursively examine contents of nested groups ... # (See also print.nc for a visual overview) get_global_atts <- function(ncid) { inq <- grp.inq.nc(ncid) atts <- character(inq$ngatts) for (ii in seq_len(inq$ngatts)) { atts[ii] <- att.get.nc(ncid, "NC_GLOBAL", ii-1) } ngrps <- length(inq$grps) grps <- vector("list", ngrps + 1) grps[[1]] <- atts for (ii in seq_len(ngrps)) { grps[[ii + 1]] <- get_global_atts(inq$grps[[ii]]) } return(grps) } get_global_atts(nc) ## Tidy up: close.nc(nc) unlink(file1)
Rename a NetCDF group.
grp.rename.nc(ncid, newname, oldname=NULL)
grp.rename.nc(ncid, newname, oldname=NULL)
ncid |
Object of class |
newname |
The new group name. |
oldname |
By default, the rename applies to the group represented by |
This function renames an existing group in a dataset of "netcdf4"
format that is open for writing. A group cannot be renamed to have the same name as another group, type or variable in the parent group.
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## Create a new NetCDF dataset and define a group file1 <- tempfile("grp.rename_", fileext=".nc") nc <- create.nc(file1, format="netcdf4") grp <- grp.def.nc(nc, "oldgroup") ## Rename the group (operation not supported by early versions of the netcdf4 library) try(grp.rename.nc(grp, "newgroup")) close.nc(nc) unlink(file1)
## Create a new NetCDF dataset and define a group file1 <- tempfile("grp.rename_", fileext=".nc") nc <- create.nc(file1, format="netcdf4") grp <- grp.def.nc(nc, "oldgroup") ## Rename the group (operation not supported by early versions of the netcdf4 library) try(grp.rename.nc(grp, "newgroup")) close.nc(nc) unlink(file1)
Open an existing NetCDF dataset for reading and (optionally) writing.
open.nc(con, write=FALSE, share=FALSE, prefill=TRUE, diskless=FALSE, persist=FALSE, mpi_comm=NULL, mpi_info=NULL, ...)
open.nc(con, write=FALSE, share=FALSE, prefill=TRUE, diskless=FALSE, persist=FALSE, mpi_comm=NULL, mpi_info=NULL, ...)
con |
Filename of the NetCDF dataset to be opened. If the underlying NetCDF library supports OPeNDAP, |
write |
If |
share |
The buffer scheme. If |
prefill |
The prefill mode. If |
diskless |
When |
persist |
When |
mpi_comm |
Fortran handle of MPI communicator for parallel I/O. The default of |
mpi_info |
Fortran handle of MPI Info object for parallel I/O. The default value |
... |
Arguments passed to or from other methods (not used). |
This function opens an existing NetCDF dataset for access. By default, the dataset is opened read-only. If write=TRUE
, then the dataset can be changed. This includes appending or changing data, adding dimensions, variables, and attributes.
Object of class NetCDF
which points to the NetCDF dataset, returned invisibly.
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## Create a void NetCDF dataset file1 <- tempfile("open_", fileext=".nc") nc <- create.nc(file1) close.nc(nc) ## Open the NetCDF dataset for writing nc <- open.nc(file1, write=TRUE) close.nc(nc) unlink(file1)
## Create a void NetCDF dataset file1 <- tempfile("open_", fileext=".nc") nc <- create.nc(file1) close.nc(nc) ## Open the NetCDF dataset for writing nc <- open.nc(file1, write=TRUE) close.nc(nc) unlink(file1)
Print summary information about a NetCDF dataset.
print.nc(x, ...)
print.nc(x, ...)
x |
Object of class |
... |
Arguments passed to or from other methods (not used). |
This function prints information about the structure of a NetCDF dataset, including lists of all groups, dimensions, user-defined types, variables and attributes.
The output of this function is similar to the ncdump -h
command supplied with the NetCDF C library. One important difference is that array dimensions are shown by print.nc
in the order used by R, where the leftmost subscript varies fastest.
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## Create a new NetCDF dataset file1 <- tempfile("print_", fileext=".nc") nc <- create.nc(file1, format="netcdf4") ## Create a group (just because we can!): grp <- grp.def.nc(nc, "data") ## Create some dimensions, putting one inside the group: dim.def.nc(nc, "time", unlim=TRUE) dim.def.nc(grp, "station", 5) ## Create two variables, putting one inside the group: var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(grp, "temperature", "NC_DOUBLE", c("station","time")) ## Put some attributes att.put.nc(nc, "NC_GLOBAL", "history", "NC_CHAR", paste("Created on", date())) att.put.nc(grp, "temperature", "_FillValue", "NC_DOUBLE", -99999.9) att.put.nc(grp, "temperature", "long_name", "NC_CHAR", "air temperature") att.put.nc(grp, "NC_GLOBAL", "title", "NC_CHAR", "Data from Foo") ## Print summary information about the dataset print.nc(nc) close.nc(nc) unlink(file1)
## Create a new NetCDF dataset file1 <- tempfile("print_", fileext=".nc") nc <- create.nc(file1, format="netcdf4") ## Create a group (just because we can!): grp <- grp.def.nc(nc, "data") ## Create some dimensions, putting one inside the group: dim.def.nc(nc, "time", unlim=TRUE) dim.def.nc(grp, "station", 5) ## Create two variables, putting one inside the group: var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(grp, "temperature", "NC_DOUBLE", c("station","time")) ## Put some attributes att.put.nc(nc, "NC_GLOBAL", "history", "NC_CHAR", paste("Created on", date())) att.put.nc(grp, "temperature", "_FillValue", "NC_DOUBLE", -99999.9) att.put.nc(grp, "temperature", "long_name", "NC_CHAR", "air temperature") att.put.nc(grp, "NC_GLOBAL", "title", "NC_CHAR", "Data from Foo") ## Print summary information about the dataset print.nc(nc) close.nc(nc) unlink(file1)
Read all data from a NetCDF dataset.
read.nc(ncfile, recursive=FALSE, ...)
read.nc(ncfile, recursive=FALSE, ...)
ncfile |
Object of class |
recursive |
Descend recursively into any groups in the dataset if |
... |
Optional arguments passed to |
This function reads all variable data from a NetCDF dataset into a list. The list elements (arrays) have the same names as the variables in the NetCDF dataset.
Groups in the dataset may optionally be read recursively and returned as nested lists. Each list has the name of the corresponding group in the dataset.
A list with the list elements containing an array for each variable or a (possibly nested) list for each group in the NetCDF dataset.
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## Create a new NetCDF dataset file1 <- tempfile("read_", fileext=".nc") nc <- create.nc(file1, format="netcdf4") dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) dim.def.nc(nc, "max_string_length", 32) ## Create two coordinate variables var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(nc, "name", "NC_CHAR", c("max_string_length", "station")) ## Create a group to contain the data # This is not necessary, but shows it can be done. grp <- grp.def.nc(nc, "data") ## Create a data variable var.def.nc(grp, "temperature", "NC_DOUBLE", c("station","time")) ## Put some _FillValue attribute for temperature att.put.nc(grp, "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") ## Put the data var.put.nc(nc, "time", mytime, 1, length(mytime)) var.put.nc(nc, "name", myname, c(1,1), c(32,5)) var.put.nc(grp, "temperature", mytemperature, c(1,1), c(5,2)) sync.nc(nc) ## Read the dataset, including the contents of any groups read.nc(nc, recursive=TRUE) close.nc(nc) unlink(file1)
## Create a new NetCDF dataset file1 <- tempfile("read_", fileext=".nc") nc <- create.nc(file1, format="netcdf4") dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) dim.def.nc(nc, "max_string_length", 32) ## Create two coordinate variables var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(nc, "name", "NC_CHAR", c("max_string_length", "station")) ## Create a group to contain the data # This is not necessary, but shows it can be done. grp <- grp.def.nc(nc, "data") ## Create a data variable var.def.nc(grp, "temperature", "NC_DOUBLE", c("station","time")) ## Put some _FillValue attribute for temperature att.put.nc(grp, "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") ## Put the data var.put.nc(nc, "time", mytime, 1, length(mytime)) var.put.nc(nc, "name", myname, c(1,1), c(32,5)) var.put.nc(grp, "temperature", mytemperature, c(1,1), c(5,2)) sync.nc(nc) ## Read the dataset, including the contents of any groups read.nc(nc, recursive=TRUE) close.nc(nc) unlink(file1)
This package provides an interface to Unidata's NetCDF library functions (version 4) and furthermore access to Unidata's UDUNITS (version 2) calendar conversions. The routines and the documentation follow the NetCDF and UDUNITS C interface, so the corresponding manuals can be consulted for more detailed information.
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.
First versions of the R and C code of this package were based on the netCDF
package by Thomas Lumley and the ncdf
package by David Pierce. Milton Woods added some enhancements of the NetCDF library versions 3.6 and 4.x.
Help pages are available for the following RNetCDF functions:
Category | Function |
Dataset | close.nc |
create.nc |
|
file.inq.nc |
|
open.nc |
|
print.nc |
|
read.nc |
|
sync.nc |
|
Group | grp.def.nc |
grp.inq.nc |
|
grp.rename.nc |
|
Attribute | att.copy.nc |
att.delete.nc |
|
att.get.nc |
|
att.inq.nc |
|
att.put.nc |
|
att.rename.nc |
|
Dimension | dim.def.nc |
dim.inq.nc |
|
dim.rename.nc |
|
Data type | type.def.nc |
type.inq.nc |
|
Variable | var.def.nc |
var.get.nc |
|
var.inq.nc |
|
var.par.nc |
|
var.put.nc |
|
var.rename.nc |
|
Calendar | utcal.nc |
utinit.nc |
|
utinvcal.nc
|
The external types supported by all NetCDF datasets are:
NC_CHAR |
8-bit characters intended for representing text. |
NC_BYTE |
8-bit signed integers. |
NC_SHORT |
16-bit signed integers. |
NC_INT |
32-bit signed integers. |
NC_FLOAT |
32-bit IEEE floating-point. |
NC_DOUBLE |
64-bit IEEE floating-point. |
Datasets in NetCDF4 format support additional external types, including:
NC_UBYTE |
8-bit unsigned integers. |
NC_USHORT |
16-bit unsigned integers. |
NC_UINT |
32-bit unsigned integers. |
NC_INT64 |
64-bit signed integers. |
NC_UINT64 |
64-bit unsigned integers. |
NC_STRING |
variable length character strings. |
These types are called “external”, because they correspond to the portable external representation for NetCDF data. When a program reads external NetCDF data into an internal variable, the data is converted, if necessary, into the specified internal type. Similarly, if you write internal data into a NetCDF variable, this may cause it to be converted to a different external type, if the external type for the NetCDF variable differs from the internal type.
In addition to the external types, NetCDF4 supports user-defined types. See type.def.nc
for more explanation.
When installing RNetCDF from source code, the netcdf4 library and header files must be installed on the system. Calendar functions will only be enabled in RNetCDF if the udunits2 library and header files are detected during the build process. Parallel file access requires a netcdf4 library built with MPI support along with an MPI interface package installed in R (e.g. pbdMPI or Rmpi).
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
https://www.unidata.ucar.edu/software/udunits/
Synchronize an open NetCDF dataset to disk.
sync.nc(ncfile)
sync.nc(ncfile)
ncfile |
Object of class |
This function offers a way to synchronize the disk copy of a NetCDF dataset with in-memory buffers. There are two reasons one might want to synchronize after writes: To minimize data loss in case of abnormal termination, or to make data available to other processes for reading immediately after it is written.
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("sync_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Create two variables, one as coordinate variable var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(nc, "temperature", "NC_DOUBLE", c(0,1)) ## Define variable values mytime <- c(1:2) dim(mytime) <- c(2) mytemp <- c(0.0, 1.1, 2.2, 3.3, 4.4, 5.5, 6.6, 7.7, 8.8, 9.9) dim(mytemp) <- c(5,2) ## Put the data var.put.nc(nc, "time", mytime) var.put.nc(nc, "temperature", mytemp) ## Synchronize to disk sync.nc(nc) ## Open a new connection to the dataset and read data: nc2 <- open.nc(file1) newtime <- var.get.nc(nc2, 0) newtemp <- var.get.nc(nc2, "temperature") stopifnot(all.equal(newtime,mytime)) stopifnot(all.equal(newtemp,mytemp)) close.nc(nc) close.nc(nc2) unlink(file1)
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("sync_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Create two variables, one as coordinate variable var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(nc, "temperature", "NC_DOUBLE", c(0,1)) ## Define variable values mytime <- c(1:2) dim(mytime) <- c(2) mytemp <- c(0.0, 1.1, 2.2, 3.3, 4.4, 5.5, 6.6, 7.7, 8.8, 9.9) dim(mytemp) <- c(5,2) ## Put the data var.put.nc(nc, "time", mytime) var.put.nc(nc, "temperature", mytemp) ## Synchronize to disk sync.nc(nc) ## Open a new connection to the dataset and read data: nc2 <- open.nc(file1) newtime <- var.get.nc(nc2, 0) newtemp <- var.get.nc(nc2, "temperature") stopifnot(all.equal(newtime,mytime)) stopifnot(all.equal(newtemp,mytemp)) close.nc(nc) close.nc(nc2) unlink(file1)
Define complex data structures based on existing NetCDF data types.
type.def.nc(ncfile, typename, class, size=NULL, basetype=NULL, names=NULL, values=NULL, subtypes=NULL, dimsizes=NULL)
type.def.nc(ncfile, typename, class, size=NULL, basetype=NULL, names=NULL, values=NULL, subtypes=NULL, dimsizes=NULL)
ncfile |
Object of class |
typename |
Name to identify the new data type. Must begin with an alphabetic character, followed by zero or more alphanumeric characters including the underscore ( |
class |
One of the keywords |
size |
( |
basetype |
( |
names |
( |
values |
( |
subtypes |
( |
dimsizes |
( |
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.
NetCDF type identifier, returned invisibly.
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## 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)
## 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)
Inquire about a NetCDF builtin or user-defined data type.
type.inq.nc(ncfile, type, fields=TRUE)
type.inq.nc(ncfile, type, fields=TRUE)
ncfile |
Object of class |
type |
ID or name of a NetCDF data type. |
fields |
Read members of enum types or fields of compound types (default |
This function obtains information about a NetCDF data type, which could be builtin or user-defined. The items in the return list depend on the class of the NetCDF type.
A list containing the following components:
id |
Type ID. |
name |
Type name. |
class |
One of the keywords |
size |
Size in bytes of a single item of the type (or a single element of a |
basetype |
( |
If fields=TRUE
, the return list includes details about members of enum types or fields of compound types:
value |
( |
offset |
( |
subtype |
( |
dimsizes |
( |
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
grp.inq.nc
- get a list of NetCDF types defined in a dataset or group.
type.def.nc
- define a new NetCDF type.
## Create a new NetCDF4 dataset and define types file1 <- tempfile("type.inq_", fileext=".nc") nc <- create.nc(file1, format="netcdf4") # Define a type of each class: type.def.nc(nc, "blob", "opaque", size=128) type.def.nc(nc, "vector", "vlen", basetype="NC_FLOAT") type.def.nc(nc, "factor", "enum", basetype="NC_INT", names=c("peanut butter", "jelly"), values=c(101, 102)) type.def.nc(nc, "struct", "compound", names=c("siteid", "height", "colour"), subtypes=c("NC_INT", "NC_DOUBLE", "NC_SHORT"), dimsizes=list(NULL, NULL, c(3))) # Inquire about the types: typeids <- grp.inq.nc(nc)$typeids for (typeid in typeids) { print(type.inq.nc(nc, typeid)) } close.nc(nc) unlink(file1)
## Create a new NetCDF4 dataset and define types file1 <- tempfile("type.inq_", fileext=".nc") nc <- create.nc(file1, format="netcdf4") # Define a type of each class: type.def.nc(nc, "blob", "opaque", size=128) type.def.nc(nc, "vector", "vlen", basetype="NC_FLOAT") type.def.nc(nc, "factor", "enum", basetype="NC_INT", names=c("peanut butter", "jelly"), values=c(101, 102)) type.def.nc(nc, "struct", "compound", names=c("siteid", "height", "colour"), subtypes=c("NC_INT", "NC_DOUBLE", "NC_SHORT"), dimsizes=list(NULL, NULL, c(3))) # Inquire about the types: typeids <- grp.inq.nc(nc)$typeids for (typeid in typeids) { print(type.inq.nc(nc, typeid)) } close.nc(nc) unlink(file1)
Convert temporal amounts to UTC referenced date and time.
utcal.nc(unitstring, value, type="n")
utcal.nc(unitstring, value, type="n")
unitstring |
A temporal unit with an origin (e.g., |
value |
An amount (quantity) of the given temporal unit. |
type |
Character string which determines the output type. Can be |
Converts the amount, value
, of the temporal unit, unitstring
, into a UTC-referenced date and time.
Functions utcal.nc
and utinvcal.nc
provide a convenient way to convert time values between the forms used by NetCDF variables and R functions. Most R functions require times to be expressed as seconds since the beginning of 1970 in the UTC time zone, typically using objects of class POSIXct
or POSIXlt
. NetCDF files store times in numeric variables with a wide variety of units. The units and calendar are stored in attributes of the time variable, as described by the CF Conventions. Units are expressed as a string, in the form of a time unit since a fixed date-time (e.g. "hours since 2000-01-01 00:00:00 +00:00"
, or more simply "hours since 2000-01-01"
).
The conversions of times between units are performed by the UDUNITS library using a mixed Gregorian/Julian calendar system. Dates prior to 1582-10-15 are assumed to use the Julian calendar, which was introduced by Julius Caesar in 46 BCE and is based on a year that is exactly 365.25 days long. Dates on and after 1582-10-15 are assumed to use the Gregorian calendar, which was introduced on that date and is based on a year that is exactly 365.2425 days long. (A year is actually approximately 365.242198781 days long.) Seemingly strange behavior of the UDUNITS package can result if a user-given time interval includes the changeover date.
Conversions involving alternative calendars are not supported by UDUNITS, but they can be performed by other R packages. For example, https://CRAN.R-project.org/package=PCICt implements 360- and 365-day calendars.
If the output type is set to numeric, result is a matrix containing the corresponding date(s) and time(s), with the following columns: year, month, day, hour, minute, second. If the output type is string, result is a vector of strings in the form "YYYY-MM-DD hh:mm:ss"
. Otherwise result is a vector of POSIXct values.
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/udunits/
if (inherits(try(utcal.nc("seconds since 1970-01-01", 0)), "try-error")) { warning("UDUNITS calendar conversions not supported by this build of RNetCDF") } else { ## Convert units to UTC referenced time utcal.nc("hours since 1900-01-01 00:00:00 +01:00", c(0:5)) utcal.nc("hours since 1900-01-01 00:00:00 +01:00", c(0:5), type="s") utcal.nc("hours since 1900-01-01 00:00:00 +01:00", c(0:5), type="c") ## Create netcdf file with a time coordinate variable. # Create a time variable (using type POSIXct for convenience): nt <- 24 time_posixct <- seq(ISOdatetime(1900,1,1,0,0,0,tz="UTC"), by="hour", len=nt) # Convert time variable to specified units: time_unit <- "hours since 1900-01-01 00:00:00 +00:00" time_coord <- utinvcal.nc(time_unit, time_posixct) # Create a netcdf file: file1 <- tempfile("utcal_", fileext=".nc") nc <- create.nc(file1) # Global attributes: att.put.nc(nc, "NC_GLOBAL", "Conventions", "NC_CHAR", "CF-1.6") att.put.nc(nc, "NC_GLOBAL", "title", "NC_CHAR", "RNetCDF example: time coordinate") att.put.nc(nc, "NC_GLOBAL", "institution", "NC_CHAR", "University of Areland") att.put.nc(nc, "NC_GLOBAL", "source", "NC_CHAR", paste("RNetCDF", utils::packageVersion("RNetCDF"), sep="_")) att.put.nc(nc, "NC_GLOBAL", "history", "NC_CHAR", paste(Sys.time(), "File created")) att.put.nc(nc, "NC_GLOBAL", "references", "NC_CHAR", "https://www.unidata.ucar.edu/software/udunits") att.put.nc(nc, "NC_GLOBAL", "comment", "NC_CHAR", "Uses attributes recommended by http://cfconventions.org") # Define time coordinate and attributes: dim.def.nc(nc, "time", nt) var.def.nc(nc, "time", "NC_DOUBLE", "time") att.put.nc(nc, "time", "long_name", "NC_CHAR", "time") att.put.nc(nc, "time", "units", "NC_CHAR", time_unit) # Calendar is optional (gregorian is the default): att.put.nc(nc, "time", "calendar", "NC_CHAR", "gregorian") # Write the data: var.put.nc(nc, "time", time_coord) close.nc(nc) ## Read time coordinate from netcdf file: # Open the file prepared earlier: nc <- open.nc(file1) # Read time coordinate and attributes: time_coord2 <- var.get.nc(nc, "time") time_unit2 <- att.get.nc(nc, "time", "units") close.nc(nc) unlink(file1) # Convert the time variable to POSIXct: time_posixct2 <- utcal.nc(time_unit2, time_coord2, "c") # Compare with original POSIXct variable: stopifnot(all.equal(time_posixct, time_posixct2)) }
if (inherits(try(utcal.nc("seconds since 1970-01-01", 0)), "try-error")) { warning("UDUNITS calendar conversions not supported by this build of RNetCDF") } else { ## Convert units to UTC referenced time utcal.nc("hours since 1900-01-01 00:00:00 +01:00", c(0:5)) utcal.nc("hours since 1900-01-01 00:00:00 +01:00", c(0:5), type="s") utcal.nc("hours since 1900-01-01 00:00:00 +01:00", c(0:5), type="c") ## Create netcdf file with a time coordinate variable. # Create a time variable (using type POSIXct for convenience): nt <- 24 time_posixct <- seq(ISOdatetime(1900,1,1,0,0,0,tz="UTC"), by="hour", len=nt) # Convert time variable to specified units: time_unit <- "hours since 1900-01-01 00:00:00 +00:00" time_coord <- utinvcal.nc(time_unit, time_posixct) # Create a netcdf file: file1 <- tempfile("utcal_", fileext=".nc") nc <- create.nc(file1) # Global attributes: att.put.nc(nc, "NC_GLOBAL", "Conventions", "NC_CHAR", "CF-1.6") att.put.nc(nc, "NC_GLOBAL", "title", "NC_CHAR", "RNetCDF example: time coordinate") att.put.nc(nc, "NC_GLOBAL", "institution", "NC_CHAR", "University of Areland") att.put.nc(nc, "NC_GLOBAL", "source", "NC_CHAR", paste("RNetCDF", utils::packageVersion("RNetCDF"), sep="_")) att.put.nc(nc, "NC_GLOBAL", "history", "NC_CHAR", paste(Sys.time(), "File created")) att.put.nc(nc, "NC_GLOBAL", "references", "NC_CHAR", "https://www.unidata.ucar.edu/software/udunits") att.put.nc(nc, "NC_GLOBAL", "comment", "NC_CHAR", "Uses attributes recommended by http://cfconventions.org") # Define time coordinate and attributes: dim.def.nc(nc, "time", nt) var.def.nc(nc, "time", "NC_DOUBLE", "time") att.put.nc(nc, "time", "long_name", "NC_CHAR", "time") att.put.nc(nc, "time", "units", "NC_CHAR", time_unit) # Calendar is optional (gregorian is the default): att.put.nc(nc, "time", "calendar", "NC_CHAR", "gregorian") # Write the data: var.put.nc(nc, "time", time_coord) close.nc(nc) ## Read time coordinate from netcdf file: # Open the file prepared earlier: nc <- open.nc(file1) # Read time coordinate and attributes: time_coord2 <- var.get.nc(nc, "time") time_unit2 <- att.get.nc(nc, "time", "units") close.nc(nc) unlink(file1) # Convert the time variable to POSIXct: time_posixct2 <- utcal.nc(time_unit2, time_coord2, "c") # Compare with original POSIXct variable: stopifnot(all.equal(time_posixct, time_posixct2)) }
Initialize the UDUNITS2 library.
utinit.nc(path="")
utinit.nc(path="")
path |
Path to an XML-formatted unit-database for UDUNITS2. |
This function initializes the UDUNITS2 library. It is called by .onLoad
when the package is loaded. Normally, the user does not need to call this function.
UDUNITS2 obtains a unit system by reading an XML file. The file name is given by argument path
, if it is a non-empty character string. Otherwise, the file name is taken from environment variable UDUNITS2_XML_PATH
, if it is a non-empty character string. By default, the file name is set to an XML file distributed with RNetCDF.
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/udunits/
Convert a UTC referenced date into a temporal amount.
utinvcal.nc(unitstring, value)
utinvcal.nc(unitstring, value)
unitstring |
A temporal unit with an origin (e.g., |
value |
Dates to convert as a numeric vector or array, or a vector of strings or POSIXct values. |
Uses the UDUNITS library to convert a UTC-referenced date and time into the amount, value
, of the temporal unit, unitstring
.
If the dates are given in string form, the structure must be exactly "YYYY-MM-DD hh:mm:ss"
.
A vector of POSIXct values is also accepted as input. These are converted to the specified units by a linear transformation, without an intermediate separation into date components.
A vector containing the amount(s) of the temporal unit(s) corresponding to the given date(s).
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/udunits/
if (inherits(try(utcal.nc("seconds since 1970-01-01", 0)), "try-error")) { warning("UDUNITS calendar conversions not supported by this build of RNetCDF") } else { ## Convert UTC referenced time to other time units utinvcal.nc("hours since 1900-01-01 00:00:00 +01:00", c(1900,1,1,5,25,0)) utinvcal.nc("hours since 1900-01-01 00:00:00 +01:00", "1900-01-01 05:25:00") utinvcal.nc("hours since 1900-01-01 00:00:00 +01:00", ISOdatetime(1900,1,1,5,25,0,tz="UTC")) } ## An example of reading and writing a netcdf time coordinate ## is given in the help for utcal.nc
if (inherits(try(utcal.nc("seconds since 1970-01-01", 0)), "try-error")) { warning("UDUNITS calendar conversions not supported by this build of RNetCDF") } else { ## Convert UTC referenced time to other time units utinvcal.nc("hours since 1900-01-01 00:00:00 +01:00", c(1900,1,1,5,25,0)) utinvcal.nc("hours since 1900-01-01 00:00:00 +01:00", "1900-01-01 05:25:00") utinvcal.nc("hours since 1900-01-01 00:00:00 +01:00", ISOdatetime(1900,1,1,5,25,0,tz="UTC")) } ## An example of reading and writing a netcdf time coordinate ## is given in the help for utcal.nc
Define a new NetCDF variable.
var.def.nc(ncfile, varname, vartype, dimensions, chunking=NA, chunksizes=NULL, deflate=NA, shuffle=FALSE, big_endian=NA, fletcher32=FALSE, filter_id=integer(0), filter_params=list())
var.def.nc(ncfile, varname, vartype, dimensions, chunking=NA, chunksizes=NULL, deflate=NA, shuffle=FALSE, big_endian=NA, fletcher32=FALSE, filter_id=integer(0), filter_params=list())
Arguments marked "netcdf4"
are optional for datasets in that format and ignored for other formats.
ncfile |
Object of class |
varname |
Variable name. Must begin with an alphabetic character, followed by zero or more alphanumeric characters including the underscore ( |
vartype |
External NetCDF data type as one of the following labels: |
dimensions |
Vector of |
chunking |
( |
chunksizes |
( |
deflate |
( |
shuffle |
( |
big_endian |
( |
fletcher32 |
( |
filter_id |
( |
filter_params |
( |
This function creates a new NetCDF variable. A NetCDF variable has a name, a type, and a shape, which are specified when it is defined. A variable may also have values, which are established later in data mode.
Ordinarily, the name, type, and shape are fixed when the variable is first defined. The name may be changed, but the type and shape of a variable cannot be changed. However, a variable defined in terms of the unlimited dimension can grow without bound in that dimension. The fastest varying dimension has to be first in dimensions
, the slowest varying dimension last (this is the same way as an array is defined in R; i.e., opposite to the CDL conventions).
A NetCDF variable in an open NetCDF dataset is referred to by a small integer called a variable ID. Variable IDs are 0, 1, 2,..., in the order in which the variables were defined within a NetCDF dataset.
Attributes may be associated with a variable to specify such properties as units.
NetCDF variable identifier, returned invisibly.
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("var.def_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Create two variables, one as coordinate variable var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(nc, "temperature", "NC_DOUBLE", c(0,1)) close.nc(nc) unlink(file1)
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("var.def_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Create two variables, one as coordinate variable var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(nc, "temperature", "NC_DOUBLE", c(0,1)) close.nc(nc) unlink(file1)
Read the contents of a NetCDF variable.
var.get.nc(ncfile, variable, start=NA, count=NA, na.mode=4, collapse=TRUE, unpack=FALSE, rawchar=FALSE, fitnum=FALSE, cache_bytes=NA, cache_slots=NA, cache_preemption=NA)
var.get.nc(ncfile, variable, start=NA, count=NA, na.mode=4, collapse=TRUE, unpack=FALSE, rawchar=FALSE, fitnum=FALSE, cache_bytes=NA, cache_slots=NA, cache_preemption=NA)
Arguments marked "netcdf4"
are optional for datasets in that format and ignored for other formats.
ncfile |
Object of class |
|||||||||||||||||||||||||
variable |
ID or name of the NetCDF variable. |
|||||||||||||||||||||||||
start |
A vector of indices specifying the element where reading starts along each dimension of |
|||||||||||||||||||||||||
count |
A vector of integers specifying the number of values to read along each dimension of |
|||||||||||||||||||||||||
na.mode |
Missing values in the NetCDF dataset are converted to
For explanation of attribute conventions used by mode 4, please see: https://docs.unidata.ucar.edu/nug/current/attribute_conventions.html |
|||||||||||||||||||||||||
collapse |
|
|||||||||||||||||||||||||
unpack |
Packed variables are unpacked if |
|||||||||||||||||||||||||
rawchar |
This option only relates to NetCDF variables of type |
|||||||||||||||||||||||||
fitnum |
By default, all numeric variables are read into R as double precision values. When
|
|||||||||||||||||||||||||
cache_bytes |
( |
|||||||||||||||||||||||||
cache_slots |
( |
|||||||||||||||||||||||||
cache_preemption |
( |
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 a NetCDF variable that are deemed to be missing are automatically converted to NA
in the results returned to R. Unusual cases can be handled directly in user code by setting na.mode=3
.
To reduce the storage space required by a NetCDF file, numeric variables are sometimes packed into types of lower precision. The original data can be recovered (approximately) by multiplication of the stored values by attribute scale_factor
followed by addition of attribute add_offset
. This unpacking operation is performed automatically for variables with attributes scale_factor
and/or add_offset
if argument unpack
is set to TRUE
. If unpack
is FALSE
, values are read from each 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 reading starts and the number of values to read along each dimension.
The argument collapse
allows to keep degenerated dimensions (if set to FALSE
). As default, array dimensions with length=1 are omitted (e.g., an array with dimensions [2,1,3,4] in the NetCDF dataset is returned as [2,3,4]).
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).
An array with dimensions determined by count
and a data type that depends on the type of variable
. For NetCDF variables of type NC_CHAR
, the R type is either character
or raw
, as specified by argument rawchar
. For NC_STRING
, the R type is character
. Numeric variables are read as double precision by default, but the smallest R type that exactly represents each external type is used if fitnum
is TRUE
.
Variables of user-defined types are supported. "compound"
arrays are read into R as lists, with items named for the compound fields; items of base NetCDF data types are converted to R arrays, with leading dimensions from the field dimensions (if any) and trailing dimensions from the NetCDF variable. "enum"
arrays are read into R as factor arrays. "opaque"
arrays are read into 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 read into R as a list with dimensions of the NetCDF variable; items in the list may have different lengths; base NetCDF data types are converted to R vectors.
The dimension order in the R array is reversed relative to the order reported by NetCDF commands such as ncdump
, because NetCDF arrays are stored in row-major (C) order whereas R arrays are stored in column-major (Fortran) order.
Arrays of type character
drop the fastest-varying dimension of the corresponding NC_CHAR
array, because this dimension corresponds to the length of the individual character
elements. For example, an NC_CHAR
array with dimensions (5,10) would be returned as a character
vector containing 5 elements, each with a maximum length of 10 characters.
The arguments marked for "netcdf4"
format refer to the chunk cache used for reading and writing variables. Default cache settings are defined by the NetCDF library, and they can be adjusted for each variable to improve performance in some applications.
NC_BYTE
is always interpreted as signed.
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("var.get_", 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") ## Put the data var.put.nc(nc, "time", mytime, 1, length(mytime)) var.put.nc(nc, "temperature", mytemperature, c(1,1), c(5,2)) var.put.nc(nc, "name", myname, c(1,1), c(32,5)) sync.nc(nc) ## Get the data (or a subset) var.get.nc(nc, 0) var.get.nc(nc, "temperature") var.get.nc(nc, "temperature", c(3,1), c(1,1)) var.get.nc(nc, "temperature", c(3,2)) var.get.nc(nc, "temperature", c(NA,2), c(NA,1)) var.get.nc(nc, "name") var.get.nc(nc, "name", c(1,2), c(4,2)) var.get.nc(nc, "name", c(1,2), c(NA,2)) close.nc(nc) unlink(file1)
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("var.get_", 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") ## Put the data var.put.nc(nc, "time", mytime, 1, length(mytime)) var.put.nc(nc, "temperature", mytemperature, c(1,1), c(5,2)) var.put.nc(nc, "name", myname, c(1,1), c(32,5)) sync.nc(nc) ## Get the data (or a subset) var.get.nc(nc, 0) var.get.nc(nc, "temperature") var.get.nc(nc, "temperature", c(3,1), c(1,1)) var.get.nc(nc, "temperature", c(3,2)) var.get.nc(nc, "temperature", c(NA,2), c(NA,1)) var.get.nc(nc, "name") var.get.nc(nc, "name", c(1,2), c(4,2)) var.get.nc(nc, "name", c(1,2), c(NA,2)) close.nc(nc) unlink(file1)
Inquire about a NetCDF variable.
var.inq.nc(ncfile, variable)
var.inq.nc(ncfile, variable)
ncfile |
Object of class |
variable |
Either the ID or the name of the variable to be inquired. |
This function returns information about a NetCDF variable, including its name, ID, type, number of dimensions, a vector of the dimension IDs, and the number of attributes.
A list of named components, some of which are only included for datasets in "netcdf4"
format (as reported by file.inq.nc
).
id |
Variable ID. |
name |
Variable name. |
type |
External NetCDF data type as one of the following labels: |
ndims |
Number of dimensions the variable was defined as using. |
dimids |
Vector of dimension IDs corresponding to the variable dimensions ( |
natts |
Number of variable attributes assigned to this variable. |
chunksizes |
( |
cache_bytes |
( |
cache_slots |
( |
cache_preemption |
( |
deflate |
( |
shuffle |
( |
big_endian |
( |
fletcher32 |
( |
szip_options |
( |
szip_bits |
( |
filter_id |
( |
filter_params |
( |
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("var.inq_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Create two variables, one as coordinate variable var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(nc, "temperature", "NC_DOUBLE", c(0,1)) ## Inquire about these variables var.inq.nc(nc, 0) var.inq.nc(nc, "temperature") close.nc(nc) unlink(file1)
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("var.inq_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Create two variables, one as coordinate variable var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(nc, "temperature", "NC_DOUBLE", c(0,1)) ## Inquire about these variables var.inq.nc(nc, 0) var.inq.nc(nc, "temperature") close.nc(nc) unlink(file1)
Change the parallel access mode of a NetCDF variable from independent to collective and vice versa.
var.par.nc(ncfile, variable, access="NC_COLLECTIVE")
var.par.nc(ncfile, variable, access="NC_COLLECTIVE")
ncfile |
Object of class |
variable |
Numeric ID or name of the variable for which to change the parallel access mode. Use |
access |
Parallel access mode as one of the following strings: |
Parallel file access is either collective (all processors must participate) or independent (any processor may access the data without waiting for others). Data reads and writes (i.e. calls to var.put.nc
and var.get.nc
) are independent by default. Use this function to change the parallel access mode for a variable from independent to collective mode or vice versa.
All netCDF metadata writing operations are collective - all creation of groups, types, variables, dimensions, or attributes.
Note that when the file format is "classic"
or "offset64"
, the change always applies to all variables in the file, even if a single variable is specified in argument variable
.
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## Not run: # This example assumes that the NetCDF library was built with MPI support, # and that both RNetCDF and pbdMPI are installed in R. # If the example code is stored in a file myexample.R, # run R under MPI using a command similar to: # SHELL> mpiexec -np 2 Rscript --vanilla myexample.R library(pbdMPI, quiet = TRUE) library(RNetCDF, quiet = TRUE) # Get MPI parameters init() rank <- comm.rank() size <- comm.size() # Define dimensions and data nr <- 5 nc_local <- 4 nc <- nc_local * size data_local <- matrix(rank, nrow=nr, ncol=nc_local) # Open file for parallel access and define metadata filename <- "myexample.nc" info.create() ncid <- create.nc(filename, format="netcdf4", mpi_comm=comm.c2f(), mpi_info=info.c2f()) rdim <- dim.def.nc(ncid, "rows", nr) cdim <- dim.def.nc(ncid, "cols", nc) varid <- var.def.nc(ncid, "data", "NC_INT", c(rdim, cdim)) # Use collective I/O var.par.nc(ncid, "data", "NC_COLLECTIVE") # Write data var.put.nc(ncid, varid, data_local, start=c(1,rank*nc_local+1), count=c(nr,nc_local)) # Finish up close.nc(ncid) info.free() finalize() ## End(Not run)
## Not run: # This example assumes that the NetCDF library was built with MPI support, # and that both RNetCDF and pbdMPI are installed in R. # If the example code is stored in a file myexample.R, # run R under MPI using a command similar to: # SHELL> mpiexec -np 2 Rscript --vanilla myexample.R library(pbdMPI, quiet = TRUE) library(RNetCDF, quiet = TRUE) # Get MPI parameters init() rank <- comm.rank() size <- comm.size() # Define dimensions and data nr <- 5 nc_local <- 4 nc <- nc_local * size data_local <- matrix(rank, nrow=nr, ncol=nc_local) # Open file for parallel access and define metadata filename <- "myexample.nc" info.create() ncid <- create.nc(filename, format="netcdf4", mpi_comm=comm.c2f(), mpi_info=info.c2f()) rdim <- dim.def.nc(ncid, "rows", nr) cdim <- dim.def.nc(ncid, "cols", nc) varid <- var.def.nc(ncid, "data", "NC_INT", c(rdim, cdim)) # Use collective I/O var.par.nc(ncid, "data", "NC_COLLECTIVE") # Write data var.put.nc(ncid, varid, data_local, start=c(1,rank*nc_local+1), count=c(nr,nc_local)) # Finish up close.nc(ncid) info.free() finalize() ## End(Not run)
Write the contents of a NetCDF variable.
var.put.nc(ncfile, variable, data, start=NA, count=NA, na.mode=4, pack=FALSE, cache_bytes=NA, cache_slots=NA, cache_preemption=NA)
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 marked "netcdf4"
are optional for datasets in that format and ignored for other formats.
ncfile |
Object of class |
|||||||||||||||||||||||||
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 |
|||||||||||||||||||||||||
start |
A vector of indices specifying the element where writing starts along each dimension of |
|||||||||||||||||||||||||
count |
A vector of integers specifying the number of values to write along each dimension of |
|||||||||||||||||||||||||
na.mode |
For explanation of attribute conventions used by mode 4, please see: https://docs.unidata.ucar.edu/nug/current/attribute_conventions.html |
|||||||||||||||||||||||||
pack |
Variables are packed if |
|||||||||||||||||||||||||
cache_bytes |
( |
|||||||||||||||||||||||||
cache_slots |
( |
|||||||||||||||||||||||||
cache_preemption |
( |
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, integer64
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 attributes add_offset
and/or 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).
The arguments marked for "netcdf4"
format refer to the chunk cache used for reading and writing variables. Default cache settings are defined by the NetCDF library, and they can be adjusted for each variable to improve performance in some applications.
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.
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## 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)
## 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)
Rename a NetCDF variable.
var.rename.nc(ncfile, variable, newname)
var.rename.nc(ncfile, variable, newname)
ncfile |
Object of class |
variable |
Either the ID or the name of the variable to be renamed. |
newname |
The new variable name. |
This function renames an existing variable in a NetCDF dataset open for writing. A variable cannot be renamed to have the same name as another variable.
Pavel Michna, Milton Woods
https://www.unidata.ucar.edu/software/netcdf/
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("var.rename_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Create two variables, one as coordinate variable var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(nc, "temperature", "NC_DOUBLE", c(0,1)) ## Rename these variables var.rename.nc(nc, 0, "mytime") var.rename.nc(nc, "temperature", "mytemperature") close.nc(nc) unlink(file1)
## Create a new NetCDF dataset and define two dimensions file1 <- tempfile("var.rename_", fileext=".nc") nc <- create.nc(file1) dim.def.nc(nc, "station", 5) dim.def.nc(nc, "time", unlim=TRUE) ## Create two variables, one as coordinate variable var.def.nc(nc, "time", "NC_INT", "time") var.def.nc(nc, "temperature", "NC_DOUBLE", c(0,1)) ## Rename these variables var.rename.nc(nc, 0, "mytime") var.rename.nc(nc, "temperature", "mytemperature") close.nc(nc) unlink(file1)