cfapyx 1.0.0__tar.gz

cfapyx-1.0.0/LICENSE

@@ -0,0 +1,31 @@
+BSD 3-Clause License
+
+Copyright (c) 2023-2024, Centre of Environmental Data Analysis Developers,
+Scientific and Technical Facilities Council (STFC),
+UK Research and Innovation (UKRI).
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without 
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this 
+list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this 
+list of conditions and the following disclaimer in the documentation and/or other 
+materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors 
+may be used to endorse or promote products derived from this software without 
+specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS”
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

cfapyx-1.0.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: cfapyx
+Version: 1.0.0
+Summary: The pure-Python implementation of the CF Aggregation conventions, including the Xarray engine to enable reading CFA-netCDF files.
+License: BSD 3
+License-File: LICENSE
+Author: Daniel Westwood
+Author-email: daniel.westwood@stfc.ac.uk
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Dist: cftime (>=1.6.5,<2.0.0)
+Requires-Dist: dask (>=2025.3.0)
+Requires-Dist: netCDF4 (>=1.7.2)
+Requires-Dist: numpy (>=2.0.0)
+Requires-Dist: pint (>=0.25.3,<0.26.0)
+Requires-Dist: pyfive (>=1.1.2,<2.0.0)
+Requires-Dist: xarray (>=2025.11.0)
+Description-Content-Type: text/markdown
+
+![CFAPyX long logo: Blue, Green and White squares arranged in Diamond formation](https://github.com/cedadev/CFAPyX/blob/main/docs/source/_images/CFAPyX_long.jpg)
+
+![Static Badge](https://img.shields.io/badge/Xarray%20Engine%20Component-1E4B23)
+[![PyPI version](https://badge.fury.io/py/cfapyx.svg)](https://pypi.python.org/pypi/cfapyx/)
+
+CFA python Xarray module for using CFA files with xarray.
+
+See the [Documentation](https://cedadev.github.io/CFAPyX/) for more details.
+cfapyx on [Github](https://github.com/cedadev/CFAPyX)
+
+For use with the Xarray module as an additional backend.
+
+> **_NOTE:_** The `create` functionality was added to version 2024.10.11 and is currently in alpha release. Please report any unexpected errors or issues using the GitHub Issues tab for this repository.
+
+# Installation
+
+```
+pip install cfapyx
+```
+
+# Usage as Xarray Engine
+
+```
+import xarray as xr
+
+ds = xr.open_dataset('cfa_file.nca', engine='CFA')
+# Continue as normal
+
+```
+

cfapyx-1.0.0/README.md

@@ -0,0 +1,29 @@
+![CFAPyX long logo: Blue, Green and White squares arranged in Diamond formation](https://github.com/cedadev/CFAPyX/blob/main/docs/source/_images/CFAPyX_long.jpg)
+
+![Static Badge](https://img.shields.io/badge/Xarray%20Engine%20Component-1E4B23)
+[![PyPI version](https://badge.fury.io/py/cfapyx.svg)](https://pypi.python.org/pypi/cfapyx/)
+
+CFA python Xarray module for using CFA files with xarray.
+
+See the [Documentation](https://cedadev.github.io/CFAPyX/) for more details.
+cfapyx on [Github](https://github.com/cedadev/CFAPyX)
+
+For use with the Xarray module as an additional backend.
+
+> **_NOTE:_** The `create` functionality was added to version 2024.10.11 and is currently in alpha release. Please report any unexpected errors or issues using the GitHub Issues tab for this repository.
+
+# Installation
+
+```
+pip install cfapyx
+```
+
+# Usage as Xarray Engine
+
+```
+import xarray as xr
+
+ds = xr.open_dataset('cfa_file.nca', engine='CFA')
+# Continue as normal
+
+```

cfapyx-1.0.0/cfapyx/__init__.py

@@ -0,0 +1,3 @@
+from .backend import CFANetCDFBackendEntrypoint as CFANetCDFBackendEntrypoint
+from .creator import CFANetCDF as CFANetCDF
+from .utils import set_verbose as set_verbose

cfapyx-1.0.0/cfapyx/backend.py

@@ -0,0 +1,181 @@
+__author__ = "Daniel Westwood"
+__contact__ = "daniel.westwood@stfc.ac.uk"
+__copyright__ = "Copyright 2024 United Kingdom Research and Innovation"
+
+import logging
+
+from xarray import conventions
+from xarray.backends import BackendEntrypoint, StoreBackendEntrypoint
+from xarray.backends.common import AbstractDataStore
+from xarray.core.dataset import Dataset
+
+from cfapyx.datastore import CFADataStore
+from cfapyx.utils import logstream
+
+logger = logging.getLogger(__name__)
+
+logger.addHandler(logstream)
+logger.propagate = False
+
+
+def 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,
+):
+    """
+    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.
+
+    :param filename_or_obj:       (str) The path to a CFA-netCDF file to be
+        opened by Xarray
+
+    :param cfa_options:           (dict) A set of kwargs provided to CFA which
+        provide additional configurations. Currently implemented are:
+        substitutions (dict), decode_cfa (bool)
+
+    :param 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.
+    """
+
+    cfa_options = cfa_options or {}
+
+    # Load the CFA datastore from the provided file (object not supported).
+    store = CFADataStore.open(filename_or_obj, group=group)
+
+    # Expands cfa_options into individual kwargs for the store.
+    store.cfa_options = cfa_options
+    # Mask/scale decoding now done internally.
+    store.mask_and_scale = mask_and_scale
+
+    # Xarray makes use of StoreBackendEntrypoints to provide the Dataset 'ds'
+    store_entrypoint = CFAStoreBackendEntrypoint()
+    ds = store_entrypoint.open_dataset(
+        store,
+        decode_times=decode_times,
+        concat_characters=concat_characters,
+        decode_coords=decode_coords,
+        drop_variables=drop_variables,
+        use_cftime=use_cftime,
+        decode_timedelta=decode_timedelta,
+    )
+
+    return ds
+
+
+class CFANetCDFBackendEntrypoint(BackendEntrypoint):
+    """Open CFA-netCDF files (.nca) using 'cfapyx' in Xarray"""
+
+    description = 'Open CFA-netCDF files (.nca) using "cfapyx" in Xarray'
+    url = "https://cedadev.github.io/CFAPyX/"
+
+    def open_dataset(
+        self,
+        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,
+        # backend specific keyword arguments
+        # do not use 'chunks' or 'cache' here
+    ):
+        """
+        Returns a complete xarray representation of a CFA-netCDF dataset which
+        includes expanding/decoding CFA aggregated variables into proper arrays.
+        """
+
+        cfa_options = cfa_options or {}
+
+        return open_cfa_dataset(
+            filename_or_obj,
+            drop_variables=drop_variables,
+            mask_and_scale=mask_and_scale,
+            decode_times=decode_times,
+            concat_characters=concat_characters,
+            decode_coords=decode_coords,
+            use_cftime=use_cftime,
+            decode_timedelta=decode_timedelta,
+            cfa_options=cfa_options,
+            group=group,
+        )
+
+
+class CFAStoreBackendEntrypoint(StoreBackendEntrypoint):
+    """Open CFA-based Abstract Data Store"""
+
+    description = "Open CFA-based Abstract Data Store"
+    url = "https://cedadev.github.io/CFAPyX/"
+
+    def open_dataset(
+        self,
+        cfa_xarray_store,
+        decode_times=True,
+        concat_characters=True,
+        decode_coords=True,
+        drop_variables=None,
+        use_cftime=None,
+        decode_timedelta=None,
+    ) -> Dataset:
+        """
+        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.
+
+        :param 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.
+
+        """
+        assert isinstance(cfa_xarray_store, AbstractDataStore)
+
+        # Same as NetCDF4 operations, just with the CFA Datastore
+        vars, attrs = cfa_xarray_store.load()
+        encoding = cfa_xarray_store.get_encoding()
+
+        # Ensures variables/attributes comply with CF conventions.
+        vars, attrs, coord_names = conventions.decode_cf_variables(
+            vars,
+            attrs,
+            decode_times=decode_times,
+            concat_characters=concat_characters,
+            decode_coords=decode_coords,
+            drop_variables=drop_variables,
+            use_cftime=use_cftime,
+            decode_timedelta=decode_timedelta,
+        )
+
+        # Create the xarray.Dataset object here.
+        ds = Dataset(vars, attrs=attrs)
+
+        ds = ds.set_coords(coord_names.intersection(vars))
+        ds.set_close(cfa_xarray_store.close)
+        ds.encoding = encoding
+
+        return ds