pyepwmorph 2.2.0__tar.gz → 3.0.0__tar.gz

{pyepwmorph-2.2.0 → pyepwmorph-3.0.0}/PKG-INFO

@@ -1,12 +1,14 @@
 Metadata-Version: 2.4
 Name: pyepwmorph
-Version: 2.2.0
+Version: 3.0.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
+Project-URL: Changelog, https://github.com/justinfmccarty/pyepwmorph/blob/main/CHANGELOG.md
 Author-email: Justin McCarty <mccarty.justin.f@gmail.com>
 License: MIT
 License-File: LICENSE
+Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
@@ -14,21 +16,17 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
 Requires-Python: >=3.9
 Requires-Dist: dask>=2023.5.0
-Requires-Dist: distributed>=2023.5.0
 Requires-Dist: gcsfs>=2023.5.0
 Requires-Dist: intake-esm>=2023.6.0
 Requires-Dist: intake>=0.6.0
-Requires-Dist: ipython>=7.0
-Requires-Dist: lz4>=4.0.0
-Requires-Dist: meteocalc>=1.1.0
-Requires-Dist: numpy>=1.20.0
-Requires-Dist: pandas>=1.3.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.2
 Requires-Dist: pvlib<1.0.0,>=0.13.0
 Requires-Dist: pyarrow>=13.0.0
-Requires-Dist: skyfield>=1.40
-Requires-Dist: timezonefinder>=6.0.0
 Requires-Dist: xarray>=2022.3.0
 Provides-Extra: dev
 Requires-Dist: build>=0.10; extra == 'dev'
@@ -43,7 +41,7 @@ Description-Content-Type: text/markdown
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
-[![Version](https://img.shields.io/badge/version-2.0.0-green.svg)](https://github.com/justinfmccarty/pyepwmorph)
+[![PyPI](https://img.shields.io/pypi/v/pyepwmorph.svg)](https://pypi.org/project/pyepwmorph/)
 
 A Python package for morphing EnergyPlus Weather (EPW) files with climate model data. Supports CMIP6 projections from Google Cloud and custom CSV-based model data for both future and historical scenarios.
 
@@ -128,19 +126,21 @@ results = workflow.morphing_workflow(
 
 Custom CSVs should have a `date` column (parseable by pandas) and a column named after the CMIP6 variable (e.g. `tas`, `tasmax`). Rows should be monthly.
 
+The reference and target scenarios must cover **different years**, the same way the CMIP6 `historical` and `sspXXX` experiments do. The two series are concatenated before the baseline and target periods are sliced out, so overlapping years get averaged together and weaken the climate signal. Keep `baseline_range` inside the years the reference scenario covers.
+
 ## Climate scenarios
 
-| Scenario | SSP | Description | Expected warming |
-|----------|-----|-------------|------------------|
-| Best Case Scenario | ssp126 | Strong mitigation, renewable transition | ~1.8 C by 2100 |
-| Middle of the Road | ssp245 | Moderate mitigation efforts | ~2.7 C by 2100 |
-| Upper Middle Scenario | ssp370 | Regional rivalry, slow convergence | ~3.6 C by 2100 |
-| Worst Case Scenario | ssp585 | Fossil-fueled development | ~4.4 C by 2100 |
+| Scenario              | SSP    | Description                             | Expected warming |
+| --------------------- | ------ | --------------------------------------- | ---------------- |
+| Best Case Scenario    | ssp126 | Strong mitigation, renewable transition | ~1.8 C by 2100   |
+| Middle of the Road    | ssp245 | Moderate mitigation efforts             | ~2.7 C by 2100   |
+| Upper Middle Scenario | ssp370 | Regional rivalry, slow convergence      | ~3.6 C by 2100   |
+| Worst Case Scenario   | ssp585 | Fossil-fueled development               | ~4.4 C by 2100   |
 
 ## Morphing variables
 
 - **Temperature** -- dry bulb temperature (shift + stretch)
-- **Humidity** -- relative humidity via specific humidity (stretch)
+- **Humidity** -- relative humidity, stretched in specific humidity space
 - **Pressure** -- atmospheric pressure (shift)
 - **Wind** -- wind speed (stretch)
 - **Clouds and Radiation** -- global/diffuse/direct radiation and sky cover
@@ -148,14 +148,16 @@ Custom CSVs should have a `date` column (parseable by pandas) and a column named
 
 ### Variable dependencies
 
-Some variables are automatically added when needed:
+Some variables cannot be morphed on their own:
 
 - **Humidity** requires Temperature and Pressure
 - **Dew Point** requires Temperature, Humidity, and Pressure
 
+Dependencies are added automatically and are **written to the output file**. Asking for `Dew Point` alone therefore returns an EPW with morphed pressure, temperature, relative humidity, and dew point, which keeps the file internally consistent. `MorphConfig.resolved_variables` shows exactly what will be written, in the order it is computed.
+
 ## Caching
 
-Climate model data is cached locally after the first download to speed up repeated analyses.
+Climate model data is cached locally after the first download, and the cache is consulted before the remote catalogue is opened so a hit costs no network traffic.
 
 ```python
 import pyepwmorph.models.access as access
@@ -164,6 +166,13 @@ stats = access.get_cmip6_cache_stats()
 access.clear_cmip6_cache()
 ```
 
+Cache entries live in the per-user cache directory (`~/Library/Caches/pyepwmorph` on macOS, `~/.cache/pyepwmorph` on Linux, `%LOCALAPPDATA%\pyepwmorph` on Windows) and are keyed by location, pathway, variable, model sources, and time slices. Two environment variables override the defaults:
+
+| Variable                  | Purpose                        | Default |
+| ------------------------- | ------------------------------ | ------- |
+| `PYEPWMORPH_CACHE_DIR`    | Where cache files are written  | per-user cache directory |
+| `PYEPWMORPH_CACHE_MAX_MB` | Size cap before old files go   | 500 |
+
 ## Available climate models
 
 ```python
@@ -179,51 +188,39 @@ git clone https://github.com/justinfmccarty/pyepwmorph.git
 cd pyepwmorph
 uv sync --extra dev
 
-# Run tests
-pytest
+# Run tests (fully offline)
+uv run pytest
 
 # Run with coverage
-pytest --cov=pyepwmorph
+uv run pytest --cov=pyepwmorph
+
+# Lint
+uv run ruff check pyepwmorph tests gui
 ```
 
 ### Releases
+
 ```bash
 ./release.sh [patch|minor|major]
 ```
 
-Copy-paste (change version number) for release statement
-```bash
-gh release create v2.2.0 \
-  --title "v2.2.0" \
-  --notes "## What's new
+The script refuses to run on a dirty tree, off `main`, with failing lint or tests, or without a matching `CHANGELOG.md` section. It bumps the version, tags, and pushes; creating the GitHub Release then triggers the PyPI publish workflow.
 
-See README for full breaking changes list."
+```bash
+gh release create v3.0.0 \
+  --title "v3.0.0" \
+  --notes "See CHANGELOG.md."
 ```
 
+## Changes
 
-
-## Breaking changes in v2.0.0
-
-- **License changed** from GPL-3.0 to MIT.
-- **`future_years`** parameter renamed to **`target_years`** across the API.
-  The old name is still accepted with a deprecation warning.
-- **`MorphConfig`** accepts new parameters: `data_source`, `custom_data`,
-  `reference_scenario`, and `target_years`.
-- **EPW I/O** (`pyepwmorph.tools.io`) rewritten with stricter validation.
-  Files that are not exactly 8760 data rows will now raise `ValueError`.
-  The lat/lon parsing bug in the standalone `epw_location()` function has
-  been fixed.
-- **`coordinate_cmip6_data`** now accepts an optional `time_slices` dict
-  for custom temporal bounds instead of hardcoded 1960-2014 / 2015-2100.
-- **Removed** `requirements.txt`, `environment.yml`, `.bumpversion.cfg`.
-  Use `uv sync` or `pip install .` instead.
-- **Per-module `__version__`** strings removed. Use
-  `pyepwmorph.__version__` or `importlib.metadata.version("pyepwmorph")`.
+See [CHANGELOG.md](CHANGELOG.md) for the full history. The most recent release corrects several morphing calculations, so morphed humidity, dew point, wind speed, cloud cover, and direct/diffuse radiation all differ from files produced by earlier versions.
 
 ## Requirements
 
 - Python >= 3.9
-- Internet connection (for CMIP6 data download)
+- pandas >= 2.2
+- Internet connection (for CMIP6 data download; the custom CSV workflow runs offline)
 
 ## License
 
@@ -233,6 +230,6 @@ MIT License. See [LICENSE](LICENSE).
 
 ```text
 McCarty, J. (2026). pyepwmorph: A Python package for climate-informed
-EPW file morphing. Version 2.0.0.
+EPW file morphing. Version 3.0.0.
 https://github.com/justinfmccarty/pyepwmorph
 ```

{pyepwmorph-2.2.0 → pyepwmorph-3.0.0}/README.md

@@ -2,7 +2,7 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
-[![Version](https://img.shields.io/badge/version-2.0.0-green.svg)](https://github.com/justinfmccarty/pyepwmorph)
+[![PyPI](https://img.shields.io/pypi/v/pyepwmorph.svg)](https://pypi.org/project/pyepwmorph/)
 
 A Python package for morphing EnergyPlus Weather (EPW) files with climate model data. Supports CMIP6 projections from Google Cloud and custom CSV-based model data for both future and historical scenarios.
 
@@ -87,19 +87,21 @@ results = workflow.morphing_workflow(
 
 Custom CSVs should have a `date` column (parseable by pandas) and a column named after the CMIP6 variable (e.g. `tas`, `tasmax`). Rows should be monthly.
 
+The reference and target scenarios must cover **different years**, the same way the CMIP6 `historical` and `sspXXX` experiments do. The two series are concatenated before the baseline and target periods are sliced out, so overlapping years get averaged together and weaken the climate signal. Keep `baseline_range` inside the years the reference scenario covers.
+
 ## Climate scenarios
 
-| Scenario | SSP | Description | Expected warming |
-|----------|-----|-------------|------------------|
-| Best Case Scenario | ssp126 | Strong mitigation, renewable transition | ~1.8 C by 2100 |
-| Middle of the Road | ssp245 | Moderate mitigation efforts | ~2.7 C by 2100 |
-| Upper Middle Scenario | ssp370 | Regional rivalry, slow convergence | ~3.6 C by 2100 |
-| Worst Case Scenario | ssp585 | Fossil-fueled development | ~4.4 C by 2100 |
+| Scenario              | SSP    | Description                             | Expected warming |
+| --------------------- | ------ | --------------------------------------- | ---------------- |
+| Best Case Scenario    | ssp126 | Strong mitigation, renewable transition | ~1.8 C by 2100   |
+| Middle of the Road    | ssp245 | Moderate mitigation efforts             | ~2.7 C by 2100   |
+| Upper Middle Scenario | ssp370 | Regional rivalry, slow convergence      | ~3.6 C by 2100   |
+| Worst Case Scenario   | ssp585 | Fossil-fueled development               | ~4.4 C by 2100   |
 
 ## Morphing variables
 
 - **Temperature** -- dry bulb temperature (shift + stretch)
-- **Humidity** -- relative humidity via specific humidity (stretch)
+- **Humidity** -- relative humidity, stretched in specific humidity space
 - **Pressure** -- atmospheric pressure (shift)
 - **Wind** -- wind speed (stretch)
 - **Clouds and Radiation** -- global/diffuse/direct radiation and sky cover
@@ -107,14 +109,16 @@ Custom CSVs should have a `date` column (parseable by pandas) and a column named
 
 ### Variable dependencies
 
-Some variables are automatically added when needed:
+Some variables cannot be morphed on their own:
 
 - **Humidity** requires Temperature and Pressure
 - **Dew Point** requires Temperature, Humidity, and Pressure
 
+Dependencies are added automatically and are **written to the output file**. Asking for `Dew Point` alone therefore returns an EPW with morphed pressure, temperature, relative humidity, and dew point, which keeps the file internally consistent. `MorphConfig.resolved_variables` shows exactly what will be written, in the order it is computed.
+
 ## Caching
 
-Climate model data is cached locally after the first download to speed up repeated analyses.
+Climate model data is cached locally after the first download, and the cache is consulted before the remote catalogue is opened so a hit costs no network traffic.
 
 ```python
 import pyepwmorph.models.access as access
@@ -123,6 +127,13 @@ stats = access.get_cmip6_cache_stats()
 access.clear_cmip6_cache()
 ```
 
+Cache entries live in the per-user cache directory (`~/Library/Caches/pyepwmorph` on macOS, `~/.cache/pyepwmorph` on Linux, `%LOCALAPPDATA%\pyepwmorph` on Windows) and are keyed by location, pathway, variable, model sources, and time slices. Two environment variables override the defaults:
+
+| Variable                  | Purpose                        | Default |
+| ------------------------- | ------------------------------ | ------- |
+| `PYEPWMORPH_CACHE_DIR`    | Where cache files are written  | per-user cache directory |
+| `PYEPWMORPH_CACHE_MAX_MB` | Size cap before old files go   | 500 |
+
 ## Available climate models
 
 ```python
@@ -138,51 +149,39 @@ git clone https://github.com/justinfmccarty/pyepwmorph.git
 cd pyepwmorph
 uv sync --extra dev
 
-# Run tests
-pytest
+# Run tests (fully offline)
+uv run pytest
 
 # Run with coverage
-pytest --cov=pyepwmorph
+uv run pytest --cov=pyepwmorph
+
+# Lint
+uv run ruff check pyepwmorph tests gui
 ```
 
 ### Releases
+
 ```bash
 ./release.sh [patch|minor|major]
 ```
 
-Copy-paste (change version number) for release statement
-```bash
-gh release create v2.2.0 \
-  --title "v2.2.0" \
-  --notes "## What's new
+The script refuses to run on a dirty tree, off `main`, with failing lint or tests, or without a matching `CHANGELOG.md` section. It bumps the version, tags, and pushes; creating the GitHub Release then triggers the PyPI publish workflow.
 
-See README for full breaking changes list."
+```bash
+gh release create v3.0.0 \
+  --title "v3.0.0" \
+  --notes "See CHANGELOG.md."
 ```
 
+## Changes
 
-
-## Breaking changes in v2.0.0
-
-- **License changed** from GPL-3.0 to MIT.
-- **`future_years`** parameter renamed to **`target_years`** across the API.
-  The old name is still accepted with a deprecation warning.
-- **`MorphConfig`** accepts new parameters: `data_source`, `custom_data`,
-  `reference_scenario`, and `target_years`.
-- **EPW I/O** (`pyepwmorph.tools.io`) rewritten with stricter validation.
-  Files that are not exactly 8760 data rows will now raise `ValueError`.
-  The lat/lon parsing bug in the standalone `epw_location()` function has
-  been fixed.
-- **`coordinate_cmip6_data`** now accepts an optional `time_slices` dict
-  for custom temporal bounds instead of hardcoded 1960-2014 / 2015-2100.
-- **Removed** `requirements.txt`, `environment.yml`, `.bumpversion.cfg`.
-  Use `uv sync` or `pip install .` instead.
-- **Per-module `__version__`** strings removed. Use
-  `pyepwmorph.__version__` or `importlib.metadata.version("pyepwmorph")`.
+See [CHANGELOG.md](CHANGELOG.md) for the full history. The most recent release corrects several morphing calculations, so morphed humidity, dew point, wind speed, cloud cover, and direct/diffuse radiation all differ from files produced by earlier versions.
 
 ## Requirements
 
 - Python >= 3.9
-- Internet connection (for CMIP6 data download)
+- pandas >= 2.2
+- Internet connection (for CMIP6 data download; the custom CSV workflow runs offline)
 
 ## License
 
@@ -192,6 +191,6 @@ MIT License. See [LICENSE](LICENSE).
 
 ```text
 McCarty, J. (2026). pyepwmorph: A Python package for climate-informed
-EPW file morphing. Version 2.0.0.
+EPW file morphing. Version 3.0.0.
 https://github.com/justinfmccarty/pyepwmorph
 ```

pyepwmorph-3.0.0/pyepwmorph/__init__.py

@@ -0,0 +1,8 @@
+"""pyepwmorph -- Climate model data gathering and EPW file morphing."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("pyepwmorph")
+except PackageNotFoundError:  # running from a source tree that was never installed
+    __version__ = "0.0.0+unknown"

{pyepwmorph-2.2.0 → pyepwmorph-3.0.0}/pyepwmorph/models/access.py

@@ -1,16 +1,11 @@
-# coding=utf-8
 """
 various scripts for accessing different flavors of climate models
 """
 
-import warnings
-
 from pyepwmorph.tools import cache
 
-warnings.filterwarnings("ignore")
-
 __author__ = "Justin McCarty"
-__copyright__ = "Copyright 2023"
+__copyright__ = "Copyright 2023-2026"
 __credits__ = ["Justin McCarty"]
 __license__ = "MIT"
 
@@ -46,12 +41,12 @@ def access_cmip6_data(models, pathway, variable):
     import intake
 
     # NOTE: No caching at this level because the data contains lazy dask arrays
-    # that reference the full global grid. Caching happens in coordinate.py after
+    # that reference the full global grid. Caching happens in workflow.py once
     # the data has been spatially selected and computed for a specific location.
-    
+
     table_id = 'Amon'  # atmospheric variables (A) saved at monthly resolution (mon)
     member_id = 'r1i1p1f1'
-    
+
     # Fetch from Google Cloud
     gcsfs.GCSFileSystem(token='anon')
     # datastore_json = 'pangeo-cmip6.json'
@@ -64,7 +59,7 @@ def access_cmip6_data(models, pathway, variable):
 
     # convert data catalog into a dictionary of xarray datasets
     dataset_dict = model_search.to_dataset_dict(zarr_kwargs={'consolidated': True, 'decode_times': False})
-    
+
     return dataset_dict
 
 
@@ -84,19 +79,18 @@ def build_accessible_data_list():
     import gcsfs
     import intake
     gcsfs.GCSFileSystem(token='anon')
-    # datastore_json = 'pangeo-cmip6.json'
     esm_data = intake.open_esm_datastore("https://storage.googleapis.com/cmip6/pangeo-cmip6.json")
-    # return esm_data.df['source_id'].unique().tolist()
+    return sorted(esm_data.df['source_id'].unique().tolist())
 
 
 def clear_cmip6_cache():
     """
     Clear all cached CMIP6 data.
-    
+
     This clears location-specific cached data that has been processed and stored
-    for faster repeated access. This is useful for development or when you want 
+    for faster repeated access. This is useful for development or when you want
     to free up disk space.
-    
+
     Examples
     --------
     >>> clear_cmip6_cache()
@@ -107,11 +101,11 @@ def clear_cmip6_cache():
 def get_cmip6_cache_stats():
     """
     Get statistics about the CMIP6 data cache.
-    
+
     Returns information about cache size, number of files, and individual
     file details for development and monitoring purposes. The cache stores
     location-specific processed data.
-    
+
     Returns
     -------
     dict
@@ -122,10 +116,10 @@ def get_cmip6_cache_stats():
         - max_size_mb: Maximum allowed cache size
         - usage_percent: Percentage of max size used
         - files: List of individual file details
-    
+
     Examples
     --------
     >>> stats = get_cmip6_cache_stats()
     >>> print(f"Cache using {stats['total_size_mb']} MB ({stats['usage_percent']}%)")
     """
-    return cache.get_cache_stats()
+    return cache.get_cache_stats()

{pyepwmorph-2.2.0 → pyepwmorph-3.0.0}/pyepwmorph/models/assemble.py

@@ -1,17 +1,14 @@
-# coding=utf-8
 """
 This module creates ensembles from multiple model inputs downloaded for a single pathway and variable.
 This is what enables the slicing of the data from a percentile point of view.
 """
 import pandas as pd
 import xarray as xr
-from pyepwmorph.tools import utilities
-import warnings
 
-warnings.filterwarnings("ignore")
+from pyepwmorph.tools import utilities
 
 __author__ = "Justin McCarty"
-__copyright__ = "Copyright 2023"
+__copyright__ = "Copyright 2023-2026"
 __credits__ = ["Justin McCarty"]
 __license__ = "MIT"
 
@@ -111,4 +108,4 @@ def calc_model_climatologies(baseline_range, future_range, baseline_data, future
     future_means = utilities.monthly_means(future_data).rename(variable)
 
 
-    return baseline_means, future_means
+    return baseline_means, future_means

{pyepwmorph-2.2.0 → pyepwmorph-3.0.0}/pyepwmorph/models/coordinate.py

@@ -1,4 +1,3 @@
-# coding=utf-8
 """Coordinate CMIP6 model data into a standard grid and time system.
 
 Climate model data comes in varied grid systems and temporal indices.
@@ -7,16 +6,10 @@ it is fed to the morphing algorithm.
 """
 
 import logging
-import time
-import warnings
 
 import dask
-import pandas as pd
 import xarray as xr
 
-from pyepwmorph.tools import cache
-
-warnings.filterwarnings("ignore")
 logger = logging.getLogger(__name__)
 
 __author__ = "Justin McCarty"
@@ -64,30 +57,17 @@ def coordinate_cmip6_data(
     -------
     dict
         Dictionary of computed xarray Datasets keyed by source name.
+
+    Notes
+    -----
+    Caching lives in ``workflow.compile_climate_model_data`` so that a cache
+    hit avoids opening the remote catalogue at all.  Calling this function
+    directly always recomputes.
     """
     slices = {**DEFAULT_TIME_SLICES}
     if time_slices:
         slices.update(time_slices)
 
-    source_ids = list(dset_dict.keys())
-    model_names = []
-    for source_id in source_ids:
-        parts = source_id.split('.')
-        if len(parts) >= 3:
-            model_names.append(parts[2])
-        else:
-            model_names.append(source_id)
-
-    cached_data = cache.get_cached_coordinate_data(
-        latitude=latitude,
-        longitude=longitude,
-        pathway=pathway,
-        variable=variable,
-        source_id=model_names,
-    )
-    if cached_data is not None:
-        return cached_data
-
     time_start, time_end = slices.get(pathway, DEFAULT_SSP_SLICE)
 
     ds_dict = {}
@@ -118,15 +98,4 @@ def coordinate_cmip6_data(
 
         ds_dict[name] = ds
 
-    datasets = dask.compute(ds_dict)[0]
-
-    cache.save_coordinate_to_cache(
-        data=datasets,
-        latitude=latitude,
-        longitude=longitude,
-        pathway=pathway,
-        variable=variable,
-        source_id=model_names,
-    )
-
-    return datasets
+    return dask.compute(ds_dict)[0]

{pyepwmorph-2.2.0 → pyepwmorph-3.0.0}/pyepwmorph/models/custom.py

@@ -1,4 +1,3 @@
-# coding=utf-8
 """Load custom (non-CMIP6) climate model data from CSV files.
 
 The CSV format expected is: