Xarray Backend Entrypoint for cfapyx

cfapyx.backend.open_cfa_dataset(filename_or_obj, drop_variables=None, mask_and_scale=False, decode_times=True, concat_characters=None, decode_coords=None, use_cftime=None, decode_timedelta=None, cfa_options: dict = None, group=None)[source]

Top-level function which opens a CFA dataset using Xarray.

Creates a CFA Datastore from the filename_or_obj provided, then passes this to a CFA StoreBackendEntrypoint to create an Xarray Dataset. Most parameters are not handled by CFA, so only the CFA-relevant ones are described here.

Parameters:
  • filename_or_obj – (str) The path to a CFA-netCDF file to be opened by Xarray

  • cfa_options – (dict) A set of kwargs provided to CFA which provide additional configurations. Currently implemented are: substitutions (dict), decode_cfa (bool)

  • group – (str) The name or path to a NetCDF group. CFA can handle opening from specific groups and will inherit both group and global dimensions/attributes.

Returns:

An xarray.Dataset object composed of xarray.DataArray objects representing the different NetCDF variables and dimensions. CFA aggregated variables are decoded unless the decode_cfa parameter in cfa_options is false.

class cfapyx.backend.CFANetCDFBackendEntrypoint[source]

Open CFA-netCDF files (.nca) using ‘cfapyx’ in Xarray

open_dataset(filename_or_obj, *, drop_variables=None, mask_and_scale=False, decode_times=True, concat_characters=None, decode_coords=None, use_cftime=None, decode_timedelta=None, cfa_options=None, group=None)[source]

Returns a complete xarray representation of a CFA-netCDF dataset which includes expanding/decoding CFA aggregated variables into proper arrays.

class cfapyx.backend.CFADatetimeCoder(variables: Mapping[str, Variable] | None = None, use_cftime: bool | None = None, time_unit: str = 'ns')[source]

CFA-aware extension of Xarray’s CFDatetimeCoder.

Xarray’s default CFDatetimeCoder decodes an example_value assembled from the first and last items of a variable’s array in order to infer the decoded datetime dtype (e.g. datetime64[ns] vs object for cftime.datetime). For CFA-aggregated variables such as time_bnds, fetching those items forces remote fragment files to be opened at dataset open time even when the variable is never accessed.

CFADatetimeCoder bypasses fragment fetching for CFA-aggregated variables by generating example_value from the corresponding non-aggregated coordinate variable (such as time) already stored in the CFA dataset.

decode(variable: Variable, name=None) → Variable[source]

Custom Datetime decoder, defaults to CFDatetimeCoder.decode where not using a CFA FragmentArrayWrapper for a variable.

class cfapyx.backend.CFAStoreBackendEntrypoint[source]

Open CFA-based Abstract Data Store

open_dataset(cfa_xarray_store, decode_times=True, concat_characters=True, decode_coords=True, drop_variables=None, use_cftime=None, decode_timedelta=None) → Dataset[source]

Takes cfa_xarray_store of type AbstractDataStore and creates an xarray.Dataset object. Most parameters are not handled by CFA, so only the CFA-relevant ones are described here.

Parameters:

cfa_xarray_store – (obj) The CFA Datastore object which loads and decodes CFA aggregated variables and dimensions.

Returns:

An xarray.Dataset object composed of xarray.DataArray objects representing the different NetCDF variables and dimensions. CFA aggregated variables are decoded unless the decode_cfa parameter in cfa_options is false.