Package ucar.nc2.dataset

Class NetcdfDataset

java.lang.Object
ucar.nc2.NetcdfFile
ucar.nc2.dataset.NetcdfDataset
All Implemented Interfaces:
Closeable, AutoCloseable, ucar.nc2.util.cache.FileCacheable
public class NetcdfDataset extends NetcdfFile

NetcdfDataset extends the netCDF API, adding standard attribute parsing such as scale and offset, and explicit support for Coordinate Systems. A NetcdfDataset wraps a NetcdfFile, or is defined by an NcML document.

Be sure to close the dataset when done. Using statics in NetcdfDatets, best practice is to use try-with-resource: 

 try (NetcdfDataset ncd = NetcdfDatasets.openDataset(fileName)) {
   ...
 }

By default @code NetcdfDataset} is opened with all enhancements turned on. The default "enhance mode" can be set through setDefaultEnhanceMode(). One can also explicitly set the enhancements you want in the dataset factory methods. The enhancements are:

  • ConvertEnums: convert enum values to their corresponding Strings. If you want to do this manually, you can call Variable.lookupEnumString().
  • ConvertUnsigned: reinterpret the bit patterns of any negative values as unsigned.
  • ApplyScaleOffset: process scale/offset attributes, and automatically convert the data.
  • ConvertMissing: replace missing data with NaNs, for efficiency.
  • CoordSystems: extract CoordinateSystem using the CoordSysBuilder plug-in mechanism.

Automatic scale/offset processing has some overhead that you may not want to incur up-front. If so, open the NetcdfDataset without ApplyScaleOffset. The VariableDS data type is not promoted and the data is not converted on a read, but you can call the convertScaleOffset() routines to do the conversion later.

See Also:

  • Method Details

    • getEnhanceAll

      public static Set<NetcdfDataset.Enhance> getEnhanceAll()

    • getEnhanceNone

      public static Set<NetcdfDataset.Enhance> getEnhanceNone()

    • getDefaultEnhanceMode

      public static Set<NetcdfDataset.Enhance> getDefaultEnhanceMode()

    • setDefaultEnhanceMode

      public static void setDefaultEnhanceMode(Set<NetcdfDataset.Enhance> mode)
      Set the default set of Enhancements to do for all subsequent dataset opens and acquires.
      Parameters:
      mode - the default set of Enhancements for open and acquire factory methods

    • getCoordinateSystems

      public com.google.common.collect.ImmutableList<CoordinateSystem> getCoordinateSystems()
      Get the list of all CoordinateSystem objects used by this dataset.
      Returns:
      list of type CoordinateSystem; may be empty, not null.

    • getConventionUsed

      public String getConventionUsed()
      Get conventions used to analyse coordinate systems.
      Returns:
      conventions used to analyse coordinate systems

    • getEnhanceMode

      public Set<NetcdfDataset.Enhance> getEnhanceMode()
      Get the current state of dataset enhancement.
      Returns:
      the current state of dataset enhancement.

    • getCoordinateTransforms

      public com.google.common.collect.ImmutableList<CoordinateTransform> getCoordinateTransforms()
      Get the list of all CoordinateTransform objects used by this dataset.
      Returns:
      list of type CoordinateTransform; may be empty, not null.

    • getCoordinateAxes

      public com.google.common.collect.ImmutableList<CoordinateAxis> getCoordinateAxes()
      Get the list of all CoordinateAxis objects used by this dataset.
      Returns:
      list of type CoordinateAxis; may be empty, not null.

    • findCoordinateAxis

      public CoordinateAxis findCoordinateAxis(AxisType type)
      Retrieve the CoordinateAxis with the specified Axis Type.
      Parameters:
      type - axis type
      Returns:
      the first CoordinateAxis that has that type, or null if not found

    • findCoordinateAxis

      public CoordinateAxis findCoordinateAxis(String fullName)
      Retrieve the CoordinateAxis with the specified type.
      Parameters:
      fullName - full escaped name of the coordinate axis
      Returns:
      the CoordinateAxis, or null if not found

    • findCoordinateSystem

      public CoordinateSystem findCoordinateSystem(String name)
      Retrieve the CoordinateSystem with the specified name.
      Parameters:
      name - String which identifies the desired CoordinateSystem
      Returns:
      the CoordinateSystem, or null if not found

    • findCoordinateTransform

      public CoordinateTransform findCoordinateTransform(String name)
      Retrieve the CoordinateTransform with the specified name.
      Parameters:
      name - String which identifies the desired CoordinateSystem
      Returns:
      the CoordinateSystem, or null if not found

    • close

      public void close() throws IOException
      Close all resources (files, sockets, etc) associated with this dataset. If the underlying file was acquired, it will be released, otherwise closed.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Specified by:
      close in interface ucar.nc2.util.cache.FileCacheable
      Overrides:
      close in class NetcdfFile
      Throws:
      IOException - if error when closing

    • getLastModified

      public long getLastModified()

    • getDetailInfo

      public void getDetailInfo(Formatter f)
      Show debug / underlying implementation details
      Overrides:
      getDetailInfo in class NetcdfFile

    • getFileTypeId

      public String getFileTypeId()
      Description copied from class: NetcdfFile
      Get the file type id for the underlying data source.
      Overrides:
      getFileTypeId in class NetcdfFile
      Returns:
      registered id of the file type
      See Also:
      • "https://www.unidata.ucar.edu/software/netcdf-java/formats/FileTypes.html"

    • getFileTypeDescription

      public String getFileTypeDescription()
      Description copied from class: NetcdfFile
      Get a human-readable description for this file type.
      Overrides:
      getFileTypeDescription in class NetcdfFile
      Returns:
      description of the file type
      See Also:
      • "https://www.unidata.ucar.edu/software/netcdf-java/formats/FileTypes.html"

    • toBuilder

      public NetcdfDataset.Builder<?> toBuilder()
      Description copied from class: NetcdfFile
      Turn into a mutable Builder. Can use toBuilder().build() to copy.
      Overrides:
      toBuilder in class NetcdfFile

    • builder

      public static NetcdfDataset.Builder<?> builder()
      Get Builder for this class that allows subclassing.
      See Also:
      • "https://community.oracle.com/blogs/emcmanus/2010/10/24/using-builder-pattern-subclasses"

    • builder

      public static NetcdfDataset.Builder builder(NetcdfFile from)