Source code for energy_data_retrieval.sources.pvcz.client

"""Read pinned PVCZ CSV data without loading upstream pickle files."""

from __future__ import annotations

from pathlib import Path

import pandas as pd

from energy_data_retrieval.sources._climate_catalogue import validate_catalogue
from energy_data_retrieval.transport import HTTPClient, RequestRecord

REFERENCE_IDS = ("karin_2019_pvcz", "karin_pvcz_software")
COMMIT = "aa89fab8d1d66f46f4ea8575e2452aa75a927535"
URL = (
    f"https://raw.githubusercontent.com/toddkarin/pvcz/{COMMIT}/pvcz/"
    "PVCZ-2019_ver0p2_world_PV_climate_stressors_and_zones.csv"
)


[docs] def download(http: HTTPClient, path: Path) -> RequestRecord: """Download the pinned public CSV with the shared transport's provenance.""" return http.download_file(URL, path)
[docs] def read_catalogue(path: Path) -> pd.DataFrame: """Keep original stress values and authoritative labels, including rounding. The author CSV rounds stresses. Reclassifying a rounded value exactly on a threshold can disagree with its original label; do not overwrite that label. Three-significant-digit coordinates can coincide for distinct native cells. Preserve these rows; coordinates are not unique IDs or exact grid centers. """ result = validate_catalogue( pd.read_csv(path), ("T_equiv_rack_1p1eV", "specific_humidity_mean", "pvcz"), rounded_locations=True, ) if "pvcz_labeled" not in result: raise ValueError("Missing published PVCZ labels") valid = {f"T{t}:H{h}": (h - 1) * 10 + t - 1 for h in range(1, 6) for t in range(1, 11)} mapped = result.pvcz_labeled.map(valid) if mapped.isna().any() or not mapped.eq(result.pvcz).all(): raise ValueError("Published PVCZ IDs and labels disagree") if ((result.specific_humidity_mean < 0) | (result.specific_humidity_mean > 1000)).any(): raise ValueError("Expected specific humidity in g/kg") return result