pyepwmorph 3.1.0__tar.gz → 3.2.0__tar.gz

{pyepwmorph-3.1.0 → pyepwmorph-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyepwmorph
-Version: 3.1.0
+Version: 3.2.0
 Summary: A python package to enable simple and easy gathering of climate model data and morphing of EPW files
 Project-URL: Homepage, https://github.com/justinfmccarty/pyepwmorph
 Project-URL: Issues, https://github.com/justinfmccarty/pyepwmorph/issues
@@ -148,7 +148,7 @@ morphed = results["gwl2.0"]["50"]
 
 The site is matched to the nearest station that has the requested variables (or, with `ch2025_full_coverage=True`, the nearest station that has every CH2025 variable), with an elevation penalty so a much higher station is not chosen just because it is close on the map. Supported variables are temperature, humidity, dew point, wind, and radiation (global, diffuse, and direct). Pressure and cloud cover are not in CH2025; requesting them raises an error. Sky cover is left at the EPW's baseline values when radiation is morphed, so longwave sky temperature in EnergyPlus does not follow the shortwave change.
 
-The signal is the change from the 1991-2020 reference climate to the chosen warming level. Each model chain's change is computed first, over the chains that reach that warming level, and the percentiles are taken of those changes. If the EPW's years fall outside 1991-2020, a `UserWarning` recommends a TMY built from 1991-2020 data and the signal is still applied to the file as it stands. The same caveats are listed in `MorphConfig.ch2025_notes` and the matched station in `MorphConfig.ch2025_station`.
+The signal is the change from the 1991-2020 reference climate to the chosen warming level. Each model chain's change is computed first, over the chains that reach that warming level, and the percentiles are taken of those changes. The EPW's period is read from the `Period of Record` in its header. If that is not exactly 1991-2020, a `UserWarning` recommends a TMY built from 1991-2020 data. If the header states no period, a second warning says the period could not be detected, and the mismatch warning still fires if the data rows' years fall outside 1991-2020. The signal is applied to the file as it stands either way. `tools.io.write_period_of_record` adds the statement to files built without one. The same caveats are listed in `MorphConfig.ch2025_notes` and the matched station in `MorphConfig.ch2025_station`.
 
 CH2025 data: MeteoSwiss & ETH Zurich (2025), Climate CH2025 - Daily Datasets, CC-BY 4.0, https://doi.org/10.18751/climate/scenarios/ch2025/data/1.0/
 

{pyepwmorph-3.1.0 → pyepwmorph-3.2.0}/README.md

@@ -109,7 +109,7 @@ morphed = results["gwl2.0"]["50"]
 
 The site is matched to the nearest station that has the requested variables (or, with `ch2025_full_coverage=True`, the nearest station that has every CH2025 variable), with an elevation penalty so a much higher station is not chosen just because it is close on the map. Supported variables are temperature, humidity, dew point, wind, and radiation (global, diffuse, and direct). Pressure and cloud cover are not in CH2025; requesting them raises an error. Sky cover is left at the EPW's baseline values when radiation is morphed, so longwave sky temperature in EnergyPlus does not follow the shortwave change.
 
-The signal is the change from the 1991-2020 reference climate to the chosen warming level. Each model chain's change is computed first, over the chains that reach that warming level, and the percentiles are taken of those changes. If the EPW's years fall outside 1991-2020, a `UserWarning` recommends a TMY built from 1991-2020 data and the signal is still applied to the file as it stands. The same caveats are listed in `MorphConfig.ch2025_notes` and the matched station in `MorphConfig.ch2025_station`.
+The signal is the change from the 1991-2020 reference climate to the chosen warming level. Each model chain's change is computed first, over the chains that reach that warming level, and the percentiles are taken of those changes. The EPW's period is read from the `Period of Record` in its header. If that is not exactly 1991-2020, a `UserWarning` recommends a TMY built from 1991-2020 data. If the header states no period, a second warning says the period could not be detected, and the mismatch warning still fires if the data rows' years fall outside 1991-2020. The signal is applied to the file as it stands either way. `tools.io.write_period_of_record` adds the statement to files built without one. The same caveats are listed in `MorphConfig.ch2025_notes` and the matched station in `MorphConfig.ch2025_station`.
 
 CH2025 data: MeteoSwiss & ETH Zurich (2025), Climate CH2025 - Daily Datasets, CC-BY 4.0, https://doi.org/10.18751/climate/scenarios/ch2025/data/1.0/
 

{pyepwmorph-3.1.0 → pyepwmorph-3.2.0}/pyepwmorph/models/ch2025.py

@@ -93,10 +93,8 @@ def reference_key(state: str) -> str:
 
 
 def baseline_matches(baseline_range) -> bool:
-    """Return whether an EPW baseline lies inside the CH2025 reference period."""
-    start, end = (int(year) for year in baseline_range)
-    ref_start, ref_end = CH2025_BASELINE_RANGE
-    return ref_start <= start and end <= ref_end
+    """Return whether an EPW baseline is exactly the CH2025 reference period."""
+    return tuple(int(year) for year in baseline_range) == CH2025_BASELINE_RANGE
 
 
 def in_switzerland(latitude: float, longitude: float) -> bool:

{pyepwmorph-3.1.0 → pyepwmorph-3.2.0}/pyepwmorph/morph/procedures.py

@@ -7,6 +7,8 @@ Container for all of the individual morphing calculations which can be traced ba
         55 514–524 ISSN 0960-1481 URL https://www.sciencedirect.com/science/article/pii/S0960148113000232
 
 """
+import calendar
+
 import numpy as np
 import pandas as pd
 
@@ -33,10 +35,17 @@ def _index_of(*candidates):
 
 
 def _year_of(index):
-    """Return the year of a DatetimeIndex, or the default solar year."""
+    """Return a non-leap year to build solar geometry for the data in *index*.
+
+    EPW files always hold 8760 hours with no 29 February, so their calendar
+    is a non-leap year's even when the first data row says 2016. Building
+    daily series for a leap year would add an empty 29 February and shift
+    every later day by one, so a leap year is replaced by the year before.
+    """
     if index is None or len(index) == 0:
         return morph_solar_utils.DEFAULT_SOLAR_YEAR
-    return int(index[0].year)
+    year = int(index[0].year)
+    return year - 1 if calendar.isleap(year) else year
 
 
 def _as_series(values, index, name, decimals=2):

{pyepwmorph-3.1.0 → pyepwmorph-3.2.0}/pyepwmorph/tools/configuration.py

@@ -70,6 +70,46 @@ MORPH_ORDER = [
 ]
 
 
+def _ch2025_baseline_notes(baseline_range, source, reference_range, matches):
+    """Plain-language caveats about how the EPW's period compares with 1991-2020.
+
+    A stated period (header or caller) must equal the reference exactly. When
+    only the data rows are available, the period cannot be confirmed, which
+    is its own caveat; years outside the reference are also a mismatch.
+    """
+    start, end = (int(year) for year in baseline_range)
+    ref_start, ref_end = reference_range
+    notes = []
+
+    if source == "data":
+        notes.append(
+            f"The period this weather file was built from is not stated in its header, "
+            f"so it cannot be checked against the CH2025 reference period "
+            f"({ref_start}-{ref_end}). Its months come from {start}-{end}. Check the "
+            f"source of the file to confirm the period it represents."
+        )
+        mismatched = not (ref_start <= start and end <= ref_end)
+        described = f"The weather file's months come from {start}-{end}"
+    else:
+        mismatched = not matches((start, end))
+        described = f"The weather file was built from {start}-{end}"
+
+    if mismatched:
+        midpoint = (start + end) / 2.0
+        ref_midpoint = (ref_start + ref_end) / 2.0
+        if midpoint > ref_midpoint:
+            effect = "It is centred later and already holds part of that warming, so the morphed file may overstate it."
+        elif midpoint < ref_midpoint:
+            effect = "It is centred earlier, so the morphed file may understate the warming."
+        else:
+            effect = "It spans different years, so the change may not fit it exactly."
+        notes.append(
+            f"{described}, but CH2025 changes are measured from {ref_start}-{ref_end}. "
+            f"{effect} For CH2025, use a TMY built from {ref_start}-{ref_end} data."
+        )
+    return notes
+
+
 def _dependencies_for(data_source):
     if data_source == "ch2025":
         return CH2025_VARIABLE_DEPENDENCIES
@@ -170,7 +210,12 @@ class MorphConfig:
         ``elevation_difference_m`` and ``weak_match``.
     ch2025_notes : list[str]
         CH2025 only. Plain-language caveats about this morph (baseline
-        mismatch, weak station match), for display to users.
+        mismatch, undetectable baseline, weak station match), for display
+        to users.
+    baseline_source : str
+        Where ``baseline_range`` came from: ``"user"`` (passed in),
+        ``"comments"`` (the EPW's Period of Record) or ``"data"`` (the span
+        of years in the data rows).
 
     Backward Compatibility
     ----------------------
@@ -272,7 +317,9 @@ class MorphConfig:
         self.location['elevation'] = self.epw.location['elevation']
         self.location['utc_offset'] = self.epw.location['utc_offset']
         if self.baseline_range is None:
-            self.baseline_range = self.epw.detect_baseline_range()
+            self.baseline_range, self.baseline_source = self.epw.detect_baseline_period()
+        else:
+            self.baseline_source = "user"
 
         if self.data_source == "ch2025":
             from pyepwmorph.models.ch2025 import (
@@ -291,24 +338,10 @@ class MorphConfig:
                     f"CH2025 covers longitude {west} to {east} and latitude {south} to {north}. "
                     f"Use data_source='cmip6' for locations outside that domain."
                 )
-            if not baseline_matches(self.baseline_range):
-                start, end = (int(year) for year in self.baseline_range)
-                ref_start, ref_end = CH2025_BASELINE_RANGE
-                if end > ref_end:
-                    effect = (
-                        f"Years after {ref_end} already contain part of that warming, "
-                        f"so the morphed file may overstate it."
-                    )
-                else:
-                    effect = (
-                        f"Years before {ref_start} were cooler, so the morphed file may "
-                        f"understate the warming."
-                    )
-                note = (
-                    f"The EPW covers {start}-{end} but CH2025 changes are measured from "
-                    f"{ref_start}-{ref_end}. {effect} For CH2025, use a TMY built from "
-                    f"{ref_start}-{ref_end} data."
-                )
+            for note in _ch2025_baseline_notes(
+                self.baseline_range, self.baseline_source,
+                CH2025_BASELINE_RANGE, baseline_matches,
+            ):
                 self.ch2025_notes.append(note)
                 warnings.warn(note, UserWarning, stacklevel=2)
 

{pyepwmorph-3.1.0 → pyepwmorph-3.2.0}/pyepwmorph/tools/io.py

@@ -109,6 +109,62 @@ def epw_baseline_range(file_content: list[str]) -> tuple[int, int]:
     return (int(years.min()), int(years.max()))
 
 
+#: Matches a "Period of Record" statement, as ClimateOneBuilding writes it.
+_PERIOD_OF_RECORD_RE = re.compile(r"\s*;?\s*Period of Record\s*=?\s*\d{4}\s*-\s*\d{4}")
+
+
+def epw_data_years(file_content: list[str]) -> list[int]:
+    """Return the distinct years in an EPW's data rows, sorted.
+
+    A typical year stitches months from different years, so these are the
+    years the months were taken from, not the period the file was built
+    from. Use ``epw_baseline_range`` when the header states that period.
+    """
+    header_len = _find_header_length(file_content)
+    years = set()
+    for line in file_content[header_len:]:
+        field = line.split(",", 1)[0].strip()
+        if field.isdigit():
+            years.add(int(field))
+    if not years:
+        raise ValueError("No data rows found in EPW file")
+    return sorted(years)
+
+
+def write_period_of_record(filepath: str, start_year: int, end_year: int) -> None:
+    """Record the years an EPW was built from in its COMMENTS 1 header.
+
+    Writes ``Period of Record=start-end`` in the form ClimateOneBuilding uses,
+    which ``epw_baseline_range`` reads back. Any existing statement is
+    replaced. The data rows are not touched. If the file has no COMMENTS 1
+    line, one is inserted before COMMENTS 2 or DATA PERIODS.
+    """
+    lines = read_epw_string(filepath)
+    header_len = _find_header_length(lines)
+    statement = f"Period of Record={int(start_year)}-{int(end_year)}"
+
+    for i, line in enumerate(lines[:header_len]):
+        if not line.startswith("COMMENTS 1"):
+            continue
+        value = line.rstrip("\r\n")[len("COMMENTS 1"):].lstrip(",")
+        quoted = len(value) >= 2 and value.startswith('"') and value.endswith('"')
+        inner = value[1:-1] if quoted else value
+        inner = _PERIOD_OF_RECORD_RE.sub("", inner).strip().rstrip(";").strip()
+        inner = f"{inner}; {statement}" if inner else statement
+        lines[i] = f'COMMENTS 1,"{inner}"\n' if quoted else f"COMMENTS 1,{inner}\n"
+        break
+    else:
+        position = next(
+            (i for i, line in enumerate(lines[:header_len])
+             if line.startswith(("COMMENTS 2", "DATA PERIODS"))),
+            header_len,
+        )
+        lines.insert(position, f"COMMENTS 1,{statement}\n")
+
+    with open(filepath, "w", encoding="utf-8") as fh:
+        fh.writelines(lines)
+
+
 def read_epw_dataframe(filepath: str, normalize_hours: bool = True) -> pd.DataFrame:
     """Read an EPW file into a pandas DataFrame with an 8760-hour index.
 
@@ -247,10 +303,24 @@ class Epw:
         with open(filepath, "w", encoding="utf-8") as fh:
             fh.write(self.make_epw_string())
 
-    def detect_baseline_range(self) -> tuple[int, int]:
-        """Detect the baseline year range from EPW comments or data."""
+    def detect_baseline_period(self) -> tuple[tuple[int, int], str]:
+        """Detect the baseline years and say where they came from.
+
+        Returns
+        -------
+        tuple
+            ``((start, end), source)``. *source* is ``"comments"`` when the
+            header states a Period of Record, which is the period the file
+            was built from. Otherwise it is ``"data"`` and the range spans
+            the years in the data rows, which for a typical year are only
+            the years its months were taken from.
+        """
         try:
-            return epw_baseline_range(self.string)
+            return epw_baseline_range(self.string), "comments"
         except (ValueError, IndexError):
-            years = self.dataframe['year'].to_numpy()
-            return (int(years.min()), int(years.max()))
+            years = epw_data_years(self.string)
+            return (years[0], years[-1]), "data"
+
+    def detect_baseline_range(self) -> tuple[int, int]:
+        """Detect the baseline year range from EPW comments or data rows."""
+        return self.detect_baseline_period()[0]

{pyepwmorph-3.1.0 → pyepwmorph-3.2.0}/pyproject.toml

@@ -17,7 +17,7 @@ core-metadata-version = "2.4"
 
 [project]
 name = "pyepwmorph"
-version = "3.1.0"
+version = "3.2.0"
 authors = [
   { name="Justin McCarty", email="mccarty.justin.f@gmail.com" },
 ]