pycontrails 0.54.0__cp312-cp312-macosx_10_13_x86_64.whl

pycontrails/utils/json.py

@@ -0,0 +1,188 @@
+"""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,165 @@
+"""Convienence types."""
+
+from __future__ import annotations
+
+import functools
+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, xr.DataArray | np.ndarray)
+
+#: Array or Float (np.ndarray, float)
+ArrayOrFloat = TypeVar(
+    "ArrayOrFloat", npt.NDArray[np.float64], float, float | npt.NDArray[np.float64]
+)
+
+#: Array like input (np.ndarray, xr.DataArray, np.float64, float)
+ArrayScalarLike = TypeVar(
+    "ArrayScalarLike",
+    np.ndarray,
+    xr.DataArray,
+    np.float64,
+    float,
+    np.ndarray | float,
+    xr.DataArray | np.ndarray,
+)
+
+#: Datetime like input (datetime, pd.Timestamp, np.datetime64)
+DatetimeLike = TypeVar("DatetimeLike", datetime, pd.Timestamp, np.datetime64, str)
+
+
+def support_arraylike(
+    func: Callable[[np.ndarray], np.ndarray],
+) -> 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 | np.float64):
+            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.54.0.dist-info/LICENSE

@@ -0,0 +1,178 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+