sandplover.io.NetCDFIO

class sandplover.io.NetCDFIO(data_path, auxdata_path=None, engine=None, write=False)

Utility for consistent IO with netCDF4 files.

This module wraps calls to the netCDF4 python module in a consistent API, so the user can work seamlessly with either netCDF4 files or HDF5 files. The public methods of this class are consistent with HDFIO.

Note that the netCDF4, netCDF4-classic, and HDF5 file standards are very similar and (almost) interchangable. This means that the same data loader can be used to handle these files. We use the xarray data reader which supports the netCDF4/HDF5 file-format.

Older file formats such as netCDF3 or HDF4 are unsupported. For more information about the netCDF4 format, visit the netCDF4 docs.

__init__(data_path, auxdata_path=None, engine=None, write=False)

Initialize the NetCDFIO handler.

Initialize a connection to a NetCDF file.

Parameters:

  • data_path (str) – Path to file to read or write to.

  • auxdata_path (str, optional) – Path to auxilliary data that exist in the file. This is most commonly the name of a group within the file. Default is None, and no auxilliary data is assigned.

  • engine (str, optional) – Engine used to open the file with xarray. Default is None, which will lead to trying to infer from file extension. If no inference can be made, we pass no engine during loading and allow xarray to attempt to determine the file type. For a netCDF4 file use ‘netcdf4’ or for an HDF5 file use ‘h5netcdf’, or any other valid engine for xarray.

  • write (bool, optional) – Whether to allow writing to an existing file. Set to False by default, if a file already exists at data_path, writing is disabled, unless write is set to True.

Methods

__init__(data_path[, auxdata_path, engine, ...])

Initialize the NetCDFIO handler.

connect()

Connect to the data file.

get_known_coords()

List known coordinates.

get_known_variables()

List known variables.

read(var[, force])

Read variable from file and into memory.

write()

Write data to file.

Attributes

aux

data_path

Path to data file.

keys

Variable names in file.

meta

alias for backwards compatability
connect()

Connect to the data file.

Initialize the file if it does not exist, or simply return if the file already exists. This connection to the data file is “lazy” loading, meaning that array values are not being loaded into memory.

Note

This function is automatically called during initialization of any IO object, so it is not necessary to call it directly.

property data_path

Path to data file.

Parameters:

data_path (str) – path to data file for IO operations.

Notes

The setter method validates the path, and returns a FileNotFoundError if the file is not found.

Type:

str

get_known_coords()

List known coordinates.

These coordinates are pulled from the loaded dataset.

get_known_variables()

List known variables.

These variables are pulled from the loaded dataset.

property keys

Variable names in file.

property meta

alias for backwards compatability

read(var, force=False)

Read variable from file and into memory.

Converts variables in data file to xarray objects for coersion into a Cube instance.

Parameters:

  • var (str) – Which variable to load from the file.

  • force (bool, optional) – If True, bypass memory safety checks and load the data regardless of size. Default is False.

Warning

If the variable size exceeds 80% of currently available RAM and force=False, a warning will be issued and the data will NOT be loaded into memory. Set force=True to override this check.

write()

Write data to file.

Take a Cube and write it to file.

Warning

Not Implemented.