pycontrails 0.54.5__cp311-cp311-win_amd64.whl → 0.54.7__cp311-cp311-win_amd64.whl

pycontrails/core/vector.py

@@ -507,6 +507,9 @@ class VectorDataset:
         >>> vector.get_data_or_attr("c", default=5)
         5
 
+        See Also
+        --------
+        get_constant
         """
         marker = self.__marker
 
@@ -1013,6 +1016,69 @@ class VectorDataset:
         )
         self.broadcast_attrs(numeric_attrs, overwrite)
 
+    def get_constant(self, key: str, default: Any = __marker) -> Any:
+        """Get a constant value from :attr:`attrs` or :attr:`data`.
+
+        - If ``key`` is found in :attr:`attrs`, the value is returned.
+        - If ``key`` is found in :attr:`data`, the common value is returned if all
+          values are equal.
+        - If ``key`` is not found in :attr:`attrs` or :attr:`data` and a ``default`` is provided,
+          the ``default`` is returned.
+        - Otherwise, a KeyError is raised.
+
+        Parameters
+        ----------
+        key : str
+            Key to look for.
+        default : Any, optional
+            Default value to return if ``key`` is not found in :attr:`attrs` or :attr:`data`.
+
+        Returns
+        -------
+        Any
+            The constant value for ``key``.
+
+        Raises
+        ------
+        KeyError
+            If ``key`` is not found in :attr:`attrs` or the values in :attr:`data` are not equal
+            and ``default`` is not provided.
+
+        Examples
+        --------
+        >>> vector = VectorDataset({"a": [1, 1, 1], "b": [2, 2, 3]})
+        >>> vector.get_constant("a")
+        np.int64(1)
+        >>> vector.get_constant("b")
+        Traceback (most recent call last):
+        ...
+        KeyError: "A constant key 'b' not found in attrs or data"
+        >>> vector.get_constant("b", 3)
+        3
+
+        See Also
+        --------
+        get_data_or_attr
+        GeoVectorDataset.constants
+        """
+        marker = self.__marker
+
+        out = self.attrs.get(key, marker)
+        if out is not marker:
+            return out
+
+        out = self.data.get(key, marker)
+        if out is not marker:
+            vals = np.unique(out)
+            if len(vals) == 1:
+                return vals[0]
+
+        if default is not marker:
+            return default
+
+        msg = f"A constant key '{key}' not found in attrs or data"
+        raise KeyError(msg)
+
     # ------------
     # I / O
     # ------------

pycontrails/datalib/_met_utils/metsource.py

@@ -265,7 +265,7 @@ def _find_match(
 
     # list of MetVariable options
     # here we extract the first MetVariable in var that is supported
-    elif isinstance(var, list | tuple):
+    if isinstance(var, list | tuple):
         for v in var:
             # sanity check since we don't support other types as lists
             if not isinstance(v, MetVariable):

pycontrails/datalib/ecmwf/era5.py

@@ -88,9 +88,8 @@ class ERA5(ECMWFAPI):
         If None, cache is turned off.
     url : str | None
         Override the default `cdsapi <https://github.com/ecmwf/cdsapi>`_ url.
-        As of August 2024, the url for the `CDS-Beta <https://cds-beta.climate.copernicus.eu>`_
-        is "https://cds-beta.climate.copernicus.eu/api", and the url for the legacy server is
-        "https://cds.climate.copernicus.eu/api/v2". If None, the url is set
+        As of January 2025, the url for the `CDS Server <https://cds.climate.copernicus.eu>`_
+        is "https://cds.climate.copernicus.eu/api". If None, the url is set
         by the ``CDSAPI_URL`` environment variable. If this is not defined, the
         ``cdsapi`` package will determine the url.
     key : str | None
@@ -539,12 +538,12 @@ class ERA5(ECMWFAPI):
             LOG.debug("Input dataset processed with pycontrails > 0.29")
             return ds
 
-        # For "reanalysis-era5-single-levels"
-        # then the netcdf file does not contain the dimension "level"
+        # For "reanalysis-era5-single-levels",
+        # the netcdf file does not contain the dimension "level"
         if self.is_single_level:
             ds = ds.expand_dims(level=self.pressure_levels)
 
-        # New CDS-Beta gives "valid_time" instead of "time"
+        # New CDS (Aug 2024) gives "valid_time" instead of "time"
         # and "pressure_level" instead of "level"
         if "valid_time" in ds:
             ds = ds.rename(valid_time="time")

pycontrails/datalib/ecmwf/era5_model_level.py

@@ -119,9 +119,8 @@ class ERA5ModelLevel(ECMWFAPI):
         By default, False.
     url : str | None
         Override the default `cdsapi <https://github.com/ecmwf/cdsapi>`_ url.
-        As of August 2024, the url for the `CDS-Beta <https://cds-beta.climate.copernicus.eu>`_
-        is "https://cds-beta.climate.copernicus.eu/api", and the url for the legacy server is
-        "https://cds.climate.copernicus.eu/api/v2". If None, the url is set
+        As of January 2025, the url for the `CDS Server <https://cds.climate.copernicus.eu>`_
+        is "https://cds.climate.copernicus.eu/api". If None, the url is set
         by the ``CDSAPI_URL`` environment variable. If this is not defined, the
         ``cdsapi`` package will determine the url.
     key : str | None
@@ -465,13 +464,13 @@ class ERA5ModelLevel(ECMWFAPI):
             ds_ml = xr.open_dataset(ml_target)
             lnsp = xr.open_dataarray(lnsp_target)
 
-            # New CDS-Beta gives "valid_time" instead of "time"
+            # New CDS (Aug 2024) gives "valid_time" instead of "time"
             if "valid_time" in ds_ml:
                 ds_ml = ds_ml.rename(valid_time="time")
             if "valid_time" in lnsp.dims:
                 lnsp = lnsp.rename(valid_time="time")
 
-            # The legacy CDS gives "level" instead of "model_level"
+            # Legacy CDS (prior to Aug 2024) gives "level" instead of "model_level"
             if "level" in ds_ml.dims:
                 ds_ml = ds_ml.rename(level="model_level")
 

pycontrails/datalib/ecmwf/ifs.py

@@ -247,9 +247,7 @@ class IFS(metsource.MetDataSource):
         ds_fl = ds_fl.drop_vars(names=["hyai", "hybi", "hyam", "hybm"])
 
         # merge all datasets using the "ds_fl" dimensions as the join keys
-        ds = xr.merge([ds_fl, ds_full, ds_surface, ds_rad], join="left")  # order matters!
-
-        return ds
+        return xr.merge([ds_fl, ds_full, ds_surface, ds_rad], join="left")  # order matters!
 
     def _calc_geopotential(self, ds: xr.Dataset) -> xr.DataArray:
         warnings.warn(

pycontrails/datalib/gfs/gfs.py

@@ -570,9 +570,7 @@ class GFSForecast(metsource.MetDataSource):
         ds = ds.expand_dims("time")
 
         # drop step/number
-        ds = ds.drop_vars(["step", "nominalTop", "surface"], errors="ignore")
-
-        return ds
+        return ds.drop_vars(["step", "nominalTop", "surface"], errors="ignore")
 
     def _process_dataset(self, ds: xr.Dataset, **kwargs: Any) -> met.MetDataset:
         """Process the :class:`xr.Dataset` opened from cache or local files.

pycontrails/datalib/spire/__init__.py

@@ -0,0 +1,5 @@
+"""`Spire Aviation <https://spire.com/aviation/>`_ ADS-B data support."""
+
+from pycontrails.datalib.spire.spire import ValidateTrajectoryHandler
+
+__all__ = ["ValidateTrajectoryHandler"]

pycontrails/datalib/spire/exceptions.py

@@ -0,0 +1,62 @@
+"""Custom exceptions used for spire data validation."""
+
+
+class BaseSpireError(Exception):
+    """Base class for all spire exceptions."""
+
+
+class BadTrajectoryException(BaseSpireError):
+    """A generic exception indicating a trajectory (flight instance) is invalid."""
+
+
+class SchemaError(BaseSpireError):
+    """Data object is inconsistent with required schema."""
+
+
+class OrderingError(BaseSpireError):
+    """Data object has incorrect ordering."""
+
+
+class OriginAirportError(BaseSpireError):
+    """
+    Trajectory is not originating at expected location.
+
+    We do not assume that the departure airports are invariant in the dataframe,
+    thus we handle the case of multiple airports listed.
+    """
+
+
+class DestinationAirportError(BaseSpireError):
+    """Trajectory is not terminating at expected location."""
+
+
+class FlightTooShortError(BaseSpireError):
+    """Trajectory is unreasonably short in flight time."""
+
+
+class FlightTooLongError(BaseSpireError):
+    """Trajectory is unreasonably long in flight time."""
+
+
+class FlightTooSlowError(BaseSpireError):
+    """Trajectory has period(s) of unrealistically slow speed."""
+
+
+class FlightTooFastError(BaseSpireError):
+    """Trajectory has period(s) of unrealistically high speed."""
+
+
+class ROCDError(BaseSpireError):
+    """Trajectory has an unrealistic rate of climb or descent."""
+
+
+class FlightAltitudeProfileError(BaseSpireError):
+    """Trajectory has an unrealistic rate of climb or descent."""
+
+
+class FlightDuplicateTimestamps(BaseSpireError):
+    """Trajectory contains waypoints with the same timestamp."""
+
+
+class FlightInvariantFieldViolation(BaseSpireError):
+    """Trajectory has multiple values for field(s) that should be invariant."""