CAMs Global FX Datasource

[NickGeneva]

Earth2Studio Pull Request

Description

Clean up and getting test working of the PR: #780

Sample script:

#!/usr/bin/env python
# SPDX-FileCopyrightText: Copyright (c) 2024-2026 NVIDIA CORPORATION & AFFILIATES.
# SPDX-FileCopyrightText: All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""
CAMS Global Forecast – fetch a variable and plot it on a map.

Usage:
    python cams_visualization.py                    # default: aod550 at lead_time=0h
    python cams_visualization.py u500 6             # u-wind at 500 hPa, 6h lead
    python cams_visualization.py t2m 0 --no-show    # save only, no GUI window

Requires:
    pip install 'earth2studio[data]' matplotlib cartopy

Note:
    You need ADS API credentials configured.
    See: https://ads.atmosphere.copernicus.eu/how-to-api
"""

import argparse
import datetime

import cartopy.crs as ccrs
import cartopy.feature as cfeature
import matplotlib.pyplot as plt
import numpy as np

from earth2studio.data import CAMS_FX


def main() -> None:
    parser = argparse.ArgumentParser(description="Plot a CAMS Global forecast field.")
    parser.add_argument(
        "variable",
        nargs="?",
        default="aod550",
        help="Variable name from CAMSGlobalLexicon (default: aod550)",
    )
    parser.add_argument(
        "lead_hours",
        nargs="?",
        type=int,
        default=0,
        help="Forecast lead time in hours (default: 0)",
    )
    parser.add_argument(
        "--date",
        type=str,
        default=None,
        help="Init date YYYY-MM-DD (default: yesterday 00Z)",
    )
    parser.add_argument(
        "--no-show",
        action="store_true",
        help="Save the figure but do not open a GUI window",
    )
    args = parser.parse_args()

    # Resolve init time
    if args.date:
        init_time = datetime.datetime.strptime(args.date, "%Y-%m-%d").replace(
            tzinfo=datetime.timezone.utc
        )
    else:
        init_time = datetime.datetime.now(datetime.timezone.utc).replace(
            hour=0, minute=0, second=0, microsecond=0
        ) - datetime.timedelta(days=1)

    lead_time = datetime.timedelta(hours=args.lead_hours)
    variable = args.variable

    print(f"Fetching CAMS: var={variable}  init={init_time}  lead={lead_time}")

    ds = CAMS_FX(cache=True, verbose=True)
    data = ds(init_time, lead_time, variable)

    # Extract the 2-D field (time=0, lead_time=0, variable=0)
    field = data.values[0, 0, 0]
    lat = data.coords["lat"].values
    lon = data.coords["lon"].values

    valid_time = init_time + lead_time
    title = (
        f"CAMS Global – {variable}\n"
        f"Init: {init_time:%Y-%m-%d %H}Z   "
        f"Valid: {valid_time:%Y-%m-%d %H}Z  (T+{args.lead_hours}h)"
    )

    # Plot
    fig, ax = plt.subplots(
        figsize=(14, 7),
        subplot_kw={"projection": ccrs.Robinson()},
    )
    ax.set_global()
    ax.add_feature(cfeature.COASTLINE, linewidth=0.5)
    ax.add_feature(cfeature.BORDERS, linewidth=0.3, linestyle="--")

    im = ax.pcolormesh(
        lon,
        lat,
        field,
        transform=ccrs.PlateCarree(),
        cmap="turbo",
        shading="auto",
    )

    cbar = fig.colorbar(im, ax=ax, orientation="horizontal", pad=0.05, shrink=0.7)
    cbar.set_label(variable)
    ax.set_title(title, fontsize=13)

    out_path = f"cams_{variable}_T{args.lead_hours:03d}.png"
    fig.savefig(out_path, dpi=150, bbox_inches="tight")
    print(f"Saved → {out_path}")

    if not args.no_show:
        plt.show()


if __name__ == "__main__":
    main()

Checklist

• I am familiar with the Contributing Guidelines.
• New or existing tests cover these changes.
• The documentation is up to date with these changes.
• The CHANGELOG.md is up to date with these changes.
• An issue is linked to this pull request.
• Assess and address Greptile feedback (AI code review bot for guidance; use discretion, addressing all feedback is not required).

Dependencies

[NickGeneva]

/blossom-ci

[greptile-apps]

Greptile Summary

This PR adds a new CAMS_FX forecast data source backed by the CAMS Global Atmospheric Composition Forecasts API (cdsapi), along with a CAMSGlobalLexicon covering surface, aerosol, trace-gas, and pressure-level variables. It also adds an autouse fixture to test_cds.py to ensure the CDS tests hit the correct API endpoint.

• P1 — silent lead-time truncation: np.timedelta64(lt, \"h\").astype(int) truncates fractional hours before _validate_leadtime is called; the guard for non-whole-hour inputs never fires and the wrong lead time is silently requested from the API.

Confidence Score: 4/5

Safe to merge after addressing the sub-hour lead-time truncation bug; P2 findings are non-blocking.

One P1 defect remains: fractional-hour lead times are silently truncated rather than rejected, causing the wrong data to be fetched without any error. The two P2 findings (available() inconsistency, nearest-neighbor without tolerance) are quality improvements but do not block users on the primary path.

earth2studio/data/cams.py — specifically the lead_hours conversion and _extract_field nearest-neighbor logic.

Important Files Changed

Filename	Overview
earth2studio/data/cams.py	New CAMS_FX data source; contains a P1 bug where fractional-hour lead times are silently truncated instead of rejected, and two P2 concerns around available() inconsistency and silent nearest-neighbor matching in _extract_field.
earth2studio/lexicon/cams.py	New CAMSGlobalLexicon; VOCAB entries are consistent, tco3 maps to nc_key "gtco3" which matches ECMWF conventions. Surface "z" and pressure-level "z*" both use nc_key "z" but live in separate datasets so no collision.
test/data/test_cams.py	New test file with mocked unit tests and slow/xfail integration tests; covers surface, pressure-level, mixed fetches, deduplication, cache behaviour, and lead-time validation.
earth2studio/lexicon/base.py	Adds 10 new CAMS variable descriptions to E2STUDIO_VOCAB; no conflicts with existing entries.
test/data/test_cds.py	Adds autouse fixture to point cdsapi at the CDS endpoint, preventing test modules from accidentally hitting the ADS endpoint.
test/lexicon/test_cams_lexicon.py	New lexicon tests covering all VOCAB entries and the four-part key format.

_{Reviews (2): Last reviewed commit: "Fix" | Re-trigger Greptile}

[NickGeneva]

/blossom-ci

[NickGeneva]

/blossom-ci

[NickGeneva]

/blossom-ci

[NickGeneva]

/blossom-ci