pycontrails 0.54.12__cp311-cp311-macosx_10_9_x86_64.whl → 0.56.0__cp311-cp311-macosx_10_9_x86_64.whl

pycontrails/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.54.12'
-__version_tuple__ = version_tuple = (0, 54, 12)
+__version__ = version = '0.56.0'
+__version_tuple__ = version_tuple = (0, 56, 0)
 
-__commit_id__ = commit_id = 'g5920a0c98'
+__commit_id__ = commit_id = 'gec7f244f4'

pycontrails/core/airports.py

@@ -142,7 +142,7 @@ def find_nearest_airport(
 
     Returns
     -------
-    str
+    str | None
         ICAO code of nearest airport.
         Returns None if no airport is found within ``bbox``.
 

pycontrails/core/cache.py

@@ -168,12 +168,12 @@ class DiskCacheStore(CacheStore):
 
     Parameters
     ----------
-    allow_clear : bool, optional
-        Allow this cache to be cleared using :meth:`clear()`. Defaults to False.
-    cache_dir : str | pathlib.Path, optional
+    cache_dir : str | pathlib.Path | None, optional
         Root cache directory.
         By default, looks first for ``PYCONTRAILS_CACHE_DIR`` environment variable,
         then uses the OS specific :func:`platformdirs.user_cache_dir` function.
+    allow_clear : bool, optional
+        Allow this cache to be cleared using :meth:`clear()`. Defaults to False.
 
     Examples
     --------

pycontrails/core/fleet.py

@@ -182,7 +182,7 @@ class Fleet(Flight):
 
         Returns
         -------
-        Fleet
+        Self
             A `Fleet` instance made from concatenating the :class:`Flight`
             instances in ``seq``. The fuel type is taken from the first :class:`Flight`
             in ``seq``.

pycontrails/core/flight.py

@@ -25,7 +25,7 @@ import pandas as pd
 import scipy.signal
 
 from pycontrails.core.fuel import Fuel, JetA
-from pycontrails.core.vector import AttrDict, GeoVectorDataset, VectorDataDict, VectorDataset
+from pycontrails.core.vector import GeoVectorDataset, VectorDataDict, VectorDataset
 from pycontrails.physics import constants, geo, units
 from pycontrails.utils import dependencies
 from pycontrails.utils.types import ArrayOrFloat
@@ -86,31 +86,31 @@ class Flight(GeoVectorDataset):
 
     Parameters
     ----------
-    data : dict[str, np.ndarray] | pd.DataFrame | VectorDataDict | VectorDataset | None
+    data : dict[str, npt.ArrayLike] | pd.DataFrame | VectorDataDict | VectorDataset | None
         Flight trajectory waypoints as data dictionary or :class:`pandas.DataFrame`.
         Must include columns ``time``, ``latitude``, ``longitude``, ``altitude`` or ``level``.
         Keyword arguments for ``time``, ``latitude``, ``longitude``, ``altitude`` or ``level``
         will override ``data`` inputs. Expects ``altitude`` in meters and ``time`` as a
         DatetimeLike (or array that can processed with :func:`pd.to_datetime`).
         Additional waypoint-specific data can be included as additional keys/columns.
-    longitude : npt.ArrayLike, optional
+    longitude : npt.ArrayLike | None, optional
         Flight trajectory waypoint longitude.
         Defaults to None.
-    latitude : npt.ArrayLike, optional
+    latitude : npt.ArrayLike | None, optional
         Flight trajectory waypoint latitude.
         Defaults to None.
-    altitude : npt.ArrayLike, optional
+    altitude : npt.ArrayLike | None, optional
         Flight trajectory waypoint altitude, [:math:`m`].
         Defaults to None.
-    altitude_ft : npt.ArrayLike, optional
+    altitude_ft : npt.ArrayLike | None, optional
         Flight trajectory waypoint altitude, [:math:`ft`].
-    level : npt.ArrayLike, optional
+    level : npt.ArrayLike | None, optional
         Flight trajectory waypoint pressure level, [:math:`hPa`].
         Defaults to None.
-    time : npt.ArrayLike, optional
+    time : npt.ArrayLike | None, optional
         Flight trajectory waypoint time.
         Defaults to None.
-    attrs : dict[str, Any], optional
+    attrs : dict[str, Any] | None, optional
         Additional flight properties as a dictionary.
         While different models may utilize Flight attributes differently,
         pycontrails applies the following conventions:
@@ -132,7 +132,7 @@ class Flight(GeoVectorDataset):
     copy : bool, optional
         Copy data on Flight creation.
         Defaults to True.
-    fuel : Fuel, optional
+    fuel : Fuel | None, optional
         Fuel used in flight trajectory. Defaults to :class:`JetA`.
     drop_duplicated_times : bool, optional
         Drop duplicate times in flight trajectory. Defaults to False.
@@ -219,7 +219,7 @@ class Flight(GeoVectorDataset):
         altitude_ft: npt.ArrayLike | None = None,
         level: npt.ArrayLike | None = None,
         time: npt.ArrayLike | None = None,
-        attrs: dict[str, Any] | AttrDict | None = None,
+        attrs: dict[str, Any] | None = None,
         copy: bool = True,
         fuel: Fuel | None = None,
         drop_duplicated_times: bool = False,
@@ -422,9 +422,9 @@ class Flight(GeoVectorDataset):
 
         Parameters
         ----------
-        dtype : np.dtype
+        dtype : npt.DTypeLike, optional
             Numpy dtype for time difference.
-            Defaults to ``np.float64``
+            Defaults to ``np.float32``
 
         Returns
         -------
@@ -519,7 +519,7 @@ class Flight(GeoVectorDataset):
 
         Returns
         -------
-        npt.NDArray[np.floating], npt.NDArray[np.floating]
+        tuple[npt.NDArray[np.floating], npt.NDArray[np.floating]]
             Returns ``sin(a), cos(a)``, where ``a`` is the angle between the segment and the
             longitudinal axis. The final values are of both arrays are ``np.nan``.
 
@@ -774,7 +774,7 @@ class Flight(GeoVectorDataset):
 
         Returns
         -------
-        Flight
+        Self
             Filtered Flight instance
 
         Examples
@@ -828,7 +828,7 @@ class Flight(GeoVectorDataset):
         ----------
         freq : str, optional
             Resampling frequency, by default "1min"
-        fill_method : {"geodesic", "linear"}, optional
+        fill_method : str, optional
             Choose between ``"geodesic"`` and ``"linear"``, by default ``"geodesic"``.
             In geodesic mode, large gaps between waypoints are filled with geodesic
             interpolation and small gaps are filled with linear interpolation. In linear
@@ -837,7 +837,7 @@ class Flight(GeoVectorDataset):
             Threshold for geodesic interpolation, [:math:`m`].
             If the distance between consecutive waypoints is under this threshold,
             values are interpolated linearly.
-        nominal_rocd : float | None, optional
+        nominal_rocd : float, optional
             Nominal rate of climb / descent for aircraft type.
             Defaults to :attr:`constants.nominal_rocd`.
         drop : bool, optional
@@ -849,13 +849,13 @@ class Flight(GeoVectorDataset):
             Keep the original index of the :class:`Flight` in addition to the new
             resampled index. Defaults to ``False``.
             .. versionadded:: 0.45.2
-        time : npt.NDArray[np.datetime64], optional
+        time : npt.NDArray[np.datetime64] | None, optional
             Times to resample to. Will override ``freq`` if provided.
             .. versionadded:: 0.54.11
 
         Returns
         -------
-        Flight
+        Self
             Filled Flight
 
         Raises
@@ -995,7 +995,7 @@ class Flight(GeoVectorDataset):
         ----------
         freq : str, optional
             Resampling frequency, by default "1min"
-        fill_method : {"geodesic", "linear"}, optional
+        fill_method : str, optional
             Choose between ``"geodesic"`` and ``"linear"``, by default ``"geodesic"``.
             In geodesic mode, large gaps between waypoints are filled with geodesic
             interpolation and small gaps are filled with linear interpolation. In linear
@@ -1010,7 +1010,7 @@ class Flight(GeoVectorDataset):
         kernel_size : int, optional
             Passed directly to :func:`scipy.signal.medfilt`, by default 11.
             Passed also to :func:`scipy.signal.medfilt`
-        cruise_theshold : float, optional
+        cruise_threshold : float, optional
             Minimal length of time, in seconds, for a flight to be in cruise to apply median filter
         force_filter: bool, optional
             If set to true, meth:`filter_altitude` will always be called. otherwise, it will only
@@ -1027,7 +1027,7 @@ class Flight(GeoVectorDataset):
 
         Returns
         -------
-        Flight
+        Self
             Filled Flight
         """
         clean_flight: Flight
@@ -1089,12 +1089,12 @@ class Flight(GeoVectorDataset):
         kernel_size : int, optional
             Passed directly to :func:`scipy.signal.medfilt`, by default 11.
             Passed also to :func:`scipy.signal.medfilt`
-        cruise_theshold : float, optional
+        cruise_threshold : float, optional
             Minimal length of time, in seconds, for a flight to be in cruise to apply median filter
 
         Returns
         -------
-        Flight
+        Self
             Filtered Flight
 
         Notes
@@ -1142,8 +1142,8 @@ class Flight(GeoVectorDataset):
 
         Returns
         -------
-        (ArrayOrFloat, ArrayOrFloat, int | npt.NDArray[int])
-            latitude, longitude, and segment index cooresponding to distance.
+        tuple[ArrayOrFloat, ArrayOrFloat, np.intp | npt.NDArray[np.intp]]
+            latitude, longitude, and segment index corresponding to distance.
         """
 
         # Check if flight crosses antimeridian line
@@ -1376,7 +1376,7 @@ class Flight(GeoVectorDataset):
 
         Parameters
         ----------
-        key : str, optional
+        key : str | None, optional
             If provided, name of :attr:`data` column to group by.
         split_antimeridian : bool, optional
             Split linestrings that cross the antimeridian. Defaults to True.
@@ -1391,12 +1391,9 @@ class Flight(GeoVectorDataset):
         KeyError
             ``key`` is provided but :attr:`data` does not contain column ``key``
         """
-        if key is not None and key not in self.dataframe.columns:
-            raise KeyError(f"Column {key} does not exist in data.")
-
         jump_indices = _antimeridian_index(pd.Series(self["longitude"]))
 
-        def _group_to_feature(name: str, group: pd.DataFrame) -> dict[str, str | dict[str, Any]]:
+        def _group_to_feature(name: Any, group: pd.DataFrame) -> dict[str, str | dict[str, Any]]:
             # assigns a different value to each group of consecutive indices
             subgrouping = group.index.to_series().diff().ne(1).cumsum()
 
@@ -1417,13 +1414,20 @@ class Flight(GeoVectorDataset):
             properties.update(self.constants)
             return {"type": "Feature", "geometry": geometry, "properties": properties}
 
+        # Add altitude (needed in _return_linestring) without mutating self
+        df = self.dataframe
+        if "altitude" not in self:
+            df["altitude"] = self.altitude
+
         if key is not None:
-            groups = self.dataframe.groupby(key)
+            if key not in self:
+                raise KeyError(f"Column {key} does not exist in data.")
+            groups = df.groupby(key)
         else:
             # create a single group containing all rows of dataframe
-            groups = self.dataframe.groupby(lambda _: 0)
+            groups = [(None, df)]  # name is ignored in this case
 
-        features = [_group_to_feature(*name_group) for name_group in groups]
+        features = [_group_to_feature(name, group) for name, group in groups]
         return {"type": "FeatureCollection", "features": features}
 
     def to_traffic(self) -> traffic.core.Flight:
@@ -1578,7 +1582,7 @@ class Flight(GeoVectorDataset):
 
         Returns
         -------
-        :class:`matplotlib.axes.Axes`
+        matplotlib.axes.Axes
             Plot
         """
         kwargs.setdefault("legend", False)
@@ -1596,7 +1600,7 @@ class Flight(GeoVectorDataset):
 
         Returns
         -------
-        :class:`matplotlib.axes.Axes`
+        matplotlib.axes.Axes
             Plot
         """
         kwargs.setdefault("legend", False)
@@ -1881,8 +1885,8 @@ def filter_altitude(
     time: npt.NDArray[np.datetime64],
     altitude_ft: npt.NDArray[np.floating],
     kernel_size: int = 17,
-    cruise_threshold: float = 120,
-    air_temperature: None | npt.NDArray[np.floating] = None,
+    cruise_threshold: float = 120.0,
+    air_temperature: npt.NDArray[np.floating] | None = None,
 ) -> npt.NDArray[np.floating]:
     """
     Filter noisy altitude on a single flight.
@@ -1900,9 +1904,9 @@ def filter_altitude(
     kernel_size : int, optional
         Passed directly to :func:`scipy.signal.medfilt`, by default 11.
         Passed also to :func:`scipy.signal.medfilt`
-    cruise_theshold : int, optional
+    cruise_threshold : float, optional
         Minimal length of time, in seconds, for a flight to be in cruise to apply median filter
-    air_temperature: None | npt.NDArray[np.floating]
+    air_temperature: npt.NDArray[np.floating] | None, optional
         Air temperature of each flight waypoint, [:math:`K`]
 
     Returns
@@ -2004,7 +2008,7 @@ def segment_duration(
     ----------
     time : npt.NDArray[np.datetime64]
         Waypoint time in ``np.datetime64`` format.
-    dtype : np.dtype
+    dtype : npt.DTypeLike, optional
         Numpy dtype for time difference.
         Defaults to ``np.float32``
 
@@ -2031,7 +2035,7 @@ def segment_phase(
 
     Parameters
     ----------
-    rocd: pt.NDArray[np.float64]
+    rocd: npt.NDArray[np.floating]
         Rate of climb and descent across segment, [:math:`ft min^{-1}`].
         See output from :func:`segment_rocd`.
     altitude_ft: npt.NDArray[np.floating]
@@ -2154,7 +2158,7 @@ def _resample_to_freq_or_time(
     freq : str
         Frequency to resample to. See :func:`pd.DataFrame.resample` for
         valid frequency strings.
-    time : pd.DatetimeIndex | None
+    time : npt.NDArray[np.datetime64] | None
         Times to resample to. Overrides ``freq`` if not ``None``.
 
     Returns

pycontrails/core/met_var.py

@@ -80,7 +80,7 @@ class MetVariable:
 
         Returns
         -------
-        str
+        str | None
             Database link in the ECMWF Parameter Database
         """
         return (

pycontrails/core/vector.py

@@ -86,7 +86,7 @@ class VectorDataDict(dict[str, np.ndarray]):
 
     Parameters
     ----------
-    data : dict[str, np.ndarray], optional
+    data : dict[str, np.ndarray] | None, optional
         Dictionary input. A shallow copy is always made.
     """
 
@@ -112,7 +112,7 @@ class VectorDataDict(dict[str, np.ndarray]):
         ----------
         k : str
             Key
-        v : np.ndarray
+        v : npt.ArrayLike
             Values
 
         See Also
@@ -145,12 +145,12 @@ class VectorDataDict(dict[str, np.ndarray]):
         ----------
         k : str
             Key
-        default : npt.ArrayLike, optional
+        default : npt.ArrayLike | None, optional
             Default value for key ``k``
 
         Returns
         -------
-        Any
+        np.ndarray
             Value at ``k``
         """
         ret = self.get(k, None)
@@ -647,13 +647,13 @@ class VectorDataset:  # noqa: PLW1641
             List of :class:`VectorDataset` instances to concatenate.
         infer_attrs : bool, optional
             If True, infer attributes from the first element in the sequence.
-        fill_value : float, optional
+        fill_value : float | None, optional
             Fill value to use when concatenating arrays. By default None, which raises
             an error if incompatible keys are found.
 
         Returns
         -------
-        VectorDataset
+        Self
             Sum of all instances in ``vectors``.
 
         Raises
@@ -997,7 +997,7 @@ class VectorDataset:  # noqa: PLW1641
 
         Parameters
         ----------
-        ignore_keys: str | Iterable[str], optional
+        ignore_keys: str | Iterable[str] | None, optional
             Do not broadcast selected keys.
             Defaults to None.
         overwrite : bool, optional
@@ -1281,9 +1281,9 @@ class VectorDataset:  # noqa: PLW1641
             Passed into :meth:`filter`. Defaults to True. Recommend to keep as True
             based on `numpy best practices <https://numpy.org/doc/stable/user/basics.indexing.html#slicing-and-striding>`_.
 
-        Returns
-        -------
-        Generator[Self, None, None]
+        Yields
+        ------
+        Self
             Generator of split vectors.
 
         See Also
@@ -1320,27 +1320,27 @@ class GeoVectorDataset(VectorDataset):
         override ``data`` inputs. Expects ``altitude`` in meters and ``time``
         as a DatetimeLike (or array that can processed with :meth:`pd.to_datetime`).
         Additional waypoint-specific data can be included as additional keys/columns.
-    longitude : npt.ArrayLike, optional
+    longitude : npt.ArrayLike | None, optional
         Longitude data.
         Defaults to None.
-    latitude : npt.ArrayLike, optional
+    latitude : npt.ArrayLike | None, optional
         Latitude data.
         Defaults to None.
-    altitude : npt.ArrayLike, optional
+    altitude : npt.ArrayLike | None, optional
         Altitude data, [:math:`m`].
         Defaults to None.
-    altitude_ft : npt.ArrayLike, optional
+    altitude_ft : npt.ArrayLike | None, optional
         Altitude data, [:math:`ft`].
         Defaults to None.
-    level : npt.ArrayLike, optional
+    level : npt.ArrayLike | None, optional
         Level data, [:math:`hPa`].
         Defaults to None.
-    time : npt.ArrayLike, optional
+    time : npt.ArrayLike | None, optional
         Time data.
         Expects an array of DatetimeLike values,
         or array that can processed with :meth:`pd.to_datetime`.
         Defaults to None.
-    attrs : dict[Hashable, Any] | AttrDict, optional
+    attrs : dict[str, Any] | None, optional
         Additional properties as a dictionary.
         Defaults to {}.
     copy : bool, optional
@@ -1606,8 +1606,8 @@ class GeoVectorDataset(VectorDataset):
 
         Returns
         -------
-        pd.DataFrame
-            :class:`pd.DataFrame` with columns `longitude`, `latitude`, `level`, and `time`.
+        dict[str, np.ndarray]
+            A dictionary with fields `longitude`, `latitude`, `level`, and `time`.
         """
         return {
             "longitude": self["longitude"],
@@ -1628,8 +1628,6 @@ class GeoVectorDataset(VectorDataset):
         crs : str
             Target CRS. Passed into to :class:`pyproj.Transformer`. The source CRS
             is assumed to be EPSG:4326.
-        copy : bool, optional
-            Copy data on transformation. Defaults to True.
 
         Returns
         -------
@@ -1675,7 +1673,7 @@ class GeoVectorDataset(VectorDataset):
 
         Parameters
         ----------
-        met : MetDataset | MetDataArray
+        met : met_module.MetDataset | met_module.MetDataArray
             MetDataset or MetDataArray to compare.
 
         Returns
@@ -1719,15 +1717,15 @@ class GeoVectorDataset(VectorDataset):
 
         Parameters
         ----------
-        mda : MetDataArray
+        mda : met_module.MetDataArray
             MetDataArray containing a meteorological variable at spatio-temporal coordinates.
-        longitude : npt.NDArray[np.floating], optional
+        longitude : npt.NDArray[np.floating] | None, optional
             Override existing coordinates for met interpolation
-        latitude : npt.NDArray[np.floating], optional
+        latitude : npt.NDArray[np.floating] | None, optional
             Override existing coordinates for met interpolation
-        level : npt.NDArray[np.floating], optional
+        level : npt.NDArray[np.floating] | None, optional
             Override existing coordinates for met interpolation
-        time : npt.NDArray[np.datetime64], optional
+        time : npt.NDArray[np.datetime64] | None, optional
             Override existing coordinates for met interpolation
         use_indices : bool, optional
             Experimental.
@@ -1870,7 +1868,7 @@ class GeoVectorDataset(VectorDataset):
 
         Returns
         -------
-        tuple | None
+        interpolation.RGIArtifacts | None
             Previously cached output of
             :meth:`scipy.interpolate.RegularGridInterpolator._find_indices`,
             or None if cached output is not present on instance.
@@ -1950,7 +1948,7 @@ class GeoVectorDataset(VectorDataset):
 
         Parameters
         ----------
-        met : MetDataset | MetDataArray
+        met : met_module.MetDataType
             MetDataset or MetDataArray to downselect.
         longitude_buffer : tuple[float, float], optional
             Extend longitude domain past by ``longitude_buffer[0]`` on the low side
@@ -1975,7 +1973,7 @@ class GeoVectorDataset(VectorDataset):
 
         Returns
         -------
-        MetDataset | MetDataArray
+        met_module.MetDataType
             Copy of downselected MetDataset or MetDataArray.
         """
         indexes = met.indexes