pynnlf 0.2.2__tar.gz

pynnlf-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 M. Syahman Samhan
+
+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.

pynnlf-0.2.2/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: pynnlf
+Version: 0.2.2
+Summary: Python Network Net Load Forecasting (PyNNLF): reproducible evaluation of net load forecasting models.
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: attrs>=24.2.0
+Requires-Dist: certifi>=2025.6.15
+Requires-Dist: charset-normalizer>=3.4.2
+Requires-Dist: click>=8.2.1
+Requires-Dist: cmdstanpy>=1.2.5
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: cftime>=1.6.4.post1
+Requires-Dist: contourpy>=1.3.0
+Requires-Dist: cycler>=0.12.1
+Requires-Dist: DateTime>=5.5
+Requires-Dist: debugpy>=1.8.5
+Requires-Dist: decorator>=5.1.1
+Requires-Dist: dill>=0.3.9
+Requires-Dist: et-xmlfile>=2.0.0
+Requires-Dist: filelock>=3.16.1
+Requires-Dist: fonttools>=4.54.0
+Requires-Dist: fsspec>=2024.12.0
+Requires-Dist: holidays>=0.72
+Requires-Dist: idna>=3.10
+Requires-Dist: importlib_resources>=6.5.2
+Requires-Dist: Jinja2>=3.1.5
+Requires-Dist: joblib>=1.4.2
+Requires-Dist: kiwisolver>=1.4.7
+Requires-Dist: MarkupSafe>=3.0.2
+Requires-Dist: matplotlib>=3.9.2
+Requires-Dist: mpmath>=1.3.0
+Requires-Dist: nbformat>=5.10.4
+Requires-Dist: nest-asyncio>=1.6.0
+Requires-Dist: netCDF4>=1.7.2
+Requires-Dist: networkx>=3.4.2
+Requires-Dist: numpy>=2.1.1
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: packaging>=24.1
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: patsy>=1.0.1
+Requires-Dist: pillow>=10.4.0
+Requires-Dist: platformdirs>=4.3.6
+Requires-Dist: prophet>=1.1.6
+Requires-Dist: psutil>=6.0.0
+Requires-Dist: PyYAML>=6.0.2
+Requires-Dist: pyyaml_env_tag>=1.1
+Requires-Dist: pyzmq>=26.2.0
+Requires-Dist: requests>=2.32.4
+Requires-Dist: scikit-learn>=1.6.0
+Requires-Dist: scipy>=1.14.1
+Requires-Dist: shapely>=2.1.1
+Requires-Dist: six>=1.16.0
+Requires-Dist: stanio>=0.5.1
+Requires-Dist: statsmodels>=0.14.4
+Requires-Dist: sympy>=1.13.1
+Requires-Dist: threadpoolctl>=3.5.0
+Requires-Dist: torch>=2.5.1
+Requires-Dist: tornado>=6.4.1
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: typing_extensions>=4.12.2
+Requires-Dist: tzdata>=2024.1
+Requires-Dist: urllib3>=2.5.0
+Requires-Dist: wcwidth>=0.2.13
+Requires-Dist: xgboost>=3.0.0
+Requires-Dist: zope.interface>=7.0.3
+Requires-Dist: pywin32>=306; platform_system == "Windows"
+Provides-Extra: notebook
+Requires-Dist: ipykernel>=6.29.5; extra == "notebook"
+Requires-Dist: ipython>=8.27.0; extra == "notebook"
+Requires-Dist: jupyter_client>=8.6.3; extra == "notebook"
+Requires-Dist: jupyter_core>=5.7.2; extra == "notebook"
+Requires-Dist: matplotlib-inline>=0.1.7; extra == "notebook"
+Requires-Dist: prompt_toolkit>=3.0.47; extra == "notebook"
+Requires-Dist: Pygments>=2.18.0; extra == "notebook"
+Requires-Dist: stack-data>=0.6.3; extra == "notebook"
+Requires-Dist: traitlets>=5.14.3; extra == "notebook"
+Provides-Extra: docs
+Requires-Dist: babel>=2.17.0; extra == "docs"
+Requires-Dist: backrefs>=5.9; extra == "docs"
+Requires-Dist: ghp-import>=2.1.0; extra == "docs"
+Requires-Dist: griffe>=1.14.0; extra == "docs"
+Requires-Dist: Markdown>=3.9; extra == "docs"
+Requires-Dist: mergedeep>=1.3.4; extra == "docs"
+Requires-Dist: mkdocs>=1.6.1; extra == "docs"
+Requires-Dist: mkdocs-autorefs>=1.4.3; extra == "docs"
+Requires-Dist: mkdocs-get-deps>=0.2.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.6.20; extra == "docs"
+Requires-Dist: mkdocs-material-extensions>=1.3.1; extra == "docs"
+Requires-Dist: mkdocstrings>=0.30.0; extra == "docs"
+Requires-Dist: mkdocstrings-python>=1.18.2; extra == "docs"
+Requires-Dist: paginate>=0.5.7; extra == "docs"
+Requires-Dist: pathspec>=0.12.1; extra == "docs"
+Requires-Dist: pymdown-extensions>=10.16.1; extra == "docs"
+Requires-Dist: PyYAML>=6.0.2; extra == "docs"
+Requires-Dist: watchdog>=6.0.0; extra == "docs"
+
+# Welcome to PyNNLF
+PyNNLF (Python for Network Net Load Forecast) is a tool to evaluate net load forecasting model performance in a reliable and reproducible way.
+
+This tool evaluates net load forecasting models aiming to make new net load forecasting research more reliable and reproducible. It includes a library of public net load datasets and common forecasting models, including simple benchmark models. Users input the forecast problem and model specification, and the tool outputs evaluation results. 
+It also allows users to add datasets, models, and modify hyperparameters. Researchers claiming a new or superior model can compare their model with existing ones on public datasets. The target audience includes researchers working in academia or industry focusing on evaluating and optimizing net load forecasting models. 
+
+A visual illustration of the tool's workflow is shown below. 
+
+![Home Illustration](./docs/img/home_illustration.png)
+
+# Input
+1. **Forecast Target**: Dataset and forecast horizon defined in the YAML spec at example_project/specs/experiment.yaml.
+2. **Model Specification**: Model and hyperparameters defined in the YAML spec at example_project/specs/experiment.yaml.
+
+# Output
+1. a1_experiment_result.csv – Contains accuracy (cross-validated test n-RMSE), stability (accuracy standard deviation), and training time.
+2. a2_hyperparameter.csv – Lists the hyperparameters used for each model.
+3. a3_cross_validation_result.csv – Detailed results for each cross-validation split.
+4. cv_plots/ – Folder with plots including:
+   - Observation vs forecast (time plot)
+   - Observation vs forecast (scatter plot)
+   - Residual time plot
+   - Residual histogram
+5. cv_test/ and cv_train/ – Folders containing time series of observations, forecasts, and residuals for each cross-validation split.
+
+# Tool Output Naming Convention
+Format:
+[experiment_no]_[experiment_date]_[dataset]_[forecast_horizon]_[model]_[hyperparameter]
+
+Example:
+E00001_250915_ds0_fh30_m6_lr_hp1
+
+# Installation Instruction
+1. Install the package:
+On macOS, use `python3`/`pip3` if `python`/`pip` are not available.
+```bash
+python -m pip install pynnlf
+```
+
+# How to Use The Tool
+1. Initialize a workspace in any directory you want (example name: my_project). By default, only the sample dataset (ds0) is included. You can choose to download all datasets if needed:
+On macOS, use `python3 -c` if `python -c` is not available.
+```bash
+python -c "import pynnlf; pynnlf.init('my_project')"
+```
+2. Set up your experiment in example_project/specs/experiment.yaml.
+3. Run the experiment:
+```bash
+python -c "import pynnlf; pynnlf.run_experiment('my_project/specs/experiment.yaml')"
+```
+4. View results under example_project/experiment_result.
+
+# CI
+CI (Continuous Integration) is automated testing that runs on code changes. CI is available to run smoke tests on 3 models and check whether results fall within the standard benchmark.
+
+# Output
+The tool will output the evaluation result in example_project/experiment_result as one folder.
+
+# Full Documentation
+Detailed documentation including examples, testing, detailed guide, API reference, features & limitations, etc. can be seen here. [PyNNLF Documentation](https://mssamhan31.github.io/PyNNLF/)
+
+# Acknowledgements
+This project is part of Samhan's PhD study, supported by the University International Postgraduate Award (UIPA) Scholarship from UNSW, the Industry Collaboration Project Scholarship from Ausgrid, and the RACE for 2030 Scholarship. We also acknowledge Solcast and the Australian Bureau of Meteorology (BOM) for providing access to historical weather datasets for this research. We further acknowledge the use of Python libraries including Pandas, NumPy, PyTorch, Scikit-learn, XGBoost, Prophet, Statsmodels, and Matplotlib. Finally, we thank the reviewers and editor of the Journal of Open Source Software for their valuable feedback and guidance.
+
+The authors declare that they have no competing financial, personal, or professional interests related to this work.
+
+# Contributors
+- **M. Syahman Samhan** (m.samhan@unsw.edu.au): Lead developer and researcher. Responsible for conceptualization, implementation, documentation, and experimentation.
+- **Anna Bruce**: Supervisor. Provided guidance on research direction and methodology.
+- **Baran Yildiz**: Supervisor. Provided guidance on research direction and methodology.

pynnlf-0.2.2/README.md

@@ -0,0 +1,70 @@
+# Welcome to PyNNLF
+PyNNLF (Python for Network Net Load Forecast) is a tool to evaluate net load forecasting model performance in a reliable and reproducible way.
+
+This tool evaluates net load forecasting models aiming to make new net load forecasting research more reliable and reproducible. It includes a library of public net load datasets and common forecasting models, including simple benchmark models. Users input the forecast problem and model specification, and the tool outputs evaluation results. 
+It also allows users to add datasets, models, and modify hyperparameters. Researchers claiming a new or superior model can compare their model with existing ones on public datasets. The target audience includes researchers working in academia or industry focusing on evaluating and optimizing net load forecasting models. 
+
+A visual illustration of the tool's workflow is shown below. 
+
+![Home Illustration](./docs/img/home_illustration.png)
+
+# Input
+1. **Forecast Target**: Dataset and forecast horizon defined in the YAML spec at example_project/specs/experiment.yaml.
+2. **Model Specification**: Model and hyperparameters defined in the YAML spec at example_project/specs/experiment.yaml.
+
+# Output
+1. a1_experiment_result.csv – Contains accuracy (cross-validated test n-RMSE), stability (accuracy standard deviation), and training time.
+2. a2_hyperparameter.csv – Lists the hyperparameters used for each model.
+3. a3_cross_validation_result.csv – Detailed results for each cross-validation split.
+4. cv_plots/ – Folder with plots including:
+   - Observation vs forecast (time plot)
+   - Observation vs forecast (scatter plot)
+   - Residual time plot
+   - Residual histogram
+5. cv_test/ and cv_train/ – Folders containing time series of observations, forecasts, and residuals for each cross-validation split.
+
+# Tool Output Naming Convention
+Format:
+[experiment_no]_[experiment_date]_[dataset]_[forecast_horizon]_[model]_[hyperparameter]
+
+Example:
+E00001_250915_ds0_fh30_m6_lr_hp1
+
+# Installation Instruction
+1. Install the package:
+On macOS, use `python3`/`pip3` if `python`/`pip` are not available.
+```bash
+python -m pip install pynnlf
+```
+
+# How to Use The Tool
+1. Initialize a workspace in any directory you want (example name: my_project). By default, only the sample dataset (ds0) is included. You can choose to download all datasets if needed:
+On macOS, use `python3 -c` if `python -c` is not available.
+```bash
+python -c "import pynnlf; pynnlf.init('my_project')"
+```
+2. Set up your experiment in example_project/specs/experiment.yaml.
+3. Run the experiment:
+```bash
+python -c "import pynnlf; pynnlf.run_experiment('my_project/specs/experiment.yaml')"
+```
+4. View results under example_project/experiment_result.
+
+# CI
+CI (Continuous Integration) is automated testing that runs on code changes. CI is available to run smoke tests on 3 models and check whether results fall within the standard benchmark.
+
+# Output
+The tool will output the evaluation result in example_project/experiment_result as one folder.
+
+# Full Documentation
+Detailed documentation including examples, testing, detailed guide, API reference, features & limitations, etc. can be seen here. [PyNNLF Documentation](https://mssamhan31.github.io/PyNNLF/)
+
+# Acknowledgements
+This project is part of Samhan's PhD study, supported by the University International Postgraduate Award (UIPA) Scholarship from UNSW, the Industry Collaboration Project Scholarship from Ausgrid, and the RACE for 2030 Scholarship. We also acknowledge Solcast and the Australian Bureau of Meteorology (BOM) for providing access to historical weather datasets for this research. We further acknowledge the use of Python libraries including Pandas, NumPy, PyTorch, Scikit-learn, XGBoost, Prophet, Statsmodels, and Matplotlib. Finally, we thank the reviewers and editor of the Journal of Open Source Software for their valuable feedback and guidance.
+
+The authors declare that they have no competing financial, personal, or professional interests related to this work.
+
+# Contributors
+- **M. Syahman Samhan** (m.samhan@unsw.edu.au): Lead developer and researcher. Responsible for conceptualization, implementation, documentation, and experimentation.
+- **Anna Bruce**: Supervisor. Provided guidance on research direction and methodology.
+- **Baran Yildiz**: Supervisor. Provided guidance on research direction and methodology.

pynnlf-0.2.2/pyproject.toml

@@ -0,0 +1,127 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pynnlf"
+dynamic = ["version"]
+description = "Python Network Net Load Forecasting (PyNNLF): reproducible evaluation of net load forecasting models."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+
+# --- Runtime dependencies (minimum versions for compatibility) ---
+dependencies = [
+  "attrs>=24.2.0",
+  "certifi>=2025.6.15",
+  "charset-normalizer>=3.4.2",
+  "click>=8.2.1",
+  "cmdstanpy>=1.2.5",
+  "colorama>=0.4.6",
+  "cftime>=1.6.4.post1",
+  "contourpy>=1.3.0",
+  "cycler>=0.12.1",
+  "DateTime>=5.5",
+  "debugpy>=1.8.5",
+  "decorator>=5.1.1",
+  "dill>=0.3.9",
+  "et-xmlfile>=2.0.0",
+  "filelock>=3.16.1",
+  "fonttools>=4.54.0",
+  "fsspec>=2024.12.0",
+  "holidays>=0.72",
+  "idna>=3.10",
+  "importlib_resources>=6.5.2",
+  "Jinja2>=3.1.5",
+  "joblib>=1.4.2",
+  "kiwisolver>=1.4.7",
+  "MarkupSafe>=3.0.2",
+  "matplotlib>=3.9.2",
+  "mpmath>=1.3.0",
+  "nbformat>=5.10.4",
+  "nest-asyncio>=1.6.0",
+  "netCDF4>=1.7.2",
+  "networkx>=3.4.2",
+  "numpy>=2.1.1",
+  "openpyxl>=3.1.5",
+  "packaging>=24.1",
+  "pandas>=2.2.3",
+  "patsy>=1.0.1",
+  "pillow>=10.4.0",
+  "platformdirs>=4.3.6",
+  "prophet>=1.1.6",
+  "psutil>=6.0.0",
+  "PyYAML>=6.0.2",
+  "pyyaml_env_tag>=1.1",
+  "pyzmq>=26.2.0",
+  "requests>=2.32.4",
+  "scikit-learn>=1.6.0",
+  "scipy>=1.14.1",
+  "shapely>=2.1.1",
+  "six>=1.16.0",
+  "stanio>=0.5.1",
+  "statsmodels>=0.14.4",
+  "sympy>=1.13.1",
+  "threadpoolctl>=3.5.0",
+  "torch>=2.5.1",
+  "tornado>=6.4.1",
+  "tqdm>=4.67.1",
+  "typing_extensions>=4.12.2",
+  "tzdata>=2024.1",
+  "urllib3>=2.5.0",
+  "wcwidth>=0.2.13",
+  "xgboost>=3.0.0",
+  "zope.interface>=7.0.3",
+
+  # Windows-only:
+  "pywin32>=306; platform_system=='Windows'",
+]
+
+[project.optional-dependencies]
+# Keep notebook tooling optional (since notebooks won't be "the software" anymore)
+notebook = [
+  "ipykernel>=6.29.5",
+  "ipython>=8.27.0",
+  "jupyter_client>=8.6.3",
+  "jupyter_core>=5.7.2",
+  "matplotlib-inline>=0.1.7",
+  "prompt_toolkit>=3.0.47",
+  "Pygments>=2.18.0",
+  "stack-data>=0.6.3",
+  "traitlets>=5.14.3",
+]
+
+# Keep docs tooling optional
+docs = [
+  "babel>=2.17.0",
+  "backrefs>=5.9",
+  "ghp-import>=2.1.0",
+  "griffe>=1.14.0",
+  "Markdown>=3.9",
+  "mergedeep>=1.3.4",
+  "mkdocs>=1.6.1",
+  "mkdocs-autorefs>=1.4.3",
+  "mkdocs-get-deps>=0.2.0",
+  "mkdocs-material>=9.6.20",
+  "mkdocs-material-extensions>=1.3.1",
+  "mkdocstrings>=0.30.0",
+  "mkdocstrings-python>=1.18.2",
+  "paginate>=0.5.7",
+  "pathspec>=0.12.1",
+  "pymdown-extensions>=10.16.1",
+  "PyYAML>=6.0.2",
+  "watchdog>=6.0.0",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+license-files = []
+
+[tool.setuptools.dynamic]
+version = { attr = "pynnlf.__about__.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pynnlf = ["scaffold/**/*"]

pynnlf-0.2.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pynnlf-0.2.2/src/pynnlf/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.2.2"

pynnlf-0.2.2/src/pynnlf/__init__.py

@@ -0,0 +1,5 @@
+from .__about__ import __version__
+from .api import run_experiment, run_experiment_batch, run_tests
+from .workspace import init
+
+__all__ = ["__version__", "init", "run_experiment", "run_experiment_batch", "run_tests"]

pynnlf-0.2.2/src/pynnlf/api.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+from pathlib import Path
+from typing import Optional, Literal, Union
+from .runner import run_single, run_batch
+from .tests_runner import run_tests
+
+PathLike = Union[str, Path]
+TestMode = Literal["smoke", "full"]
+
+
+def run_experiment(spec_path: str | Path) -> None:
+    """Run a single experiment from <workspace>/specs/experiment.yaml."""
+    run_single(spec_path)
+
+def run_experiment_batch(spec_path: str | Path) -> None:
+    """Run batch experiments from <workspace>/specs/batch.yaml."""
+    run_batch(spec_path)

pynnlf-0.2.2/src/pynnlf/discovery.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python
+# coding: utf-8
+
+from pathlib import Path
+
+def discover_unique_file(directory: Path, prefix: str, suffix: str):
+    """
+    Discover a unique file in a directory by prefix and suffix.
+
+    Example:
+        prefix="m19" suffix=".py" matches: m19_*.py
+        prefix="ds19" suffix=".csv" matches: ds19_*.csv
+
+    Args:
+        directory (Path): Directory to search.
+        prefix (str): Required filename prefix (e.g. "m19" or "ds19").
+        suffix (str): Required suffix (e.g. ".py" or ".csv").
+
+    Returns:
+        Path: The unique matching file path.
+
+    Raises:
+        FileNotFoundError: If no match found.
+        ValueError: If more than one match found.
+    """
+    directory = Path(directory)
+    matches = sorted(directory.glob(f"{prefix}_*{suffix}"))
+    if len(matches) == 0:
+        # also allow exact name without underscore: ds19.csv / m19.py
+        exact = directory / f"{prefix}{suffix}"
+        if exact.exists():
+            return exact
+        raise FileNotFoundError(f"No file found for '{prefix}' in {directory}")
+    if len(matches) > 1:
+        raise ValueError(f"Multiple matches for '{prefix}' in {directory}: {[m.name for m in matches]}")
+    return matches[0]
+
+def discover_model_name(models_dir: Path, model_id: str) -> str:
+    """
+    Discover model file and return model_name (file stem).
+
+    Args:
+        models_dir (Path): <workspace>/models
+        model_id (str): model ID from spec, e.g. "m6" or "m19"
+
+    Returns:
+        str: model_name file stem, e.g. "m6_lr" or "m19_my_model"
+    """
+    p = discover_unique_file(models_dir, model_id, ".py")
+    return p.stem
+
+def discover_dataset_path(data_dir: Path, dataset_id: str) -> Path:
+    """
+    Discover dataset file path from dataset ID.
+
+    Args:
+        data_dir (Path): <workspace>/data
+        dataset_id (str): dataset ID from spec, e.g. "ds0" or "ds19"
+
+    Returns:
+        Path: dataset file path.
+    """
+    return discover_unique_file(data_dir, dataset_id, ".csv")