Was 2024 warmer or wetter than normal?

from datetime import UTC, datetime
from pathlib import Path

import pandas as pd
from IPython.display import Markdown, display

import usdata
from usdata.pull import pull, verify

manifest = Path("examples/climate-anomalies/dataset.yaml")
if not manifest.is_file():
    manifest = Path("dataset.yaml")

pd.set_option("display.max_rows", 12)
pd.set_option("display.max_columns", 8)
print(f"Executed (UTC): {datetime.now(UTC).isoformat(timespec='seconds')}")
print(f"usdata {usdata.__version__}; pandas {pd.__version__}")

print(manifest.read_text())

result = pull(manifest)
items = {item.asset.dataset_id: item for item in result.fetched}
assert len(items) == len(result.fetched) == 2, "expected exactly one asset per source"
observed = items["noaa:gsom"].open(dtype={"DATE": "string"}).set_index("DATE")
normals = (
    items["noaa:climate-normals"]
    .open(dtype={"DATE": "string", "MLY-TAVG-NORMAL": "string"})
    .set_index("DATE")
)
print(f"Observed months: {len(observed)}; monthly normals rows: {len(normals)}")
display(observed[["STATION", "PRCP", "TAVG"]].head(3))
display(normals[["MLY-PRCP-NORMAL", "MLY-TAVG-NORMAL"]].head(3))

for item in result.fetched:
    print(f"{item.asset.dataset_id}")
    print(f"Retrieved (UTC): {item.provenance.retrieved_at.isoformat()}")
    print(f"Bytes: {item.provenance.size}; cache hit: {item.from_cache}")
    print(f"Checksum: {item.provenance.checksum}")
    display(Markdown(f"[Source request](<{item.provenance.source_url}>)"))

aligned = normals.loc[observed.index.str.slice(5, 7)].set_axis(observed.index)
fahrenheit = aligned["MLY-TAVG-NORMAL"]
if not fahrenheit.str.startswith(" ").all():
    raise ValueError("MLY-TAVG-NORMAL lost its standard-unit marker; recheck units first")
tavg_normal = (fahrenheit.astype("float64") - 32) * 5 / 9
if (observed["TAVG"] - tavg_normal).abs().max() > 10:
    raise ValueError("converted MLY-TAVG-NORMAL is implausible against observed TAVG")
prcp_normal = aligned["MLY-PRCP-NORMAL"]
frame = pd.DataFrame(
    {
        "TAVG": observed["TAVG"],
        "TAVG normal": tavg_normal,
        "TAVG anomaly": observed["TAVG"] - tavg_normal,
        "PRCP": observed["PRCP"],
        "PRCP normal": prcp_normal,
        "PRCP anomaly": observed["PRCP"] - prcp_normal,
    }
).round(1)
assert frame.notna().all().all(), "every selected month needs an observation and a normal"
display(frame)

%matplotlib inline
import matplotlib.pyplot as plt

months = frame.index.str.slice(5, 7)
fig, axes = plt.subplots(2, 1, figsize=(7, 4.6), layout="constrained", sharex=True)
for ax, column, title, unit, (above, below) in zip(
    axes,
    ["TAVG anomaly", "PRCP anomaly"],
    ["Mean temperature minus normal", "Total precipitation minus normal"],
    ["°C", "mm"],
    [("#b45631", "#2563a6"), ("#2563a6", "#b45631")],
    strict=True,
):
    values = frame[column]
    ax.bar(
        months,
        values,
        width=0.6,
        color=[above if value >= 0 else below for value in values],
    )
    ax.axhline(0, color="#444444", linewidth=0.8)
    ax.set(title=title, ylabel=unit)
    ax.margins(y=0.25)
axes[-1].set_xlabel("2024 month")
fig.suptitle("Will Rogers World Airport · 2024 anomalies against 1991-2020 normals")
plt.show()

temperature_difference = observed["TAVG"] - tavg_normal
precipitation_difference = observed["PRCP"].sum() - prcp_normal.sum()
warmer_months = int((temperature_difference > 0).sum())
wetness = (
    "wetter"
    if precipitation_difference > 0
    else "drier"
    if precipitation_difference < 0
    else "equal to normal"
)
print(f"{warmer_months} of 12 months had a higher mean temperature than normal.")
print(f"2024 precipitation: {observed['PRCP'].sum():.1f} mm; normal: {prcp_normal.sum():.1f} mm.")
print(f"The year was {wetness}: {precipitation_difference:+.1f} mm relative to normal.")
print("Scope: Will Rogers World Airport, 2024, compared with 1991-2020 monthly normals.")

drift = verify(manifest)
assert not drift, drift
again = pull(manifest)
print(f"Verification passed: {not drift}")
print(f"Restored from lockfile: {again.from_lockfile}")
print(f"All assets came from cache: {all(value.from_cache for value in again.fetched)}")