pycontrails 0.41.0__cp39-cp39-macosx_11_0_arm64.whl → 0.42.2__cp39-cp39-macosx_11_0_arm64.whl

pycontrails/core/flight.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import dataclasses
+import enum
 import logging
 import warnings
 from typing import TYPE_CHECKING, Any
@@ -26,6 +27,31 @@ if TYPE_CHECKING:
     import traffic
 
 
+class FlightPhase(enum.IntEnum):
+    """Flight phase enumeration."""
+
+    CLIMB = enum.auto()
+    CRUISE = enum.auto()
+    DESCENT = enum.auto()
+    LEVEL_FLIGHT = enum.auto()
+    NAN = enum.auto()
+
+
+#: Max airport elevation, [:math:`ft`]
+#: See `Daocheng_Yading_Airport <https://en.wikipedia.org/wiki/Daocheng_Yading_Airport>`_
+MAX_AIRPORT_ELEVATION = 15_000.0
+
+#: Min estimated cruise altitude, [:math:`ft`]
+MIN_CRUISE_ALTITUDE = 20_000.0
+
+#: Short haul duration cutoff, [:math:`s`]
+SHORT_HAUL_DURATION = 3600.0
+
+#: Set maximum speed compatible with "on_ground" indicator, [:math:`mph`]
+#: Thresholds assessed based on scatter plot (150 knots = 278 km/h)
+MAX_ON_GROUND_SPEED = 150.0
+
+
 @dataclasses.dataclass
 class Aircraft:
     """Base class for the physical parameters of the aircraft."""
@@ -52,51 +78,12 @@ class Aircraft:
     max_altitude: float | None = None
 
 
-@dataclasses.dataclass
-class FlightPhase:
-    """Container for boolean arrays describing phase of the flight.
-
-    Each array is expected to have the same shape. Arrays should be pairwise disjoint and cover
-    each waypoint (for each waypoint, exactly one of the four arrays should be True.)
-
-    .. todo::
-
-        Refactor to include this data as property in :class:`Flight` with enum for FlightPhase
-    """
-
-    cruise: np.ndarray
-    climb: np.ndarray
-    descent: np.ndarray
-    nan: np.ndarray
-
-    @classmethod
-    def all_cruise(cls, size: int) -> FlightPhase:
-        """Generate `FlightPhase` instance in which all waypoints are at cruise.
-
-        Parameters
-        ----------
-        size : int
-            Number of waypoints
-
-        Returns
-        -------
-        FlightPhase
-            All waypoints are given a cruise state..
-        """
-        return cls(
-            cruise=np.ones(size).astype(bool),
-            climb=np.zeros(size).astype(bool),
-            descent=np.zeros(size).astype(bool),
-            nan=np.zeros(size).astype(bool),
-        )
-
-
 class Flight(GeoVectorDataset):
     """A single flight trajectory.
 
-    Expect latitude-longitude CRS in WGS 84.
+    Expect latitude-longitude coordinates in WGS 84.
     Expect altitude in [:math:`m`].
-    Expect level in [:math:`hPa`].
+    Expect pressure level (`level`) in [:math:`hPa`].
 
     Use the attribute :attr:`attrs["crs"]` to specify coordinate reference system
     using `PROJ <https://proj.org/>`_ or `EPSG <https://epsg.org/home.html>`_ syntax.
@@ -110,19 +97,19 @@ class Flight(GeoVectorDataset):
         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 : np.ndarray, optional
+    longitude : npt.ArrayLike, optional
         Flight trajectory waypoint longitude.
         Defaults to None.
-    latitude : np.ndarray, optional
+    latitude : npt.ArrayLike, optional
         Flight trajectory waypoint latitude.
         Defaults to None.
-    altitude : np.ndarray, optional
+    altitude : npt.ArrayLike, optional
         Flight trajectory waypoint altitude, [:math:`m`].
         Defaults to None.
-    level : np.ndarray, optional
+    level : npt.ArrayLike, optional
         Flight trajectory waypoint pressure level, [:math:`hPa`].
         Defaults to None.
-    time : np.ndarray, optional
+    time : npt.ArrayLike, optional
         Flight trajectory waypoint time.
         Defaults to None.
     attrs : dict[str, Any], optional
@@ -149,6 +136,12 @@ class Flight(GeoVectorDataset):
         Raises if ``data`` input does not contain at least ``time``, ``latitude``, ``longitude``,
         (``altitude`` or ``level``).
 
+    Notes
+    -----
+    The `Traffic <https://traffic-viz.github.io/index.html>`_ library has many helpful
+    flight processing utilities.
+
+    See :class:`traffic.core.Flight` for more information.
 
     Examples
     --------
@@ -207,11 +200,15 @@ class Flight(GeoVectorDataset):
 
     def __init__(
         self,
-        data: dict[str, np.ndarray] | pd.DataFrame | VectorDataDict | VectorDataset | None = None,
-        longitude: np.ndarray | None = None,
-        latitude: np.ndarray | None = None,
-        altitude: np.ndarray | None = None,
-        time: np.ndarray | None = None,
+        data: dict[str, npt.ArrayLike]
+        | pd.DataFrame
+        | VectorDataDict
+        | VectorDataset
+        | None = None,
+        longitude: npt.ArrayLike | None = None,
+        latitude: npt.ArrayLike | None = None,
+        altitude: npt.ArrayLike | None = None,
+        time: npt.ArrayLike | None = None,
         attrs: dict[str, Any] | AttrDict | None = None,
         copy: bool = True,
         aircraft: Aircraft | None = None,
@@ -245,7 +242,7 @@ class Flight(GeoVectorDataset):
         self.fuel = fuel or JetA()
 
         # Check flight data for possible errors
-        if np.any(self.altitude > 16000):
+        if np.any(self.altitude > 16000.0):
             flight_id = self.attrs.get("flight_id", "")
             flight_id = flight_id and f" for flight {flight_id}"
             warnings.warn(
@@ -260,35 +257,36 @@ class Flight(GeoVectorDataset):
                 "with segment-based methods (e.g. 'segment_true_airspeed')."
             )
 
-        diff_ = np.diff(self["time"])
+        time_diff = np.diff(self["time"])
 
         # Ensure that time is sorted
-        if self and np.any(diff_ < np.timedelta64(0)):
+        if self and np.any(time_diff < np.timedelta64(0)):
             if not copy:
                 raise ValueError(
-                    "`time` data must be sorted if `copy` is False on creation. "
+                    "The 'time' array must be sorted if 'copy=False' on creation. "
                     "Set copy=False, or sort data before creating Flight."
                 )
-            warnings.warn("Sorting Flight data by `time`.")
+            warnings.warn("Sorting Flight data by time.")
 
             sorted_flight = self.sort("time")
             self.data = sorted_flight.data
-            # Update diff_ ... we use it again below
-            diff_ = np.diff(self["time"])
+
+            # Update time_diff ... we use it again below
+            time_diff = np.diff(self["time"])
 
         # Check for duplicate times. If dropping duplicates,
-        # keep the *first* occurrence of each time. This is achieved with
-        # the np.insert (rather than np.append) function.
-        filt = np.insert(diff_ > np.timedelta64(0), 0, True)
-        if not np.all(filt):
+        # keep the *first* occurrence of each time.
+        duplicated_times = time_diff == np.timedelta64(0)
+        if self and np.any(duplicated_times):
             if drop_duplicated_times:
-                filtered_flight = self.filter(filt, copy=False)
+                mask = np.insert(duplicated_times, 0, False)
+                filtered_flight = self.filter(~mask, copy=False)
                 self.data = filtered_flight.data
             else:
                 warnings.warn(
-                    "Flight contains duplicate times. This will cause errors "
-                    "with segment-based methods (e.g. 'segment_true_airspeed'). Set "
-                    "'drop_duplicated=True' or call the 'resample_and_fill' method."
+                    f"Flight contains {duplicated_times.sum()} duplicate times. "
+                    "This will cause errors with segment-based methods. Set "
+                    "'drop_duplicated_times=True' or call the 'resample_and_fill' method."
                 )
 
     @overrides
@@ -420,7 +418,7 @@ class Flight(GeoVectorDataset):
     # Segment Properties
     # ------------
 
-    def segment_duration(self, dtype: np.dtype = np.dtype(np.float32)) -> np.ndarray:
+    def segment_duration(self, dtype: npt.DTypeLike = np.float32) -> npt.NDArray[np.float_]:
         r"""Compute time elapsed between waypoints in seconds.
 
         ``np.nan`` appended so the length of the output is the same as number of waypoints.
@@ -433,14 +431,14 @@ class Flight(GeoVectorDataset):
 
         Returns
         -------
-        np.ndarray
+        npt.NDArray[np.float_]
             Time difference between waypoints, [:math:`s`].
             Returns an array with dtype specified by``dtype``
         """
 
-        return _dt_waypoints(self.data["time"], dtype=dtype)
+        return segment_duration(self.data["time"], dtype=dtype)
 
-    def segment_length(self) -> np.ndarray:
+    def segment_length(self) -> npt.NDArray[np.float_]:
         """Compute spherical distance between flight waypoints.
 
         Helper function used in :meth:`length` and :meth:`length_met`.
@@ -448,7 +446,7 @@ class Flight(GeoVectorDataset):
 
         Returns
         -------
-        np.ndarray
+        npt.NDArray[np.float_]
             Array of distances in [:math:`m`] between waypoints
 
         Raises
@@ -478,7 +476,7 @@ class Flight(GeoVectorDataset):
 
         return geo.segment_length(self["longitude"], self["latitude"], self.altitude)
 
-    def segment_angle(self) -> tuple[np.ndarray, np.ndarray]:
+    def segment_angle(self) -> tuple[npt.NDArray[np.float_], npt.NDArray[np.float_]]:
         """Calculate sin/cos for the angle between each segment and the longitudinal axis.
 
         This is different from the usual navigational angle between two points known as *bearing*.
@@ -498,7 +496,7 @@ class Flight(GeoVectorDataset):
 
         Returns
         -------
-        np.ndarray, np.ndarray
+        npt.NDArray[np.float_], npt.NDArray[np.float_]
             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``.
 
@@ -528,7 +526,7 @@ class Flight(GeoVectorDataset):
         """
         return geo.segment_angle(self["longitude"], self["latitude"])
 
-    def segment_azimuth(self) -> np.ndarray:
+    def segment_azimuth(self) -> npt.NDArray[np.float_]:
         """Calculate (forward) azimuth at each waypoint.
 
         Method calls `pyproj.Geod.inv`, which is slow. See `geo.forward_azimuth`
@@ -540,7 +538,7 @@ class Flight(GeoVectorDataset):
 
         Returns
         -------
-        np.ndarray
+        npt.NDArray[np.float_]
             Array of azimuths.
         """
         lon = self["longitude"]
@@ -564,7 +562,7 @@ class Flight(GeoVectorDataset):
 
     def segment_groundspeed(
         self, smooth: bool = False, window_length: int = 7, polyorder: int = 1
-    ) -> np.ndarray:
+    ) -> npt.NDArray[np.float_]:
         """Return groundspeed across segments.
 
         Calculate by dividing the horizontal segment length by the difference in waypoint times.
@@ -581,16 +579,14 @@ class Flight(GeoVectorDataset):
 
         Returns
         -------
-        np.ndarray
+        npt.NDArray[np.float_]
             Groundspeed of the segment, [:math:`m s^{-1}`]
         """
-        # get horizontal distance - set altitude to 0
+        # get horizontal distance (altitude is ignored)
         horizontal_segment_length = geo.segment_haversine(self["longitude"], self["latitude"])
 
         # time between waypoints, in seconds
-        dt_sec = np.empty_like(horizontal_segment_length)
-        dt_sec[:-1] = np.diff(self["time"]) / np.timedelta64(1, "s")
-        dt_sec[-1] = np.nan
+        dt_sec = self.segment_duration(dtype=horizontal_segment_length.dtype)
 
         # calculate groundspeed
         groundspeed = horizontal_segment_length / dt_sec
@@ -605,8 +601,8 @@ class Flight(GeoVectorDataset):
 
     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,
@@ -617,10 +613,10 @@ class Flight(GeoVectorDataset):
 
         Parameters
         ----------
-        u_wind : npt.NDArray[np.float_], optional
+        u_wind : npt.NDArray[np.float_] | float
             U wind speed, [:math:`m \ s^{-1}`].
             Defaults to 0 for all waypoints.
-        v_wind : npt.NDArray[np.float_], optional
+        v_wind : npt.NDArray[np.float_] | float
             V wind speed, [:math:`m \ s^{-1}`].
             Defaults to 0 for all waypoints.
         smooth : bool, optional
@@ -638,12 +634,6 @@ class Flight(GeoVectorDataset):
         """
         groundspeed = self.segment_groundspeed(smooth, window_length, polyorder)
 
-        if u_wind is None:
-            u_wind = np.zeros_like(groundspeed)
-
-        if v_wind is None:
-            v_wind = np.zeros_like(groundspeed)
-
         sin_a, cos_a = self.segment_angle()
         gs_x = groundspeed * cos_a
         gs_y = groundspeed * sin_a
@@ -653,25 +643,76 @@ class Flight(GeoVectorDataset):
         return np.sqrt(tas_x * tas_x + tas_y * tas_y)
 
     def segment_mach_number(
-        self, true_airspeed: np.ndarray, air_temperature: np.ndarray
-    ) -> np.ndarray:
+        self, true_airspeed: npt.NDArray[np.float_], air_temperature: npt.NDArray[np.float_]
+    ) -> npt.NDArray[np.float_]:
         r"""Calculate the mach number of each segment.
 
         Parameters
         ----------
-        true_airspeed : np.ndarray
+        true_airspeed : npt.NDArray[np.float_]
             True airspeed of the segment, [:math:`m \ s^{-1}`].
             See :meth:`segment_true_airspeed`.
-        air_temperature : np.ndarray
+        air_temperature : npt.NDArray[np.float_]
             Average air temperature of each segment, [:math:`K`]
 
         Returns
         -------
-        np.ndarray
+        npt.NDArray[np.float_]
             Mach number of each segment
         """
         return units.tas_to_mach_number(true_airspeed, air_temperature)
 
+    def segment_rocd(self) -> npt.NDArray[np.float_]:
+        """Calculate the rate of climb and descent (ROCD).
+
+        Returns
+        -------
+        npt.NDArray[np.float_]
+            Rate of climb and descent over segment, [:math:`ft min^{-1}`]
+
+        See Also
+        --------
+        :func:`segment_rocd`
+        """
+        return segment_rocd(self.segment_duration(), self.altitude_ft)
+
+    def segment_phase(
+        self,
+        threshold_rocd: float = 250.0,
+        min_cruise_altitude_ft: float = 20000.0,
+    ) -> npt.NDArray[np.uint8]:
+        """Identify the phase of flight (climb, cruise, descent) for each segment.
+
+        Parameters
+        ----------
+        threshold_rocd : float, optional
+            ROCD threshold to identify climb and descent, [:math:`ft min^{-1}`].
+            Currently set to 250 ft/min.
+        min_cruise_altitude_ft : float, optional
+            Minimum altitude for cruise, [:math:`ft`]
+            This is specific for each aircraft type,
+            and can be approximated as 50% of the altitude ceiling.
+            Defaults to 20000 ft.
+
+        Returns
+        -------
+        npt.NDArray[np.uint8]
+            Array of values enumerating the flight phase.
+            See :attr:`flight.FlightPhase` for enumeration.
+
+        See Also
+        --------
+        :attr:`FlightPhase`
+        :func:`segment_phase`
+        :func:`segment_rocd`
+        """
+        return segment_phase(
+            self.segment_rocd(),
+            self.altitude_ft,
+            threshold_rocd=threshold_rocd,
+            min_cruise_altitude_ft=min_cruise_altitude_ft,
+        )
+
     # ------------
     # Filter/Resample
     # ------------
@@ -772,20 +813,20 @@ class Flight(GeoVectorDataset):
                    2       50.0       0.0       0.0 2020-01-01 02:00:00
 
         >>> fl.resample_and_fill('10T').dataframe  # resample with 10 minute frequency
-                          time  longitude  latitude  altitude
-        0  2020-01-01 00:00:00   0.000000       0.0       0.0
-        1  2020-01-01 00:10:00   0.000000       0.0       0.0
-        2  2020-01-01 00:20:00   0.000000       0.0       0.0
-        3  2020-01-01 00:30:00   0.000000       0.0       0.0
-        4  2020-01-01 00:40:00   0.000000       0.0       0.0
-        5  2020-01-01 00:50:00   0.000000       0.0       0.0
-        6  2020-01-01 01:00:00   0.000000       0.0       0.0
-        7  2020-01-01 01:10:00   8.928571       0.0       0.0
-        8  2020-01-01 01:20:00  16.964286       0.0       0.0
-        9  2020-01-01 01:30:00  25.892857       0.0       0.0
-        10 2020-01-01 01:40:00  33.928571       0.0       0.0
-        11 2020-01-01 01:50:00  41.964286       0.0       0.0
-        12 2020-01-01 02:00:00  50.000000       0.0       0.0
+            longitude  latitude  altitude                time
+        0    0.000000       0.0       0.0 2020-01-01 00:00:00
+        1    0.000000       0.0       0.0 2020-01-01 00:10:00
+        2    0.000000       0.0       0.0 2020-01-01 00:20:00
+        3    0.000000       0.0       0.0 2020-01-01 00:30:00
+        4    0.000000       0.0       0.0 2020-01-01 00:40:00
+        5    0.000000       0.0       0.0 2020-01-01 00:50:00
+        6    0.000000       0.0       0.0 2020-01-01 01:00:00
+        7    8.928571       0.0       0.0 2020-01-01 01:10:00
+        8   16.964286       0.0       0.0 2020-01-01 01:20:00
+        9   25.892857       0.0       0.0 2020-01-01 01:30:00
+        10  33.928571       0.0       0.0 2020-01-01 01:40:00
+        11  41.964286       0.0       0.0 2020-01-01 01:50:00
+        12  50.000000       0.0       0.0 2020-01-01 02:00:00
         """
         methods = "geodesic", "linear"
         if fill_method not in methods:
@@ -840,7 +881,7 @@ class Flight(GeoVectorDataset):
         # STEP 5: Resample flight to freq
         df = df.resample(freq).first()
 
-        # STEP 6: Linearly interprolate small horizontal gaps and account
+        # STEP 6: Linearly interpolate small horizontal gaps and account
         # for previous longitude shift.
         keys = ["latitude", "longitude"]
         df.loc[:, keys] = df.loc[:, keys].interpolate(method="linear")
@@ -860,6 +901,65 @@ class Flight(GeoVectorDataset):
         df = df.reset_index()
         return Flight(data=df, attrs=self.attrs)
 
+    def fit_altitude(
+        self,
+        max_segments: int = 30,
+        pop: int = 3,
+        r2_target: float = 0.999,
+        max_cruise_rocd: float = 10.0,
+        sg_window: int = 7,
+        sg_polyorder: int = 1,
+    ) -> Flight:
+        """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
+        -------
+        Flight
+            Smoothed flight
+        """
+        # np.roll pushes the last NaN value from `segment_duration` to the front
+        # so the elapsed time at the first waypoint will be 0
+        seg_dur = self.segment_duration(dtype=np.float64)
+        elapsed_time = np.nancumsum(np.roll(seg_dur, 1))
+        alt_ft = fit_altitude(
+            elapsed_time,
+            np.copy(self.altitude_ft),
+            max_segments,
+            pop,
+            r2_target,
+            max_cruise_rocd,
+            sg_window,
+        )
+
+        flight = self.copy()
+        flight.update(altitude_ft=alt_ft)
+        return flight
+
     def _geodesic_interpolation(self, geodesic_threshold: float) -> pd.DataFrame | None:
         """Geodesic interpolate between large gaps between waypoints.
 
@@ -1075,7 +1175,7 @@ class Flight(GeoVectorDataset):
         >>> variables = ["air_temperature", "specific_humidity"]
         >>> levels = [300, 250, 200]
         >>> era5 = ERA5(time=times, variables=variables, pressure_levels=levels)
-        >>> met = era5.open_metdataset(xr_kwargs=dict(parallel=False))
+        >>> met = era5.open_metdataset()
 
         >>> # Build flight
         >>> df = pd.DataFrame()
@@ -1169,12 +1269,12 @@ class Flight(GeoVectorDataset):
         return ax
 
 
-def _return_linestring(data: dict[str, np.ndarray]) -> list[list[float]]:
+def _return_linestring(data: dict[str, npt.NDArray[np.float_]]) -> list[list[float]]:
     """Return list of coordinates for geojson constructions.
 
     Parameters
     ----------
-    data : dict[str, np.ndarray]
+    data : dict[str, npt.NDArray[np.float_]]
         :attr:`data` containing `longitude`, `latitude`, and `altitude` keys
 
     Returns
@@ -1184,9 +1284,9 @@ def _return_linestring(data: dict[str, np.ndarray]) -> list[list[float]]:
     """
     # rounding to reduce the size of resultant json arrays
     points = zip(  # pylint: disable=zip-builtin-not-iterating
-        np.around(data["longitude"], decimals=4),
-        np.around(data["latitude"], decimals=4),
-        np.around(data["altitude"], decimals=4),
+        np.round(data["longitude"], decimals=4),
+        np.round(data["latitude"], decimals=4),
+        np.round(data["altitude"], decimals=4),
     )
     return [list(p) for p in points]
 
@@ -1248,16 +1348,16 @@ def _antimeridian_index(longitude: pd.Series, crs: str = "EPSG:4326") -> int:
     return -1
 
 
-def _sg_filter(vals: np.ndarray, window_length: int = 7, polyorder: int = 1) -> np.ndarray:
+def _sg_filter(
+    vals: npt.NDArray[np.float_], window_length: int = 7, polyorder: int = 1
+) -> npt.NDArray[np.float_]:
     """Apply Savitzky-Golay filter to smooth out noise in the time-series data.
 
-    Used to smooth true airspeed & fuel flow.
-
-    TODO: move to a more centralized location in the codebase if used again
+    Used to smooth true airspeed, fuel flow, and altitude.
 
     Parameters
     ----------
-    vals : np.ndarray
+    vals : npt.NDArray[np.float_]
         Input array
     window_length : int, optional
         Parameter for :func:`scipy.signal.savgol_filter`
@@ -1266,7 +1366,7 @@ def _sg_filter(vals: np.ndarray, window_length: int = 7, polyorder: int = 1) ->
 
     Returns
     -------
-    np.ndarray
+    npt.NDArray[np.float_]
         Smoothed values
 
     Raises
@@ -1292,8 +1392,8 @@ def _sg_filter(vals: np.ndarray, window_length: int = 7, polyorder: int = 1) ->
 
 
 def _altitude_interpolation(
-    altitude: np.ndarray, nominal_rocd: float, freq: np.timedelta64
-) -> np.ndarray:
+    altitude: npt.NDArray[np.float_], nominal_rocd: float, freq: np.timedelta64
+) -> npt.NDArray[np.float_]:
     """Interpolate nan values in `altitude` array.
 
     Suppose each group of consecutive nan values is enclosed by `a0` and `a1` with
@@ -1304,7 +1404,7 @@ def _altitude_interpolation(
 
     Parameters
     ----------
-    altitude : np.ndarray
+    altitude : npt.NDArray[np.float_]
         Array of altitude values containing nan values. This function will raise
         an error if `altitude` does not contain nan values. Moreover, this function
         assumes the initial and final entries in `altitude` are not nan.
@@ -1315,7 +1415,7 @@ def _altitude_interpolation(
 
     Returns
     -------
-    np.ndarray
+    npt.NDArray[np.float_]
         Altitude after nan values have been filled
     """
     # Determine nan state of altitude
@@ -1360,12 +1460,14 @@ def _altitude_interpolation(
     return np.where(sign == 1, fill_climb, fill_descent)
 
 
-def _verify_altitude(altitude: np.ndarray, nominal_rocd: float, freq: np.timedelta64) -> None:
+def _verify_altitude(
+    altitude: npt.NDArray[np.float_], nominal_rocd: float, freq: np.timedelta64
+) -> None:
     """Confirm that the time derivative of `altitude` does not exceed twice `nominal_rocd`.
 
     Parameters
     ----------
-    altitude : np.ndarray
+    altitude : npt.NDArray[np.float_]
         Array of filled altitude values containing nan values.
     nominal_rocd : float
         Nominal rate of climb/descent, in m/s
@@ -1386,14 +1488,94 @@ def _verify_altitude(altitude: np.ndarray, nominal_rocd: float, freq: np.timedel
         )
 
 
-def _dt_waypoints(
-    time: npt.NDArray[np.datetime64], dtype: np.dtype = np.dtype(np.float32)
+def filter_altitude(
+    altitude: npt.NDArray[np.float_], *, kernel_size: int = 17
+) -> npt.NDArray[np.float_]:
+    """
+    Filter noisy altitude on a single flight.
+
+    Currently runs altitude through a median filter using :func:`scipy.signal.medfilt`
+    with ``kernel_size``, then a Savitzky-Golay filter to filter noise.
+
+    .. todo::
+
+        This method assumes that the time interval between altitude points
+        (:func:`segment_duration`) is moderately small (e.g. minutes).
+        This filter may not work as well when waypoints are close (seconds) or
+        farther apart in time (e.g. 30 minutes).
+
+        The optimal altitude filter is a work in a progress
+        and may change in the future.
+
+    Parameters
+    ----------
+    altitude : npt.NDArray[np.float_]
+        Altitude signal
+    kernel_size : int, optional
+        Passed directly to :func:`scipy.signal.medfilt`, by default 11.
+        Passed also to :func:`scipy.signal.medfilt`
+
+    Returns
+    -------
+    npt.NDArray[np.float_]
+        Filtered altitude
+
+    Notes
+    -----
+    Algorithm is derived from :meth:`traffic.core.flight.Flight.filter`.
+
+    The `traffic
+    <https://traffic-viz.github.io/api_reference/traffic.core.flight.html#traffic.core.Flight.filter>`_
+    algorithm also computes thresholds on sliding windows
+    and replaces unacceptable values with NaNs.
+
+    Errors may raised if the ``kernel_size`` is too large.
+
+    See Also
+    --------
+    :meth:`traffic.core.flight.Flight.filter`
+    :func:`scipy.signal.medfilt`
+    """  # noqa: E501
+    if not len(altitude):
+        raise ValueError("Altitude must have non-zero length to filter")
+
+    # The kernel_size must be less than or equal to the number of data points available.
+    kernel_size = min(kernel_size, altitude.size)
+
+    # The kernel_size must be odd.
+    if (kernel_size % 2) == 0:
+        kernel_size -= 1
+
+    # Apply a median filter above a certain threshold
+    altitude_filt = scipy.signal.medfilt(altitude, kernel_size=kernel_size)
+
+    # TODO: I think this makes sense because it smooths the climb/descent phases
+    altitude_filt = _sg_filter(altitude_filt, window_length=kernel_size)
+
+    # TODO: The right way to do this is with a low pass filter at
+    # a reasonable rocd threshold ~300-500 ft/min, e.g.
+    # sos = scipy.signal.butter(4, 250, 'low', output='sos')
+    # return scipy.signal.sosfilt(sos, altitude_filt1)
+    #
+    # Remove noise manually
+    # only remove above max airport elevation
+    d_alt_ft = np.diff(altitude_filt, append=np.nan)
+    is_noise = (np.abs(d_alt_ft) <= 25.0) & (altitude_filt > MAX_AIRPORT_ELEVATION)
+    altitude_filt[is_noise] = np.round(altitude_filt[is_noise], -3)
+
+    return altitude_filt
+
+
+def segment_duration(
+    time: npt.NDArray[np.datetime64], dtype: npt.DTypeLike = np.float32
 ) -> npt.NDArray[np.float_]:
     """Calculate the time difference between waypoints.
 
+    ``np.nan`` appended so the length of the output is the same as number of waypoints.
+
     Parameters
     ----------
-    time : np.ndarray
+    time : npt.NDArray[np.datetime64]
         Waypoint time in ``np.datetime64`` format.
     dtype : np.dtype
         Numpy dtype for time difference.
@@ -1401,11 +1583,180 @@ def _dt_waypoints(
 
     Returns
     -------
-    np.ndarray
+    npt.NDArray[np.float_]
         Time difference between waypoints, [:math:`s`].
-        This returns an array with dtype specified by``dtype``
+        This returns an array with dtype specified by``dtype``.
     """
     out = np.empty_like(time, dtype=dtype)
     out[-1] = np.nan
     out[:-1] = np.diff(time) / np.timedelta64(1, "s")
     return out
+
+
+def segment_phase(
+    rocd: npt.NDArray[np.float_],
+    altitude_ft: npt.NDArray[np.float_],
+    *,
+    threshold_rocd: float = 250.0,
+    min_cruise_altitude_ft: float = MIN_CRUISE_ALTITUDE,
+) -> npt.NDArray[np.uint8]:
+    """Identify the phase of flight (climb, cruise, descent) for each segment.
+
+    Parameters
+    ----------
+    rocd: pt.NDArray[np.float_]
+        Rate of climb and descent across segment, [:math:`ft min^{-1}`].
+        See output from :func:`segment_rocd`.
+    altitude_ft: npt.NDArray[np.float_]
+        Altitude, [:math:`ft`]
+    threshold_rocd: float, optional
+        ROCD threshold to identify climb and descent, [:math:`ft min^{-1}`].
+        Defaults to 250 ft/min.
+    min_cruise_altitude_ft: float, optional
+        Minimum threshold altitude for cruise, [:math:`ft`]
+        This is specific for each aircraft type,
+        and can be approximated as 50% of the altitude ceiling.
+        Defaults to :attr:`MIN_CRUISE_ALTITUDE`.
+
+    Returns
+    -------
+    npt.NDArray[np.uint8]
+        Array of values enumerating the flight phase.
+        See :attr:`flight.FlightPhase` for enumeration.
+
+    Notes
+    -----
+    Flight data derived from ADS-B and radar sources could contain noise leading
+    to small changes in altitude and ROCD. Hence, an arbitrary ``threshold_rocd``
+    is specified to identify the different phases of flight.
+
+    The flight phase "level-flight" is when an aircraft is holding at lower altitudes.
+    The cruise phase of flight only occurs above a certain threshold altitude.
+
+    See Also
+    --------
+    :attr:`FlightPhase`
+    :func:`segment_rocd`
+    """
+    nan = np.isnan(rocd)
+    cruise = (
+        (rocd < threshold_rocd) & (rocd > -threshold_rocd) & (altitude_ft > min_cruise_altitude_ft)
+    )
+    climb = ~cruise & (rocd > 0)
+    descent = ~cruise & (rocd < 0)
+    level_flight = ~(nan | cruise | climb | descent)
+
+    phase = np.empty(rocd.shape, dtype=np.uint8)
+    phase[cruise] = FlightPhase.CRUISE
+    phase[climb] = FlightPhase.CLIMB
+    phase[descent] = FlightPhase.DESCENT
+    phase[level_flight] = FlightPhase.LEVEL_FLIGHT
+    phase[nan] = FlightPhase.NAN
+
+    return phase
+
+
+def segment_rocd(
+    segment_duration: npt.NDArray[np.float_], altitude_ft: npt.NDArray[np.float_]
+) -> npt.NDArray[np.float_]:
+    """Calculate the rate of climb and descent (ROCD).
+
+    Parameters
+    ----------
+    segment_duration: npt.NDArray[np.float_]
+        Time difference between waypoints, [:math:`s`].
+        Expected to have numeric `dtype`, not `"timedelta64"`.
+        See output from :func:`segment_duration`.
+    altitude_ft: npt.NDArray[np.float_]
+        Altitude of each waypoint, [:math:`ft`]
+
+    Returns
+    -------
+    npt.NDArray[np.float_]
+        Rate of climb and descent over segment, [:math:`ft min^{-1}`]
+
+    See Also
+    --------
+    :func:`segment_duration`
+    """
+    dt_min = segment_duration / 60.0
+
+    out = np.empty_like(altitude_ft)
+    out[:-1] = np.diff(altitude_ft) / dt_min[:-1]
+    out[-1] = np.nan
+
+    return out
+
+
+def fit_altitude(
+    elapsed_time: npt.NDArray[np.float_],
+    altitude_ft: npt.NDArray[np.float_],
+    max_segments: int = 30,
+    pop: int = 3,
+    r2_target: float = 0.999,
+    max_cruise_rocd: float = 10.0,
+    sg_window: int = 7,
+    sg_polyorder: int = 1,
+) -> npt.NDArray[np.float_]:
+    """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
+    ----------
+    elapsed_time: npt.NDArray[np.float_]
+        Cumulative time of flight between waypoints, [:math:`s`]
+    altitude_ft: npt.NDArray[np.float_]
+        Altitude of each waypoint, [:math:`ft`
+    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
+    -------
+    npt.NDArray[np.float_]
+        Smoothed flight altitudes
+    """
+    try:
+        import pwlf
+    except ModuleNotFoundError:
+        raise ModuleNotFoundError(
+            "The 'fit_altitude' function requires the 'pwlf' package."
+            "This can be installed with 'pip install pwlf'."
+        )
+    for i in range(1, max_segments):
+        m2 = pwlf.PiecewiseLinFit(elapsed_time, altitude_ft)
+        r = m2.fitfast(i, pop)
+        r2 = m2.r_squared()
+        if r2 > r2_target:
+            break
+
+    mask = abs(m2.slopes) < max_cruise_rocd / 60.0
+    bounds = r[:-1][mask], r[1:][mask]
+    lvl = np.round(m2.intercepts[mask], -3)
+    time_stack = np.repeat(elapsed_time[:, np.newaxis], lvl.size, axis=1)
+    filt = (time_stack >= bounds[0]) & (time_stack <= bounds[1])
+    altitude_ft = np.copy(altitude_ft)
+    for i in range(lvl.size):
+        altitude_ft[filt[:, i]] = lvl[i]
+
+    altitude_ft = scipy.signal.savgol_filter(altitude_ft, sg_window, sg_polyorder)
+
+    return altitude_ft