Title: | Straightforward 'NetCDF' Metadata |
---|---|
Description: | Extract metadata from 'NetCDF' data sources, these can be files, file handles or servers. This package leverages and extends the lower level functions of the 'RNetCDF' package providing a consistent set of functions that all return data frames. We introduce named concepts of 'grid', 'axis' and 'source' which are all meaningful entities without formal definition in the 'NetCDF' library <https://www.unidata.ucar.edu/software/netcdf/>. 'RNetCDF' matches the library itself with only the named concepts of 'variables', 'dimensions' and 'attributes'. |
Authors: | Michael Sumner [aut, cre], Tomas Remenyi [ctb], Ben Raymond [ctb], David Blodgett [ctb], Milton Woods [ctb], Patrick Van Laake [ctb] |
Maintainer: | Michael Sumner <[email protected]> |
License: | GPL-3 |
Version: | 0.4.0.9002 |
Built: | 2024-11-21 02:48:59 UTC |
Source: | https://github.com/hypertidy/ncmeta |
Variable attributes are number 0:(n-1). Global attributes are indexed by -1 or the label "NC_GLOBAL".
nc_att(x, variable, attribute, ...) ## S3 method for class 'NetCDF' nc_att(x, variable, attribute, ...) ## S3 method for class 'character' nc_att(x, variable, attribute, ...)
nc_att(x, variable, attribute, ...) ## S3 method for class 'NetCDF' nc_att(x, variable, attribute, ...) ## S3 method for class 'character' nc_att(x, variable, attribute, ...)
x |
or file handle |
variable |
name or index (zero based) of variable |
attribute |
name or index (zero based) of attribute |
... |
ignored |
nc_inq
includes the number of global attributes
nc_vars
includes the number of variable attributes
data frame of attribute with numeric id, character attribute name, character or numeric variable id or name depending on input, and attribute value.
f <- system.file("extdata", "S2008001.L3m_DAY_CHL_chlor_a_9km.nc", package = "ncmeta") nc_att(f, 0, 0)
f <- system.file("extdata", "S2008001.L3m_DAY_CHL_chlor_a_9km.nc", package = "ncmeta") nc_att(f, 0, 0)
All attributes in the file, globals are treated as if they belong to variable 'NC_GLOBAL'. Attributes for a single variable may be returned by specifying 'variable' - 'NC_GLOBAL' can stand in to return only those attributes.
nc_atts(x, variable = NULL, ...) ## S3 method for class 'NetCDF' nc_atts(x, variable = NULL, ...) ## S3 method for class 'character' nc_atts(x, variable = NULL, ...)
nc_atts(x, variable = NULL, ...) ## S3 method for class 'NetCDF' nc_atts(x, variable = NULL, ...) ## S3 method for class 'character' nc_atts(x, variable = NULL, ...)
x |
filename or handle |
variable |
optional single name of a variable, or 'NC_GLOBAL' |
... |
ignored |
data frame of attributes
f <- system.file("extdata", "S2008001.L3m_DAY_CHL_chlor_a_9km.nc", package = "ncmeta") nc_atts(f)
f <- system.file("extdata", "S2008001.L3m_DAY_CHL_chlor_a_9km.nc", package = "ncmeta") nc_atts(f)
An axis
is an instance of a dimension.
nc_axes(x, variables = NULL, ...) ## S3 method for class 'character' nc_axes(x, variables = NULL, ...) ## S3 method for class 'NetCDF' nc_axes(x, variables = NULL, ...)
nc_axes(x, variables = NULL, ...) ## S3 method for class 'character' nc_axes(x, variables = NULL, ...) ## S3 method for class 'NetCDF' nc_axes(x, variables = NULL, ...)
x |
NetCDF source |
variables |
names of vars to query |
... |
ignored |
Each data source has a set of dimensions available for use by variables. Each axis is a 1-dimensional instance.
An axis
is an instance of a dimension.
nc_axis(x, i) ## S3 method for class 'character' nc_axis(x, i) ## S3 method for class 'NetCDF' nc_axis(x, i)
nc_axis(x, i) ## S3 method for class 'character' nc_axis(x, i) ## S3 method for class 'NetCDF' nc_axis(x, i)
x |
NetCDF source |
i |
index of axis (1-based, 0 is "empty") |
Each data source has a set of dimensions available for use by variables. Each axis is a 1-dimensional instance.
In NetCDF, variables are defined along dimensions and are said to have "coordinate variables" that define the (typically spatio-temporal) positions of the data's cells.
nc_coord_var(x, variable = NULL, ...) ## S3 method for class 'character' nc_coord_var(x, variable = NULL, ...) ## S3 method for class 'NetCDF' nc_coord_var(x, variable = NULL, ...)
nc_coord_var(x, variable = NULL, ...) ## S3 method for class 'character' nc_coord_var(x, variable = NULL, ...) ## S3 method for class 'NetCDF' nc_coord_var(x, variable = NULL, ...)
x |
NetCDF source |
variable |
variable name of interest. If not included, all variables will be returned. |
... |
ignored |
This function attempts to identify the X, Y, Z, and T coordinate variables for each data variable in the provided NetCDF source. The NetCDF-CF attribute conventions are used to make this determination.
All variables that can be related to a spatio-temporal axis, including coordinate variables are returned. For coordinate variables, a "bounds" column is included in the response indicating which variable contains bounds information.
See http://cfconventions.org/cf-conventions/v1.6.0/cf-conventions.html#coordinate-system for more.
tibble with "variable", "X", "Y", "Z", "T", and "bounds" columns that reference variables by name.
f <- system.file("extdata", "S2008001.L3m_DAY_CHL_chlor_a_9km.nc", package = "ncmeta") nc_coord_var(f, "chlor_a") f <- system.file("extdata", "guam.nc", package = "ncmeta") nc_coord_var(f)
f <- system.file("extdata", "S2008001.L3m_DAY_CHL_chlor_a_9km.nc", package = "ncmeta") nc_coord_var(f, "chlor_a") f <- system.file("extdata", "guam.nc", package = "ncmeta") nc_coord_var(f)
NetCDF variables Obtain information about a single dimension by index.
nc_dim(x, i, ...) ## S3 method for class 'character' nc_dim(x, i, ...) ## S3 method for class 'NetCDF' nc_dim(x, i, ...) ## S3 method for class 'ncdf4' nc_dim(x, i, ...)
nc_dim(x, i, ...) ## S3 method for class 'character' nc_dim(x, i, ...) ## S3 method for class 'NetCDF' nc_dim(x, i, ...) ## S3 method for class 'ncdf4' nc_dim(x, i, ...)
x |
filename or handle |
i |
index of dimension (zero based) |
... |
ignored |
nc_vars
to obtain information about all dimensions, nc_inq
for an
overview of the file
Get information about the dimensions in a NetCDF source.
nc_dims(x, ...) ## S3 method for class 'character' nc_dims(x, ...) ## S3 method for class 'NetCDF' nc_dims(x, ...) ## S3 method for class 'ncdf4' nc_dims(x, ...)
nc_dims(x, ...) ## S3 method for class 'character' nc_dims(x, ...) ## S3 method for class 'NetCDF' nc_dims(x, ...) ## S3 method for class 'ncdf4' nc_dims(x, ...)
x |
file address or handle |
... |
ignored |
Generate a table of all extended dimension attributes. For now that means interpretation of any "time" dimension.
nc_extended(x, ...) ## S3 method for class 'character' nc_extended(x, ...) ## S3 method for class 'NetCDF' nc_extended(x, ...) ## S3 method for class 'ncdf4' nc_extended(x, ...)
nc_extended(x, ...) ## S3 method for class 'character' nc_extended(x, ...) ## S3 method for class 'NetCDF' nc_extended(x, ...) ## S3 method for class 'ncdf4' nc_extended(x, ...)
x |
filename or handle |
... |
ignored currently |
data frame of extended dimension attribute information
Takes NetCDF-CF grid mapping attributes and returns a proj4 string.
nc_gm_to_prj(x) ## S3 method for class 'data.frame' nc_gm_to_prj(x) ## S3 method for class 'list' nc_gm_to_prj(x)
nc_gm_to_prj(x) ## S3 method for class 'data.frame' nc_gm_to_prj(x) ## S3 method for class 'list' nc_gm_to_prj(x)
x |
list or data.frame of attributes of the grid mapping variable as returned by ncdf or ncdf4's get attributes functions or ncmeta's nc_grid_mapping_atts. |
The WGS84 datum is used as a default if one os not provided in the grid mapping.
If only a semi_major axis is provided, a sperical earth is assumed.
A proj4 string.
https://trac.osgeo.org/gdal/wiki/NetCDF_ProjectionTestingStatus
http://cfconventions.org/cf-conventions/cf-conventions.html#appendix-grid-mappings
crs <- list(grid_mapping_name="latitude_longitude", longitude_of_prime_meridian = 0, semi_major_axis = 6378137, inverse_flattening = 298) nc_gm_to_prj(crs)
crs <- list(grid_mapping_name="latitude_longitude", longitude_of_prime_meridian = 0, semi_major_axis = 6378137, inverse_flattening = 298) nc_gm_to_prj(crs)
Get the grid mapping from a NetCDF file
nc_grid_mapping_atts(x, data_variable = NULL) ## S3 method for class 'character' nc_grid_mapping_atts(x, data_variable = NULL) ## S3 method for class 'NetCDF' nc_grid_mapping_atts(x, data_variable = NULL) ## S3 method for class 'data.frame' nc_grid_mapping_atts(x, data_variable = NULL)
nc_grid_mapping_atts(x, data_variable = NULL) ## S3 method for class 'character' nc_grid_mapping_atts(x, data_variable = NULL) ## S3 method for class 'NetCDF' nc_grid_mapping_atts(x, data_variable = NULL) ## S3 method for class 'data.frame' nc_grid_mapping_atts(x, data_variable = NULL)
x |
open NetCDF object, character file path or url to be opened with RNetCDF::open.nc, or data.frame as returned from ncmeta::nc_atts |
data_variable |
character variable of interest |
tibble containing attributes that make up the file's grid_mapping. A data_variable column is included to indicate which data variable the grid mapping belongs to.
nc_grid_mapping_atts(system.file("extdata/daymet_sample.nc", package = "ncmeta"))
nc_grid_mapping_atts(system.file("extdata/daymet_sample.nc", package = "ncmeta"))
A grid
is a discretized space, defined by a set of dimensions. These are the spaces used
by one or more variables in a source. Traditional summaries are organized by variable, but
when organized by space or grid we can treat multiple variables together using standard
database techniques.
nc_grids(x, ...) ## S3 method for class 'character' nc_grids(x, ...) ## S3 method for class 'NetCDF' nc_grids(x, ...) ## S3 method for class 'tidync' nc_grids(x, ...)
nc_grids(x, ...) ## S3 method for class 'character' nc_grids(x, ...) ## S3 method for class 'NetCDF' nc_grids(x, ...) ## S3 method for class 'tidync' nc_grids(x, ...)
x |
NetCDF source |
... |
ignored |
Each data source has a set of dimensions available for use by variables. Each grid is an n-dimensional space available for use by 0, 1 or more variables. A grid only really exists if variable is defined for it, and 'grid' is an implicit entity not an explicit part of the NetCDF API definition. The Unidata pages refer to "shape", which is more or less what we mean by "grid".
Get information about a NetCDF data source, may be a file path, or a RNetCDF
file handle, or an OpenDAP/Thredds server address.
nc_inq(x, ...) ## S3 method for class 'NetCDF' nc_inq(x, ...) ## S3 method for class 'character' nc_inq(x, ...)
nc_inq(x, ...) ## S3 method for class 'NetCDF' nc_inq(x, ...) ## S3 method for class 'character' nc_inq(x, ...)
x |
filename or handle |
... |
ignored |
## Not run: f <- raadfiles:::cmip5_files()$fullname[1] nc_inq(f) nc_var(f, 0) nc_dim(f, 0) ## End(Not run) f <- system.file("extdata", "S2008001.L3m_DAY_CHL_chlor_a_9km.nc", package = "ncmeta") nc_inq(f) nc_var(f, 0) nc_dim(f, 0) nc_vars(f) nc_dims(f)
## Not run: f <- raadfiles:::cmip5_files()$fullname[1] nc_inq(f) nc_var(f, 0) nc_dim(f, 0) ## End(Not run) f <- system.file("extdata", "S2008001.L3m_DAY_CHL_chlor_a_9km.nc", package = "ncmeta") nc_inq(f) nc_var(f, 0) nc_dim(f, 0) nc_vars(f) nc_dims(f)
This function exists to maintain the open connection while all dimension, variable, and attribute metadata is extracted.
nc_meta(x, ...) ## S3 method for class 'NetCDF' nc_meta(x, ...) ## S3 method for class 'character' nc_meta(x, ...)
nc_meta(x, ...) ## S3 method for class 'NetCDF' nc_meta(x, ...) ## S3 method for class 'character' nc_meta(x, ...)
x |
data source address, file name or handle |
... |
ignored |
This function is pretty ambitious, and will send nearly any string to the underlying NetCDF library other than "", which immediately generates an error. This should be robust, but might present fairly obscure error messages from the underlying library.
f <- system.file("extdata", "S2008001.L3m_DAY_CHL_chlor_a_9km.nc", package = "ncmeta") nc_meta(f) ## Not run: u <- "https://upwell.pfeg.noaa.gov/erddap/tabledap/FRDCPSTrawlLHHaulCatch" nc_meta(u) ## End(Not run)
f <- system.file("extdata", "S2008001.L3m_DAY_CHL_chlor_a_9km.nc", package = "ncmeta") nc_meta(f) ## Not run: u <- "https://upwell.pfeg.noaa.gov/erddap/tabledap/FRDCPSTrawlLHHaulCatch" nc_meta(u) ## End(Not run)
Takes a proj4 string and returns a NetCDF-CF projection as a named list of attributes.
nc_prj_to_gridmapping(prj)
nc_prj_to_gridmapping(prj)
prj |
character PROJ string as used in raster, sf, sp, proj4, and rgdal packages. |
A named list containing attributes required for that grid_mapping.
https://trac.osgeo.org/gdal/wiki/NetCDF_ProjectionTestingStatus
http://cfconventions.org/cf-conventions/cf-conventions.html#appendix-grid-mappings
prj <- "+proj=longlat +datum=NAD27 +no_defs" nc_prj_to_gridmapping(prj) p1 <- "+proj=aea +lat_1=29.5 +lat_2=45.5 +lat_0=23 +lon_0=-96" p2 <- "+x_0=0 +y_0=0 +ellps=GRS80 +towgs84=0,0,0,0,0,0,0 +units=m +no_defs" prj2 <- sprintf("%s %s", p1, p2) nc_prj_to_gridmapping(prj2) nc_prj_to_gridmapping("+proj=longlat +a=6378137 +f=0.00335281066474748 +pm=0 +no_defs")
prj <- "+proj=longlat +datum=NAD27 +no_defs" nc_prj_to_gridmapping(prj) p1 <- "+proj=aea +lat_1=29.5 +lat_2=45.5 +lat_0=23 +lon_0=-96" p2 <- "+x_0=0 +y_0=0 +ellps=GRS80 +towgs84=0,0,0,0,0,0,0 +units=m +no_defs" prj2 <- sprintf("%s %s", p1, p2) nc_prj_to_gridmapping(prj2) nc_prj_to_gridmapping("+proj=longlat +a=6378137 +f=0.00335281066474748 +pm=0 +no_defs")
A record of file, URL, or any data source with NetCDF.
nc_sources(x, ...) ## S3 method for class 'character' nc_sources(x, ...)
nc_sources(x, ...) ## S3 method for class 'character' nc_sources(x, ...)
x |
data source string |
... |
ignored |
Return a data frame about the variable at index i
.
nc_var(x, i) ## S3 method for class 'character' nc_var(x, i) ## S3 method for class 'NetCDF' nc_var(x, i)
nc_var(x, i) ## S3 method for class 'character' nc_var(x, i) ## S3 method for class 'NetCDF' nc_var(x, i)
x |
file name or handle |
i |
variable index (zero based) |
data frame of variable information
nc_vars
to obtain information about all variables, nc_inq
for an
overview of the file
Generate a table of all variables.
nc_vars(x, ...) ## S3 method for class 'character' nc_vars(x, ...) ## S3 method for class 'NetCDF' nc_vars(x, ...)
nc_vars(x, ...) ## S3 method for class 'character' nc_vars(x, ...) ## S3 method for class 'NetCDF' nc_vars(x, ...)
x |
filename or handle |
... |
ignored currently |
data frame of variable information