One site: climate metadata and practical next steps#

Look up KGPV, JRC, ML21 and PVCZ context for a coordinate near Rengo, Chile. This is an illustrative coordinate, not a surveyed PV plant. The offline bundle keeps all native columns for nearby source rows, rather than only map labels.

Download the runnable site bundle and read the site lookup guide for full catalogue use, units, source access, tie handling and operational interpretation.

import json
from pathlib import Path

import matplotlib.pyplot as plt
import pandas as pd

from energy_analysis.climate_comparison.site import load_site_example, site_climate_profile

One call returns four schemes and their metadata#

The 50 km threshold is an explicit search limit, not a claim of scientific representativeness. The query never selects a farther complete row to hide missing data, and it reports ambiguous labels at equally nearest source points.

catalogues, manifest, model = load_site_example(Path("."))
latitude, longitude = manifest["site"]["latitude"], manifest["site"]["longitude"]
profile = site_climate_profile(
    latitude,
    longitude,
    catalogues=catalogues,
    source_metadata=manifest["sources"],
    jrc_model=model,
    radius_km=50,
)
rows = []
for scheme, result in profile["classifications"].items():
    rows.append(
        {
            "scheme": scheme,
            "status": result["status"],
            "code": result["code"],
            "distance_km": result["distance_km"],
            "period": result["source"]["period"],
            "resolution": result["source"]["resolution"],
        }
    )
print(pd.DataFrame(rows).to_string(index=False))
scheme  status  code  distance_km                                      period                       resolution
   JRC matched JRC09     3.910633                                   2005-2023                       0.1 degree
  KGPV matched    DH    16.696486 Mixed source climatologies; see publication                       0.5 degree
  ML21 matched  Mou1    16.696486 Mixed source climatologies; see publication                       0.5 degree
  PVCZ matched T6:H3     3.910633                                   2010-2018 0.25 degree; rounded coordinates

Inspect where the metadata comes from#

KGPV and ML21 share the same reference workbook here, so their source markers overlap. PVCZ can contain several records at the same rounded coordinates; the returned candidates preserve all such rows. No marker is moved to the site.

fig, ax = plt.subplots(figsize=(9, 6), layout="constrained")
ax.scatter(longitude, latitude, marker="*", s=220, c="#111827", label="Requested site", zorder=5)
colors = {"JRC": "#d97706", "KGPV": "#15803d", "ML21": "#2563eb", "PVCZ": "#9333ea"}
for index, (scheme, result) in enumerate(profile["classifications"].items()):
    for candidate in result["candidates"]:
        ax.scatter(
            candidate["lon"],
            candidate["lat"],
            s=70 + index * 25,
            facecolors="none",
            edgecolors=colors[scheme],
            linewidths=2,
        )
        ax.plot(
            [longitude, candidate["lon"]],
            [latitude, candidate["lat"]],
            color=colors[scheme],
            alpha=0.5,
            linewidth=0.8,
        )
    if result["candidates"]:
        candidate = result["candidates"][0]
        ax.annotate(
            f"{scheme}: {result['code']} ({result['distance_km']:.1f} km)",
            (candidate["lon"], candidate["lat"]),
            xytext=(10, 12 + index * 16),
            textcoords="offset points",
            color=colors[scheme],
            fontsize=9,
        )
ax.set(
    xlabel="Longitude (°)",
    ylabel="Latitude (°)",
    title=(
        "Rengo site and nearest source coordinates\n"
        "Point distances do not establish local representativeness"
    ),
)
ax.margins(0.4)
ax.grid(alpha=0.2)
ax.legend(loc="lower left")
plt.show()
Rengo site and nearest source coordinates Point distances do not establish local representativeness

Inspect the complete fields and provenance#

Each entry contains its label, all source-row fields, units, source URL/hash, period, native resolution and interpretation. The JRC entry also records the frozen model, centroid meaning and whether inputs exceed its training range. Missing numerical values serialize as JSON null, never invented zeros.

for scheme, result in profile["classifications"].items():
    print(f"\n{scheme}: {result['label']}")
    print("Source:", json.dumps(result["source"], ensure_ascii=False, indent=2))
    for candidate in result["candidates"]:
        details = [
            {"field": name, "value": value, "units": result["field_metadata"][name]["units"]}
            for name, value in candidate.items()
        ]
        print(pd.DataFrame(details).to_string(index=False))

# Save the complete record when running locally:
# Path("my_site_climate.json").write_text(json.dumps(profile, indent=2, allow_nan=False))
JRC: POA 2101 kWh/m²/year; module 46.1 °C
Source: {
  "url": "https://jeodpp.jrc.ec.europa.eu/ftp/jrc-opendata/PVGIS/climatic-zones-pv/means-global.csv",
  "sha256": "55aa6751bdf5e05351a65aad4271125caeac443b4d45287a129183249856f19a",
  "size_bytes": 211755040,
  "period": "2005-2023",
  "resolution": "0.1 degree",
  "licence": "European Commission reuse notice; attribution required",
  "source": "JRC PVGIS/ERA5 climate catalogue",
  "sample_support": {
    "latitude": -34.406,
    "longitude": -70.858,
    "radius_km": 75.0
  },
  "selection": "Every native row within 75 km of the declared Rengo coordinate; all columns retained",
  "original_rows": 1452132,
  "retained_rows": 172,
  "columns": [
    "lat",
    "lon",
    "tilt",
    "G",
    "Tamb",
    "Tmod",
    "Tw",
    "E",
    "eff",
    "suff"
  ],
  "sample_sha256": "707f92de6dc0a1bce8ee0b20d9adc70d45ae231b5b614ed2ee14d4149f33b0d8",
  "reference_ids": [
    "jrc_2025_climate_dataset",
    "medina_2026_pv_climates"
  ]
}
field       value                                  units
  lat  -34.400000                           degree north
  lon  -70.900000                            degree east
 tilt   31.000000            degree, source optimal tilt
    G 2255.724365            kWh/m²/year, plane-of-array
 Tamb   14.507441                     degC, ambient mean
 Tmod   22.030064                      degC, module mean
   Tw   41.953919       degC, irradiance-weighted module
    E 2128.277632  kWh/kWp/year, modelled specific yield
  eff    0.943501     source-native efficiency statistic
 suff    0.632285 source-native; see provider definition

KGPV: Temperate; merged high irradiation class
Source: {
  "url": "https://ars.els-cdn.com/content/image/1-s2.0-S0960148125013473-mmc1.xlsx",
  "sha256": "d8eb4c55df1e5e937f8460dada0fdb9f3b52dbc8cb79da14aa44319c1ab46891",
  "size_bytes": 10777807,
  "period": "Mixed source climatologies; see publication",
  "resolution": "0.5 degree",
  "licence": "Article CC BY; attributed supplementary-data extracts",
  "source": "ML21 publisher supplementary workbook",
  "sample_support": {
    "latitude": -34.406,
    "longitude": -70.858,
    "radius_km": 75.0
  },
  "selection": "Every native row within 75 km of the declared Rengo coordinate; all columns retained",
  "original_rows": 55418,
  "retained_rows": 8,
  "columns": [
    "lat",
    "lon",
    "Tann",
    "Tmax",
    "Tmin",
    "DTRann",
    "Pann",
    "Pmin",
    "RHann",
    "GHIann",
    "GHImax",
    "GHImin",
    "UVann",
    "WSann",
    "Yf",
    "ml21_zone",
    "KGPV",
    "kgpv_zone"
  ],
  "sample_sha256": "81941d33566c5cd7aeb4f4c8cb24b9fd10171edbab547e2b333ddd48c27064b1",
  "reference_ids": [
    "triana_2026_ml_climates"
  ]
}
    field             value                                  units
      lat             -34.5                           degree north
      lon             -71.0                            degree east
     Tann         13.023522                                   degC
     Tmax         19.492742                                   degC
     Tmin          7.037097                                   degC
   DTRann         11.312366                                   degC
     Pann        598.324834 source-native; see provider definition
     Pmin          1.913833 source-native; see provider definition
    RHann         68.274498 source-native; see provider definition
   GHIann  238071234.984443        J/m², native workbook statistic
   GHImax   31681346.063567        J/m², native workbook statistic
   GHImin    7846540.387097        J/m², native workbook statistic
    UVann   13789838.333302        J/m², native workbook statistic
    WSann          1.232025 source-native; see provider definition
       Yf          1825.495            kWh/kWp/year, source target
ml21_zone              Mou1 source-native; see provider definition
     KGPV                 5 source-native; see provider definition
kgpv_zone                DH source-native; see provider definition

ML21: Mountainous; published subtype 1
Source: {
  "url": "https://ars.els-cdn.com/content/image/1-s2.0-S0960148125013473-mmc1.xlsx",
  "sha256": "d8eb4c55df1e5e937f8460dada0fdb9f3b52dbc8cb79da14aa44319c1ab46891",
  "size_bytes": 10777807,
  "period": "Mixed source climatologies; see publication",
  "resolution": "0.5 degree",
  "licence": "Article CC BY; attributed supplementary-data extracts",
  "source": "ML21 publisher supplementary workbook",
  "sample_support": {
    "latitude": -34.406,
    "longitude": -70.858,
    "radius_km": 75.0
  },
  "selection": "Every native row within 75 km of the declared Rengo coordinate; all columns retained",
  "original_rows": 55418,
  "retained_rows": 8,
  "columns": [
    "lat",
    "lon",
    "Tann",
    "Tmax",
    "Tmin",
    "DTRann",
    "Pann",
    "Pmin",
    "RHann",
    "GHIann",
    "GHImax",
    "GHImin",
    "UVann",
    "WSann",
    "Yf",
    "ml21_zone",
    "KGPV",
    "kgpv_zone"
  ],
  "sample_sha256": "81941d33566c5cd7aeb4f4c8cb24b9fd10171edbab547e2b333ddd48c27064b1",
  "reference_ids": [
    "triana_2026_ml_climates"
  ]
}
    field             value                                  units
      lat             -34.5                           degree north
      lon             -71.0                            degree east
     Tann         13.023522                                   degC
     Tmax         19.492742                                   degC
     Tmin          7.037097                                   degC
   DTRann         11.312366                                   degC
     Pann        598.324834 source-native; see provider definition
     Pmin          1.913833 source-native; see provider definition
    RHann         68.274498 source-native; see provider definition
   GHIann  238071234.984443        J/m², native workbook statistic
   GHImax   31681346.063567        J/m², native workbook statistic
   GHImin    7846540.387097        J/m², native workbook statistic
    UVann   13789838.333302        J/m², native workbook statistic
    WSann          1.232025 source-native; see provider definition
       Yf          1825.495            kWh/kWp/year, source target
ml21_zone              Mou1 source-native; see provider definition
     KGPV                 5 source-native; see provider definition
kgpv_zone                DH source-native; see provider definition

PVCZ: Module stress 34-<39 °C; humidity 4.1-<5.9 g/kg
Source: {
  "url": "https://raw.githubusercontent.com/toddkarin/pvcz/aa89fab8d1d66f46f4ea8575e2452aa75a927535/pvcz/PVCZ-2019_ver0p2_world_PV_climate_stressors_and_zones.csv",
  "sha256": "14e7e06010620f8054b3ba7ee49256bc4d26c017c51da2d188d9753cff7d9801",
  "size_bytes": 48588578,
  "period": "2010-2018",
  "resolution": "0.25 degree; rounded coordinates",
  "licence": "MIT",
  "commit": "aa89fab8d1d66f46f4ea8575e2452aa75a927535",
  "source": "PVCZ author stressor catalogue",
  "sample_support": {
    "latitude": -34.406,
    "longitude": -70.858,
    "radius_km": 75.0
  },
  "selection": "Every native row within 75 km of the declared Rengo coordinate; all columns retained",
  "original_rows": 230742,
  "retained_rows": 28,
  "columns": [
    "lat",
    "lon",
    "T_ambient_mean",
    "T_ambient_min",
    "T_ambient_max",
    "T_equiv_rack_0p1eV",
    "T_equiv_rack_0p3eV",
    "T_equiv_rack_0p5eV",
    "T_equiv_rack_0p7eV",
    "T_equiv_rack_0p9eV",
    "T_equiv_rack_1p1eV",
    "T_equiv_rack_1p3eV",
    "T_equiv_rack_1p5eV",
    "T_equiv_rack_1p7eV",
    "T_equiv_rack_1p9eV",
    "T_equiv_rack_2p1eV",
    "T_equiv_roof_0p1eV",
    "T_equiv_roof_0p3eV",
    "T_equiv_roof_0p5eV",
    "T_equiv_roof_0p7eV",
    "T_equiv_roof_0p9eV",
    "T_equiv_roof_1p1eV",
    "T_equiv_roof_1p3eV",
    "T_equiv_roof_1p5eV",
    "T_equiv_roof_1p7eV",
    "T_equiv_roof_1p9eV",
    "T_equiv_roof_2p1eV",
    "T_velocity_rack",
    "T_velocity_roof",
    "specific_humidity_mean",
    "specific_humidity_rms",
    "GHI_mean",
    "wind_speed_rms",
    "wind_speed_max",
    "ASCE 7-16 MRI 25-Year",
    "KG_zone",
    "KG_class_0",
    "KG_class_1",
    "KG_class_2",
    "KG_class_02",
    "T_equiv_rack_1p1eV_zone",
    "T_equiv_roof_1p1eV_zone",
    "specific_humidity_mean_zone",
    "ASCE 7-16 MRI 25-Year_zone",
    "KG_numeric_zone",
    "pvcz",
    "pvcz_labeled",
    "wind_speed",
    "wind_speed_zone"
  ],
  "sample_sha256": "eb36404e5b452f5ad2245e7e5345c416d665c55ce489816309f3bab42cc370f8",
  "reference_ids": [
    "karin_2019_pvcz",
    "karin_pvcz_software"
  ]
}
                      field value                                                units
                        lat -34.4                                         degree north
                        lon -70.9                                          degree east
             T_ambient_mean  16.7                                                 degC
              T_ambient_min  -2.7                                                 degC
              T_ambient_max  37.4                                                 degC
         T_equiv_rack_0p1eV  22.9 degC, source-specific activation energy and mounting
         T_equiv_rack_0p3eV  25.7 degC, source-specific activation energy and mounting
         T_equiv_rack_0p5eV  28.6 degC, source-specific activation energy and mounting
         T_equiv_rack_0p7eV  31.5 degC, source-specific activation energy and mounting
         T_equiv_rack_0p9eV  34.0 degC, source-specific activation energy and mounting
         T_equiv_rack_1p1eV  36.2 degC, source-specific activation energy and mounting
         T_equiv_rack_1p3eV  38.1 degC, source-specific activation energy and mounting
         T_equiv_rack_1p5eV  39.6 degC, source-specific activation energy and mounting
         T_equiv_rack_1p7eV  41.0 degC, source-specific activation energy and mounting
         T_equiv_rack_1p9eV  42.1 degC, source-specific activation energy and mounting
         T_equiv_rack_2p1eV  43.1 degC, source-specific activation energy and mounting
         T_equiv_roof_0p1eV  28.5 degC, source-specific activation energy and mounting
         T_equiv_roof_0p3eV  34.4 degC, source-specific activation energy and mounting
         T_equiv_roof_0p5eV  40.4 degC, source-specific activation energy and mounting
         T_equiv_roof_0p7eV  45.6 degC, source-specific activation energy and mounting
         T_equiv_roof_0p9eV  49.8 degC, source-specific activation energy and mounting
         T_equiv_roof_1p1eV  53.0 degC, source-specific activation energy and mounting
         T_equiv_roof_1p3eV  55.7 degC, source-specific activation energy and mounting
         T_equiv_roof_1p5eV  57.8 degC, source-specific activation energy and mounting
         T_equiv_roof_1p7eV  59.6 degC, source-specific activation energy and mounting
         T_equiv_roof_1p9eV  61.1 degC, source-specific activation energy and mounting
         T_equiv_roof_2p1eV  62.5 degC, source-specific activation energy and mounting
            T_velocity_rack  2.54                                            degC/hour
            T_velocity_roof  3.83                                            degC/hour
     specific_humidity_mean  5.11                                                 g/kg
      specific_humidity_rms  2.26                                                 g/kg
                   GHI_mean  5.57                                           kWh/m²/day
             wind_speed_rms  2.29               source-native; see provider definition
             wind_speed_max  12.2               source-native; see provider definition
      ASCE 7-16 MRI 25-Year  -5.0               source-native; see provider definition
                    KG_zone   Csb               source-native; see provider definition
                 KG_class_0     C               source-native; see provider definition
                 KG_class_1     s               source-native; see provider definition
                 KG_class_2     b               source-native; see provider definition
                KG_class_02    Cb               source-native; see provider definition
    T_equiv_rack_1p1eV_zone     5               source-native; see provider definition
    T_equiv_roof_1p1eV_zone     8               source-native; see provider definition
specific_humidity_mean_zone     2               source-native; see provider definition
 ASCE 7-16 MRI 25-Year_zone     0               source-native; see provider definition
            KG_numeric_zone    17               source-native; see provider definition
                       pvcz    25               source-native; see provider definition
               pvcz_labeled T6:H3               source-native; see provider definition
                 wind_speed  -5.0             m/s, source 25-year recurrence statistic
            wind_speed_zone     0               source-native; see provider definition

What to do with these results#

  • KGPV: group sites into climate peers before a fleet performance comparison.

  • JRC: examine irradiation and module-temperature conditions, then use local weather and the real tilt/mounting for a yield or thermal-loss model.

  • ML21: stratify benchmarking by PV-climate family; keep technology, design and data-quality differences under control.

  • PVCZ: use thermal/humidity stress as input to a qualification or inspection plan, then confirm mechanisms with module and field evidence.

  • Degradation rate: supply module calibration and hourly temperature/RH/UV stresses to the separate degradation model. A class is not a %/year rate.

Inspect sources before acting. These products use different periods and model assumptions; their IDs have no cross-scheme numeric equivalence. If any entry is missing, outside the radius or ambiguous, resolve it with appropriate local data instead of widening the search just to obtain a label.

for scheme, result in profile["classifications"].items():
    print(f"{scheme}: {result['use']} {result['limitation']}")
for step in profile["next_steps"]:
    print("Next:", step)
JRC: Screen POA and module-temperature conditions; verify mounting and tilt before yield modelling. PVGIS optimal-tilt model inputs and refitted classes are not operating-plant measurements.
KGPV: Group sites into broad climate/irradiation peers before comparing performance. A broad class does not give hourly expected power or a measured loss rate.
ML21: Stratify performance benchmarks by published PV climate family; validate peers with local data. Published labels and a new ML21 refit have different identities; native feature conventions matter.
PVCZ: Screen thermal/humidity stress and plan module qualification or targeted inspection. Stress classes are not degradation %/year, failure diagnoses or warranted lifetimes.
Next: Check distance, native resolution, period and terrain before assigning a site class.
Next: Retrieve local hourly weather and measured PV data; compare sites with compatible design and data quality.
Next: For degradation %/year, use module calibration and temperature/RH/UV/cycles; do not convert a class ID to a rate.
Next: Validate modelled risk against observed performance loss and inspection evidence before operational decisions.

Query a different site#

The included files are a bounded Rengo subset, so arbitrary sites require full source catalogues. site_climate_profile accepts the existing JRC/ML21/PVCZ reader outputs; the guide shows the download/read calls and exact metadata. The same query with radius_km=0.1 shows an honest no-nearby-source result.

strict = site_climate_profile(
    latitude,
    longitude,
    catalogues=catalogues,
    source_metadata=manifest["sources"],
    jrc_model=model,
    radius_km=0.1,
)
print({name: entry["status"] for name, entry in strict["classifications"].items()})
{'JRC': 'outside_radius', 'KGPV': 'outside_radius', 'ML21': 'outside_radius', 'PVCZ': 'outside_radius'}

Total running time of the script: (0 minutes 0.191 seconds)

Gallery generated by Sphinx-Gallery