The Common Data Model Scientific Datatype layer adds another layer of functionality on top of NetcdfDataset, by specializing in various kinds of data that are common in Earth Science. The abstract concepts and concrete classes are continually evolving, and we have concentrated on, for obvious reasons, the types of datasets and data that Unidata is most familiar with, mainly from the Atmospheric and Ocean sciences.
All Scientific Datatypes have georeferencing coordinate systems, from which a location in real physical space and time can be found, usually with reference to the Earth. Each adds special data subsetting methods which cannot be done efficiently or at all in the general case of NetcdfDataset objects.
A Grid Coordinate System at the minimum has a Lat and Lon coordinate axis, or a GeoX and GeoY coordinate axis plus a Projection that maps x, y to lat, lon. It usually has a time coordinate axis. It may optionally have a vertical coordinate axis, classified as Height, Pressure, or GeoZ. If it is a GeoZ axis, it may have a Vertical Transform that maps GeoZ to height or pressure. A special kind of Grid called Forecast Model Run Collection (FMRC) may optionally have a Runtime and/or Ensemble coordinate axis.
A Grid Datatype (aka Grid or GeoGrid) is a special kind of Variable that has a Grid Coordinate System, and whose dimensions are all connected, meaning that neighbors in index space are connected neighbors in coordinate space. This means that data values that are close to each other in the real world (coordinate space) are close to each other in the data array, and are usually stored close to each other on disk, making coordinate subsetting easy and efficient.
A Grid Dataset is a NetcdfDataset whose Grids have been identified and grouped into Gridsets based on common Grid Coordinate Systems. Here is the UML for the Grid interface classes, found in the ucar.nc2.dt package:
The correct way to open a GridDataset is to use the TypedDatasetFactory class. This allows third parties to plug-in alternative imlpementations of GridDataset at runtime. For example:
StringBuffer errlog = new StringBuffer();
ucar.nc2.dt.GridDataset gds = (ucar.nc2.dt.GridDataset) ucar.nc2.dt.TypedDatasetFactory.open( thredds.catalog.DataType.GRID, location, cancelTask, errlog); if (null == gds) throw Exception("Cant open GRID at location= "+location+"; error message= "+errlog);
Note that ucar.nc2.dt.GridDataset is a subclass of ucar.nc2.dt.TypedDataset, and is new as of version 2.2.17. This superceeds the old ucar.nc2.dataset.grid.GridDataset. If you need a drop-in replacement for that older class, you can use
GridDataset gds = ucar.nc2.dataset.grid.GridDataset.open(uriString);
But this will not see any classes loaded at runtime. It will see CoordSysBuilder and CoordTransBuilder plug-ins, however.
If you use ucar.nc2.dataset.grid.GridDataset.open(), to avoid import clashes, we recommend using the idiom of never importing ucar.nc2.dt.grid.GridDataset, and using it only to open.
A GridCoordSys wraps a georeferencing coordinate system. It always has 1D or 2D XHoriz and YHoriz axes, and optionally 1D vertical and time axes. The XHoriz/YHoriz axes will be lat/lon if isLatLon() is true, otherwise they will be GeoX,GeoY with an appropriate Projection. The getBoundingBox() method returns a bounding box from the XHoriz/YHoriz corner points. The getLatLonBoundingBox() method returns the smallest lat/lon bounding box that contains getBoundingBox().
If there is a vertical axis, isZPositive() is true if increasing values of the vertical axis should be displayed “up”. The getLevels() and getTimes() returns the list of levels and times, if they exist, as lists of NamedObjects that are convenient for display. If there is a time axis, and it can be converted (via ucar.units) into a Date, isDate() is true, and getTimeDates() returns the time coordinates as Date objects. The findTimeCoordElement() method does a reverse lookup, finding the time index that corresponds to a given Date.
A GeoGrid wraps a VariableDS in a VariableStandarized, and also has a GridCoordSys. You can think of it as a specialized Variable that explicitly handles X,Y,Z,T dimensions, which are put into canonical order: (t, z, y, x). It has various convenience routines that expose methods from the GridCoordSys and VariableDS objects. The main data access method is readDataSlice, where you can fix an index on any Dimension, or use a -1 t oget all the data in that Dimension. The subset method allows you to create a logical subset of a GeoGrid using index Ranges.
You can use ToolsUI Grid Tab to view Grid Datasets very similar to the Coordinate Systems Tab. This consists of 3 tables that show the Grid DataTypes, the Grid Coordinate systems, and the coordinate axes.
button to display the grids in the Grid Viewer.
