pycontrails 0.51.2__cp311-cp311-macosx_11_0_arm64.whl → 0.52.1__cp311-cp311-macosx_11_0_arm64.whl

pycontrails/__init__.py

@@ -30,7 +30,6 @@ with contextlib.suppress(ImportError):
     import netCDF4  # noqa: F401
 
 from pycontrails.core.cache import DiskCacheStore, GCPCacheStore
-from pycontrails.core.datalib import MetDataSource
 from pycontrails.core.fleet import Fleet
 from pycontrails.core.flight import Flight, FlightPhase
 from pycontrails.core.fuel import Fuel, HydrogenFuel, JetA, SAFBlend
@@ -38,6 +37,7 @@ from pycontrails.core.met import MetDataArray, MetDataset
 from pycontrails.core.met_var import MetVariable
 from pycontrails.core.models import Model, ModelParams
 from pycontrails.core.vector import GeoVectorDataset, VectorDataset
+from pycontrails.datalib._met_utils.metsource import MetDataSource
 
 __version__ = metadata.version("pycontrails")
 __license__ = "Apache-2.0"

pycontrails/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.51.2'
-__version_tuple__ = version_tuple = (0, 51, 2)
+__version__ = version = '0.52.1'
+__version_tuple__ = version_tuple = (0, 52, 1)

pycontrails/core/__init__.py

@@ -1,7 +1,6 @@
 """Core data structures and methods."""
 
 from pycontrails.core.cache import DiskCacheStore, GCPCacheStore
-from pycontrails.core.datalib import MetDataSource
 from pycontrails.core.fleet import Fleet
 from pycontrails.core.flight import Flight
 from pycontrails.core.fuel import Fuel, HydrogenFuel, JetA, SAFBlend
@@ -9,6 +8,7 @@ from pycontrails.core.met import MetDataArray, MetDataset
 from pycontrails.core.met_var import MetVariable
 from pycontrails.core.models import Model, ModelParams
 from pycontrails.core.vector import GeoVectorDataset, VectorDataset
+from pycontrails.datalib._met_utils.metsource import MetDataSource
 
 __all__ = [
     "DiskCacheStore",

pycontrails/core/cache.py

@@ -20,7 +20,7 @@ from pycontrails.utils import dependencies
 
 # optional imports
 if TYPE_CHECKING:
-    import google
+    import google.cloud.storage
 
 
 @functools.cache

pycontrails/core/coordinates.py

@@ -59,27 +59,27 @@ def slice_domain(
     >>> # Call with request as np.array
     >>> request = np.linspace(-20, 20, 100)
     >>> slice_domain(domain, request)
-    slice(640, 801, None)
+    slice(np.int64(640), np.int64(801), None)
 
     >>> # Call with request as tuple
     >>> request = -20, 20
     >>> slice_domain(domain, request)
-    slice(640, 801, None)
+    slice(np.int64(640), np.int64(801), None)
 
     >>> # Call with a buffer
     >>> request = -16, 13
     >>> buffer = 4, 7
     >>> slice_domain(domain, request, buffer)
-    slice(640, 801, None)
+    slice(np.int64(640), np.int64(801), None)
 
     >>> # Call with request as a single number
     >>> request = -20
     >>> slice_domain(domain, request)
-    slice(640, 641, None)
+    slice(np.int64(640), np.int64(641), None)
 
     >>> request = -19.9
     >>> slice_domain(domain, request)
-    slice(640, 642, None)
+    slice(np.int64(640), np.int64(642), None)
 
     """
     # if the length of domain coordinates is <= 2, return the whole domain

pycontrails/core/flight.py

@@ -384,7 +384,7 @@ class Flight(GeoVectorDataset):
         ...     time=pd.date_range('2021-01-01T12', '2021-01-01T14', periods=200),
         ... )
         >>> fl.max_distance_gap
-        7391.27...
+        np.float64(7391.27...)
         """
         if self.attrs["crs"] != "EPSG:4326":
             raise NotImplementedError("Only implemented for EPSG:4326 CRS.")
@@ -415,7 +415,7 @@ class Flight(GeoVectorDataset):
         ...     time=pd.date_range('2021-01-01T12', '2021-01-01T14', periods=200),
         ... )
         >>> fl.length
-        1436924.67...
+        np.float64(1436924.67...)
         """
         if self.attrs["crs"] != "EPSG:4326":
             raise NotImplementedError("Only implemented for EPSG:4326 CRS.")
@@ -1374,21 +1374,20 @@ class Flight(GeoVectorDataset):
         return {"type": "FeatureCollection", "features": [linestring]}
 
     def to_geojson_multilinestring(
-        self, key: str, split_antimeridian: bool = True
+        self, key: str | None = None, split_antimeridian: bool = True
     ) -> dict[str, Any]:
         """Return trajectory as GeoJSON FeatureCollection of MultiLineStrings.
 
-        Flight :attr:`data` is grouped according to values of ``key``. Each group gives rise to a
-        Feature containing a MultiLineString geometry. LineStrings can be split over the
-        antimeridian.
+        If `key` is provided, Flight :attr:`data` is grouped according to values of ``key``.
+        Each group gives rise to a Feature containing a MultiLineString geometry.
+        Each MultiLineString can optionally be split over the antimeridian.
 
         Parameters
         ----------
-        key : str
-            Name of :attr:`data` column to group by
+        key : str, optional
+            If provided, name of :attr:`data` column to group by.
         split_antimeridian : bool, optional
-            Split linestrings that cross the antimeridian.
-            Defaults to True
+            Split linestrings that cross the antimeridian. Defaults to True.
 
         Returns
         -------
@@ -1398,31 +1397,41 @@ class Flight(GeoVectorDataset):
         Raises
         ------
         KeyError
-            :attr:`data` does not contain column ``key``
+            ``key`` is provided but :attr:`data` does not contain column ``key``
         """
-        if key not in self.dataframe.columns:
+        if key is not None and key not in self.dataframe.columns:
             raise KeyError(f"Column {key} does not exist in data.")
 
-        jump_index = _antimeridian_index(pd.Series(self["longitude"]), self.attrs["crs"])
+        jump_indices = _antimeridian_index(pd.Series(self["longitude"]), self.attrs["crs"])
 
         def _group_to_feature(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()
-            # additional splitting at antimeridian
-            if jump_index in subgrouping and split_antimeridian:
-                subgrouping.loc[jump_index:] += 1
+
+            # increments values after antimeridian crossings
+            if split_antimeridian:
+                for jump_index in jump_indices:
+                    if jump_index in subgrouping:
+                        subgrouping.loc[jump_index:] += 1
+
+            # creates separate linestrings for sets of points
+            # - with non-consecutive indices
+            # - before and after antimeridian crossings
             multi_ls = [_return_linestring(g) for _, g in group.groupby(subgrouping)]
             geometry = {"type": "MultiLineString", "coordinates": multi_ls}
 
             # adding in static properties
-            properties: dict[str, Any] = {key: group.name}
+            properties: dict[str, Any] = {key: group.name} if key is not None else {}
             properties.update(self.constants)
             return {"type": "Feature", "geometry": geometry, "properties": properties}
 
-        features = (
-            self.dataframe.groupby(key)
-            .apply(_group_to_feature, include_groups=False)
-            .values.tolist()
-        )
+        if key is not None:
+            groups = self.dataframe.groupby(key)
+        else:
+            # create a single group containing all rows of dataframe
+            groups = self.dataframe.groupby(lambda _: 0)
+
+        features = groups.apply(_group_to_feature, include_groups=False).values.tolist()
         return {"type": "FeatureCollection", "features": features}
 
     def to_traffic(self) -> traffic.core.Flight:
@@ -1511,11 +1520,11 @@ class Flight(GeoVectorDataset):
 
         >>> # Length (in meters) of waypoints whose temperature exceeds 236K
         >>> fl.length_met("air_temperature", threshold=236)
-        4132178.159...
+        np.float64(4132178.159...)
 
         >>> # Proportion (with respect to distance) of waypoints whose temperature exceeds 236K
         >>> fl.proportion_met("air_temperature", threshold=236)
-        0.663552...
+        np.float64(0.663552...)
         """
         if key not in self.data:
             raise KeyError(f"Column {key} does not exist in data.")
@@ -1609,8 +1618,8 @@ def _return_linestring(data: dict[str, npt.NDArray[np.float64]]) -> list[list[fl
     return [list(p) for p in points]
 
 
-def _antimeridian_index(longitude: pd.Series, crs: str = "EPSG:4326") -> int:
-    """Return index after flight crosses antimeridian, or -1 if flight does not cross.
+def _antimeridian_index(longitude: pd.Series, crs: str = "EPSG:4326") -> list[int]:
+    """Return indices after flight crosses antimeridian, or an empty list if flight does not cross.
 
     Parameters
     ----------
@@ -1658,12 +1667,7 @@ def _antimeridian_index(longitude: pd.Series, crs: str = "EPSG:4326") -> int:
     jump21 = longitude[s1.shift() & s2]
     jump_index = pd.concat([jump12, jump21]).index.to_list()
 
-    if len(jump_index) > 1:
-        raise ValueError("Only implemented for trajectories jumping the antimeridian at most once.")
-    if len(jump_index) == 1:
-        return jump_index[0]
-
-    return -1
+    return jump_index
 
 
 def _sg_filter(

pycontrails/core/interpolation.py

@@ -621,11 +621,11 @@ class EmissionsProfileInterpolator:
     >>> epi = EmissionsProfileInterpolator(xp, fp)
     >>> # Interpolate a single value
     >>> epi.interp(5)
-    0.150000...
+    np.float64(0.150000...)
 
     >>> # Interpolate a single value on a logarithmic scale
     >>> epi.log_interp(5)
-    1.105171...
+    np.float64(1.105171...)
 
     >>> # Demonstrate speed up compared with xarray.DataArray interpolation
     >>> import time, xarray as xr

pycontrails/core/met.py

@@ -1375,9 +1375,10 @@ class MetDataArray(MetBase):
 
         # try to create DataArray out of input data and **kwargs
         if not isinstance(data, xr.DataArray):
-            DeprecationWarning(
+            warnings.warn(
                 "Input 'data' must be an xarray DataArray. "
-                "Passing arbitrary kwargs will be removed in future versions."
+                "Passing arbitrary kwargs will be removed in future versions.",
+                DeprecationWarning,
             )
             data = xr.DataArray(data, **kwargs)
 
@@ -2609,13 +2610,14 @@ def _load(hash: str, cachestore: CacheStore, chunks: dict[str, int]) -> xr.Datas
 
 
 def _add_vertical_coords(data: XArrayType) -> XArrayType:
-    """Add "air_pressure" and "altitude" coordinates to data."""
+    """Add "air_pressure" and "altitude" coordinates to data.
 
-    data["level"].attrs.update(units="hPa", long_name="Pressure", positive="down")
+    .. versionchanged:: 0.52.1
+        Ensure that the ``dtype`` of the additional vertical coordinates agree
+        with the ``dtype`` of the underlying gridded data.
+    """
 
-    coords = data.coords
-    if "air_pressure" in coords and "altitude" in coords:
-        return data
+    data["level"].attrs.update(units="hPa", long_name="Pressure", positive="down")
 
     # XXX: use the dtype of the data to determine the precision of these coordinates
     # There are two competing conventions here:
@@ -2625,25 +2627,32 @@ def _add_vertical_coords(data: XArrayType) -> XArrayType:
     # It is more important for air_pressure and altitude to be grid-aligned than to be
     # coordinate-aligned, so we use the dtype of the data to determine the precision of
     # these coordinates
-    if isinstance(data, xr.Dataset):
-        dtype = np.result_type(*data.data_vars.values(), np.float32)
-    else:
-        dtype = data.dtype
-    level = data["level"].values.astype(dtype, copy=False)
+    dtype = (
+        np.result_type(*data.data_vars.values(), np.float32)
+        if isinstance(data, xr.Dataset)
+        else data.dtype
+    )
 
-    if "air_pressure" not in coords:
+    level = data["level"].values
+
+    if "air_pressure" not in data.coords:
         data = data.assign_coords(air_pressure=("level", level * 100.0))
         data.coords["air_pressure"].attrs.update(
             standard_name=AirPressure.standard_name,
             long_name=AirPressure.long_name,
             units=AirPressure.units,
         )
-    if "altitude" not in coords:
+    if data.coords["air_pressure"].dtype != dtype:
+        data.coords["air_pressure"] = data.coords["air_pressure"].astype(dtype, copy=False)
+
+    if "altitude" not in data.coords:
         data = data.assign_coords(altitude=("level", units.pl_to_m(level)))
         data.coords["altitude"].attrs.update(
             standard_name=Altitude.standard_name,
             long_name=Altitude.long_name,
             units=Altitude.units,
         )
+    if data.coords["altitude"].dtype != dtype:
+        data.coords["altitude"] = data.coords["altitude"].astype(dtype, copy=False)
 
     return data

pycontrails/core/polygon.py

@@ -536,7 +536,7 @@ def multipolygon_to_geojson(
             else:
                 shape = len(ring.coords), 3
                 coords = np.empty(shape)
-                coords[:, :2] = ring.coords
+                coords[:, :2] = np.asarray(ring.coords)
                 coords[:, 2] = altitude
 
             poly_coords.append(coords.tolist())

pycontrails/core/vector.py

@@ -2057,7 +2057,7 @@ def vector_to_lon_lat_grid(
            [2.97, 0.12, 1.33, ..., 3.54, 0.74, 2.59]])
 
     >>> da.sum().item() == vector["foo"].sum()
-    True
+    np.True_
 
     """
     df = vector.select(("longitude", "latitude", *agg), copy=False).dataframe

pycontrails/datalib/__init__.py

@@ -1,9 +1,12 @@
 """
-Meteorology and Air Traffic data source wrappers.
+Meteorology, Air Traffic, and Observation data source wrappers.
 
 See individual modules for met variables and additional exports.
 
 - :module:`pycontrails.datalib.ecmwf`
 - :module:`pycontrails.datalib.gfs`
 - :module:`pycontrails.datalib.spire`
+- :module:`pycontrails.datalib.goes`
+- :module:`pycontrails.datalib.landsat`
+- :module:`pycontrails.datalib.sentinel`
 """

pycontrails/datalib/_leo_utils/search.py

@@ -0,0 +1,250 @@
+"""Tools for searching for low Earth orbit satellite imagery."""
+
+import dataclasses
+import pathlib
+
+import numpy as np
+import pandas as pd
+
+from pycontrails.core import Flight
+from pycontrails.utils import dependencies
+
+try:
+    import geojson
+except ModuleNotFoundError as exc:
+    dependencies.raise_module_not_found_error(
+        name="datalib._leo_utils module",
+        package_name="geojson",
+        module_not_found_error=exc,
+        pycontrails_optional_package="sat",
+    )
+
+_path_to_static = pathlib.Path(__file__).parent / "static"
+ROI_QUERY_FILENAME = _path_to_static / "bq_roi_query.sql"
+
+
+#: GeoJSON polygon that covers the entire globe.
+GLOBAL_EXTENT = geojson.dumps(
+    geojson.Polygon([[(-180, -90), (180, -90), (180, 90), (-180, 90), (-180, -90)]])
+)
+
+
+@dataclasses.dataclass
+class ROI:
+    """Spatiotemporal region of interest."""
+
+    #: Start time
+    start_time: np.datetime64
+
+    #: End time
+    end_time: np.datetime64
+
+    #: GeoJSON representation of spatial ROI.
+    extent: str
+
+    def __post_init__(self) -> None:
+        """Validate region of interest."""
+        if self.start_time > self.end_time:
+            msg = "start_time must be before end_time"
+            raise ValueError(msg)
+
+        try:
+            decoded = geojson.Feature(geometry=geojson.loads(self.extent))
+        except Exception as exc:
+            msg = "extent cannot be converted to GeoJSON structure"
+            raise ValueError(msg) from exc
+        if not decoded.is_valid:
+            msg = "extent is not valid GeoJSON"
+            raise ValueError(msg)
+
+
+def track_to_geojson(flight: Flight) -> str:
+    """Convert ground track to GeoJSON string, splitting at antimeridian crossings.
+
+    Coordinates contain longitude and latitude only (no altitude coordinate)
+    and are padded to terminate and restart exactly at the antimeridian when
+    antimeridian crossings are encountered.
+
+    Parameters
+    ----------
+    flight : Flight
+        Flight with ground track to convert to GeoJSON string.
+
+    Returns
+    -------
+    str
+        String encoding of a GeoJSON MultiLineString containing ground track split at
+        antimeridian crossings.
+
+    See Also
+    --------
+    :meth:`Flight.to_geojson_multilinestring`
+    """
+
+    # Logic assumes longitudes are between -180 and 180.
+    # Raise an error if this is not the case.
+    if np.abs(flight["longitude"]).max() > 180.0:
+        msg = "Flight longitudes must be between -180 and 180."
+        raise ValueError(msg)
+
+    # Get feature collection containing a single multilinestring
+    # split at antimeridian crossings
+    fc = flight.to_geojson_multilinestring(split_antimeridian=True)
+
+    # Extract multilinestring
+    mls = fc["features"][0]["geometry"]
+
+    # Strip altitude coordinates
+    coords = [[[c[0], c[1]] for c in linestring] for linestring in mls["coordinates"]]
+
+    # No padding required if no antimeridian crossings were encountered
+    if len(coords) == 1:
+        return geojson.dumps(geojson.MultiLineString(coords))
+
+    # Pad at crossings
+    for i in range(len(coords) - 1):
+        x0 = coords[i][-1][0]
+        x1 = coords[i + 1][0][0]
+        if abs(x0) == 180.0 and abs(x1) == 180.0:
+            continue
+        y0 = coords[i][-1][1]
+        y1 = coords[i + 1][0][1]
+        xl = 180.0 * np.sign(x0)
+        xr = 180.0 * np.sign(x1)
+        w0 = np.abs(xr - x1)
+        w1 = np.abs(xl - x0)
+        yc = (w0 * y0 + w1 * y1) / (w0 + w1)
+        if abs(x0) < 180.0:
+            coords[i].append([xl, yc])
+        if abs(x1) < 180.0:
+            coords[i + 1].insert(0, [xr, yc])
+
+    # Encode as string
+    return geojson.dumps(geojson.MultiLineString(coords))
+
+
+def query(table: str, roi: ROI, columns: list[str], extra_filters: str = "") -> pd.DataFrame:
+    """Find satellite imagery within region of interest.
+
+    This function requires access to the
+    `Google BigQuery API <https://cloud.google.com/bigquery?hl=en>`__
+    and uses the `BigQuery python library <https://cloud.google.com/python/docs/reference/bigquery/latest/index.html>`__.
+
+    Parameters
+    ----------
+    table : str
+        Name of BigQuery table to query
+    roi : ROI
+        Region of interest
+    columns : list[str]
+        Columns to return from Google
+        `BigQuery table <https://console.cloud.google.com/bigquery?p=bigquery-public-data&d=cloud_storage_geo_index&t=landsat_index&page=table&_ga=2.90807450.1051800793.1716904050-255800408.1705955196>`__.
+    extra_filters : str, optional
+        Additional selection filters, injected verbatim into constructed query.
+
+    Returns
+    -------
+    pd.DataFrame
+        Query results in pandas DataFrame
+    """
+    try:
+        from google.cloud import bigquery
+    except ModuleNotFoundError as exc:
+        dependencies.raise_module_not_found_error(
+            name="landsat module",
+            package_name="google-cloud-bigquery",
+            module_not_found_error=exc,
+            pycontrails_optional_package="landsat",
+        )
+
+    if len(columns) == 0:
+        msg = "At least column must be provided."
+        raise ValueError(msg)
+
+    start_time = pd.Timestamp(roi.start_time).strftime("%Y-%m-%d %H:%M:%S")
+    end_time = pd.Timestamp(roi.end_time).strftime("%Y-%m-%d %H:%M:%S")
+    extent = roi.extent.replace('"', "'")
+
+    client = bigquery.Client()
+    with open(ROI_QUERY_FILENAME) as f:
+        query_str = f.read().format(
+            table=table,
+            columns=",".join(columns),
+            start_time=start_time,
+            end_time=end_time,
+            geojson_str=extent,
+            extra_filters=extra_filters,
+        )
+
+    result = client.query(query_str)
+    return result.to_dataframe()
+
+
+def intersect(
+    table: str, flight: Flight, columns: list[str], extra_filters: str = ""
+) -> pd.DataFrame:
+    """Find satellite imagery intersecting with flight track.
+
+    This function will return all scenes with a bounding box that includes flight waypoints
+    both before and after the sensing time.
+
+    This function requires access to the
+    `Google BigQuery API <https://cloud.google.com/bigquery?hl=en>`__
+    and uses the `BigQuery python library <https://cloud.google.com/python/docs/reference/bigquery/latest/index.html>`__.
+
+    Parameters
+    ----------
+    table : str
+        Name of BigQuery table to query
+    flight : Flight
+        Flight for intersection
+    columns : list[str]
+        Columns to return from Google
+        `BigQuery table <https://console.cloud.google.com/bigquery?p=bigquery-public-data&d=cloud_storage_geo_index&t=landsat_index&page=table&_ga=2.90807450.1051800793.1716904050-255800408.1705955196>`__.
+    extra_filters : str, optional
+        Additional selection filters, injected verbatim into constructed query.
+
+    Returns
+    -------
+    pd.DataFrame
+        Query results in pandas DataFrame
+    """
+
+    # create ROI with time span between flight start and end
+    # and spatial extent set to flight track
+    extent = track_to_geojson(flight)
+    roi = ROI(start_time=flight["time"].min(), end_time=flight["time"].max(), extent=extent)
+
+    # first pass: query for intersections with ROI
+    # requires additional columns for final intersection with flight
+    required_columns = set(["sensing_time", "west_lon", "east_lon", "south_lat", "north_lat"])
+    queried_columns = list(required_columns.union(set(columns)))
+    candidates = query(table, roi, queried_columns, extra_filters)
+
+    if len(candidates) == 0:  # already know there are no intersections
+        return candidates[columns]
+
+    # second pass: keep images with where flight waypoints
+    # bounding sensing time are both within bounding box
+    flight_data = flight.dataframe
+
+    def intersects(scene: pd.Series) -> bool:
+        if scene["west_lon"] <= scene["east_lon"]:  # scene does not span antimeridian
+            bbox_data = flight_data[
+                flight_data["longitude"].between(scene["west_lon"], scene["east_lon"])
+                & flight_data["latitude"].between(scene["south_lat"], scene["north_lat"])
+            ]
+        else:  # scene spans antimeridian
+            bbox_data = flight_data[
+                (
+                    flight_data["longitude"]
+                    > scene["west_lon"] | flight.data["longitude"]
+                    < scene["east_lon"]
+                )
+                & flight_data["latitude"].between(scene["south_lat"], scene["north_lat"])
+            ]
+        sensing_time = pd.Timestamp(scene["sensing_time"]).tz_localize(None)
+        return bbox_data["time"].min() <= sensing_time and bbox_data["time"].max() >= sensing_time
+
+    mask = candidates.apply(intersects, axis="columns")
+    return candidates[columns][mask]

pycontrails/datalib/_leo_utils/static/bq_roi_query.sql

@@ -0,0 +1,6 @@
+SELECT {columns} FROM `{table}` WHERE 
+   sensing_time >= "{start_time}" AND
+   sensing_time <= "{end_time}" AND
+   ST_INTERSECTSBOX(ST_GEOGFROMGEOJSON("{geojson_str}"), west_lon, south_lat, east_lon, north_lat)
+   {extra_filters}
+   ORDER BY sensing_time ASC

pycontrails/datalib/_leo_utils/vis.py

@@ -0,0 +1,60 @@
+"""Utilities for visualization of low-Earth orbit satellite imagery."""
+
+from typing import Any
+
+import numpy as np
+
+from pycontrails.utils import dependencies
+
+try:
+    import skimage as ski
+except ModuleNotFoundError as exc:
+    dependencies.raise_module_not_found_error(
+        name="landsat module",
+        package_name="scikit-image",
+        module_not_found_error=exc,
+        pycontrails_optional_package="sat",
+    )
+
+
+def normalize(channel: np.ndarray) -> np.ndarray:
+    """Normalize channel values to range [0, 1], preserving ``np.nan`` in output.
+
+    Parameters
+    ----------
+    channel: np.ndarray
+        Array of channel values for normalization.
+
+    Returns
+    -------
+    np.ndarray
+        Equalized channel values. ``np.nan`` will be preserved wherever present in input.
+    """
+    return (channel - np.nanmin(channel)) / (np.nanmax(channel) - np.nanmin(channel))
+
+
+def equalize(channel: np.ndarray, **equalize_kwargs: Any) -> np.ndarray:
+    """Apply :py:func:`ski.exposure.equalize_adapthist`, preserving ``np.nan`` in output.
+
+    Parameters
+    ----------
+    channel: np.ndarray
+        Array of channel values for equalization.
+    **equalize_kwargs : Any
+        Keyword arguments passed to :py:func:`ski.exposure.equalize_adapthist`.
+
+    Returns
+    -------
+    np.ndarray
+        Equalized channel values. ``np.nan`` will be preserved wherever present in input.
+
+    Notes
+    -----
+    NaN values are converted to 0 before passing to :py:func:`ski.exposure.equalize_adapthist`
+    and may affect equalized values in the neighborhood where they occur.
+    """
+    return np.where(
+        np.isnan(channel),
+        np.nan,
+        ski.exposure.equalize_adapthist(np.nan_to_num(channel, nan=0), **equalize_kwargs),
+    )