# pyfwg: Python Future Weather Generator
[](https://badge.fury.io/py/pyfwg)
[](https://opensource.org/licenses/MIT)
[](https://pyfwg.readthedocs.io/en/latest/?badge=latest)
[](https://doi.org/10.5281/zenodo.16908690)
A robust, step-by-step Python workflow manager for the [FutureWeatherGenerator](https://future-weather-generator.adai.pt/) command-line tool.
`pyfwg` provides a safe and intuitive way to automate the morphing of EnergyPlus Weather (EPW) files. It offers two main interfaces:
- A simple, one-shot function for direct morphing.
- A powerful `MorphingWorkflow` class for complex scenarios involving filename parsing, category mapping, and detailed process control.
## Key Features
- **Simple and Advanced APIs**: Use a single function for quick tasks or a full workflow class for complex projects.
- **Step-by-Step Control**: Analyze, preview, configure, and then execute, preventing errors before they happen.
- **Flexible Filename Mapping**: Handle both structured (regex-based) and unstructured (keyword-based) filenames with ease.
- **Built-in Validation**: Automatically validates all `FutureWeatherGenerator` parameters before execution to catch typos and invalid values.
- **Clear and Organized Output**: Automatically renames and organizes the final `.epw` and `.stat` files into a clean directory structure.
## Requirements
Before using `pyfwg`, you need to have the following installed and configured:
* **Python 3.9+**
* **Java**: The `java` command must be accessible from your system's terminal (i.e., it must be in your system's PATH).
* **FutureWeatherGenerator**: You must download the tool's `.jar` file. This library has been tested with FutureWeatherGenerator **v3.0.0** and **v3.0.1**.
* [Download from the official website](https://future-weather-generator.adai.pt/)
## Installation
You can install `pyfwg` directly from PyPI:
```bash
pip install pyfwg
```
## Quick Start: Simple Morphing
For direct morphing without complex renaming, use the `morph_epw` function. It provides full control over the FWG tool's parameters in a single call.
```python
from pyfwg import morph_epw
# 1. Define paths
jar_path = r"D:\path\to\your\FutureWeatherGenerator_v3.0.0.jar"
epw_file = 'epws/sevilla_present.epw'
# 2. Run the morphing process
# The generated files will appear in './morphed_epws' by default.
created_files = morph_epw(
epw_paths=epw_file,
fwg_jar_path=jar_path,
fwg_show_tool_output=True, # See the tool's progress
fwg_gcms=['CanESM5', 'MIROC6'] # Use a specific set of GCMs
)
print("Successfully created files:")
for f in created_files:
print(f)
```
## Advanced Usage: The MorphingWorkflow Class
For complex projects with custom renaming rules, the `MorphingWorkflow` class gives you full control over each step.
```python
from pyfwg import MorphingWorkflow
# --- STEP 0: Instantiate the workflow ---
workflow = MorphingWorkflow()
# --- STEP 1: Map categories from source filenames ---
# Use a regex pattern and normalization rules
workflow.map_categories(
epw_files=['epws/SVQ_uhi-tipo-2.epw'],
input_filename_pattern=r'(?P<city>.*?)_(?P<uhi_type>.*)',
keyword_mapping={
'city': {'seville': ['sevilla', 'svq']},
'uhi_type': {'type_2': ['uhi-tipo-2']}
}
)
# --- STEP 2: Define the output and preview the plan ---
workflow.preview_rename_plan(
final_output_dir='./final_results',
output_filename_pattern='{city}_{uhi_type}_{ssp}_{year}',
scenario_mapping={'ssp585': 'SSP5-8.5'}
)
# --- STEP 3: Set and validate the execution configuration ---
workflow.set_morphing_config(
fwg_jar_path=r"D:\path\to\your\FutureWeatherGenerator_v3.0.0.jar",
fwg_interpolation_method_id=2, # Override a specific parameter
fwg_show_tool_output=True
)
# --- STEP 4: Execute the morphing process ---
# This is only called after you are satisfied with the preview and config.
if workflow.is_config_valid:
workflow.execute_morphing()
```
## Acknowledgements
This library would not be possible without the foundational work of **Eugénio Rodrigues (University of Coimbra)**, the creator of the [FutureWeatherGenerator tool](https://future-weather-generator.adai.pt/). `pyfwg` is essentially a Python wrapper designed to automate and streamline the use of his powerful command-line application.
## License
This project is licensed under the GNU (GPLv3) License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/dsanchez-garcia/pyfwg",
"name": "pyfwg",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Daniel S\u00e1nchez-Garc\u00eda",
"author_email": "daniel.sanchezgarcia@uca.es",
"download_url": "https://files.pythonhosted.org/packages/df/03/584656ba07828aa697267ce3c12fe64f06644f954a39072bbea8519d3f1c/pyfwg-0.1.1.tar.gz",
"platform": null,
"description": "# pyfwg: Python Future Weather Generator\r\n\r\n[](https://badge.fury.io/py/pyfwg)\r\n[](https://opensource.org/licenses/MIT)\r\n[](https://pyfwg.readthedocs.io/en/latest/?badge=latest)\r\n[](https://doi.org/10.5281/zenodo.16908690)\r\n\r\nA robust, step-by-step Python workflow manager for the [FutureWeatherGenerator](https://future-weather-generator.adai.pt/) command-line tool.\r\n\r\n`pyfwg` provides a safe and intuitive way to automate the morphing of EnergyPlus Weather (EPW) files. It offers two main interfaces:\r\n- A simple, one-shot function for direct morphing.\r\n- A powerful `MorphingWorkflow` class for complex scenarios involving filename parsing, category mapping, and detailed process control.\r\n\r\n## Key Features\r\n\r\n- **Simple and Advanced APIs**: Use a single function for quick tasks or a full workflow class for complex projects.\r\n- **Step-by-Step Control**: Analyze, preview, configure, and then execute, preventing errors before they happen.\r\n- **Flexible Filename Mapping**: Handle both structured (regex-based) and unstructured (keyword-based) filenames with ease.\r\n- **Built-in Validation**: Automatically validates all `FutureWeatherGenerator` parameters before execution to catch typos and invalid values.\r\n- **Clear and Organized Output**: Automatically renames and organizes the final `.epw` and `.stat` files into a clean directory structure.\r\n\r\n## Requirements\r\n\r\nBefore using `pyfwg`, you need to have the following installed and configured:\r\n\r\n* **Python 3.9+**\r\n* **Java**: The `java` command must be accessible from your system's terminal (i.e., it must be in your system's PATH).\r\n* **FutureWeatherGenerator**: You must download the tool's `.jar` file. This library has been tested with FutureWeatherGenerator **v3.0.0** and **v3.0.1**.\r\n * [Download from the official website](https://future-weather-generator.adai.pt/)\r\n\r\n## Installation\r\n\r\nYou can install `pyfwg` directly from PyPI:\r\n\r\n```bash\r\npip install pyfwg\r\n```\r\n\r\n## Quick Start: Simple Morphing\r\n\r\nFor direct morphing without complex renaming, use the `morph_epw` function. It provides full control over the FWG tool's parameters in a single call.\r\n\r\n```python\r\nfrom pyfwg import morph_epw\r\n\r\n# 1. Define paths\r\njar_path = r\"D:\\path\\to\\your\\FutureWeatherGenerator_v3.0.0.jar\"\r\nepw_file = 'epws/sevilla_present.epw'\r\n\r\n# 2. Run the morphing process\r\n# The generated files will appear in './morphed_epws' by default.\r\ncreated_files = morph_epw(\r\n epw_paths=epw_file,\r\n fwg_jar_path=jar_path,\r\n fwg_show_tool_output=True, # See the tool's progress\r\n fwg_gcms=['CanESM5', 'MIROC6'] # Use a specific set of GCMs\r\n)\r\n\r\nprint(\"Successfully created files:\")\r\nfor f in created_files:\r\n print(f)\r\n```\r\n\r\n## Advanced Usage: The MorphingWorkflow Class\r\n\r\nFor complex projects with custom renaming rules, the `MorphingWorkflow` class gives you full control over each step.\r\n\r\n```python\r\nfrom pyfwg import MorphingWorkflow\r\n\r\n# --- STEP 0: Instantiate the workflow ---\r\nworkflow = MorphingWorkflow()\r\n\r\n# --- STEP 1: Map categories from source filenames ---\r\n# Use a regex pattern and normalization rules\r\nworkflow.map_categories(\r\n epw_files=['epws/SVQ_uhi-tipo-2.epw'],\r\n input_filename_pattern=r'(?P<city>.*?)_(?P<uhi_type>.*)',\r\n keyword_mapping={\r\n 'city': {'seville': ['sevilla', 'svq']},\r\n 'uhi_type': {'type_2': ['uhi-tipo-2']}\r\n }\r\n)\r\n\r\n# --- STEP 2: Define the output and preview the plan ---\r\nworkflow.preview_rename_plan(\r\n final_output_dir='./final_results',\r\n output_filename_pattern='{city}_{uhi_type}_{ssp}_{year}',\r\n scenario_mapping={'ssp585': 'SSP5-8.5'}\r\n)\r\n\r\n# --- STEP 3: Set and validate the execution configuration ---\r\nworkflow.set_morphing_config(\r\n fwg_jar_path=r\"D:\\path\\to\\your\\FutureWeatherGenerator_v3.0.0.jar\",\r\n fwg_interpolation_method_id=2, # Override a specific parameter\r\n fwg_show_tool_output=True\r\n)\r\n\r\n# --- STEP 4: Execute the morphing process ---\r\n# This is only called after you are satisfied with the preview and config.\r\nif workflow.is_config_valid:\r\n workflow.execute_morphing()\r\n```\r\n\r\n## Acknowledgements\r\n\r\nThis library would not be possible without the foundational work of **Eug\u00e9nio Rodrigues (University of Coimbra)**, the creator of the [FutureWeatherGenerator tool](https://future-weather-generator.adai.pt/). `pyfwg` is essentially a Python wrapper designed to automate and streamline the use of his powerful command-line application.\r\n\r\n## License\r\n\r\nThis project is licensed under the GNU (GPLv3) License - see the [LICENSE](LICENSE) file for details.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python workflow manager for the Future Weather Generator tool.",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/dsanchez-garcia/pyfwg/issues",
"Documentation": "https://pyfwg.readthedocs.io/",
"Homepage": "https://github.com/dsanchez-garcia/pyfwg"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "58de65c03840a24393f36cecfd3f42f8fbe874b235d535733df54ea39d5d59d6",
"md5": "5506d88458a2ca85d142abbdd931efbe",
"sha256": "6e1ebfced427decdfe51eb05b3805c59e759e1c629b33af1f0f432d8e44341ca"
},
"downloads": -1,
"filename": "pyfwg-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5506d88458a2ca85d142abbdd931efbe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 971463,
"upload_time": "2025-08-30T15:37:41",
"upload_time_iso_8601": "2025-08-30T15:37:41.783587Z",
"url": "https://files.pythonhosted.org/packages/58/de/65c03840a24393f36cecfd3f42f8fbe874b235d535733df54ea39d5d59d6/pyfwg-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "df03584656ba07828aa697267ce3c12fe64f06644f954a39072bbea8519d3f1c",
"md5": "4d011509934eb0f2f41f0ac108a14c60",
"sha256": "62e1c3a419a89c60bed64a67f6cb01f2c3ef91e2f278b2dea94123cb76e79b61"
},
"downloads": -1,
"filename": "pyfwg-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "4d011509934eb0f2f41f0ac108a14c60",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 931961,
"upload_time": "2025-08-30T15:37:43",
"upload_time_iso_8601": "2025-08-30T15:37:43.297657Z",
"url": "https://files.pythonhosted.org/packages/df/03/584656ba07828aa697267ce3c12fe64f06644f954a39072bbea8519d3f1c/pyfwg-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-30 15:37:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dsanchez-garcia",
"github_project": "pyfwg",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pyfwg"
}
JSON
