New examples and refactored module structure (#1)

carnosi · web-flow · commit 1482de56da61 · 2025-05-21T13:45:39.000+02:00
* refact: move neurons and layers to core for improved clarity

* fix: Correct Python version link in README and update license badge style

* fix: Update homepage URL in pyproject.toml and add IPython notebook to extend-include

* feat: Add examples section to documentation and create datasets module init

* fix: Update torch dependency to use compatible version specifier and add examples optional dependencies

* feat: Add dataset loading functions and update examples documentation

* feat: Rename load_dataset to load_example_dataset and update imports

* Remove Jupyter from dev dependencies and add it to examples; include sklearn and tqdm in examples.

* feat: include example 01

* feat: update dataset loader API reference to use load_example_dataset
diff --git a/README.md b/README.md
@@ -6,9 +6,9 @@
 
 [![Project Status: WIP](https://img.shields.io/badge/repo_status-WIP-<COLOR>?style=for-the-badge&color=yellow)](https://www.repostatus.org/#WIP) [![Read the Docs](https://img.shields.io/readthedocs/gmp?style=for-the-badge&logo=readthedocs&logoColor=white)](https://gmp.readthedocs.io/en/latest/)
 
-[![PyPI](https://img.shields.io/pypi/v/ghonn-models-pytorch?color=red&style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/ghonn-models-pytorch/) [![Python - Version](https://img.shields.io/badge/PYTHON-3.9+-red?style=for-the-badge&logo=python&logoColor=white)](https://pepy.tech/project/segmentation-models-pytorch) [![PyTorch - Version](https://img.shields.io/badge/PYTORCH-2.7+-red?style=for-the-badge&logo=pytorch)](https://pepy.tech/project/ghonn-models-pytorch)
+[![PyPI](https://img.shields.io/pypi/v/ghonn-models-pytorch?color=red&style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/ghonn-models-pytorch/) [![Python - Version](https://img.shields.io/badge/PYTHON-3.9+-red?style=for-the-badge&logo=python&logoColor=white)](https://pepy.tech/project/ghonn-models-pytorch) [![PyTorch - Version](https://img.shields.io/badge/PYTORCH-2.7+-red?style=for-the-badge&logo=pytorch)](https://pepy.tech/project/ghonn-models-pytorch)
 
-[![License](https://img.shields.io/badge/License-MIT-<COLOR>.svg?style=for-the-badge&color=blue)](https://github.com/carnosi/ghonn_models_pytorch/blob/main/LICENSE)
+[![License](https://img.shields.io/badge/License-MIT-<COLOR>?style=for-the-badge&color=blue)](https://github.com/carnosi/ghonn_models_pytorch/blob/main/LICENSE)
 
 </div>
 
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -63,7 +63,7 @@ def get_version():
 autodoc_mock_imports = [
     "torch",
     "numpy",
-    "ghonn_models_pytorch",
+    # "ghonn_models_pytorch",
 ]
 
 autoclass_content = "both"
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -0,0 +1,21 @@
+.. _examples:
+
+Examples 🧪
+============
+This section contains a collection of examples that demonstrate how you can use the GHONN Models library.
+Examples are in general provided in the form of Jupyter notebooks, which can be run interactively.
+New examples will be added over time, so check back every now and then.
+
+Available Jupyter notebooks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+- `01_air_passanger_prediction.ipynb <https://github.com/carnosi/ghonn_models_pytorch/blob/main/examples/01_air_passanger_prediction.ipynb>`_
+
+Dataset loader API
+~~~~~~~~~~~~~~~~~~~
+.. autofunction:: ghonn_models_pytorch.datasets.load_example_dataset
+
+
+Available Datasets
+~~~~~~~~~~~~~~~~~~~~
+.. automodule:: ghonn_models_pytorch.datasets.collections
+    :members:
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -13,6 +13,7 @@ Welcome to GHONN Models's documentation!
 
    install
    quickstart
+   examples
    neurons
    network_layers
    insights
@@ -23,3 +24,14 @@ Indices and tables
 * :ref:`modindex`
 * :ref:`search`
 
+References
+==========
+
+.. [Jiang_KATS_2022] Xiaodong Jiang, Sudeep Srivastava, Sourav Chatterjee, Yang Yu, Jeffrey Handler,
+   Peiyi Zhang, Rohan Bopardikar, Dawei Li, Yanjun Lin, Uttam Thakore, Michael Brundage, Ginger Holt,
+   Caner Komurlu, Rakshita Nagalla, Zhichao Wang, Hechao Sun, Peng Gao, Wei Cheung, Jun Gao, Qi Wang,
+   Marius Guerard, Morteza Kazemi, Yulin Chen, Chong Zhou, Sean Lee, Nikolay Laptev, Tihamér Levendovszky,
+   Jake Taylor, Huijun Qian, Jian Zhang, Aida Shoydokova, Trisha Singh, Chengjun Zhu, Zeynep Baz,
+   Christoph Bergmeir, Di Yu, Ahmet Koylan, Kun Jiang, Ploy Temiyasathit, and Emre Yurtbay.
+   Kats. 3 2022. `https://github.com/facebookresearch/Kats <https://github.com/facebookresearch/Kats>`_.
+
diff --git a/docs/source/network_layers.rst b/docs/source/network_layers.rst
@@ -10,10 +10,10 @@ Network Layers 🧩
 
 HONN
 ~~~~
-.. autoclass:: ghonn_models_pytorch.HONN
+.. autoclass:: ghonn_models_pytorch.core.HONN
 
 .. _ghonn:
 
 GHONN
 ~~~~~
-.. autoclass:: ghonn_models_pytorch.GHONN
+.. autoclass:: ghonn_models_pytorch.core.GHONN
diff --git a/docs/source/neurons.rst b/docs/source/neurons.rst
@@ -10,10 +10,10 @@ Neurons 🧠
 
 HONU
 ~~~~
-.. autoclass:: ghonn_models_pytorch.HONU
+.. autoclass:: ghonn_models_pytorch.core.HONU
 
 .. _ghonu:
 
 GHONU
 ~~~~~
-.. autoclass:: ghonn_models_pytorch.GHONU
+.. autoclass:: ghonn_models_pytorch.core.GHONU
diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst
@@ -87,5 +87,5 @@ Quick Start 🚀
             # Update weights
             optimizer.step()
 
-For more information you can check the following examples:
-- TBD
+.. note::
+    For additional details and practical usage, please refer to the :doc:`examples` section.
diff --git a/examples/01_air_passanger_prediction.ipynb b/examples/01_air_passanger_prediction.ipynb
diff --git a/ghonn_models_pytorch/__init__.py b/ghonn_models_pytorch/__init__.py
@@ -1,10 +1,8 @@
 """GHONN - A Python package for Gated Higher Order Neural Networks."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 
-from .ghonn import GHONN
-from .ghonu import GHONU
-from .honn import HONN
-from .honu import HONU
+from .core import GHONN, GHONU, HONN, HONU
+from .datasets import load_example_dataset
 
-__all__ = ["GHONN", "GHONU", "HONN", "HONU"]
+__all__ = ["GHONN", "GHONU", "HONN", "HONU", "load_example_dataset"]
diff --git a/ghonn_models_pytorch/core/__init__.py b/ghonn_models_pytorch/core/__init__.py
@@ -0,0 +1,8 @@
+"""Core modules for elementary neurons and layers."""
+
+from .ghonn import GHONN
+from .ghonu import GHONU
+from .honn import HONN
+from .honu import HONU
+
+__all__ = ["GHONN", "GHONU", "HONN", "HONU"]
diff --git a/ghonn_models_pytorch/core/ghonn.py b/ghonn_models_pytorch/core/ghonn.py
diff --git a/ghonn_models_pytorch/core/ghonu.py b/ghonn_models_pytorch/core/ghonu.py
diff --git a/ghonn_models_pytorch/core/honn.py b/ghonn_models_pytorch/core/honn.py
diff --git a/ghonn_models_pytorch/core/honu.py b/ghonn_models_pytorch/core/honu.py
@@ -47,9 +47,9 @@ def __init__(
             activation (str, optional): Activation function to be used, by default "identity".
             **kwargs: Additional keyword arguments:
 
-                weight_divisor (int or float, optional): Divisor for the randomly initialized
-                    weights, by default 100.0.
-                bias (bool, optional): Whether to include a bias term in the model, by default True.
+                - weight_divisor (int or float, optional): Divisor for the randomly initialized
+                  weights, by default 100.0.
+                - bias (bool, optional): Whether to include a bias term, by default True.
 
         Attributes:
             order (int): Polynomial order of the model.
diff --git a/ghonn_models_pytorch/core/utils.py b/ghonn_models_pytorch/core/utils.py
diff --git a/ghonn_models_pytorch/datasets/__init__.py b/ghonn_models_pytorch/datasets/__init__.py
@@ -0,0 +1,9 @@
+"""Functions to load example datasets."""
+
+__version__ = "0.0.1"
+
+from .data_loaders import load_example_dataset
+
+__all__ = [
+    "load_example_dataset",
+]
diff --git a/ghonn_models_pytorch/datasets/collections.py b/ghonn_models_pytorch/datasets/collections.py
@@ -0,0 +1,20 @@
+"""This module provides API to datasets for experimentation with the repository."""
+
+__version__ = "0.0.1"
+
+
+def air_passenger() -> str:
+    """Returns the URL for the Air Passenger dataset.
+
+    This dataset is taken from the Kats Repository in the Facebook research repo,
+    see [Jiang_KATS_2022]_.
+    """
+    return "https://raw.githubusercontent.com/facebookresearch/Kats/refs/heads/main/kats/data/air_passengers.csv"  # pylint: disable=line-too-long
+
+
+if __name__ == "__main__":
+    from pathlib import Path
+
+    filename = Path(__file__).name
+    MSG = f"The {filename} is not meant to be run as a script."
+    raise OSError(MSG)
diff --git a/ghonn_models_pytorch/datasets/data_loaders.py b/ghonn_models_pytorch/datasets/data_loaders.py
@@ -0,0 +1,52 @@
+"""Dataset loading functions."""
+
+import inspect
+from types import FunctionType
+from typing import Any
+
+import pandas as pd
+
+from . import collections
+
+__version__ = "0.0.1"
+
+
+def _get_dataset_functions() -> dict[str, FunctionType]:
+    """Return a dict mapping dataset names to their URL-returning functions."""
+    return {
+        name: func
+        for name, func in inspect.getmembers(collections, inspect.isfunction)
+        if not name.startswith("_")  # skip private/internal functions
+    }
+
+
+def load_example_dataset(name: str, **kwargs: dict[str, Any]) -> pd.DataFrame:
+    """Unified dataset loader interface from collections module.
+
+    This function loads datasets from the collections module based on the provided name,
+    which corresponds to the function names in the collections module.
+
+    Args:
+        name: Name of the dataset to load which matches function names in the collections module.
+        **kwargs: Additional keyword arguments for pandas readers.
+
+    Returns:
+        The requested dataset as a DataFrame.
+
+    Raises:
+        ValueError: If the dataset name is not recognized.
+    """
+    dataset_funcs = _get_dataset_functions()
+    if name not in dataset_funcs:
+        msg = f"Unknown dataset: {name}, available datasets are: {list(dataset_funcs.keys())}"
+        raise ValueError(msg)
+    url = dataset_funcs[name]()
+    return pd.read_csv(url, **kwargs)
+
+
+if __name__ == "__main__":
+    from pathlib import Path
+
+    filename = Path(__file__).name
+    MSG = f"The {filename} is not meant to be run as a script."
+    raise OSError(MSG)
diff --git a/pyproject.toml b/pyproject.toml
@@ -21,32 +21,39 @@ classifiers = [
     "Operating System :: OS Independent",
 ]
 dependencies = [
-    "torch>=2.7.0",
+    "torch~=2.7.0",
     "numpy~=2.2.0",
+    "pandas~=2.2.0",
 ]
 dynamic = ["version"]
 
 [project.optional-dependencies]
-docs= [
+docs = [
     "sphinx",
     "autodocsumm",
     "sphinx-book-theme",
 ]
 dev = [
     "ruff>=0.11",
     "mypy",
-    "jupyter",
     "setuptools",
     "pylint",
     "build",
 ]
+examples = [
+    "matplotlib",
+    "jupyter",
+    "sklearn",
+    "tqdm",
+]
 
 [project.urls]
-Homepage = "https://github.com/carnosi/ghonn_models_pytorch"
+Homepage = "https://gmp.readthedocs.io/en/latest/"
 Repository = "https://github.com/carnosi/ghonn_models_pytorch"
 
 [tool.ruff]
 line-length = 100
+extend-include = ["*.ipynb"]
 exclude = [
     ".git",
     ".mypy_cache",

Original file line number	Diff line number	Diff line change
`@@ -63,7 +63,7 @@ def get_version():`
`63`	`63`	`autodoc_mock_imports = [`
`64`	`64`	`"torch",`
`65`	`65`	`"numpy",`
`66`		`- "ghonn_models_pytorch",`
	`66`	`+ # "ghonn_models_pytorch",`
`67`	`67`	`]`
`68`	`68`
`69`	`69`	`autoclass_content = "both"`