pycontrails 0.51.1__cp311-cp311-macosx_10_9_x86_64.whl → 0.51.2__cp311-cp311-macosx_10_9_x86_64.whl

pycontrails/_version.py

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

pycontrails/core/polygon.py

@@ -354,7 +354,7 @@ def find_multipolygon(
         return shapely.MultiPolygon()
 
     assert len(hierarchy) == 1
-    hierarchy = hierarchy[0]
+    hierarchy = hierarchy[0]  # type: ignore[index]
 
     polygons = _contours_to_polygons(
         contours,  # type: ignore[arg-type]

pycontrails/models/cocip/__init__.py

@@ -4,6 +4,7 @@ from pycontrails.models.cocip.cocip import Cocip
 from pycontrails.models.cocip.cocip_params import CocipFlightParams, CocipParams
 from pycontrails.models.cocip.cocip_uncertainty import CocipUncertaintyParams, habit_dirichlet
 from pycontrails.models.cocip.output_formats import (
+    compare_cocip_with_goes,
     contrail_flight_summary_statistics,
     contrails_to_hi_res_grid,
     flight_waypoint_summary_statistics,
@@ -24,4 +25,5 @@ __all__ = [
     "longitude_latitude_grid",
     "natural_cirrus_properties_to_hi_res_grid",
     "time_slice_statistics",
+    "compare_cocip_with_goes",
 ]

pycontrails/models/cocip/output_formats.py

@@ -14,13 +14,17 @@ This module includes functions to produce additional output formats, including t
     (6) Increase spatial resolution of natural cirrus properties, required to estimate the
         high-resolution contrail cirrus coverage for (5).
             See :func:`natural_cirrus_properties_to_hi_res_grid`.
+    (7) Comparing simulated contrails from CoCiP with GOES satellite imagery.
+            See :func:`compare_cocip_with_goes`.
 """
 
 from __future__ import annotations
 
+import pathlib
 import warnings
 from collections.abc import Hashable
 
+import matplotlib.pyplot as plt
 import numpy as np
 import numpy.typing as npt
 import pandas as pd
@@ -28,6 +32,7 @@ import xarray as xr
 
 from pycontrails.core.met import MetDataArray, MetDataset
 from pycontrails.core.vector import GeoVectorDataset, vector_to_lon_lat_grid
+from pycontrails.datalib.goes import GOES, extract_goes_visualization
 from pycontrails.models.cocip.contrail_properties import contrail_edges, plume_mass_per_distance
 from pycontrails.models.cocip.radiative_forcing import albedo
 from pycontrails.models.humidity_scaling import HumidityScaling
@@ -2077,3 +2082,163 @@ def _repeat_rows_and_columns(
 
     # Do not repeat final row and column as they are on the edge
     return array_2d_rep[: -(n_reps - 1), : -(n_reps - 1)]
+
+
+# -----------------------------------------
+# Compare CoCiP outputs with GOES satellite
+# -----------------------------------------
+
+
+def compare_cocip_with_goes(
+    time: np.timedelta64 | pd.Timestamp,
+    flight: GeoVectorDataset | pd.DataFrame,
+    contrail: GeoVectorDataset | pd.DataFrame,
+    *,
+    spatial_bbox: tuple[float, float, float, float] = (-160.0, -80.0, 10.0, 80.0),
+    region: str = "F",
+    path_write_img: pathlib.Path | None = None,
+) -> None | pathlib.Path:
+    r"""
+    Compare simulated persistent contrails from CoCiP with GOES satellite imagery.
+
+    Parameters
+    ----------
+    time : np.timedelta64 | pd.Timestamp
+        Time of GOES satellite image.
+    flight : GeoVectorDataset | pd.DataFrame
+        Flight waypoints.
+        Best to use the returned output :class:`Flight` from
+        :meth:`pycontrails.models.cocip.Cocip.eval`.
+    contrail : GeoVectorDataset | pd.DataFrame,
+        Contrail evolution outputs (:attr:`pycontrails.models.cocip.Cocip.contrail`)
+        set during :meth:`pycontrails.models.cocip.Cocip.eval`.
+    spatial_bbox : tuple[float, float, float, float]
+        Spatial bounding box, ``(lon_min, lat_min, lon_max, lat_max)``, [:math:`\deg`]
+    region : str
+        'F' for full disk (image provided every 10 m), and 'C' for CONUS (image provided every 5 m)
+    path_write_img : None | pathlib.Path
+        File path to save the CoCiP-GOES image.
+
+    Returns
+    -------
+    None | pathlib.Path
+        File path of saved CoCiP-GOES image if ``path_write_img`` is provided.
+    """
+
+    try:
+        import cartopy.crs as ccrs
+        from cartopy.mpl.ticker import LatitudeFormatter, LongitudeFormatter
+    except ModuleNotFoundError as e:
+        dependencies.raise_module_not_found_error(
+            name="compare_cocip_with_goes function",
+            package_name="cartopy",
+            module_not_found_error=e,
+            pycontrails_optional_package="goes",
+        )
+
+    # Round `time` to nearest GOES image time slice
+    if isinstance(time, np.timedelta64):
+        time = pd.to_datetime(time)
+
+    if region == "F":
+        time = time.round("10min")
+    elif region == "C":
+        time = time.round("5min")
+    else:
+        raise AssertionError("`region` only accepts inputs of `F` (full disk) or `C` (CONUS)")
+
+    _flight = GeoVectorDataset(flight)
+    _contrail = GeoVectorDataset(contrail)
+
+    # Ensure the required columns are included in `flight_waypoints` and `contrails`
+    _flight.ensure_vars(["flight_id", "waypoint"])
+    _contrail.ensure_vars(
+        ["flight_id", "waypoint", "sin_a", "cos_a", "width", "tau_contrail", "age_hours"]
+    )
+
+    # Downselect `_flight` only to spatial domain covered by GOES full disk
+    is_in_lon = _flight.dataframe["longitude"].between(spatial_bbox[0], spatial_bbox[2])
+    is_in_lat = _flight.dataframe["latitude"].between(spatial_bbox[1], spatial_bbox[3])
+    is_in_lon_lat = is_in_lon & is_in_lat
+
+    if not np.any(is_in_lon_lat):
+        warnings.warn(
+            "Flight trajectory does not intersect with the defined spatial bounding box or spatial "
+            "domain covered by GOES."
+        )
+
+    _flight = _flight.filter(is_in_lon_lat)
+
+    # Filter `_flight` if time bounds were previously defined.
+    is_before_time = _flight["time"] < time
+
+    if not np.any(is_before_time):
+        warnings.warn("No flight waypoints were recorded before the specified `time`.")
+
+    _flight = _flight.filter(is_before_time)
+
+    # Downselect `_contrail` only to include the filtered flight waypoints
+    is_in_domain = _contrail.dataframe["waypoint"].isin(_flight["waypoint"])
+
+    if not np.any(is_in_domain):
+        warnings.warn(
+            "No persistent contrails were formed within the defined spatial bounding box."
+        )
+
+    _contrail = _contrail.filter(is_in_domain)
+
+    # Download GOES image at `time`
+    goes = GOES(region=region)
+    da = goes.get(time)
+    rgb, transform, extent = extract_goes_visualization(da)
+    bbox = spatial_bbox[0], spatial_bbox[2], spatial_bbox[1], spatial_bbox[3]
+
+    # Calculate optimal figure dimensions
+    d_lon = spatial_bbox[2] - spatial_bbox[0]
+    d_lat = spatial_bbox[3] - spatial_bbox[1]
+    x_dim = 9.99
+    y_dim = x_dim * (d_lat / d_lon)
+
+    # Plot data
+    fig = plt.figure(figsize=(1.2 * x_dim, y_dim))
+    pc = ccrs.PlateCarree()
+    ax = fig.add_subplot(projection=pc, extent=bbox)
+    ax.coastlines()  # type: ignore[attr-defined]
+    ax.imshow(rgb, extent=extent, transform=transform)
+
+    ax.set_xticks([spatial_bbox[0], spatial_bbox[2]], crs=ccrs.PlateCarree())
+    ax.set_yticks([spatial_bbox[1], spatial_bbox[3]], crs=ccrs.PlateCarree())
+    lon_formatter = LongitudeFormatter(zero_direction_label=True)
+    lat_formatter = LatitudeFormatter()
+    ax.xaxis.set_major_formatter(lon_formatter)
+    ax.yaxis.set_major_formatter(lat_formatter)
+
+    # Plot flight trajectory up to `time`
+    ax.plot(_flight["longitude"], _flight["latitude"], c="k", linewidth=2.5)
+    plt.legend(["Flight trajectory"])
+
+    # Plot persistent contrails at `time`
+    is_time = (_contrail["time"] == time) & (~np.isnan(_contrail["age_hours"]))
+    im = ax.scatter(
+        _contrail["longitude"][is_time],
+        _contrail["latitude"][is_time],
+        c=_contrail["tau_contrail"][is_time],
+        s=4,
+        cmap="YlOrRd_r",
+        vmin=0,
+        vmax=0.2,
+    )
+    cbar = plt.colorbar(im)
+    cbar.set_label(r"$\tau_{\rm contrail}$")
+    ax.set_title(f"{time}")
+    plt.tight_layout()
+
+    # return output path if `path_write_img` is not None
+    if path_write_img is not None:
+        t_str = time.strftime("%Y%m%d_%H%M%S")
+        file_name = f"goes_{t_str}.png"
+        output_path = path_write_img.joinpath(file_name)
+        plt.savefig(output_path, dpi=150, bbox_inches="tight")
+        plt.close()
+
+        return output_path

{pycontrails-0.51.1.dist-info → pycontrails-0.51.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pycontrails
-Version: 0.51.1
+Version: 0.51.2
 Summary: Python library for modeling aviation climate impacts
 Author-email: Breakthrough Energy <py@contrails.org>
 License: Apache-2.0
@@ -51,6 +51,7 @@ Requires-Dist: pytest >=8.2 ; extra == 'dev'
 Requires-Dist: pytest-cov >=2.11 ; extra == 'dev'
 Requires-Dist: requests >=2.25 ; extra == 'dev'
 Requires-Dist: ruff ==0.4.1 ; extra == 'dev'
+Requires-Dist: setuptools ; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: doc8 >=1.1 ; extra == 'docs'
 Requires-Dist: furo >=2023.3 ; extra == 'docs'

{pycontrails-0.51.1.dist-info → pycontrails-0.51.2.dist-info}/RECORD

@@ -1,20 +1,20 @@
-pycontrails-0.51.1.dist-info/RECORD,,
-pycontrails-0.51.1.dist-info/LICENSE,sha256=gJ-h7SFFD1mCfR6a7HILvEtodDT6Iig8bLXdgqR6ucA,10175
-pycontrails-0.51.1.dist-info/WHEEL,sha256=3Ij8bI-sb8yCMxXItr4MLlNoRGZb2WoUxQe9xIFR_DQ,111
-pycontrails-0.51.1.dist-info/NOTICE,sha256=gKI8DcN1WhiXB2SFRKDogcjONldGubTvBxiOYdC4CXU,1926
-pycontrails-0.51.1.dist-info/top_level.txt,sha256=Z8J1R_AiBAyCVjNw6jYLdrA68PrQqTg0t3_Yek_IZ0Q,29
-pycontrails-0.51.1.dist-info/METADATA,sha256=lhvTJXjoe4RWXxzCepstWZr3jUl5KSbY1cksSS4yu-Q,8366
-pycontrails/_version.py,sha256=VFAdktfJQ1HGHeBX5jprHcVJQgl3ZamLz76UBdxPqNE,413
+pycontrails-0.51.2.dist-info/RECORD,,
+pycontrails-0.51.2.dist-info/LICENSE,sha256=gJ-h7SFFD1mCfR6a7HILvEtodDT6Iig8bLXdgqR6ucA,10175
+pycontrails-0.51.2.dist-info/WHEEL,sha256=3Ij8bI-sb8yCMxXItr4MLlNoRGZb2WoUxQe9xIFR_DQ,111
+pycontrails-0.51.2.dist-info/NOTICE,sha256=gKI8DcN1WhiXB2SFRKDogcjONldGubTvBxiOYdC4CXU,1926
+pycontrails-0.51.2.dist-info/top_level.txt,sha256=Z8J1R_AiBAyCVjNw6jYLdrA68PrQqTg0t3_Yek_IZ0Q,29
+pycontrails-0.51.2.dist-info/METADATA,sha256=GrnTFo2vRstZA-G5KqvUe070DENl48rZUYrXVPjA2BM,8409
+pycontrails/_version.py,sha256=NAimol_13XfyyQAJabjsIQxFxJiaGc5BgWOof3jZQM8,413
 pycontrails/__init__.py,sha256=c_Vtz7CvdiVAL8ggluash9-8tGcLO_5Vvu-3_Ie47CE,1985
 pycontrails/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pycontrails/core/rgi_cython.cpython-311-darwin.so,sha256=wcZj8kQ2FNewsiDutocio7a_FL1Gr2X8oocuvlw0a14,315896
+pycontrails/core/rgi_cython.cpython-311-darwin.so,sha256=Lzjfu3_E6X0m96F4ADQmySPB54MXT0u_1ZR78UEI9No,315896
 pycontrails/core/vector.py,sha256=P61Rv1M040A1SRHmdWVR_RfXcWa6faM330n-9499ilI,71722
 pycontrails/core/models.py,sha256=sipUAH_r0A1TxQ0yBjaPj8WC33Piw34ABHyrmRePfhg,39003
 pycontrails/core/interpolation.py,sha256=FFYdUnTzGnkjoGs-FKsK3Y3nSK5lQI-mpq5HPALZ-y4,25495
 pycontrails/core/fleet.py,sha256=84oTb8RJ3-bPVvZn3O2ljMEZLwJ9Q-E455ZzQJ4QaQU,16075
 pycontrails/core/flight.py,sha256=jpd1bfdzUzNuuE-7pDraRC5I9kYetSwFUAMRYwMVxzw,83143
 pycontrails/core/fuel.py,sha256=kJZ3P1lPm1L6rdPREM55XQ-VfJ_pt35cP4sO2Nnvmjs,4332
-pycontrails/core/polygon.py,sha256=bLddqnsaA7XVXFcEVXR3V1tVIu5qQ8sxPUjFbwt0lO8,17993
+pycontrails/core/polygon.py,sha256=NhoK91oVE2pse1kw2mkkhxxQpJrvBld8ofTMCwNH_h8,18016
 pycontrails/core/datalib.py,sha256=m39gKxdhy9KSBhwWlrzEc5z-tTqPfcs7bPcqSxbU0k0,23971
 pycontrails/core/cache.py,sha256=rCBZiRSVoFkRwf_ay7O-eba2PaYoXdlJSz1znZPuOQk,27957
 pycontrails/core/__init__.py,sha256=4ZE7x1gMa_Q7GcgcWpPP9fQ-sTulCXWmMjsCJ0odakY,840
@@ -74,8 +74,8 @@ pycontrails/models/humidity_scaling/quantiles/era5-model-level-quantiles.pq,sha2
 pycontrails/models/cocip/radiative_forcing.py,sha256=ERuFcYMo0_1iiOricnZ8D4ext23bMnTCeZwg9vd6Vzs,44944
 pycontrails/models/cocip/wind_shear.py,sha256=p8d3iaNzxPA3MoxFEM1ZDKt0aticoD6U9cv0QmbuBzs,3860
 pycontrails/models/cocip/cocip.py,sha256=0ILMcjbgsM00rCXAeo9UkSnUsmvq1XvORhNPI-ReNcM,97591
-pycontrails/models/cocip/output_formats.py,sha256=d9naGliEEVuk2ER0KZEY5R2FHQZIY5NcP6PamlHcBM0,77149
-pycontrails/models/cocip/__init__.py,sha256=7Wy_CnmVqg_Gpg2UhIlisJOJ3naL6c5BBzTSJqdbiM4,902
+pycontrails/models/cocip/output_formats.py,sha256=e3K-23EvEE2z9PuHNr2OQhwvN8_PYmNmR7Li-dsYZq8,83229
+pycontrails/models/cocip/__init__.py,sha256=jd-9Tq20s1kwQBlxsYfZLi3hlT5MnWOY2XsPazq1fgE,962
 pycontrails/models/cocip/cocip_params.py,sha256=R4bewge3xLgWYbBbGwd8e8r0NlaFx2IaQPZEfiqJZRI,11392
 pycontrails/models/cocip/wake_vortex.py,sha256=i_OF193KK5BCMdVCgK0_4Aqn55f6rnL4WDWEac8um-w,14421
 pycontrails/models/cocip/cocip_uncertainty.py,sha256=4JtlCVFpLBnPRlvyEp9QFpRfHFK9joSTnxe0NJdONG4,11784