pycontrails 0.58.0__cp314-cp314-macosx_10_13_x86_64.whl

pycontrails/utils/json.py

@@ -0,0 +1,187 @@
+"""JSON utilities."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+
+class NumpyEncoder(json.JSONEncoder):
+    """Custom JSONEncoder for numpy data types.
+
+    Examples
+    --------
+    >>> import json
+    >>> import numpy as np
+    >>> from pycontrails.utils.json import NumpyEncoder
+
+    >>> data = np.array([0, 1, 2, 3])
+    >>> json.dumps(data, cls=NumpyEncoder)
+    '[0, 1, 2, 3]'
+
+    >>> data = np.datetime64(1234567890, "s")
+    >>> json.dumps(data, cls=NumpyEncoder)
+    '"2009-02-13T23:31:30"'
+
+    Notes
+    -----
+    Adapted https://github.com/hmallen/numpyencoder/blob/master/numpyencoder/numpyencoder.py
+    """
+
+    def default(self, obj: Any) -> Any:
+        """Encode numpy data types.
+
+        This method overrides :meth:`default` on the JSONEncoder class.
+
+        Parameters
+        ----------
+        obj : Any
+            Object to encode.
+
+        Returns
+        -------
+        Any
+            Encoded object.
+        """
+        if isinstance(
+            obj,
+            np.int_
+            | np.intc
+            | np.intp
+            | np.int8
+            | np.int16
+            | np.int32
+            | np.int64
+            | np.uint8
+            | np.uint16
+            | np.uint32
+            | np.uint64,
+        ):
+            return int(obj)
+
+        if isinstance(obj, np.float16 | np.float32 | np.float64):
+            return float(obj)
+
+        # TODO: this is not easily reversible - np.timedelta64(str(np.timedelta64(1, "h"))) raises
+        if isinstance(obj, (np.timedelta64)):
+            return str(obj)
+
+        if isinstance(obj, (np.datetime64)):
+            return str(obj)
+
+        if isinstance(obj, np.complex64 | np.complex128):
+            return {"real": obj.real, "imag": obj.imag}
+
+        if isinstance(obj, np.ndarray):
+            return obj.tolist()
+
+        if isinstance(obj, (np.bool_)):
+            return bool(obj)
+
+        if isinstance(obj, (np.void)):
+            return None
+
+        if isinstance(obj, pd.Series | pd.Index):
+            return obj.to_numpy().tolist()
+
+        try:
+            return json.JSONEncoder.default(self, obj)
+
+        # last ditch attempt by looking for a to_json attribute
+        except TypeError as e:
+            try:
+                return obj.to_json
+            except AttributeError:
+                raise TypeError from e
+
+
+def dataframe_to_geojson_points(
+    df: pd.DataFrame,
+    properties: list[str] | None = None,
+    filter_nan: bool | list[str] = False,
+) -> dict[str, Any]:
+    """Convert a pandas DataFrame to a GeoJSON-like dictionary.
+
+    This function create a Python representation of a GeoJSON FeatureCollection with Point features
+    based on a :class:`pandas.DataFrame` with geospatial coordinate columns.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Base dataframe.
+        Must contain geospatial coordinate columns ["longitude", "latitude", "altitude", "time"]
+    properties : list[str], optional
+        Specify columns to include feature properties.
+        By default, will use all column data that is not in the coordinate columns.
+    filter_nan : bool | list[str], optional
+        Filter out points with nan values in any columns, including coordinate columns.
+        If `list of str` is input, only `filter_nan` columns will be used for filtering,
+        allowing null values in the other columns.
+
+    Returns
+    -------
+    dict[str, Any]
+        Description
+
+    Raises
+    ------
+    KeyError
+        Raises if `properties` or `filter_nan` input contains a column label that does
+        not exist in `df`
+    """
+    # required columns
+    coord_cols = ["longitude", "latitude", "altitude", "time"]
+
+    # get all properties if not defined
+    if properties is None:
+        properties = [c for c in df.columns if c not in coord_cols]
+    elif [c for c in properties if c not in df.columns]:
+        raise KeyError(
+            f"{[c for c in properties if c not in df.columns]} do not exist in dataframe"
+        )
+
+    # downselect dataframe
+    cols = ["longitude", "latitude", "altitude", "time", *properties]
+    df = df[cols]
+
+    # filter out coords with nan values, or filter just on "filter_nan" labels
+    if isinstance(filter_nan, bool) and filter_nan:
+        df = df[np.all(~np.isnan(df[cols]), axis=1)]
+    elif isinstance(filter_nan, list):
+        if [c for c in filter_nan if c not in df.columns]:
+            raise KeyError(
+                f"{[c for c in filter_nan if c not in df.columns]} do not exist in dataframe"
+            )
+        df = df[np.all(~np.isnan(df[filter_nan]), axis=1)]
+
+    def row_to_feature(row: pd.Series) -> dict[str, str | dict[str, Any]]:
+        point = [
+            np.round(row.longitude, decimals=4) if not np.isnan(row.longitude) else None,
+            np.round(row.latitude, decimals=4) if not np.isnan(row.latitude) else None,
+            np.round(row.altitude, decimals=4) if not np.isnan(row.altitude) else None,
+        ]
+        # converting to int to allow JSON serialization
+        properties = {"time": int(row.time.timestamp())}
+        used_keys = ["time", "latitude", "longitude", "altitude"]
+        unused_keys = [k for k in row.keys() if k not in used_keys]  # noqa: SIM118
+        properties.update(
+            {
+                k: (
+                    row[k]
+                    if not isinstance(row[k], float)
+                    or (isinstance(row[k], float) and not np.isnan(row[k]))
+                    else None
+                )
+                for k in unused_keys
+            }
+        )
+
+        geometry = {"type": "Point", "coordinates": point}
+        return {"type": "Feature", "geometry": geometry, "properties": properties}
+
+    features = []
+    df.apply(lambda row: features.append(row_to_feature(row)), axis=1)
+    return {"type": "FeatureCollection", "features": features}

pycontrails/utils/temp.py

@@ -0,0 +1,50 @@
+"""Temp utilities."""
+
+import logging
+import os
+import tempfile
+from collections.abc import Generator
+from contextlib import contextmanager
+
+logger = logging.getLogger(__name__)
+
+
+def temp_filename() -> str:
+    """Get a filename in the host computers temp directory.
+
+    More robust than using tempfile.NamedTemporaryFile()
+
+    Returns
+    -------
+    str
+        Temp filename
+
+    See Also
+    --------
+    temp_file : Context manager for temp file creation and cleanup
+    """
+    return os.path.join(tempfile.gettempdir(), os.urandom(24).hex())
+
+
+def remove_tempfile(temp_filename: str) -> None:
+    """Remove temp file.
+
+    Parameters
+    ----------
+    temp_filename : str
+        Temp filename
+    """
+    try:
+        os.unlink(temp_filename)
+    except OSError as e:
+        logger.warning("Failed to delete temp file %s with error %s", temp_filename, e)
+
+
+@contextmanager
+def temp_file() -> Generator[str, None, None]:
+    """Get context manager for temp file creation and cleanup."""
+    filename = temp_filename()
+    try:
+        yield filename
+    finally:
+        remove_tempfile(filename)

pycontrails/utils/types.py

@@ -0,0 +1,163 @@
+"""Convienence types."""
+
+from __future__ import annotations
+
+import functools
+import sys
+from collections.abc import Callable
+from datetime import datetime
+from typing import Any, TypeVar
+
+import numpy as np
+import numpy.typing as npt
+import pandas as pd
+import xarray as xr
+
+#: Array like (np.ndarray, xr.DataArray)
+ArrayLike = TypeVar("ArrayLike", np.ndarray, xr.DataArray)
+
+#: Array or Float (np.ndarray, float)
+ArrayOrFloat = TypeVar("ArrayOrFloat", np.ndarray, float)
+
+#: Array like input (np.ndarray, xr.DataArray, float)
+ArrayScalarLike = TypeVar("ArrayScalarLike", np.ndarray, xr.DataArray, float)
+
+#: Datetime like input (datetime, pd.Timestamp, np.datetime64)
+DatetimeLike = TypeVar("DatetimeLike", datetime, pd.Timestamp, np.datetime64, str)
+
+# Crude fix for autodoc issue calling TypeVar.__dict__ on Python 3.13
+if "sphinx" in sys.modules and sys.version_info >= (3, 13):
+    ArrayLike.__dict__ = {}
+    ArrayOrFloat.__dict__ = {}
+    ArrayScalarLike.__dict__ = {}
+    DatetimeLike.__dict__ = {}
+
+
+def support_arraylike(
+    func: Callable[[npt.NDArray[np.floating]], npt.NDArray[np.floating]],
+) -> Callable[[ArrayScalarLike], ArrayScalarLike]:
+    """Extend a numpy universal function operating on arrays of floats.
+
+    This decorator allows `func` to support any ArrayScalarLike parameter and
+    keeps the return type consistent with the parameter.
+
+    Parameters
+    ----------
+    func : Callable[[ArrayScalarLike], np.ndarray]
+        A numpy `ufunc` taking in a single array with `float`-like dtype.
+        This decorator assumes `func` returns a numpy array.
+
+    Returns
+    -------
+    Callable[[ArrayScalarLike], ArrayScalarLike]
+        Extended function.
+
+    See Also
+    --------
+    - `numpy ufuncs <https://numpy.org/doc/stable/reference/ufuncs.html>`_
+    """
+
+    def wrapped(arr: ArrayScalarLike) -> ArrayScalarLike:
+        x = np.asarray(arr)
+
+        # Convert to float if not already
+        if x.dtype not in (np.float32, np.float64):
+            x = x.astype(np.float64)
+        ret = func(x)
+
+        # Numpy in, numpy out
+        if isinstance(arr, np.ndarray):
+            return ret
+
+        # Keep python native numeric types native
+        if isinstance(arr, float | int):
+            return ret.item()
+
+        # Recreate pd.Series
+        if isinstance(arr, pd.Series):
+            return pd.Series(data=ret, index=arr.index)
+
+        # Recreate xr.DataArray
+        if isinstance(arr, xr.DataArray):
+            return arr.copy(data=ret)  # See documentation for xr.copy!
+
+        # Pass numpy `ret` through for anything else
+        return ret
+
+    # this line produces a mypy error starting on mypy version 1.1.0,
+    # likely due to changes in https://github.com/python/mypy/pull/16942
+    return functools.update_wrapper(wrapped, func)  # type: ignore
+
+
+def apply_nan_mask_to_arraylike(arr: ArrayLike, nan_mask: np.ndarray) -> ArrayLike:
+    """Apply ``nan_mask`` to ``arr`` while maintaining the type.
+
+    The parameter ``arr`` should have a ``float`` ``dtype``.
+
+    This function is tested against :class:`xr.DataArray`, :class:`pd.Series`, and
+    :class:`np.ndarray` types.
+
+    Parameters
+    ----------
+    arr : ArrayLike
+        Array with ``np.float64`` entries
+    nan_mask : np.ndarray
+        Boolean array of the same shape as ``arr``
+
+    Returns
+    -------
+    ArrayLike
+        Array ``arr`` with values in ``nan_mask`` set to ``np.nan``. The ``arr`` is
+        mutated in place if it is a :class:`np.ndarray`. For :class:`xr.DataArray`,
+        a copy is returned.
+
+    Notes
+    -----
+    When ``arr`` is a :class:`xr.DataArray`, this function keeps any ``attrs``
+    from ``arr`` in the returned instance.
+    """
+    if isinstance(arr, xr.DataArray):
+        # The previous implementation uses xr.where instead of arr.where
+        # There was some change in xarray 2022.6.0 that broke the former implementation
+        # Instead, use arr.where
+        return arr.where(~nan_mask, np.nan)
+
+    # If we want to avoid copying, use np.where(~nan_mask, arr, np.nan)
+    arr[nan_mask] = np.nan
+    return arr
+
+
+_Object = TypeVar("_Object")
+
+
+def type_guard(
+    obj: Any,
+    type_: type[_Object] | tuple[type[_Object], ...],
+    error_message: str | None = None,
+) -> _Object:
+    """Shortcut utility to type guard a variable with custom error message.
+
+    Parameters
+    ----------
+    obj : Any
+        Any variable object
+    type_ : Type[_Object]
+        Type of variable.
+        Can be a tuple of types
+    error_message : str, optional
+        Custom error message
+
+    Returns
+    -------
+    _Object
+        Returns the input object ensured to be ``type_``
+
+    Raises
+    ------
+    ValueError
+        Raises ValueError if ``obj`` is not ``type_``
+    """
+    if not isinstance(obj, type_):
+        raise TypeError(error_message or f"Object must be of type {type_}")
+
+    return obj

pycontrails-0.58.0.dist-info/METADATA

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: pycontrails
+Version: 0.58.0
+Summary: Python library for modeling aviation climate impacts
+Author-email: "Contrails.org" <py@contrails.org>
+License-Expression: Apache-2.0
+Project-URL: Changelog, https://py.contrails.org/changelog.html
+Project-URL: Documentation, https://py.contrails.org
+Project-URL: Issues, https://github.com/contrailcirrus/pycontrails/issues
+Project-URL: Repository, https://github.com/contrailcirrus/pycontrails
+Keywords: contrails,climate,aviation,geospatial
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+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: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: dask>=2022.3
+Requires-Dist: numpy>=1.22
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.12
+Requires-Dist: typing-extensions>=4.5; python_version < "3.12"
+Requires-Dist: xarray>=2022.3
+Provides-Extra: complete
+Requires-Dist: pycontrails[ecmwf,gcp,gfs,jupyter,pyproj,sat,vis,zarr]; extra == "complete"
+Provides-Extra: dev
+Requires-Dist: fastparquet>=0.8; extra == "dev"
+Requires-Dist: ipdb>=0.13; extra == "dev"
+Requires-Dist: memory_profiler; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: mypy-extensions>=1.0; extra == "dev"
+Requires-Dist: platformdirs>=3.0; extra == "dev"
+Requires-Dist: pre-commit>=2.10; extra == "dev"
+Requires-Dist: psutil; extra == "dev"
+Requires-Dist: pyarrow>=5.0; extra == "dev"
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: pytest-cov>=2.11; extra == "dev"
+Requires-Dist: requests>=2.25; extra == "dev"
+Requires-Dist: ruff>=0.9.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: doc8>=1.1; extra == "docs"
+Requires-Dist: furo>=2023.3; extra == "docs"
+Requires-Dist: myst-parser>=1.0; extra == "docs"
+Requires-Dist: nb-clean>=3.2; extra == "docs"
+Requires-Dist: nbsphinx>=0.9; extra == "docs"
+Requires-Dist: nbval!=0.10.0,>=0.9.6; extra == "docs"
+Requires-Dist: pytest-check-links>=0.8.0; extra == "docs"
+Requires-Dist: sphinx>=4.2; extra == "docs"
+Requires-Dist: sphinx-autobuild>=0.7; extra == "docs"
+Requires-Dist: sphinxcontrib-bibtex>=2.2; extra == "docs"
+Requires-Dist: sphinx_copybutton>=0.5; extra == "docs"
+Requires-Dist: sphinxext.opengraph>=0.8; extra == "docs"
+Provides-Extra: ecmwf
+Requires-Dist: cdsapi>=0.4; extra == "ecmwf"
+Requires-Dist: cfgrib>=0.9; extra == "ecmwf"
+Requires-Dist: eccodes>=2.38; extra == "ecmwf"
+Requires-Dist: ecmwf-api-client>=1.6; extra == "ecmwf"
+Requires-Dist: netcdf4>=1.6.1; extra == "ecmwf"
+Requires-Dist: platformdirs>=3.0; extra == "ecmwf"
+Requires-Dist: requests>=2.25; extra == "ecmwf"
+Provides-Extra: gcp
+Requires-Dist: google-cloud-storage>=2.1; extra == "gcp"
+Requires-Dist: platformdirs>=3.0; extra == "gcp"
+Requires-Dist: tqdm>=4.61; extra == "gcp"
+Provides-Extra: gfs
+Requires-Dist: cfgrib>=0.9; extra == "gfs"
+Requires-Dist: eccodes>=2.38; extra == "gfs"
+Requires-Dist: netcdf4>=1.6.1; extra == "gfs"
+Requires-Dist: platformdirs>=3.0; extra == "gfs"
+Requires-Dist: tqdm>=4.61; extra == "gfs"
+Provides-Extra: jupyter
+Requires-Dist: ipywidgets>=7.6; extra == "jupyter"
+Requires-Dist: jupyterlab>=2.2; extra == "jupyter"
+Provides-Extra: sat
+Requires-Dist: cartopy>=0.22; extra == "sat"
+Requires-Dist: db-dtypes>=1.2; extra == "sat"
+Requires-Dist: gcsfs>=2022.3; extra == "sat"
+Requires-Dist: geojson>=3.1; extra == "sat"
+Requires-Dist: geopandas>=1.1.1; extra == "sat"
+Requires-Dist: google-cloud-bigquery>=3.23; extra == "sat"
+Requires-Dist: google-cloud-bigquery-storage>=2.25; extra == "sat"
+Requires-Dist: pillow>=10.3; extra == "sat"
+Requires-Dist: pyproj>=3.5; extra == "sat"
+Requires-Dist: rasterio>=1.3; extra == "sat"
+Requires-Dist: s3fs>=2022.3; extra == "sat"
+Requires-Dist: scikit-image>=0.18; extra == "sat"
+Requires-Dist: shapely>=2.0; extra == "sat"
+Provides-Extra: open3d
+Requires-Dist: open3d>=0.14; extra == "open3d"
+Provides-Extra: pyproj
+Requires-Dist: pyproj>=3.5; extra == "pyproj"
+Provides-Extra: vis
+Requires-Dist: matplotlib>=3.3; extra == "vis"
+Requires-Dist: opencv-python-headless>=4.5; extra == "vis"
+Requires-Dist: scikit-learn>=0.23; extra == "vis"
+Requires-Dist: scikit-image>=0.18; extra == "vis"
+Requires-Dist: seaborn>=0.11; extra == "vis"
+Requires-Dist: shapely>=2.0; extra == "vis"
+Provides-Extra: zarr
+Requires-Dist: fsspec>=2022.7.1; extra == "zarr"
+Requires-Dist: gcsfs>=2022.7.1; extra == "zarr"
+Requires-Dist: zarr>=2.12; extra == "zarr"
+Dynamic: license-file
+
+# pycontrails
+
+> Python library for modeling aviation climate impacts
+
+|               |                                                                   |
+|---------------|-------------------------------------------------------------------|
+| **Version**   | [![PyPI version](https://img.shields.io/pypi/v/pycontrails.svg)](https://pypi.python.org/pypi/pycontrails)  [![conda-forge version](https://anaconda.org/conda-forge/pycontrails/badges/version.svg)](https://anaconda.org/conda-forge/pycontrails) [![Supported python versions](https://img.shields.io/pypi/pyversions/pycontrails.svg)](https://pypi.python.org/pypi/pycontrails) |
+| **Citation**  | [![DOI](https://zenodo.org/badge/617248930.svg)](https://zenodo.org/badge/latestdoi/617248930) |
+| **Tests**     | [![Unit test](https://github.com/contrailcirrus/pycontrails/actions/workflows/test.yaml/badge.svg)](https://github.com/contrailcirrus/pycontrails/actions/workflows/test.yaml) [![Docs](https://github.com/contrailcirrus/pycontrails/actions/workflows/docs.yaml/badge.svg?event=push)](https://github.com/contrailcirrus/pycontrails/actions/workflows/docs.yaml) [![Release](https://github.com/contrailcirrus/pycontrails/actions/workflows/release.yaml/badge.svg)](https://github.com/contrailcirrus/pycontrails/actions/workflows/release.yaml) [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/contrailcirrus/pycontrails/badge)](https://securityscorecards.dev/viewer?uri=github.com/contrailcirrus/pycontrails)|
+| **License**   | [![Apache License 2.0](https://img.shields.io/pypi/l/pycontrails.svg)](https://github.com/contrailcirrus/pycontrails/blob/main/LICENSE) |
+| **Community** | [![Github Discussions](https://img.shields.io/github/discussions/contrailcirrus/pycontrails)](https://github.com/contrailcirrus/pycontrails/discussions) [![Github Issues](https://img.shields.io/github/issues/contrailcirrus/pycontrails)](https://github.com/contrailcirrus/pycontrails/issues) [![Github PRs](https://img.shields.io/github/issues-pr/contrailcirrus/pycontrails)](https://github.com/contrailcirrus/pycontrails/pulls) |
+
+**pycontrails** is an open source project and Python package for modeling aircraft contrails and other
+aviation related climate impacts.
+
+`pycontrails` defines common [data structures](https://py.contrails.org/api.html#data) and [interfaces](https://py.contrails.org/api.html#datalib) to efficiently build and run [models](https://py.contrails.org/api.html#models) of aircraft performance, emissions, and radiative forcing.
+
+## Documentation
+
+Documentation and examples available at [py.contrails.org](https://py.contrails.org/).
+
+<!-- Try out an [interactive Colab Notebook](). -->
+
+## Install
+
+### Install with pip
+
+You can install pycontrails from PyPI with `pip` (Python 3.11 or later required):
+
+```bash
+$ pip install pycontrails
+
+# install with all optional dependencies
+$ pip install "pycontrails[complete]"
+```
+
+Install the latest development version directly from GitHub:
+
+```bash
+pip install git+https://github.com/contrailcirrus/pycontrails.git
+```
+
+### Install with conda
+
+You can install pycontrails from the [conda-forge](https://conda-forge.org/) channel with `conda` (or other `conda`-like package managers such as `mamba`):
+
+```bash
+conda install -c conda-forge pycontrails
+```
+
+The conda-forge package includes all optional runtime dependencies.
+
+See more installation options in the [install documentation](https://py.contrails.org/install).
+
+## Get Involved
+
+- Ask questions, discuss models, and present ideas in [GitHub Discussions](https://github.com/contrailcirrus/pycontrails/discussions).
+- Report bugs or suggest changes in [GitHub Issues](https://github.com/contrailcirrus/pycontrails/issues).
+- Review the [contributing guidelines](https://py.contrails.org/contributing.html) and contribute improvements as [Pull Requests](https://github.com/contrailcirrus/pycontrails/pulls).
+
+## License
+
+[Apache License 2.0](https://github.com/contrailcirrus/pycontrails/blob/main/LICENSE)
+
+Additional attributions in [NOTICE](https://github.com/contrailcirrus/pycontrails/blob/main/NOTICE).