From d94514214bca5fa063d1c97db632026bde21e731 Mon Sep 17 00:00:00 2001 From: Christoph Deil Date: Fri, 9 Oct 2026 15:55:15 +0200 Subject: [PATCH 1/2] Document the index convention of read_epw read_epw labels each EPW record with the start of its hour (EPW hour 1 becomes 00:00), while read_tmy3 labels each record with the end of its hour, so the same data read from an EPW and a TMY3 file are one hour apart. Say so in a warning, as read_tmy3 does, and show how to label the records with the time given in the EPW file. See #1156. Co-Authored-By: Claude Opus 5.5 --- docs/sphinx/source/whatsnew/v0.16.2.rst | 4 ++++ pvlib/iotools/epw.py | 11 +++++++++++ 2 files changed, 15 insertions(+) diff --git a/docs/sphinx/source/whatsnew/v0.16.2.rst b/docs/sphinx/source/whatsnew/v0.16.2.rst index f0b52494dc..a3fc8602f1 100644 --- a/docs/sphinx/source/whatsnew/v0.16.2.rst +++ b/docs/sphinx/source/whatsnew/v0.16.2.rst @@ -31,6 +31,9 @@ Documentation * Fix the :py:func:`pvlib.spa.solar_position` docstring, which listed outputs ``elevation`` and ``apparent_elevation`` in the wrong order. (:issue:`2886`, :pull:`2887`) +* Document in :py:func:`pvlib.iotools.read_epw` that each record is labelled + with the start of its hour, unlike :py:func:`pvlib.iotools.read_tmy3`, and + how to label it with the time given in the EPW file. (:issue:`1156`) Testing @@ -56,6 +59,7 @@ Contributors * Chen Yi (:ghuser:`chenyi6758-source`) * Rajiv Daxini (:ghuser:`rdaxini`) * jason-writer (:ghuser:`jason-writer`) +* Christoph Deil (:ghuser:`cdeil`) diff --git a/pvlib/iotools/epw.py b/pvlib/iotools/epw.py index 01c87c180a..c3dd848676 100644 --- a/pvlib/iotools/epw.py +++ b/pvlib/iotools/epw.py @@ -208,6 +208,17 @@ def read_epw(filename, coerce_year=None): | | liquid precipitation depth field, hour | +-------------------------------+-----------------------------------------+ + .. warning:: EPW irradiance and illuminance values are totals over the + hour *ending* at the time in the file, while temperatures, humidity + and pressure are values *at* that time [1]_. ``read_epw`` labels + each record with the *start* of its hour: EPW hour 1 (00:00-01:00) + becomes 00:00, so a full year runs from 00:00 on 1 January to 23:00 + on 31 December. :py:func:`~pvlib.iotools.read_tmy3` labels each record + with the *end* of its hour instead, so the same data read from an EPW + file and from a TMY3 file are one hour apart. To label the records + with the time given in the EPW file, add one hour to the index: + ``data.index = data.index + pd.Timedelta('1h')``. + References ---------- From b9a077493027bbb44fcb5d16aea56b9331c16c42 Mon Sep 17 00:00:00 2001 From: Christoph Deil Date: Fri, 9 Oct 2026 16:08:20 +0200 Subject: [PATCH 2/2] Add the pull request number to the what's new entry Co-Authored-By: Claude Opus 5.5 --- docs/sphinx/source/whatsnew/v0.16.2.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/sphinx/source/whatsnew/v0.16.2.rst b/docs/sphinx/source/whatsnew/v0.16.2.rst index a3fc8602f1..4f0ef42d1c 100644 --- a/docs/sphinx/source/whatsnew/v0.16.2.rst +++ b/docs/sphinx/source/whatsnew/v0.16.2.rst @@ -33,7 +33,8 @@ Documentation (:issue:`2886`, :pull:`2887`) * Document in :py:func:`pvlib.iotools.read_epw` that each record is labelled with the start of its hour, unlike :py:func:`pvlib.iotools.read_tmy3`, and - how to label it with the time given in the EPW file. (:issue:`1156`) + how to label it with the time given in the EPW file. (:issue:`1156`, + :pull:`2894`) Testing