pycontrails 0.41.0__cp311-cp311-macosx_11_0_arm64.whl → 0.42.2__cp311-cp311-macosx_11_0_arm64.whl

pycontrails/_version.py

@@ -1,4 +1,4 @@
 # file generated by setuptools_scm
 # don't change, don't track in version control
-__version__ = version = '0.41.0'
-__version_tuple__ = version_tuple = (0, 41, 0)
+__version__ = version = '0.42.2'
+__version_tuple__ = version_tuple = (0, 42, 2)

pycontrails/core/airports.py

@@ -0,0 +1,228 @@
+"""Airport data support."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from pycontrails.core import cache
+from pycontrails.physics import geo, units
+
+#: URL for `Our Airports <https://ourairports.com/>`_ database.
+#: Fork of the `ourairports-data repository <https://github.com/davidmegginson/ourairports-data>`_.
+OURAIRPORTS_DATABASE_URL: str = (
+    "https://github.com/contrailcirrus/ourairports-data/raw/main/airports.csv"
+)
+
+
+def _download_ourairports_csv() -> pd.DataFrame:
+    """Download CSV file from fork of ourairports-data github."""
+    return pd.read_csv(
+        OURAIRPORTS_DATABASE_URL,
+        usecols=[
+            "type",
+            "name",
+            "latitude_deg",
+            "longitude_deg",
+            "elevation_ft",
+            "iso_country",
+            "iso_region",
+            "municipality",
+            "scheduled_service",
+            "gps_code",
+            "iata_code",
+        ],
+    )
+
+
+def global_airport_database(
+    cachestore: cache.CacheStore | None = None, update_cache: bool = False
+) -> pd.DataFrame:
+    """
+    Load and process global airport database from `Our Airports <https://ourairports.com/>`_.
+
+    The database includes coordinates and metadata for 74867 unique airports.
+
+    Parameters
+    ----------
+    cachestore : cache.CacheStore | None, optional
+        Cache store for airport database.
+        Defaults to :class:`cache.DiskCacheStore`.
+    update_cache : bool, optional
+        Force update to cached airports database.
+
+    Returns
+    -------
+    pd.DataFrame
+        Processed global airport database.
+
+        Global airport database.
+
+    Notes
+    -----
+    As of 2023 March 30, the global airport database contains:
+
+    .. csv-table::
+       :header: "Airport Type", "Number"
+       :widths: 70, 30
+
+        "small_airport",    39327
+        "heliport",         19039
+        "closed",           10107
+        "medium_airport",   4753
+        "seaplane_base",    1133
+        "large_airport",    463
+        "balloonport",      45
+
+    References
+    ----------
+    - :cite:`megginsonOpendataDownloadsOurAirports2023`
+    """
+    cachestore = cachestore or cache.DiskCacheStore()
+
+    cache_key = "ourairports-data_airports.csv"
+    if cachestore.exists(cache_key) and not update_cache:
+        airports = pd.read_csv(cachestore.path(cache_key))
+    else:
+        airports = _download_ourairports_csv()
+        airports.to_csv(cachestore.path(cache_key), index=False)
+
+    #: Format dataset by renaming columns & filling nan values
+    airports.rename(
+        columns={"latitude_deg": "latitude", "longitude_deg": "longitude", "gps_code": "icao_code"},
+        inplace=True,
+    )
+    airports["elevation_ft"].fillna(0, inplace=True)
+
+    # Keep specific airport types used by commercial aviation
+    select_airport_types = airports["type"].isin(
+        ["large_airport", "medium_airport", "small_airport", "heliport"]
+    )
+
+    # Keep airports with valid ICAO codes
+    select_icao_codes = (airports["icao_code"].str.len() == 4) & (
+        airports["icao_code"].str.isalpha()
+    )
+
+    # filter airports
+    airports = airports.loc[select_airport_types & select_icao_codes]
+
+    # Format dataset
+    airports["elevation_m"] = units.ft_to_m(airports["elevation_ft"].to_numpy())
+    airports.sort_values(by=["icao_code"], ascending=True, inplace=True)
+
+    return airports.reset_index(drop=True)
+
+
+def find_nearest_airport(
+    airports: pd.DataFrame,
+    longitude: float,
+    latitude: float,
+    altitude: float,
+    *,
+    bbox: float = 2.0,
+) -> str | None:
+    r"""
+    Find airport nearest to the waypoints.
+
+    Parameters
+    ----------
+    airports: pd.DataFrame
+        Airport database in the format returned from :func:`global_airport_database`.
+    longitude: float
+        Waypoint longitude, [:math:`\deg`]
+    latitude: float
+        Waypoint latitude, [:math:`\deg`]
+    altitude: float
+        Waypoint altitude, [:math:`m`]
+    bbox: float
+        Search airports within spatial bounding box of ± `bbox` from the waypoint, [:math:`\deg`]
+        Defaults to :math:`2\deg`
+
+    Returns
+    -------
+    str
+        ICAO code of nearest airport.
+        Returns None if no airport is found within ``bbox``.
+
+    Notes
+    -----
+    Function will first search for large airports around the waypoint vicinity.
+    If none is found, it will search for medium and small airports
+    around the waypoint vicinity.
+
+    The waypoint must be below 10,000 feet to increase the
+    probability of identifying the correct airport.
+    """
+    if altitude > 3000:
+        raise ValueError(
+            f"Altitude ({altitude} m) is too high (> 3000 m) to identify nearest airport."
+        )
+
+    is_near_waypoint = airports["longitude"].between(
+        (longitude - bbox), (longitude + bbox)
+    ) & airports["latitude"].between((latitude - bbox), (latitude + bbox))
+
+    # Find the nearest airport from largest to smallest airport type
+    search_priority = ["large_airport", "medium_airport", "small_airport"]
+
+    for airport_type in search_priority:
+        is_airport_type = airports["type"] == airport_type
+        nearest_airports = airports.loc[is_near_waypoint & is_airport_type]
+
+        if len(nearest_airports) == 1:
+            return nearest_airports["icao_code"].values[0]
+
+        elif len(nearest_airports) > 1:
+            distance = distance_to_airports(
+                nearest_airports,
+                longitude,
+                latitude,
+                altitude,
+            )
+            i_nearest = np.argmin(distance)
+            return nearest_airports["icao_code"].values[i_nearest]
+
+        else:
+            continue
+
+    return None
+
+
+def distance_to_airports(
+    airports: pd.DataFrame,
+    longitude: float,
+    latitude: float,
+    altitude: float,
+) -> np.ndarray:
+    r"""
+    Calculate the 3D distance from the waypoint to the provided airports.
+
+    Parameters
+    ----------
+    airports : pd.DataFrame
+        Airport database in the format returned from :func:`global_airport_database`.
+    longitude : float
+        Waypoint longitude, [:math:`\deg`]
+    latitude : float
+        Waypoint latitude, [:math:`\deg`]
+    altitude : float
+        Waypoint altitude, [:math:`m`]
+
+    Returns
+    -------
+    np.ndarray
+        3D distance from waypoint to airports, [:math:`m`]
+
+    See Also
+    --------
+    :func:`geo.haversine`
+    """
+    dist_horizontal = geo.haversine(
+        np.full(airports["longitude"].shape, longitude),
+        np.full(airports["latitude"].shape, latitude),
+        airports["longitude"].to_numpy(),
+        airports["latitude"].to_numpy(),
+    )
+    dist_vertical = altitude - airports["elevation_m"].to_numpy()
+    return (dist_horizontal**2 + dist_vertical**2) ** 0.5

pycontrails/core/cache.py

@@ -370,18 +370,16 @@ class DiskCacheStore(CacheStore):
         if disk_path.is_file():
             logger.debug("Remove file at path %s", disk_path)
             disk_path.unlink()
+            return
 
         # Assume anything else is a directory
-        elif disk_path.exists():
+        if disk_path.exists():
             # rm directory recursively
             logger.debug("Remove directory at path %s", disk_path)
             shutil.rmtree(disk_path, ignore_errors=True)
+            return
 
-        else:
-            warnings.warn(f"No cache path found at {disk_path}")
-
-        # make sure local cache directory exists
-        # pathlib.Path(self.cache_dir).mkdir(parents=True, exist_ok=True)
+        warnings.warn(f"No cache path found at {disk_path}")
 
 
 class GCPCacheStore(CacheStore):

pycontrails/core/datalib.py

@@ -32,8 +32,11 @@ NETCDF_ENGINE: str = "netcdf4"
 #: Default chunking strategy when opening datasets with xarray
 DEFAULT_CHUNKS: dict[str, int] = {"time": 1}
 
+#: Whether to open multi-file datasets in parallel
+OPEN_IN_PARALLEL: bool = False
 
-def parse_timesteps(time: TimeInput | None, freq: str = "1H") -> list[datetime]:
+
+def parse_timesteps(time: TimeInput | None, freq: str | None = "1H") -> list[datetime]:
     """Parse time input into set of time steps.
 
     If input time is length 2, this creates a range of equally spaced time
@@ -46,10 +49,11 @@ def parse_timesteps(time: TimeInput | None, freq: str = "1H") -> list[datetime]:
         Either a single datetime-like or tuple of datetime-like with the first value
         the start of the date range and second value the end of the time range.
         Input values can be any type compatible with :meth:`pandas.to_datetime`.
-    freq : str, optional
+    freq : str | None, optional
         Timestep interval in range.
         See https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#timeseries-offset-aliases
         for a list of frequency aliases.
+        If None, returns input `time` as a list.
         Defaults to "1H".
 
     Returns
@@ -84,8 +88,11 @@ def parse_timesteps(time: TimeInput | None, freq: str = "1H") -> list[datetime]:
             "must be compatible with 'pd.to_datetime()'"
         )
 
-    # get date range that encompasses all whole hours
-    daterange = pd.date_range(timestamps[0].floor(freq), timestamps[1].ceil(freq), freq=freq)
+    if freq is None:
+        daterange = pd.DatetimeIndex([timestamps[0], timestamps[1]])
+    else:
+        # get date range that encompasses all whole hours
+        daterange = pd.date_range(timestamps[0].floor(freq), timestamps[1].ceil(freq), freq=freq)
 
     # return list of datetimes
     return daterange.to_pydatetime().tolist()
@@ -641,7 +648,7 @@ class MetDataSource(abc.ABC):
 
                 - chunks: {"time": 1}
                 - engine: "netcdf4"
-                - parallel: True
+                - parallel: False
 
         Returns
         -------
@@ -650,5 +657,5 @@ class MetDataSource(abc.ABC):
         """
         xr_kwargs.setdefault("engine", NETCDF_ENGINE)
         xr_kwargs.setdefault("chunks", DEFAULT_CHUNKS)
-        xr_kwargs.setdefault("parallel", True)
+        xr_kwargs.setdefault("parallel", OPEN_IN_PARALLEL)
         return xr.open_mfdataset(disk_paths, **xr_kwargs)

pycontrails/core/fleet.py

@@ -22,12 +22,12 @@ class Fleet(Flight):
 
     def __init__(
         self,
-        data: dict[str, np.ndarray] | None = None,
-        longitude: np.ndarray | None = None,
-        latitude: np.ndarray | None = None,
-        altitude: np.ndarray | None = None,
-        level: np.ndarray | None = None,
-        time: np.ndarray | None = None,
+        data: dict[str, npt.ArrayLike] | None = None,
+        longitude: npt.ArrayLike | None = None,
+        latitude: npt.ArrayLike | None = None,
+        altitude: npt.ArrayLike | None = None,
+        level: npt.ArrayLike | None = None,
+        time: npt.ArrayLike | None = None,
         attrs: dict[str, Any] | None = None,
         copy: bool = True,
         fuel: Fuel | None = None,
@@ -60,12 +60,12 @@ class Fleet(Flight):
 
         self.final_waypoints = self.calc_final_waypoints()
 
-    def calc_final_waypoints(self) -> np.ndarray:
+    def calc_final_waypoints(self) -> npt.NDArray[np.bool_]:
         """Validate data and calculate the final waypoint of each flight.
 
         Returns
         -------
-        np.ndarray
+        npt.NDArray[np.bool_]
             A boolean array in which True values correspond to final waypoint of each flight.
 
         Raises
@@ -93,6 +93,49 @@ class Fleet(Flight):
         final_waypoints[final_waypoint_indices] = True
         return final_waypoints
 
+    def fit_altitude(
+        self,
+        max_segments: int = 30,
+        pop: int = 3,
+        r2_target: float = 0.999,
+        max_cruise_rocd: float = 10,
+        sg_window: int = 7,
+        sg_polyorder: int = 1,
+    ) -> Fleet:
+        """Use piecewise linear fitting to smooth a flight profile.
+
+        Fit a flight profile to a series of line segments. Segments that have a
+        small rocd will be set to have a slope of zero and snapped to the
+        nearest thousand foot level.  A Savitzky-Golay filter will then be
+        applied to the profile to smooth the climbs and descents.  This filter
+        works best for high frequency flight data, sampled at a 1-3 second
+        sampling period.
+
+        Parameters
+        ----------
+        max_segments : int, optional
+            The maximum number of line segements to fit to the flight profile.
+        pop: int, optional
+            Population parameter used for the stocastic optimization routine
+            used to fit the flight profile.
+        r2_target: float, optional
+            Target r^2 value for solver. Solver will continue to add line
+            segments until the resulting r^2 value is greater than this.
+        max_cruise_rocd: float, optional
+            The maximum ROCD for a segment that will be forced to a slope of
+            zero, [:math:`ft s^{-1}`]
+        sg_window: int, optional
+            Parameter for :func:`scipy.signal.savgol_filter`
+        sg_polyorder: int, optional
+            Parameter for :func:`scipy.signal.savgol_filter`
+
+        Returns
+        -------
+        Fleet
+            Smoothed flight
+        """
+        raise NotImplementedError("Only implemented for Flight instances")
+
     @classmethod
     def from_seq(
         cls,
@@ -257,8 +300,8 @@ class Fleet(Flight):
 
     def segment_true_airspeed(
         self,
-        u_wind: npt.NDArray[np.float_] | None = None,
-        v_wind: npt.NDArray[np.float_] | None = None,
+        u_wind: npt.NDArray[np.float_] | float = 0.0,
+        v_wind: npt.NDArray[np.float_] | float = 0.0,
         smooth: bool = True,
         window_length: int = 7,
         polyorder: int = 1,
@@ -277,13 +320,14 @@ class Fleet(Flight):
         RuntimeError
             Unexpected key `__u_wind` or `__v_wind` found in :attr:`data`.
         """
-        if u_wind is not None:
+        if isinstance(u_wind, np.ndarray):
             # Choosing a key we don't think exists
             key = "__u_wind"
             if key in self:
                 raise RuntimeError(f"Unexpected key {key} found")
             self[key] = u_wind
-        if v_wind is not None:
+
+        if isinstance(v_wind, np.ndarray):
             # Choosing a key we don't think exists
             key = "__v_wind"
             if key in self:
@@ -291,12 +335,12 @@ class Fleet(Flight):
             self[key] = v_wind
 
         # Calculate TAS on each flight individually
-        def calc_tas(fl: Flight) -> np.ndarray:
-            u_wind = fl.get("__u_wind", None)
-            v_wind = fl.get("__v_wind", None)
+        def calc_tas(fl: Flight) -> npt.NDArray[np.float_]:
+            u = fl.get("__u_wind", u_wind)
+            v = fl.get("__v_wind", v_wind)
 
             return fl.segment_true_airspeed(
-                u_wind, v_wind, smooth=smooth, window_length=window_length, polyorder=polyorder
+                u, v, smooth=smooth, window_length=window_length, polyorder=polyorder
             )
 
         fls = self.to_flight_list(copy=False)
@@ -314,7 +358,7 @@ class Fleet(Flight):
         return np.concatenate(tas)
 
     @overrides
-    def segment_groundspeed(self, *args: Any, **kwargs: Any) -> np.ndarray:
+    def segment_groundspeed(self, *args: Any, **kwargs: Any) -> npt.NDArray[np.float_]:
         # Implement if we have a usecase for this.
         # Because the super() method uses a smoothing pattern, it will not reliably
         # work on Fleet.
@@ -327,15 +371,23 @@ class Fleet(Flight):
         raise NotImplementedError
 
     @overrides
-    def segment_length(self) -> np.ndarray:
+    def segment_length(self) -> npt.NDArray[np.float_]:
         return np.where(self.final_waypoints, np.nan, super().segment_length())
 
+    @property
+    @overrides
+    def max_distance_gap(self) -> float:
+        if self.attrs["crs"] != "EPSG:4326":
+            raise NotImplementedError("Only implemented for EPSG:4326 CRS.")
+
+        return np.nanmax(self.segment_length()).item()
+
     @overrides
-    def segment_azimuth(self) -> np.ndarray:
+    def segment_azimuth(self) -> npt.NDArray[np.float_]:
         return np.where(self.final_waypoints, np.nan, super().segment_azimuth())
 
     @overrides
-    def segment_angle(self) -> tuple[np.ndarray, np.ndarray]:
+    def segment_angle(self) -> tuple[npt.NDArray[np.float_], npt.NDArray[np.float_]]:
         sin_a, cos_a = super().segment_angle()
         sin_a[self.final_waypoints] = np.nan
         cos_a[self.final_waypoints] = np.nan