Comparing PV climate classifications#
The package adds three complementary methods alongside KGPV: JRC parametric performance climates, a seven-feature ML21 refit workflow, and PVCZ thermal and humidity stress zones. These schemes answer different questions. A PVCZ class is not an annual degradation rate, and agreement with a published map is not validation against measured PV performance.
Scheme |
Inputs and purpose |
Available implementation |
|---|---|---|
KGPV |
Monthly temperature/rainfall and annual GHI; broad PV climate |
Existing |
JRC parametric |
Annual plane-of-array irradiation and irradiance-weighted module temperature; performance climates |
|
ML21 |
Seven temperature, GHI and UV statistics, weighted by their fitted relationship to specific yield |
Original 21-class labels plus a separately identified |
PVCZ |
Arrhenius-equivalent module temperature at 1.1 eV and mean specific humidity in g/kg |
|
The thesis inspired the project’s initial climate work. JRC, ML21 and PVCZ are later additions with their own method and dataset sources. Cite the references for the schemes actually used; see the reference catalogue.
Published maps and new fits#
energy_methods.climate_zones supplies ClimateProvenance, ClimateZones and
ClimateClusterModel. Class ID zero and an empty code mean missing data. Positive
IDs are local to a scheme and model version: never join unrelated schemes on
numeric class ID. Results retain readable labels and the caller-declared source,
period, resolution and application status.
Cluster models serialize to ordinary versioned JSON, with feature order, scaling,
weights, centers, training bounds, parameters, software versions and attribution.
predict does not refit; it works in bounded batches and preserves missing rows.
Training-range flags identify feature extrapolation, not a calibrated confidence
probability. All training rows must be complete; prediction infinities fail.
import json
from pathlib import Path
from energy_methods.climate_zones import ClimateClusterModel
model = ClimateClusterModel.from_dict(
json.loads(Path("examples/analysis/climate_jrc_model.json").read_text())
)
zones = model.predict([[1800, 35], [2200, 42]])
print(zones.zone, zones.provenance.period)
JRC parametric climates#
The global reference inputs come from PVGIS/ERA5 for 2005–2023, at 0.1°
native spacing and optimal tilt. Source G is annual in-plane irradiation in
kWh/m²; it is not GHI. Tw is irradiance-weighted module temperature. E and
eff are modeled outputs, not observations of operating plants.
performance_features integrates G * duration / 1000 and computes
sum(G * T * duration) / sum(G * duration) over the last axis. Supply a complete
year; annualize the irradiation explicitly for a complete multiyear record.
Missing intervals propagate, and zero irradiation gives undefined weighted
temperature. The function cannot detect omitted timestamps.
fit_jrc_climate follows the documented global workflow: complete rows at 0.5°
nodes, population-standard-deviation scaling, cosine-latitude centroid weights,
10 clusters, seed 10, 100 random initializations and at most 20 Lloyd iterations.
The best run minimizes unweighted squared distance, as in the author notebook;
centers are ordered by [1, 1.5] in normalized feature space. Sklearn convergence
and empty-cluster handling are explicit adaptations. JRC01–JRC10 identify
this documented refit, not an exact reproduction of an author raster.
Distribution-based optimal-transport climates are outside this implementation.
ML21#
The publisher’s supplementary workbook supplies 55,418 locations, original
ML21 labels (Tro1–Tro4, Des1–Des3, Mou1–Mou3, Tem1–Tem5,
Col1–Col4, Pol1–Pol2), inherited KGPV labels and a specific-yield target.
The maps display these original labels. Their source climatologies differ; the
workbook is not represented as a common-period measured dataset.
A new fit uses the ordered features Tann, Tmax, Tmin, GHIann, GHImax, GHImin, UVann. It standardizes training features, fits ordinary least squares against
training yield, weights standardized distances by absolute coefficients, and
runs 21-cluster k-means. Normalizing all weights by their common maximum leaves
assignments unchanged. Refitted classes are named ML01–ML21, ordered by
mean irradiation statistic then temperature. They are not mapped onto the
published semantic labels or rounded published regression coefficients.
Preserve the source feature convention. The connector retains the workbook’s
radiation statistics in their native J/m² convention. It does not infer that
GHIann is a physical annual total or silently convert it to kWh/m²/year.
New fits require an explicit feature_convention; applications of a frozen model
must use the same units and aggregation. Temperatures are Celsius and target
yield is kWh/kWp/year. Numeric shape checks cannot establish semantic equivalence.
The included refit uses 44,818 training sites and 10,600 held-out sites selected
by fixed 5° geographic blocks. Both scaling and yield weights are fitted only
on training sites. The manifest records adjusted Rand agreement with published
labels and within-class yield dispersion. The original reference map was built
using its own training data, so this agreement is not independent field
validation. class_target_rmse computes dispersion around class means within
the evaluated sample, not predictive RMSE. A scientific ranking would also
require common input periods, identical sites, area weights, equal class counts,
and independent measured outcomes. The paper’s reported SSE improvement is not
a percentage improvement in forecasting accuracy.
PVCZ#
The pinned author CSV uses GLDAS 2010–2018, at 0.25° native spacing. The
reference thermal stress is based on an open-rack polymer-back module model.
equivalent_temperature implements the Arrhenius mean with duration weighting,
including night intervals; it uses a numerically stable log-sum-exp calculation.
For the published scheme use the default activation energy of 1.1 eV.
Temperature boundaries are 14, 19, 24, 29, 34, 39, 44, 49 and 54 °C; humidity
boundaries are 3, 4.1, 5.9 and 10.5 g/kg. Equality enters the warmer/wetter class.
Codes run from T1:H1 to T10:H5; positive package IDs equal upstream IDs + 1.
Humidity is not relative humidity. No percent/year degradation or lifetime is
inferred from these stress classes.
The source CSV rounds stresses and coordinates to limited precision. Distinct native cells can share a reported coordinate. The reader preserves these rows; coordinates are not unique identifiers. Rounded stresses at a threshold can recompute to a different class, so reference maps retain original author labels. Neither exact 0.25° centers nor fine local boundaries are reconstructed.
from energy_methods.climate_zones import ClimateProvenance
from energy_methods.pvcz import classify_pvcz, equivalent_temperature
teq = equivalent_temperature([[20, 35, 50, 25]], duration_hours=6)
result = classify_pvcz(
teq,
[6.0],
provenance=ClimateProvenance(
"Illustrative complete daily cycle", "synthetic day", "one site", "demonstration"
),
)
print(result.zone)
Offline maps and coverage#
The gallery compares all four schemes for the world, contiguous mainland Chile, and the Canary Islands. Source CSV subsets, frozen models, hashes and map scripts are downloadable together. Global display samples retain one actual point near each 2° bin center; there is no averaging of labels or ocean gap filling. The Chile JRC display samples use 0.2° bins, and country plots select centers within the existing mainland contour. CSV regional bounds can include neighboring countries; only the plotted subset is mainland Chile. Display marker size is not climate resolution. Each map has its own legend.
The Canary examples contain 45 JRC points, two ML21/KGPV reference points and no PVCZ observations. Empty coverage is shown explicitly. Outlines reuse the existing Canary climate-raster footprints, not surveyed coastlines. For the separate detailed KGPV applications see Canary Islands and mainland Chile; those maps use different source periods and must not be passed off as higher-resolution versions of these reference tables.
Retrieval and regeneration#
The three energy_data_retrieval.sources readers (jrc_climate, ml21, pvcz)
use the shared bounded HTTP transport when explicitly asked to download. JRC
is about 212 MB, ML21’s XLSX about 11 MB, and PVCZ about 49 MB. Downloads record
hashes. The PVCZ object is pinned to commit
aa89fab8d1d66f46f4ea8575e2452aa75a927535; no untrusted pickle is loaded.
The XLSX reader bounds the declared expanded archive size at 300 MB.
From the repository root, with the normal workspace installed:
uv run python -m energy_analysis.climate_comparison.prepare \
--raw-directory .local/pv-climate-sources \
--output-directory examples/analysis \
--world-boundaries examples/connectors/data/generation_coverage_world.geojson \
--download
cd examples/analysis
uv run python plot_climate_world.py
uv run python plot_climate_chile.py
uv run python plot_climate_canary.py
Omit --download to reuse raw sources named jrc_means_global.csv,
ml21_supplement.xlsx, and pvcz.csv. Full datasets stay outside version control;
small attributed CSV samples and numerical JSON state are committed. Keep the
existing Chile contour and Canary TIFF context files beside regional examples.
A fresh preparation records new source bytes and model versions; compare the
manifest to the reviewed one before treating it as the same study. Gallery and
CI execution are offline and do not refit or contact providers.
Sources and reuse#
Medina, Martínez and Dunlop, Parametric and distribution-based definition of climatic zones for photovoltaics, Solar Energy 306 (2026), 114295. Paper, JRC dataset, author workflow. Independent implementation; no author notebook code is vendored.
Francisco Javier Triana de las Heras, Olindo Isabella and Malte Ruben Vogt, A machine learning approach to PV-climate classification, Renewable Energy 256 (2026), 123685. Paper, supplement. Article licensed CC BY; extracts retain author/source attribution.
Todd Karin, C. Birk Jones and Anubhav Jain, Photovoltaic Degradation Climate Zones, IEEE PVSC (2019). Author repository and paper. CSV redistribution retains its MIT notice in
examples/analysis/climate_PVCZ_LICENSE.txt.European Commission JRC source reuse requires attribution; see its legal notice. Natural Earth outlines are public domain. Canary footprint attribution remains in the existing Canary source guide.