meteosynth 0.1.0__tar.gz

meteosynth-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,34 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: "3.11"
+
+      - name: Build documentation
+        run: |
+          uv run --group dev sphinx-build -b html docs/source docs/build/html
+
+      - name: Deploy to Cloudflare Workers
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: deploy
+          wranglerVersion: "4"

meteosynth-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,58 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  test-and-build:
+    name: Build distribution and run tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          uv sync --all-extras --dev
+
+      - name: Run tests
+        run: |
+          uv run pytest
+
+      - name: Build package
+        run: |
+          uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish Python distribution to PyPI
+    needs: test-and-build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/meteosynth
+    permissions:
+      id-token: write  # MANDATORY for Trusted Publishing OIDC authentication
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish package distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

meteosynth-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDEs
+.vscode/
+.idea/
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.swp
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Documentation
+docs/build/
+docs/_build/
+docs/generated/
+
+# Data and OS files
+.DS_Store
+Thumbs.db
+*.xlsx
+*.csv
+*.nc
+data/

meteosynth-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

meteosynth-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nikolaos Papadakis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

meteosynth-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: meteosynth
+Version: 0.1.0
+Summary: A package for generating synthetic environmental time-series using Markov Chain models and PVGIS data integration.
+Project-URL: Homepage, https://github.com/npapnet/meteosynth
+Project-URL: Repository, https://github.com/npapnet/meteosynth.git
+Project-URL: Documentation, https://meteosynth-docs.npapnet-cloudflare.workers.dev
+Author-email: "N.Papadakis (hmuQ)" <npap@hmu.gr>
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Python: >=3.10
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: numpy>=1.22.0
+Requires-Dist: openpyxl>=3.0.0
+Requires-Dist: pandas>=1.4.0
+Requires-Dist: pvlib>=0.9.0
+Requires-Dist: scipy>=1.8.0
+Provides-Extra: plot
+Requires-Dist: plotnine>=0.10.0; extra == 'plot'
+Requires-Dist: seaborn>=0.11.0; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# meteosynth
+
+`meteosynth` is a Python package designed to generate synthetic environmental time-series data (such as solar radiation, air temperature, wind speed) based on historical data. It implements a variety of Markov Chain models and includes utilities to interface with the PVGIS (Photovoltaic Geographical Information System) database.
+
+Its primary target is **Monte-Carlo simulation of energy-project output and requirements**, where many statistically-plausible weather realisations are needed rather than a single deterministic profile.
+
+## Features
+
+- **Markov Chain Simulators** (shared `get_next_state` / `generate_sequence` interface):
+  - `MarkovChainSimulator2dKDE`: Continuous state simulation using 2D Kernel Density Estimation with handling for various singularity cases (CC, CN, NC, NN).
+  - `ContinuousMarkovChainSimulator`: Binned continuous state simulation using 1D Kernel Density Estimation.
+  - `MarkovChainSimulatorDiscrete`: Discrete state transition modeling.
+- **Daily Series Generators** (`meteosynth.generators`):
+  - `EnvSeriesGenerator`: chains 24 hourly simulators into complete 24-hour profiles and draws Monte-Carlo ensembles via `generate_ensemble`.
+- **Meteorological Data Processing**:
+  - Pivoting hourly data into daily wide formats.
+  - Subsetting and filtering datasets by month/year.
+- **PVGIS Integration**:
+  - Retrieve hourly or Typical Meteorological Year (TMY) data directly using the `pvlib` API (`meteosynth.metdata_pvgis`).
+
+---
+
+## Installation & Setup
+
+This package is managed using the `uv` tool. To install the package and its dependencies:
+
+```bash
+# Sync core dependencies (numpy, pandas, scipy, pvlib, matplotlib) + dev group
+uv sync
+
+# Add the extra statistical-plotting helpers (seaborn, plotnine)
+uv sync --extra plot
+```
+
+`matplotlib` is a core dependency (the simulators expose plotting helpers directly).
+The `dev` dependency group — installed by default with `uv sync` — provides the
+documentation toolchain (Sphinx, furo, Mermaid, MyST) and an interactive
+workflow (`jupyter`, `notebook`, `ipykernel`) for VS Code / JupyterLab.
+
+---
+
+## Usage Example
+
+Draw a single transition or a full Markov trajectory:
+
+```python
+import pandas as pd
+from meteosynth import MarkovChainSimulator2dKDE
+
+# Load your historical training data (containing 'previous' and 'current' columns)
+data = pd.DataFrame({
+    'previous': [1.2, 1.5, 1.8, 2.1],
+    'current': [1.5, 1.9, 2.0, 2.3]
+})
+
+# Initialize the 2D KDE simulator
+simulator = MarkovChainSimulator2dKDE(data)
+
+# Generate the next state from a current value of 1.7 ...
+next_state = simulator.get_next_state(1.7, seed=42)
+print("Next state:", next_state)
+
+# ... or a whole reproducible sequence
+print(simulator.generate_sequence(start_state=1.7, length=10, seed=42))
+```
+
+### Monte-Carlo daily ensemble
+
+Chain 24 hourly simulators into synthetic days and draw an ensemble for
+downstream energy analysis:
+
+```python
+from meteosynth import MetDataProcessor, EnvSeriesGenerator
+
+# `df` is a processed PVGIS hourly frame (year, month, day, hour, poa_direct, ...)
+mdp = MetDataProcessor(df)
+may = mdp.get_month_subset(5)                     # train on one month
+
+gen = EnvSeriesGenerator(may, attr_str="poa_direct", bandwidth=0.1)
+
+# 500 independent synthetic days -> shape (500, 24)
+ensemble = gen.generate_ensemble(n_days=500, start_value=0.0, seed=1)
+daily_energy = ensemble.sum(axis=1)               # per-day yield proxy
+print(daily_energy.mean(), daily_energy.std())
+```
+
+Fetch real data from PVGIS with `meteosynth.metdata_pvgis`:
+
+```python
+from meteosynth.metdata_pvgis import fetch_pvgis_hourly, SITE_PARIS, save_hourly
+
+df = fetch_pvgis_hourly(start_year=2011, end_year=2012, **SITE_PARIS)
+save_hourly(df)   # caches to data/pvgis_hourly_data.xlsx
+```
+
+---
+
+## Examples
+
+Two runnable scripts live under `examples/`. On first run they fetch data from
+PVGIS and cache it to `data/pvgis_hourly_data.xlsx`, so subsequent runs are
+offline and fast.
+
+```bash
+# Exploratory analysis: fetch, process, and plot PVGIS data
+uv run python examples/example_exploratory_analysis.py
+
+# Synthetic generation: build hourly simulators and plot synthetic daily profiles
+uv run python examples/example_markov_generation.py
+```
+
+See the **Examples** page in the documentation for a full walk-through.
+
+---
+
+## Running Tests
+
+Verify the installation by running the test suite (`MPLBACKEND=Agg` keeps
+matplotlib headless):
+
+```bash
+# Linux/macOS
+MPLBACKEND=Agg uv run pytest
+
+# Windows (PowerShell)
+$env:MPLBACKEND = "Agg"; uv run pytest
+```
+
+---
+
+## Building Documentation
+
+The documentation uses the standard Sphinx layout (`docs/source/` for sources,
+`docs/build/` for output, with `Makefile`/`make.bat` at the `docs/` root) and
+the `furo` theme, with Mermaid diagrams and Markdown (MyST) support.
+
+```bash
+# From the docs/ directory (Windows)
+cd docs
+uv run .\make.bat html
+
+# ...or on Linux/macOS
+cd docs && uv run make html
+
+# ...or invoke sphinx-build directly from the project root
+uv run sphinx-build -b html docs/source docs/build/html
+```
+
+Open `docs/build/html/index.html` in your web browser to view it. The docs
+include a **Quickstart**, a **Theory** section explaining the KDE Markov method
+(with diagrams), an **Examples** walk-through, and the full **API reference**.

meteosynth-0.1.0/README.md

@@ -0,0 +1,151 @@
+# meteosynth
+
+`meteosynth` is a Python package designed to generate synthetic environmental time-series data (such as solar radiation, air temperature, wind speed) based on historical data. It implements a variety of Markov Chain models and includes utilities to interface with the PVGIS (Photovoltaic Geographical Information System) database.
+
+Its primary target is **Monte-Carlo simulation of energy-project output and requirements**, where many statistically-plausible weather realisations are needed rather than a single deterministic profile.
+
+## Features
+
+- **Markov Chain Simulators** (shared `get_next_state` / `generate_sequence` interface):
+  - `MarkovChainSimulator2dKDE`: Continuous state simulation using 2D Kernel Density Estimation with handling for various singularity cases (CC, CN, NC, NN).
+  - `ContinuousMarkovChainSimulator`: Binned continuous state simulation using 1D Kernel Density Estimation.
+  - `MarkovChainSimulatorDiscrete`: Discrete state transition modeling.
+- **Daily Series Generators** (`meteosynth.generators`):
+  - `EnvSeriesGenerator`: chains 24 hourly simulators into complete 24-hour profiles and draws Monte-Carlo ensembles via `generate_ensemble`.
+- **Meteorological Data Processing**:
+  - Pivoting hourly data into daily wide formats.
+  - Subsetting and filtering datasets by month/year.
+- **PVGIS Integration**:
+  - Retrieve hourly or Typical Meteorological Year (TMY) data directly using the `pvlib` API (`meteosynth.metdata_pvgis`).
+
+---
+
+## Installation & Setup
+
+This package is managed using the `uv` tool. To install the package and its dependencies:
+
+```bash
+# Sync core dependencies (numpy, pandas, scipy, pvlib, matplotlib) + dev group
+uv sync
+
+# Add the extra statistical-plotting helpers (seaborn, plotnine)
+uv sync --extra plot
+```
+
+`matplotlib` is a core dependency (the simulators expose plotting helpers directly).
+The `dev` dependency group — installed by default with `uv sync` — provides the
+documentation toolchain (Sphinx, furo, Mermaid, MyST) and an interactive
+workflow (`jupyter`, `notebook`, `ipykernel`) for VS Code / JupyterLab.
+
+---
+
+## Usage Example
+
+Draw a single transition or a full Markov trajectory:
+
+```python
+import pandas as pd
+from meteosynth import MarkovChainSimulator2dKDE
+
+# Load your historical training data (containing 'previous' and 'current' columns)
+data = pd.DataFrame({
+    'previous': [1.2, 1.5, 1.8, 2.1],
+    'current': [1.5, 1.9, 2.0, 2.3]
+})
+
+# Initialize the 2D KDE simulator
+simulator = MarkovChainSimulator2dKDE(data)
+
+# Generate the next state from a current value of 1.7 ...
+next_state = simulator.get_next_state(1.7, seed=42)
+print("Next state:", next_state)
+
+# ... or a whole reproducible sequence
+print(simulator.generate_sequence(start_state=1.7, length=10, seed=42))
+```
+
+### Monte-Carlo daily ensemble
+
+Chain 24 hourly simulators into synthetic days and draw an ensemble for
+downstream energy analysis:
+
+```python
+from meteosynth import MetDataProcessor, EnvSeriesGenerator
+
+# `df` is a processed PVGIS hourly frame (year, month, day, hour, poa_direct, ...)
+mdp = MetDataProcessor(df)
+may = mdp.get_month_subset(5)                     # train on one month
+
+gen = EnvSeriesGenerator(may, attr_str="poa_direct", bandwidth=0.1)
+
+# 500 independent synthetic days -> shape (500, 24)
+ensemble = gen.generate_ensemble(n_days=500, start_value=0.0, seed=1)
+daily_energy = ensemble.sum(axis=1)               # per-day yield proxy
+print(daily_energy.mean(), daily_energy.std())
+```
+
+Fetch real data from PVGIS with `meteosynth.metdata_pvgis`:
+
+```python
+from meteosynth.metdata_pvgis import fetch_pvgis_hourly, SITE_PARIS, save_hourly
+
+df = fetch_pvgis_hourly(start_year=2011, end_year=2012, **SITE_PARIS)
+save_hourly(df)   # caches to data/pvgis_hourly_data.xlsx
+```
+
+---
+
+## Examples
+
+Two runnable scripts live under `examples/`. On first run they fetch data from
+PVGIS and cache it to `data/pvgis_hourly_data.xlsx`, so subsequent runs are
+offline and fast.
+
+```bash
+# Exploratory analysis: fetch, process, and plot PVGIS data
+uv run python examples/example_exploratory_analysis.py
+
+# Synthetic generation: build hourly simulators and plot synthetic daily profiles
+uv run python examples/example_markov_generation.py
+```
+
+See the **Examples** page in the documentation for a full walk-through.
+
+---
+
+## Running Tests
+
+Verify the installation by running the test suite (`MPLBACKEND=Agg` keeps
+matplotlib headless):
+
+```bash
+# Linux/macOS
+MPLBACKEND=Agg uv run pytest
+
+# Windows (PowerShell)
+$env:MPLBACKEND = "Agg"; uv run pytest
+```
+
+---
+
+## Building Documentation
+
+The documentation uses the standard Sphinx layout (`docs/source/` for sources,
+`docs/build/` for output, with `Makefile`/`make.bat` at the `docs/` root) and
+the `furo` theme, with Mermaid diagrams and Markdown (MyST) support.
+
+```bash
+# From the docs/ directory (Windows)
+cd docs
+uv run .\make.bat html
+
+# ...or on Linux/macOS
+cd docs && uv run make html
+
+# ...or invoke sphinx-build directly from the project root
+uv run sphinx-build -b html docs/source docs/build/html
+```
+
+Open `docs/build/html/index.html` in your web browser to view it. The docs
+include a **Quickstart**, a **Theory** section explaining the KDE Markov method
+(with diagrams), an **Examples** walk-through, and the full **API reference**.