NetCDF (.nc)

Background & Context

    • MIME type: application/x-netcdf
    • NetCDF data file format.
    • Self-describing format for exchanging scientific data.
    • Used in atmospheric research, GIS, and related fields.
    • NetCDF is an acronym derived from network Common Data Form.
    • Binary file format.
    • Conceptually based on NASA's Common Data Format, but incompatible with this format.
    • Developed by the Unidata center at the University Corporation for Atmospheric Research (UCAR).

Import & Export

  • Import["file.nc"] imports a netCDF file, returning the names of the datasets stored in the file.
  • Import["file.nc",elem] imports the specified element from a netCDF file.
  • The import format can be specified with Import["file","NetCDF"] or Import["file",{"NetCDF",elem,}].
  • Export["file.nc",expr] exports a numeric array to netCDF.
  • Export["file.nc",{expr1,}, {"Datasets",{"dataset1",}}] creates a netCDF file, storing the data arrays {expr1,} as separate datasets.
  • Export["file.nc",expr,elem] exports the specified element to a netCDF file.
  • Export["file.nc",elem1->expr1,,"Rules"] uses rules to specify the elements to be exported.
  • See the following reference pages for full general information:
  • Import, Exportimport from or export to a file
    CloudImport, CloudExportimport from or export to a cloud object
    ImportString, ExportStringimport from or export to a string
    ImportByteArray, ExportByteArrayimport from or export to a byte array

Import Elements

  • General Import elements:
  • "Elements" list of elements and options available in this file
    "Summary"summary of the file
    "Rules"list of rules for all available elements
  • Structure elements:
  • "Datasets"names of all datasets
    "Groups"names of all groups
    "StructureGraph"a directed graph showing the structure of the datasets
    "StructureGraphLegend"legend for the structure graph
    "Summary"summary of properties
    "Version"netCDF version of the file
  • Names of groups and datasets are given as the absolute paths starting with the root group name "/".
  • Import by default uses the "Datasets" element for the netCDF format.
  • Data representation elements:
  • "Data"all datasets imported as an association
    {"Data",dataset} or datasetnamed dataset
  • The following basic data types are supported:
  • "Integer8"8-bit integers
    "Integer16"16-bit integers
    "Integer32"32-bit integers
    "Integer64"64-bit integers
    "UnsignedInteger8"8-bit unsigned integers
    "UnsignedInteger16"16-bit unsigned integers
    "UnsignedInteger32"32-bit unsigned integers
    "UnsignedInteger64"64-bit unsigned integers
    "Real32"IEEE singleprecision numbers
    "Real64"IEEE doubleprecision numbers
    "String"string of ASCII characters
  • The following structured data types are supported:
  • "ByteArray"a ByteArray of an arbitrary length
    "Enum"an enumeration
    "Compound"a compound dataset consisting of any other data format and other compound datasets
  • Metadata elements:
  • "Attributes"attributes of all groups and datasets
    "DataEncoding"specifies how each dataset is compressed
    "DataFormat"type used to represent each dataset
    "Dimensions"data dimensions of each dataset
    "DimensionNames"names of dimensions of each dataset
    {"metadata",dataset}metadata of the named dataset
    "Metadata"global attributes (attributes of the root group)

Export Elements

  • General Export element:
  • "Rules"a list of imported elements in the form of elemexpr
  • Export["file.nc",{elem1->expr1,},"Rules"] uses rules to specify the elements to be exported.
  • Available Export elements:
  • "Attributes"attributes associated to groups and datasets
    "Datasets"datasets and their associated elements
    "Dimensions"dimensions of the datasets
    "Groups"a list of group names
    "NamedDataTypes"named data types
  • With the "Attributes" element, the following expressions can be given:
  • attrattributes associated to the root group "/"
    {path1attr1,}attributes attri associated to the specified pathi
  • Attributes attri should be given in the form "attname"->attval.
  • With the "Datasets" element, the following expressions can be given:
  • datastores data under "Dataset1"
    {"name1"data1,}a list of dataset names and their associated data
    {"name1"ds1,}specifies each dataset dsi using a list of rules
  • Datasets dsi can take the following keys:
  • "Attributes"dataset attributes
    "Data"array of data
    "DataEncoding"one or more data encodings to use
    "DataFormat"data type
    "DimensionNames"names associated to array dimensions
  • The "NamedDataTypes" element can be a list of {"name1"type1,} where each typei can be an association of the following forms:
  • <|"Class""ByteArray",|>takes a "Length" key
    <|"Class""Compound",|>takes "Dimensions" and "Structure" keys
    <|"Class""Enumerated",|>takes "DataFormat" and "Structure"
    <|"Class""RaggedArray",|>takes "DataFormat" and "Dimensions" keys

Options

  • Export option:
  • ByteOrdering$ByteOrderingwhat byte ordering to use
    OverwriteTargetTruewhether to overwrite an existing file
    "Version""NC4 Enhanced"version of the file format to create
  • Using OverwriteTarget->"Append", new objects may be added to an existing file.
  • Possible values for "Version" are: "Classic" (Version 3), "Classic 64bit", "NC4 Classic" or "NC4 Enhanced" (Version 4).

Examples

open allclose all

Basic Examples  (3)

Get the names of datasets stored in a netCDF file:

Get the file summary:

Read metainformation from a netCDF file:

Export raster image data to the netCDF format:

This gives the names of the datasets stored in this file:

Scope  (13)

Import  (7)

Show all elements available in the file:

Import, by default, returns the list of datasets in the file:

Import the file structure, specifying the format explicitly:

Import contents of a dataset by specifying its name:

Import dimensions and data format for all datasets in the file:

Import dimensions and data format of a single dataset:

Import a dataset:

Render the imported data as graphics:

Export  (6)

Export a matrix to NetCDF:

Show the datasets contained in this file:

Export a named dataset:

Export two matrices to NetCDF:

Export a named dataset with given data type:

Import the data format:

Export a named compound data type in a group:

Import the file structure:

Export named datasets with attributes:

Import attributes of a particular group:

Import all attributes stored in a file:

Import Elements  (23)

Attributes  (3)

Import attributes of all groups and datasets in the file:

Import attributes of a specific dataset:

Import attributes of multiple objects:

Data  (3)

Get data from all datasets in the file:

Import data from the "MyData" dataset inside the "MyGroup" group:

When importing data from a single dataset, the "Data" element should not be specifically provided:

Import data from multiple datasets:

DataFormat  (2)

Get data type description for every dataset in the file:

Simple numeric and string types have one-word descriptions:

"DataFormat" for a compound type shows class and structure:

"DataFormat" for enumerated types includes class, base data format and a list of values and names:

Datasets  (2)

Import names of all datasets in a file:

"Datasets" is the default netCDF element:

Dimensions  (3)

Get dimensions of all datasets in a file:

Dimensions of data with only a single element are indicated by an empty list:

Get dimensions of a specific dataset:

DimensionNames  (2)

Get dimension names of all datasets in a file:

Get dimension names of a specific dataset:

Groups  (1)

Import names of all groups in the file:

Metadata  (2)

Get file metadata (attributes of the root group):

Metadata often carries information about data source:

NamedDimensions  (3)

Import all named dimensions in the file:

Dimensions may be unlimited:

Import named dimension to get coordinate values along this dimension:

Inspecting attributes often gives more information about the dimension:

Interpret time coordinates according to the information obtained from the attribute:

Summary  (1)

Get the file summary:

Version  (1)

Get the version of netCDF format:

NetCDF Version 4 is supported:

Export Elements  (25)

"Attributes"  (4)

Attach attributes to the root group:

Specify data format for attributes:

Export dataset attributes both in "Datasets" and "Attributes" elements:

Each attribute must have a name that is unique among all attributes attached to the same object:

Overwrite attribute value in existing file:

"Datasets"  (10)

"Datasets" is the default export element. Data format and dimensions are automatically inferred from the expression:

Export expressions into different datasets, each of which can have a full path:

Inspect the structure of the NetCDF file:

Export a dataset with a custom data format:

Export a dataset with an attribute:

Create a scalar dataset with a single integer:

Create an array of integer numbers:

Export an array of real numbers:

Create a dataset with strings:

A ByteArray is stored as a "ByteArray" type (also called the opaque type in NetCDF4):

Associations with string keys are exported as elements of a compound type:

"Groups"  (2)

NetCDF files always have a root group (with path "/"):

Export multiple groups by giving a list of paths:

"NamedDatatypes"  (3)

Export a compound named data type to a NetCDF file:

Use the previously exported type when exporting a dataset:

Import data format and dimensions of the dataset:

Inspect exported data:

Export a nested compound type:

Simple scalar types cannot be stored in a NetCDF file:

"NamedDimensions"  (5)

Every dimension of a NetCDF dataset must be stored in the file as separate entity. When dimensions' names are not explicitly specified, they will be assigned automatically generated names:

Specify dimension names explicitly:

Export dimensions explicitly in the form of "name"size, where as size means unlimited dimension:

Named dimensions can later be used when defining datasets:

Notice that the size of the "x" dimension has increased:

See the file structure:

Export a dimension with explicit coordinate values that will be stored in a dataset with the same name:

Create an unlimited dimension with only the first few coordinates specified:

"Rules"  (1)

Export two matrices using the "Rules" specification:

Export Options  (6)

OverwriteTarget  (2)

By default, a new file is created for each call to Export:

With OverwriteTargetFalse, existing files will not be overwritten:

To append datasets to an existing file, use OverwriteTarget"Append":

"Version"  (4)

By default, Export creates NetCDF4 files with enhanced data model:

Export data to classic NetCDF format:

Export data to classic NetCDF format with 64-bit offset:

Export data to NetCDF4 format with classic data model:

Applications  (1)

Download a netCDF file with sea surface temperature data:

Import general information about the file:

Get the list of all datasets in the file:

Read attributes of every dataset:

Get a description of every dataset to see what they contain:

Read all attributes of the "/sst" dataset:

Import dimensions of the dataset; notice that time is the first dimension:

Read the data:

Determine the range of collected data (removing duplicated first) and add a small margin to it:

Visualize the changes of sea surface temperature:

Learn more about the file contents by inspecting metadata, for instance, how the data was collected:

Properties & Relations  (1)

Every netCDF4 file is also a valid HDF5 file:

Not every HDF5 file is a valid netCDF file:

Simple HDF5 files can be read by netCDF import: