RNetCDF (version 2.11-1)

grp.inq.nc: Inquire About a NetCDF Group

Description

Inquire about a NetCDF group.

Usage

grp.inq.nc(ncid,grpname=NULL,ancestors=TRUE)

Value

A list containing the following components:

self

Object of class NetCDF representing the group.

parent

Object of class NetCDF representing the parent group, or NULL for the root group.

grps

List of objects of class NetCDF representing the groups in the group.

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 "/". Omitted if ancestors is FALSE.

dimids

Vector of dimension identifiers. If ancestors is TRUE (default), all visible dimensions in the group and its ancestors are reported, otherwise only dimensions defined in the group of ncid are shown.

unlimids

Vector of identifiers for unlimited dimensions. If ancestors is TRUE (default), all unlimited dimensions in the group and its ancestors are reported, otherwise only unlimited dimensions defined in the group of ncid are shown.

varids

Vector of identifiers for variables in the group.

typeids

Vector of identifiers for types in the group.

ngatts

Number of group attributes.

Arguments

ncid

Object of class NetCDF which points to a NetCDF group (from grp.def.nc) or dataset (from open.nc).

grpname

By default, the inquiry relates to the group represented by ncid. If grpname is a character string, a group with this name is examined instead. A hierarchical search is performed if grpname contains "/", otherwise only the immediate group of ncid is searched for a matching group name.

ancestors

If TRUE, dimensions and names of ancestor groups are examined. Otherwise, only dimensions and names defined in the current group are reported.

Author

Pavel Michna, Milton Woods

Details

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.

References

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

Examples

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