pycontrails 0.54.0__cp313-cp313-macosx_11_0_arm64.whl → 0.54.2__cp313-cp313-macosx_11_0_arm64.whl

pycontrails/core/vector.py

@@ -5,15 +5,25 @@ from __future__ import annotations
 import hashlib
 import json
 import logging
+import sys
 import warnings
 from collections.abc import Generator, Iterable, Iterator, Sequence
-from typing import Any, TypeVar, overload
+from typing import Any, overload
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
 
 import numpy as np
 import numpy.typing as npt
 import pandas as pd
 import xarray as xr
-from overrides import overrides
 
 from pycontrails.core import coordinates, interpolation
 from pycontrails.core import met as met_module
@@ -23,10 +33,6 @@ from pycontrails.utils import json as json_utils
 
 logger = logging.getLogger(__name__)
 
-#: Vector types
-VectorDatasetType = TypeVar("VectorDatasetType", bound="VectorDataset")
-GeoVectorDatasetType = TypeVar("GeoVectorDatasetType", bound="GeoVectorDataset")
-
 
 class AttrDict(dict[str, Any]):
     """Thin wrapper around dict to warn when setting a key that already exists."""
@@ -574,7 +580,7 @@ class VectorDataset:
         """
         return self.size > 0
 
-    def __add__(self: VectorDatasetType, other: VectorDatasetType | None) -> VectorDatasetType:
+    def __add__(self, other: Self | None) -> Self:
         """Concatenate two compatible instances of VectorDataset.
 
         In this context, compatibility means that both have identical :attr:`data` keys.
@@ -586,12 +592,12 @@ class VectorDataset:
 
         Parameters
         ----------
-        other : VectorDatasetType
+        other : Self | None
             Other values to concatenate
 
         Returns
         -------
-        VectorDatasetType
+        Self
             Concatenated values.
 
         Raises
@@ -610,11 +616,11 @@ class VectorDataset:
 
     @classmethod
     def sum(
-        cls: type[VectorDatasetType],
+        cls,
         vectors: Sequence[VectorDataset],
         infer_attrs: bool = True,
         fill_value: float | None = None,
-    ) -> VectorDatasetType:
+    ) -> Self:
         """Sum a list of :class:`VectorDataset` instances.
 
         Parameters
@@ -692,7 +698,7 @@ class VectorDataset:
             return cls(data, attrs=vectors[0].attrs, copy=False)
         return cls(data, copy=False)
 
-    def __eq__(self: VectorDatasetType, other: object) -> bool:
+    def __eq__(self, other: object) -> bool:
         """Determine if two instances are equal.
 
         NaN values are considered equal in this comparison.
@@ -700,7 +706,7 @@ class VectorDataset:
         Parameters
         ----------
         other : object
-            VectorDatasetType to compare with
+            VectorDataset to compare with
 
         Returns
         -------
@@ -784,8 +790,8 @@ class VectorDataset:
     # Utilities
     # ------------
 
-    def copy(self: VectorDatasetType, **kwargs: Any) -> VectorDatasetType:
-        """Return a copy of this VectorDatasetType class.
+    def copy(self, **kwargs: Any) -> Self:
+        """Return a copy of this instance.
 
         Parameters
         ----------
@@ -794,7 +800,7 @@ class VectorDataset:
 
         Returns
         -------
-        VectorDatasetType
+        Self
             Copy of class
         """
         return type(self)(data=self.data, attrs=self.attrs, copy=True, **kwargs)
@@ -820,9 +826,7 @@ class VectorDataset:
         data = {key: self[key] for key in keys}
         return VectorDataset(data=data, attrs=self.attrs, copy=copy)
 
-    def filter(
-        self: VectorDatasetType, mask: npt.NDArray[np.bool_], copy: bool = True, **kwargs: Any
-    ) -> VectorDatasetType:
+    def filter(self, mask: npt.NDArray[np.bool_], copy: bool = True, **kwargs: Any) -> Self:
         """Filter :attr:`data` according to a boolean array ``mask``.
 
         Entries corresponding to ``mask == True`` are kept.
@@ -840,7 +844,7 @@ class VectorDataset:
 
         Returns
         -------
-        VectorDatasetType
+        Self
             Containing filtered data
 
         Raises
@@ -855,7 +859,7 @@ class VectorDataset:
         data = {key: value[mask] for key, value in self.data.items()}
         return type(self)(data=data, attrs=self.attrs, copy=copy, **kwargs)
 
-    def sort(self: VectorDatasetType, by: str | list[str]) -> VectorDatasetType:
+    def sort(self, by: str | list[str]) -> Self:
         """Sort data by key(s).
 
         This method always creates a copy of the data by calling
@@ -868,7 +872,7 @@ class VectorDataset:
 
         Returns
         -------
-        VectorDatasetType
+        Self
             Instance with sorted data.
         """
         return type(self)(data=self.dataframe.sort_values(by=by), attrs=self.attrs, copy=False)
@@ -1044,7 +1048,6 @@ class VectorDataset:
         >>> pprint.pprint(fl.to_dict())
         {'aircraft_type': 'B737',
          'altitude_ft': [38661.0, 38661.0, 38661.0, 38661.0, 38661.0, 38661.0, 38661.0],
-         'crs': 'EPSG:4326',
          'latitude': [40.0, 41.724, 43.428, 45.111, 46.769, 48.399, 50.0],
          'longitude': [-100.0,
                        -101.441,
@@ -1110,12 +1113,12 @@ class VectorDataset:
 
     @classmethod
     def create_empty(
-        cls: type[VectorDatasetType],
+        cls,
         keys: Iterable[str],
         attrs: dict[str, Any] | None = None,
         **attrs_kwargs: Any,
-    ) -> VectorDatasetType:
-        """Create instance with variables defined by `keys` and size 0.
+    ) -> Self:
+        """Create instance with variables defined by ``keys`` and size 0.
 
         If instance requires additional variables to be defined, these keys will automatically
         be attached to returned instance.
@@ -1131,15 +1134,13 @@ class VectorDataset:
 
         Returns
         -------
-        VectorDatasetType
+        Self
             Empty VectorDataset instance.
         """
         return cls(data=_empty_vector_dict(keys or set()), attrs=attrs, copy=False, **attrs_kwargs)
 
     @classmethod
-    def from_dict(
-        cls: type[VectorDatasetType], obj: dict[str, Any], copy: bool = True, **obj_kwargs: Any
-    ) -> VectorDatasetType:
+    def from_dict(cls, obj: dict[str, Any], copy: bool = True, **obj_kwargs: Any) -> Self:
         """Create instance from dict representation containing data and attrs.
 
         Parameters
@@ -1154,7 +1155,7 @@ class VectorDataset:
 
         Returns
         -------
-        VectorDatasetType
+        Self
             VectorDataset instance.
 
         See Also
@@ -1172,9 +1173,7 @@ class VectorDataset:
 
         return cls(data=data, attrs=attrs, copy=copy)
 
-    def generate_splits(
-        self: VectorDatasetType, n_splits: int, copy: bool = True
-    ) -> Generator[VectorDatasetType, None, None]:
+    def generate_splits(self, n_splits: int, copy: bool = True) -> Generator[Self, None, None]:
         """Split instance into ``n_split`` sub-vectors.
 
         Parameters
@@ -1187,7 +1186,7 @@ class VectorDataset:
 
         Returns
         -------
-        Generator[VectorDatasetType, None, None]
+        Generator[Self, None, None]
             Generator of split vectors.
 
         See Also
@@ -1215,9 +1214,6 @@ class GeoVectorDataset(VectorDataset):
     Each spatial variable is expected to have "float32" or "float64" ``dtype``.
     The time variable is expected to have "datetime64[ns]" ``dtype``.
 
-    Use the attribute :attr:`attr["crs"]` to specify coordinate reference system
-    using `PROJ <https://proj.org/>`_ or `EPSG <https://epsg.org/home.html>`_ syntax.
-
     Parameters
     ----------
     data : dict[str, npt.ArrayLike] | pd.DataFrame | VectorDataDict | VectorDataset | None, optional
@@ -1364,18 +1360,14 @@ class GeoVectorDataset(VectorDataset):
             if arr.dtype not in float_dtype:
                 self.update({coord: arr.astype(np.float64)})
 
-        # set CRS to "EPSG:4326" by default
-        crs = self.attrs.setdefault("crs", "EPSG:4326")
-
-        if crs == "EPSG:4326":
-            longitude = self["longitude"]
-            if np.any(longitude > 180.0) or np.any(longitude < -180.0):
-                raise ValueError("EPSG:4326 longitude coordinates should lie between [-180, 180).")
-            latitude = self["latitude"]
-            if np.any(latitude > 90.0) or np.any(latitude < -90.0):
-                raise ValueError("EPSG:4326 latitude coordinates should lie between [-90, 90].")
+        longitude = self["longitude"]
+        if np.any(longitude > 180.0) or np.any(longitude < -180.0):
+            raise ValueError("EPSG:4326 longitude coordinates should lie between [-180, 180).")
+        latitude = self["latitude"]
+        if np.any(latitude > 90.0) or np.any(latitude < -90.0):
+            raise ValueError("EPSG:4326 latitude coordinates should lie between [-90, 90].")
 
-    @overrides
+    @override
     def _display_attrs(self) -> dict[str, str]:
         try:
             time0 = pd.Timestamp(np.nanmin(self["time"]))
@@ -1530,24 +1522,21 @@ class GeoVectorDataset(VectorDataset):
     # Utilities
     # ------------
 
-    def transform_crs(
-        self: GeoVectorDatasetType, crs: str, copy: bool = True
-    ) -> GeoVectorDatasetType:
+    def transform_crs(self, crs: str) -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]:
         """Transform trajectory data from one coordinate reference system (CRS) to another.
 
         Parameters
         ----------
         crs : str
             Target CRS. Passed into to :class:`pyproj.Transformer`. The source CRS
-            is inferred from the :attr:`attrs["crs"]` attribute.
+            is assumed to be EPSG:4326.
         copy : bool, optional
             Copy data on transformation. Defaults to True.
 
         Returns
         -------
-        GeoVectorDatasetType
-            Converted dataset with new coordinate reference system.
-            :attr:`attrs["crs"]` reflects new crs.
+        tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]
+            New x and y coordinates in the target CRS.
         """
         try:
             import pyproj
@@ -1559,14 +1548,9 @@ class GeoVectorDataset(VectorDataset):
                 pycontrails_optional_package="pyproj",
             )
 
-        transformer = pyproj.Transformer.from_crs(self.attrs["crs"], crs, always_xy=True)
-        lon, lat = transformer.transform(self["longitude"], self["latitude"])
-
-        ret = self.copy() if copy else self
-
-        ret.update(longitude=lon, latitude=lat)
-        ret.attrs.update(crs=crs)
-        return ret
+        crs_from = "EPSG:4326"
+        transformer = pyproj.Transformer.from_crs(crs_from, crs, always_xy=True)
+        return transformer.transform(self["longitude"], self["latitude"])
 
     def T_isa(self) -> npt.NDArray[np.float64]:
         """Calculate the ICAO standard atmosphere temperature at each point.
@@ -1938,13 +1922,13 @@ class GeoVectorDataset(VectorDataset):
     # ------------
 
     @classmethod
-    @overrides
+    @override
     def create_empty(
-        cls: type[GeoVectorDatasetType],
+        cls,
         keys: Iterable[str] | None = None,
         attrs: dict[str, Any] | None = None,
         **attrs_kwargs: Any,
-    ) -> GeoVectorDatasetType:
+    ) -> Self:
         keys = *cls.required_keys, "altitude", *(keys or ())
         return super().create_empty(keys, attrs, **attrs_kwargs)
 
@@ -1961,21 +1945,6 @@ class GeoVectorDataset(VectorDataset):
         """
         return json_utils.dataframe_to_geojson_points(self.dataframe)
 
-    def to_pseudo_mercator(self: GeoVectorDatasetType, copy: bool = True) -> GeoVectorDatasetType:
-        """Convert data from :attr:`attrs["crs"]` to Pseudo Mercator (EPSG:3857).
-
-        Parameters
-        ----------
-        copy : bool, optional
-            Copy data on transformation.
-            Defaults to True.
-
-        Returns
-        -------
-        GeoVectorDatasetType
-        """
-        return self.transform_crs("EPSG:3857", copy=copy)
-
     # ------------
     # Vector to grid
     # ------------

pycontrails/datalib/ecmwf/__init__.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from pycontrails.datalib.ecmwf.arco_era5 import (
-    ARCOERA5,
+    ERA5ARCO,
     open_arco_era5_model_level_data,
     open_arco_era5_single_level,
 )
@@ -40,7 +40,7 @@ from pycontrails.datalib.ecmwf.variables import (
 )
 
 __all__ = [
-    "ARCOERA5",
+    "ERA5ARCO",
     "CDSCredentialsNotFound",
     "ERA5",
     "ERA5ModelLevel",

pycontrails/datalib/ecmwf/arco_era5.py

@@ -19,11 +19,16 @@ from __future__ import annotations
 
 import datetime
 import hashlib
+import sys
 from typing import Any
 
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
 import numpy.typing as npt
 import xarray as xr
-from overrides import overrides
 
 from pycontrails.core import cache, met_var
 from pycontrails.core.met import MetDataset
@@ -197,7 +202,7 @@ def open_arco_era5_single_level(
     return MetDataset(ds).data
 
 
-class ARCOERA5(ecmwf_common.ECMWFAPI):
+class ERA5ARCO(ecmwf_common.ECMWFAPI):
     r"""ARCO ERA5 data accessed remotely through Google Cloud Storage.
 
     This is a high-level interface to access and cache
@@ -274,7 +279,7 @@ class ARCOERA5(ecmwf_common.ECMWFAPI):
         """
         return ecmwf_variables.SURFACE_VARIABLES
 
-    @overrides
+    @override
     def download_dataset(self, times: list[datetime.datetime]) -> None:
         if not times:
             return
@@ -286,7 +291,7 @@ class ARCOERA5(ecmwf_common.ECMWFAPI):
 
         self.cache_dataset(ds)
 
-    @overrides
+    @override
     def create_cachepath(self, t: datetime.datetime) -> str:
         if self.cachestore is None:
             msg = "Attribute self.cachestore must be defined to create cache path"
@@ -302,7 +307,7 @@ class ARCOERA5(ecmwf_common.ECMWFAPI):
 
         return self.cachestore.path(cache_path)
 
-    @overrides
+    @override
     def open_metdataset(
         self,
         dataset: xr.Dataset | None = None,
@@ -331,7 +336,7 @@ class ARCOERA5(ecmwf_common.ECMWFAPI):
         self.set_metadata(mds)
         return mds
 
-    @overrides
+    @override
     def set_metadata(self, ds: xr.Dataset | MetDataset) -> None:
         ds.attrs.update(
             provider="ECMWF",

pycontrails/datalib/ecmwf/common.py

@@ -4,14 +4,19 @@ from __future__ import annotations
 
 import logging
 import os
+import sys
 from typing import Any
 
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
 LOG = logging.getLogger(__name__)
 
 import numpy as np
 import pandas as pd
 import xarray as xr
-from overrides import overrides
 
 from pycontrails.core import met
 from pycontrails.datalib._met_utils import metsource
@@ -88,7 +93,7 @@ class ECMWFAPI(metsource.MetDataSource):
         kwargs.setdefault("cachestore", self.cachestore)
         return met.MetDataset(ds, **kwargs)
 
-    @overrides
+    @override
     def cache_dataset(self, dataset: xr.Dataset) -> None:
         if self.cachestore is None:
             LOG.debug("Cache is turned off, skipping")

pycontrails/datalib/ecmwf/era5.py

@@ -7,16 +7,21 @@ import hashlib
 import logging
 import os
 import pathlib
+import sys
 import warnings
 from contextlib import ExitStack
 from datetime import datetime
 from typing import TYPE_CHECKING, Any
 
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
 LOG = logging.getLogger(__name__)
 
 import pandas as pd
 import xarray as xr
-from overrides import overrides
 
 import pycontrails
 from pycontrails.core import cache
@@ -34,7 +39,7 @@ class ERA5(ECMWFAPI):
     """Class to support ERA5 data access, download, and organization.
 
     Requires account with
-    `Copernicus Data Portal <https://cds.climate.copernicus.eu/cdsapp#!/home>`_
+    `Copernicus Data Portal <https://cds.climate.copernicus.eu/how-to-api>`_
     and local credentials.
 
     API credentials can be stored in a ``~/.cdsapirc`` file
@@ -347,7 +352,7 @@ class ERA5(ECMWFAPI):
         # return cache path
         return self.cachestore.path(f"{datestr}-{suffix}.nc")
 
-    @overrides
+    @override
     def download_dataset(self, times: list[datetime]) -> None:
         download_times: dict[datetime, list[datetime]] = collections.defaultdict(list)
         for t in times:
@@ -359,7 +364,7 @@ class ERA5(ECMWFAPI):
         for times_for_day in download_times.values():
             self._download_file(times_for_day)
 
-    @overrides
+    @override
     def open_metdataset(
         self,
         dataset: xr.Dataset | None = None,
@@ -399,7 +404,7 @@ class ERA5(ECMWFAPI):
         self.set_metadata(mds)
         return mds
 
-    @overrides
+    @override
     def set_metadata(self, ds: xr.Dataset | MetDataset) -> None:
         if self.product_type == "reanalysis":
             product = "reanalysis"

pycontrails/datalib/ecmwf/era5_model_level.py

@@ -7,9 +7,9 @@ This module supports
 - Local caching of processed netCDF files.
 - Opening processed and cached files as a :class:`pycontrails.MetDataset` object.
 
-Consider using :class:`pycontrails.datalib.ecmwf.ARCOERA5`
+Consider using :class:`pycontrails.datalib.ecmwf.ERA5ARCO`
 to access model-level data from the nominal ERA5 reanalysis between 1959 and 2022.
-:class:`pycontrails.datalib.ecmwf.ARCOERA5` accesses data through Google's
+:class:`pycontrails.datalib.ecmwf.ERA5ARCO` accesses data through Google's
 `Analysis-Ready, Cloud Optimized ERA5 dataset <https://cloud.google.com/storage/docs/public-datasets/era5>`_
 and has lower latency than this module, which retrieves data from the
 `Copernicus Climate Data Store <https://cds.climate.copernicus.eu/#!/home>`_.
@@ -25,12 +25,16 @@ import contextlib
 import hashlib
 import logging
 import os
+import sys
 import threading
 import warnings
 from datetime import datetime
 from typing import Any
 
-from overrides import overrides
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
 
 LOG = logging.getLogger(__name__)
 
@@ -56,7 +60,7 @@ class ERA5ModelLevel(ECMWFAPI):
     pressure-level with much lower vertical resolution.
 
     Requires account with
-    `Copernicus Data Portal <https://cds.climate.copernicus.eu/cdsapp#!/home>`_
+    `Copernicus Data Portal <https://cds.climate.copernicus.eu/how-to-api>`_
     and local credentials.
 
     API credentials can be stored in a ``~/.cdsapirc`` file
@@ -245,7 +249,7 @@ class ERA5ModelLevel(ECMWFAPI):
         """
         return "reanalysis-era5-complete"
 
-    @overrides
+    @override
     def create_cachepath(self, t: datetime | pd.Timestamp) -> str:
         """Return cachepath to local ERA5 data file based on datetime.
 
@@ -277,7 +281,7 @@ class ERA5ModelLevel(ECMWFAPI):
 
         return self.cachestore.path(cache_path)
 
-    @overrides
+    @override
     def download_dataset(self, times: list[datetime]) -> None:
         # group data to request by month (nominal) or by day (ensemble)
         requests: dict[datetime, list[datetime]] = collections.defaultdict(list)
@@ -294,7 +298,7 @@ class ERA5ModelLevel(ECMWFAPI):
         for times_in_request in requests.values():
             self._download_convert_cache_handler(times_in_request)
 
-    @overrides
+    @override
     def open_metdataset(
         self,
         dataset: xr.Dataset | None = None,
@@ -320,7 +324,7 @@ class ERA5ModelLevel(ECMWFAPI):
         self.set_metadata(mds)
         return mds
 
-    @overrides
+    @override
     def set_metadata(self, ds: xr.Dataset | MetDataset) -> None:
         if self.product_type == "reanalysis":
             product = "reanalysis"

pycontrails/datalib/ecmwf/hres.py

@@ -5,16 +5,21 @@ from __future__ import annotations
 import hashlib
 import logging
 import pathlib
+import sys
 from contextlib import ExitStack
 from datetime import datetime
 from typing import TYPE_CHECKING, Any
 
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
 LOG = logging.getLogger(__name__)
 
 import numpy as np
 import pandas as pd
 import xarray as xr
-from overrides import overrides
 
 import pycontrails
 from pycontrails.core import cache
@@ -326,9 +331,9 @@ class HRES(ECMWFAPI):
             f" {getattr(self, 'steps', '')}"
         )
 
-    @classmethod
+    @staticmethod
     def create_synoptic_time_ranges(
-        self, timesteps: list[pd.Timestamp]
+        timesteps: list[pd.Timestamp],
     ) -> list[tuple[pd.Timestamp, pd.Timestamp]]:
         """Create synoptic time bounds encompassing date range.
 
@@ -556,7 +561,7 @@ class HRES(ECMWFAPI):
             f"\n\tgrid={request['grid']},\n\tlevtype={request['levtype']}{levelist}"
         )
 
-    @overrides
+    @override
     def create_cachepath(self, t: datetime) -> str:
         if self.cachestore is None:
             raise ValueError("self.cachestore attribute must be defined to create cache path")
@@ -574,7 +579,7 @@ class HRES(ECMWFAPI):
         # return cache path
         return self.cachestore.path(f"{datestr}-{step}-{suffix}.nc")
 
-    @overrides
+    @override
     def download_dataset(self, times: list[datetime]) -> None:
         """Download data from data source for input times.
 
@@ -595,7 +600,7 @@ class HRES(ECMWFAPI):
         elif len(steps) > 0:
             self._download_file(steps)
 
-    @overrides
+    @override
     def open_metdataset(
         self,
         dataset: xr.Dataset | None = None,
@@ -635,7 +640,7 @@ class HRES(ECMWFAPI):
         self.set_metadata(mds)
         return mds
 
-    @overrides
+    @override
     def set_metadata(self, ds: xr.Dataset | MetDataset) -> None:
         if self.stream == "oper":
             product = "forecast"