cfdm.netcdf_indexer

cfdm.netcdf_indexer(variable, mask=True, unpack=True, always_masked_array=False, orthogonal_indexing=False, attributes=None, copy=False)[source]

A data indexer that also applies netCDF masking and unpacking.

Here “netCDF” refers to the API of the netCDF data model, rather than any particular dataset encoding or software library API.

Indexing may be orthogonal or non-orthogonal. Orthogonal indexing means that the index for each dimension is applied independently, regardless of how that index was defined. For instance, the indices [[0, 1], [1, 3], 0] and [:2, 1:4:2, 0] will give identical results. Orthogonal indexing is different to the indexing behaviour of numpy. Non-orthogonal indexing means that normal numpy indexing rules are applied.

In addition, string and character variables are always converted to unicode arrays, the latter with the last dimension concatenated.

Masking and unpacking operations, either or both may be disabled via initialisation options, are defined by the conventions for netCDF attributes, which are either provided as part of the input variable object, or given with the input attributes parameter.

The relevant netCDF attributes that are considered are:

  • For masking: missing_value, valid_max, valid_min,

    valid_range, _FillValue, and _Unsigned. Note that if _FillValue is not present then the netCDF default value for the appropriate data type will be assumed, as defined by netCDF4.default_fillvals.

  • For unpacking: add_offset, scale_factor, and

    _Unsigned

Added in version (cfdm): 1.11.2.0

Examples

>>> import netCDF4
>>> nc = netCDF4.Dataset('file.nc', 'r')
>>> x = cfdm.netcdf_indexer(nc.variables['x'])
>>> x.shape
(12, 64, 128)
>>> print(x[0, 0:4, 0:3])
[[236.5, 236.2, 236.0],
 [240.9, --   , 239.6],
 [243.4, 242.4, 241.3],
 [243.1, 241.7, 240.4]]

>>> import h5netcdf
>>> h5 = h5netcdf.File('file.nc', 'r')
>>> x = cfdm.netcdf_indexer(h5.variables['x'])
>>> x.shape
(12, 64, 128)
>>> print(x[0, 0:4, 0:3])
[[236.5, 236.2, 236.0],
 [240.9, --   , 239.6],
 [243.4, 242.4, 241.3],
 [243.1, 241.7, 240.4]]

>>> import numpy as np
>>> n = np.arange(7)
>>> x = cfdm.netcdf_indexer(n)
>>> x.shape
(7,)
>>> print(x[...])
[0 1 2 3 4 5 6]
>>> x = cfdm.netcdf_indexer(n, attributes={'_FillValue': 4})
>>> print(x[...])
[0 1 2 3 -- 5 6]
>>> x = cfdm.netcdf_indexer(n, mask=False, attributes={'_FillValue': 4})
>>> print(x[...])
[0 1 2 3 4 5 6]