pycontrails 0.51.1__cp39-cp39-win_amd64.whl → 0.51.2__cp39-cp39-win_amd64.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,5 +1,5 @@
 pycontrails/__init__.py,sha256=8WUs6hZAAIH1yKfwYJ8UEqNsk5voRyLmmD3Dje9DZaE,2055
-pycontrails/_version.py,sha256=gmP4X4NUxYBWytULG1EUTGL8LNF16D8DZ1omSI-P98c,429
+pycontrails/_version.py,sha256=xMJiFm-L3Ds4ihKsGP2O4OOfKy4NICJsA72FioJ3YvQ,429
 pycontrails/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pycontrails/core/__init__.py,sha256=eNypVTz1kHBSKAJX3CgfKw-VKrMRRkKTutmjSlrfeUs,870
 pycontrails/core/aircraft_performance.py,sha256=ikeJmdvFRDa1RdfR-JKfhQbiiIzL0c2vzcBmobmoxMs,22511
@@ -15,8 +15,8 @@ pycontrails/core/interpolation.py,sha256=Sp9s17i1QQx3jZwnwvt3vo6enWwlkYwTVKCE27N
 pycontrails/core/met.py,sha256=l0A1MEFrOUtYWO_ZHoHzYgqa1rmIh7fxA8PiwE26yT8,96251
 pycontrails/core/met_var.py,sha256=JzB7UhBLQyU4TuKZqemhpBHA6Dbt89BPYO2sYBLMkL4,9504
 pycontrails/core/models.py,sha256=VS-ct4xkojJIuqdPpT1ke1ZetNzv10nNx_Z_XalZyeo,40175
-pycontrails/core/polygon.py,sha256=iliIQv-EUpstP3nOEqgpqLhztW4UI_A4NeCGQuj0Ku8,18542
-pycontrails/core/rgi_cython.cp39-win_amd64.pyd,sha256=-WEt3DcyMcH2tgxh6imppOycjXO_0KEgM3wyNJaupQQ,257536
+pycontrails/core/polygon.py,sha256=IwKnTRfKCgcOqbvKSsm-iJwd1HheS8sgsxAb6ufJy7c,18565
+pycontrails/core/rgi_cython.cp39-win_amd64.pyd,sha256=kP83euCh1NtoX4UzMC93hcuohq39lveI2_Pj6UzrYIg,258560
 pycontrails/core/vector.py,sha256=MF0oWX0Ghp_G41A712VbU1GEKRNU_Pj9PtzMREPG5Z8,73916
 pycontrails/datalib/__init__.py,sha256=WnXqgv20SrHZLjFZ9qpQEwRnf0QvfZU-YvMqh7PAUwg,246
 pycontrails/datalib/goes.py,sha256=NVk6QFfHbGpOINlKlG6PR1Hn_LCmzP7k20VJQZXpVG8,27124
@@ -48,12 +48,12 @@ pycontrails/models/pcc.py,sha256=M5KhtRgdCP9pfDFgui7ibbijtRBTjx3QOJL_m1tQYfs,114
 pycontrails/models/pcr.py,sha256=G_0yR5PsCMeJBP6tZFi3M7A6Wcq8s71UvosdA7ozUkI,5502
 pycontrails/models/sac.py,sha256=Cj4Hi3324wjqLQ7I2CPVkrIh2Fq5W5pKpGrwhYADoHI,16420
 pycontrails/models/tau_cirrus.py,sha256=eXt3yRrcFBaZNNeH6ZOuU4XEZU2rOfrLKEOC7f0_Ywo,5194
-pycontrails/models/cocip/__init__.py,sha256=X_MlkJzQ-henQ0xGq-1bfCMajH6s9tlK5QLnN7yfQ68,929
+pycontrails/models/cocip/__init__.py,sha256=miDxSFxN9PzL_ieSJb3BYeHmbKqZwGicCz1scNB5eW0,991
 pycontrails/models/cocip/cocip.py,sha256=s9j5UhPCaaxiJZDXUvQ2KnEgvQz2pMrRHlWKZijwRIw,100140
 pycontrails/models/cocip/cocip_params.py,sha256=T4IseK6KtY4hG3BuGZBtFgM90HCYecUXsb_QVEK6uGo,11670
 pycontrails/models/cocip/cocip_uncertainty.py,sha256=lksROIRLt-jxEdjJTiLP9Da-FYt1GjZKaIxwDaH2Ytg,12069
 pycontrails/models/cocip/contrail_properties.py,sha256=u6SvucHC6VtF2kujfSVFTfv0263t5uYpNOUJZAroEzc,57111
-pycontrails/models/cocip/output_formats.py,sha256=sYGYosAL6BQvntKXdeomAph-K6EKOgsI2VQynLEHxnM,79228
+pycontrails/models/cocip/output_formats.py,sha256=VFWXGIDcWg98aQhMdstOhWlfhmHEUP582eHtyfcaFvw,85473
 pycontrails/models/cocip/radiative_forcing.py,sha256=SYmQ8lL8gpWbf6he2C9mKSjODtytbFcdnMdBM-LtBKE,46206
 pycontrails/models/cocip/radiative_heating.py,sha256=N7FTR20luERmokprdqMOl-d8-cTYZZ2ZSsTdxZnLHfs,19368
 pycontrails/models/cocip/unterstrasser_wake_vortex.py,sha256=Ymz-uO9vVhLIFwT9yuF5g1g3hcT-XWdryLsebSBqoVU,14976
@@ -92,9 +92,9 @@ pycontrails/utils/iteration.py,sha256=En2YY4NiNwCNtAVO8HL6tv9byBGKs8MKSI7R8P-gZy
 pycontrails/utils/json.py,sha256=xCv71CKVZNHk4MyoYC-hl7dXObXXbI7P8gcNCn3AUoU,6172
 pycontrails/utils/temp.py,sha256=5XXqQoEfWjz1OrhoOBZD5vkkCFeuq9LpZkyhc38gIeY,1159
 pycontrails/utils/types.py,sha256=gNG9cSZ3djW7jufg0h1fXM3kD24sBY6ENE6wsxY_Q6o,4937
-pycontrails-0.51.1.dist-info/LICENSE,sha256=HVr8JnZfTaA-12BfKUQZi5hdrB3awOwLWs5X_ga5QzA,10353
-pycontrails-0.51.1.dist-info/METADATA,sha256=DV-S88nuFZuvdNYedTdFfpc7A9_kQirr1jZqn5pmDsE,8527
-pycontrails-0.51.1.dist-info/NOTICE,sha256=qYeNEp8OjDK5jSW3hTlr9LQRjZeEhXQm0zDei5UFaYs,1969
-pycontrails-0.51.1.dist-info/WHEEL,sha256=Z6c-bE0pUM47a70GvqO_SvH_XXU0lm62gEAKtoNJ08A,100
-pycontrails-0.51.1.dist-info/top_level.txt,sha256=dwaYXVcMhF92QWtAYcLvL0k02vyBqwhsv92lYs2V6zQ,23
-pycontrails-0.51.1.dist-info/RECORD,,
+pycontrails-0.51.2.dist-info/LICENSE,sha256=HVr8JnZfTaA-12BfKUQZi5hdrB3awOwLWs5X_ga5QzA,10353
+pycontrails-0.51.2.dist-info/METADATA,sha256=qgSIf3DN0e3MemCUJtmRDKoAlSm5SO3bsvwYtxli3D0,8571
+pycontrails-0.51.2.dist-info/NOTICE,sha256=qYeNEp8OjDK5jSW3hTlr9LQRjZeEhXQm0zDei5UFaYs,1969
+pycontrails-0.51.2.dist-info/WHEEL,sha256=Z6c-bE0pUM47a70GvqO_SvH_XXU0lm62gEAKtoNJ08A,100
+pycontrails-0.51.2.dist-info/top_level.txt,sha256=dwaYXVcMhF92QWtAYcLvL0k02vyBqwhsv92lYs2V6zQ,23
+pycontrails-0.51.2.dist-info/RECORD,,