vaelchi 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- vaelchi-0.1.0/.coveragerc +12 -0
- vaelchi-0.1.0/.readthedocs.yml +22 -0
- vaelchi-0.1.0/CHANGELOG.md +24 -0
- vaelchi-0.1.0/LICENSE +21 -0
- vaelchi-0.1.0/MANIFEST.in +13 -0
- vaelchi-0.1.0/PKG-INFO +113 -0
- vaelchi-0.1.0/README-PYPI.md +54 -0
- vaelchi-0.1.0/README.md +114 -0
- vaelchi-0.1.0/conftest.py +15 -0
- vaelchi-0.1.0/docs/CLUSTERING.md +79 -0
- vaelchi-0.1.0/docs/QUALITY.md +132 -0
- vaelchi-0.1.0/docs/QUALITY_GATES.md +143 -0
- vaelchi-0.1.0/docs/RELEASING.md +35 -0
- vaelchi-0.1.0/docs/_static/custom.css +86 -0
- vaelchi-0.1.0/docs/_static/vaelchi-logo-dark.png +0 -0
- vaelchi-0.1.0/docs/_static/vaelchi-logo-light.png +0 -0
- vaelchi-0.1.0/docs/api.rst +29 -0
- vaelchi-0.1.0/docs/changelog.rst +5 -0
- vaelchi-0.1.0/docs/conf.py +71 -0
- vaelchi-0.1.0/docs/examples/multiyear_representative_days.ipynb +1005 -0
- vaelchi-0.1.0/docs/examples/representative_days.ipynb +97 -0
- vaelchi-0.1.0/docs/examples/script.rst +20 -0
- vaelchi-0.1.0/docs/index.rst +58 -0
- vaelchi-0.1.0/docs/license.rst +5 -0
- vaelchi-0.1.0/docs/tutorials/filling_missing_values.rst +50 -0
- vaelchi-0.1.0/docs/tutorials/getting_started/clustering.rst +46 -0
- vaelchi-0.1.0/docs/tutorials/getting_started/index.rst +8 -0
- vaelchi-0.1.0/docs/tutorials/getting_started/installation.rst +43 -0
- vaelchi-0.1.0/docs/validation/ahc/README.md +11 -0
- vaelchi-0.1.0/docs/validation/ahc/historical.json +13124 -0
- vaelchi-0.1.0/docs/validation/ahc/port-parity.json +161 -0
- vaelchi-0.1.0/docs/validation/ahc/source-hashes.json +6 -0
- vaelchi-0.1.0/examples/representative_days.py +33 -0
- vaelchi-0.1.0/pyproject.toml +88 -0
- vaelchi-0.1.0/requirements/quality-macos-x86_64-py313.json +161 -0
- vaelchi-0.1.0/requirements/quality-macos-x86_64-py313.lock +151 -0
- vaelchi-0.1.0/ruff.toml +37 -0
- vaelchi-0.1.0/setup.cfg +4 -0
- vaelchi-0.1.0/src/vaelchi/__init__.py +10 -0
- vaelchi-0.1.0/src/vaelchi/algorithms/__init__.py +5 -0
- vaelchi-0.1.0/src/vaelchi/algorithms/ahc.py +265 -0
- vaelchi-0.1.0/src/vaelchi/functions/generate.py +26 -0
- vaelchi-0.1.0/src/vaelchi/functions/legacy.py +45 -0
- vaelchi-0.1.0/src/vaelchi/functions/measure.py +16 -0
- vaelchi-0.1.0/src/vaelchi/functions/other.py +38 -0
- vaelchi-0.1.0/src/vaelchi/preprocessing.py +143 -0
- vaelchi-0.1.0/src/vaelchi/result.py +56 -0
- vaelchi-0.1.0/src/vaelchi.egg-info/PKG-INFO +113 -0
- vaelchi-0.1.0/src/vaelchi.egg-info/SOURCES.txt +64 -0
- vaelchi-0.1.0/src/vaelchi.egg-info/dependency_links.txt +1 -0
- vaelchi-0.1.0/src/vaelchi.egg-info/requires.txt +41 -0
- vaelchi-0.1.0/src/vaelchi.egg-info/top_level.txt +1 -0
- vaelchi-0.1.0/tests/__init__.py +0 -0
- vaelchi-0.1.0/tests/ahc_test.py +208 -0
- vaelchi-0.1.0/tests/generate_test.py +29 -0
- vaelchi-0.1.0/tests/preprocessing_test.py +177 -0
- vaelchi-0.1.0/tests/result_test.py +54 -0
- vaelchi-0.1.0/tools/profile_context.py +182 -0
- vaelchi-0.1.0/tools/profile_stats.py +339 -0
- vaelchi-0.1.0/tools/pytest_profile.py +198 -0
- vaelchi-0.1.0/tools/quality.py +432 -0
- vaelchi-0.1.0/tools/quality_checks.py +62 -0
- vaelchi-0.1.0/tools/quality_lock.py +178 -0
- vaelchi-0.1.0/tools/test_profile.py +372 -0
- vaelchi-0.1.0/tools/test_quality.py +99 -0
- vaelchi-0.1.0/tox.ini +12 -0
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Read the Docs configuration file for Sphinx projects
|
|
2
|
+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
|
|
3
|
+
|
|
4
|
+
# Required
|
|
5
|
+
version: 2
|
|
6
|
+
|
|
7
|
+
# Set the OS, Python version and other tools you might need
|
|
8
|
+
build:
|
|
9
|
+
os: ubuntu-22.04
|
|
10
|
+
tools:
|
|
11
|
+
python: "3.13"
|
|
12
|
+
|
|
13
|
+
python:
|
|
14
|
+
install:
|
|
15
|
+
- method: pip
|
|
16
|
+
path: .
|
|
17
|
+
extra_requirements:
|
|
18
|
+
- docs
|
|
19
|
+
|
|
20
|
+
# Build documentation in the "docs/" directory with Sphinx
|
|
21
|
+
sphinx:
|
|
22
|
+
configuration: docs/conf.py
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented here.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
## 0.1.0 — unreleased
|
|
10
|
+
|
|
11
|
+
- Release Vaelchi as a standalone time-series preprocessing and clustering package.
|
|
12
|
+
- Provide calendar-aware missing-value filling for pandas Series and DataFrames,
|
|
13
|
+
with forward fill, backward fill, and time interpolation.
|
|
14
|
+
- Add multiyear representative-day examples with chronological mappings and
|
|
15
|
+
weighted energy accounting.
|
|
16
|
+
|
|
17
|
+
- Align Python quality gates with Gana, including automatic test profiles,
|
|
18
|
+
isolated documentation builds, and checked numerical dependency typing.
|
|
19
|
+
|
|
20
|
+
- Prepare the first pre-alpha distribution for Python 3.12 and newer.
|
|
21
|
+
- Provide adjacency-constrained AHC and framework-independent results.
|
|
22
|
+
- Retain the default `legacy` selection policy and original author credits.
|
|
23
|
+
- Add a two-feature representative-day script and notebook example.
|
|
24
|
+
- Provide Sphinx Book Theme documentation with tutorials and API reference.
|
vaelchi-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2023-2026 Rahul Kakodkar
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# include reproducible user documentation.
|
|
2
|
+
include README.md README-PYPI.md CHANGELOG.md LICENSE conftest.py
|
|
3
|
+
include .coveragerc ruff.toml tox.ini .readthedocs.yml
|
|
4
|
+
recursive-include examples *.py
|
|
5
|
+
# OpenAI Codex: preserve the documentation logos in source distributions.
|
|
6
|
+
recursive-include docs *.rst *.md *.py *.css *.ipynb *.json *.png
|
|
7
|
+
recursive-include tests *.py
|
|
8
|
+
recursive-include tools *.py
|
|
9
|
+
recursive-include requirements *.lock *.json
|
|
10
|
+
prune docs/_build
|
|
11
|
+
global-exclude __pycache__ *.py[cod] .DS_Store
|
|
12
|
+
|
|
13
|
+
prune build
|
vaelchi-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: vaelchi
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Time-series clustering and representative periods
|
|
5
|
+
Author-email: Rahul Kakodkar <cacodcar@gmail.com>
|
|
6
|
+
Maintainer-email: Rahul Kakodkar <cacodcar@gmail.com>
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
Project-URL: Homepage, https://github.com/cacodcar/vaelchi
|
|
9
|
+
Project-URL: Issues, https://github.com/cacodcar/vaelchi/issues
|
|
10
|
+
Keywords: representative days,modeling,energy systems,clustering
|
|
11
|
+
Classifier: Development Status :: 2 - Pre-Alpha
|
|
12
|
+
Classifier: Intended Audience :: Science/Research
|
|
13
|
+
Classifier: Topic :: Scientific/Engineering
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Requires-Python: >=3.12
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
License-File: LICENSE
|
|
20
|
+
Requires-Dist: pandas
|
|
21
|
+
Requires-Dist: numpy
|
|
22
|
+
Requires-Dist: scipy
|
|
23
|
+
Requires-Dist: scikit-learn
|
|
24
|
+
Provides-Extra: test
|
|
25
|
+
Requires-Dist: coverage; extra == "test"
|
|
26
|
+
Requires-Dist: pytest; extra == "test"
|
|
27
|
+
Requires-Dist: pytest-cov; extra == "test"
|
|
28
|
+
Requires-Dist: hypothesis; extra == "test"
|
|
29
|
+
Requires-Dist: flake8; extra == "test"
|
|
30
|
+
Requires-Dist: radon; extra == "test"
|
|
31
|
+
Requires-Dist: ruff==0.16.9; extra == "test"
|
|
32
|
+
Requires-Dist: tox; extra == "test"
|
|
33
|
+
Provides-Extra: quality
|
|
34
|
+
Requires-Dist: radon; extra == "quality"
|
|
35
|
+
Requires-Dist: ruff==0.16.9; extra == "quality"
|
|
36
|
+
Requires-Dist: mypy; extra == "quality"
|
|
37
|
+
Requires-Dist: tox; extra == "quality"
|
|
38
|
+
Requires-Dist: build; extra == "quality"
|
|
39
|
+
Requires-Dist: setuptools; extra == "quality"
|
|
40
|
+
Requires-Dist: wheel; extra == "quality"
|
|
41
|
+
Requires-Dist: packaging; extra == "quality"
|
|
42
|
+
Requires-Dist: pandas-stubs==3.0.5.260914; extra == "quality"
|
|
43
|
+
Requires-Dist: scipy-stubs==1.18.1.1; extra == "quality"
|
|
44
|
+
Provides-Extra: docs
|
|
45
|
+
Requires-Dist: sphinx; extra == "docs"
|
|
46
|
+
Requires-Dist: sphinx-book-theme; extra == "docs"
|
|
47
|
+
Requires-Dist: nbsphinx; extra == "docs"
|
|
48
|
+
Requires-Dist: sphinx_mdinclude; extra == "docs"
|
|
49
|
+
Requires-Dist: myst-nb; extra == "docs"
|
|
50
|
+
Requires-Dist: sphinxcontrib-bibtex; extra == "docs"
|
|
51
|
+
Requires-Dist: sphinx-copybutton; extra == "docs"
|
|
52
|
+
Requires-Dist: sphinx-togglebutton; extra == "docs"
|
|
53
|
+
Requires-Dist: sphinx-thebe; extra == "docs"
|
|
54
|
+
Requires-Dist: sphinx-design; extra == "docs"
|
|
55
|
+
Requires-Dist: sphinx-examples; extra == "docs"
|
|
56
|
+
Requires-Dist: sphinx-tabs; extra == "docs"
|
|
57
|
+
Requires-Dist: sphinxext-opengraph; extra == "docs"
|
|
58
|
+
Dynamic: license-file
|
|
59
|
+
|
|
60
|
+

|
|
61
|
+
|
|
62
|
+
# Vaelchi
|
|
63
|
+
|
|
64
|
+
Vaelchi is a standalone Python package for time-series preprocessing, clustering,
|
|
65
|
+
and representative periods. Version **0.1.0** is the first **pre-alpha** release;
|
|
66
|
+
the API may change in later releases.
|
|
67
|
+
|
|
68
|
+
## Installation
|
|
69
|
+
|
|
70
|
+
Python 3.12 or newer is required.
|
|
71
|
+
|
|
72
|
+
```sh
|
|
73
|
+
python -m pip install vaelchi
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Features
|
|
77
|
+
|
|
78
|
+
- Cluster consecutive periods with adjacency-constrained agglomerative
|
|
79
|
+
hierarchical clustering (AHC).
|
|
80
|
+
- Complete timestamped calendars and fill missing values using forward fill,
|
|
81
|
+
backward fill, or time interpolation.
|
|
82
|
+
- Select observed representative profiles and retain their original units.
|
|
83
|
+
- Export profiles, chronological mappings, weights, and errors as plain data.
|
|
84
|
+
|
|
85
|
+
## Quick start
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
from vaelchi import ahc
|
|
89
|
+
|
|
90
|
+
result = ahc(
|
|
91
|
+
[10, 12, 10, 12, 20, 24, 20, 24],
|
|
92
|
+
periods=2,
|
|
93
|
+
period_length=2,
|
|
94
|
+
selection="nearest_centroid",
|
|
95
|
+
)
|
|
96
|
+
print(result.weights) # [2 2]
|
|
97
|
+
payload = result.to_dict()
|
|
98
|
+
chronological_values = result.reconstruct()
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Each positional input is one feature. Four two-timestep periods become two
|
|
102
|
+
representative periods. Profiles retain input units; weights count the original
|
|
103
|
+
periods assigned to each representative. The default selection policy is
|
|
104
|
+
`legacy`; this example explicitly selects `nearest_centroid` to choose an
|
|
105
|
+
observed member of each cluster.
|
|
106
|
+
|
|
107
|
+
See the [repository and installation guide](https://github.com/cacodcar/vaelchi),
|
|
108
|
+
[examples](https://github.com/cacodcar/vaelchi/tree/main/docs/examples), and
|
|
109
|
+
[documentation source](https://github.com/cacodcar/vaelchi/tree/main/docs).
|
|
110
|
+
Report problems through [GitHub Issues](https://github.com/cacodcar/vaelchi/issues).
|
|
111
|
+
|
|
112
|
+
MIT license, copyright Rahul Kakodkar. Original author credits and numerical
|
|
113
|
+
validation records are retained.
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+

|
|
2
|
+
|
|
3
|
+
# Vaelchi
|
|
4
|
+
|
|
5
|
+
Vaelchi is a standalone Python package for time-series preprocessing, clustering,
|
|
6
|
+
and representative periods. Version **0.1.0** is the first **pre-alpha** release;
|
|
7
|
+
the API may change in later releases.
|
|
8
|
+
|
|
9
|
+
## Installation
|
|
10
|
+
|
|
11
|
+
Python 3.12 or newer is required.
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
python -m pip install vaelchi
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Features
|
|
18
|
+
|
|
19
|
+
- Cluster consecutive periods with adjacency-constrained agglomerative
|
|
20
|
+
hierarchical clustering (AHC).
|
|
21
|
+
- Complete timestamped calendars and fill missing values using forward fill,
|
|
22
|
+
backward fill, or time interpolation.
|
|
23
|
+
- Select observed representative profiles and retain their original units.
|
|
24
|
+
- Export profiles, chronological mappings, weights, and errors as plain data.
|
|
25
|
+
|
|
26
|
+
## Quick start
|
|
27
|
+
|
|
28
|
+
```python
|
|
29
|
+
from vaelchi import ahc
|
|
30
|
+
|
|
31
|
+
result = ahc(
|
|
32
|
+
[10, 12, 10, 12, 20, 24, 20, 24],
|
|
33
|
+
periods=2,
|
|
34
|
+
period_length=2,
|
|
35
|
+
selection="nearest_centroid",
|
|
36
|
+
)
|
|
37
|
+
print(result.weights) # [2 2]
|
|
38
|
+
payload = result.to_dict()
|
|
39
|
+
chronological_values = result.reconstruct()
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Each positional input is one feature. Four two-timestep periods become two
|
|
43
|
+
representative periods. Profiles retain input units; weights count the original
|
|
44
|
+
periods assigned to each representative. The default selection policy is
|
|
45
|
+
`legacy`; this example explicitly selects `nearest_centroid` to choose an
|
|
46
|
+
observed member of each cluster.
|
|
47
|
+
|
|
48
|
+
See the [repository and installation guide](https://github.com/cacodcar/vaelchi),
|
|
49
|
+
[examples](https://github.com/cacodcar/vaelchi/tree/main/docs/examples), and
|
|
50
|
+
[documentation source](https://github.com/cacodcar/vaelchi/tree/main/docs).
|
|
51
|
+
Report problems through [GitHub Issues](https://github.com/cacodcar/vaelchi/issues).
|
|
52
|
+
|
|
53
|
+
MIT license, copyright Rahul Kakodkar. Original author credits and numerical
|
|
54
|
+
validation records are retained.
|
vaelchi-0.1.0/README.md
ADDED
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://raw.githubusercontent.com/cacodcar/vaelchi/main/docs/_static/vaelchi-logo-dark.png#gh-dark-mode-only" alt="Vaelchi logo" width="75%">
|
|
3
|
+
<img src="https://raw.githubusercontent.com/cacodcar/vaelchi/main/docs/_static/vaelchi-logo-light.png#gh-light-mode-only" alt="Vaelchi logo" width="75%">
|
|
4
|
+
</p>
|
|
5
|
+
|
|
6
|
+
<!-- Version and documentation -->
|
|
7
|
+
[](https://github.com/cacodcar/vaelchi/blob/main/CHANGELOG.md)
|
|
8
|
+
[](https://github.com/cacodcar/vaelchi/blob/main/pyproject.toml)
|
|
9
|
+
[](https://github.com/cacodcar/vaelchi/tree/main/docs)
|
|
10
|
+
|
|
11
|
+
<!-- Quality and development -->
|
|
12
|
+
[](https://github.com/cacodcar/vaelchi/actions/workflows/quality.yml)
|
|
13
|
+
[](https://codecov.io/gh/cacodcar/vaelchi)
|
|
14
|
+
[](https://github.com/cacodcar/vaelchi/blob/main/LICENSE)
|
|
15
|
+
[](https://github.com/cacodcar/vaelchi/commits/main)
|
|
16
|
+
|
|
17
|
+
# Vaelchi
|
|
18
|
+
|
|
19
|
+
Vaelchi is a standalone Python package for time-series preprocessing,
|
|
20
|
+
clustering, and representative periods. Version **0.1.0** is the first pre-alpha
|
|
21
|
+
release candidate, providing adjacency-constrained agglomerative hierarchical
|
|
22
|
+
clustering (AHC) for one or more aligned numeric time series.
|
|
23
|
+
|
|
24
|
+
## Features
|
|
25
|
+
|
|
26
|
+
- Cluster consecutive periods with configurable period and parent lengths.
|
|
27
|
+
- Complete timestamped calendars and fill missing values with forward fill,
|
|
28
|
+
backward fill, or time interpolation.
|
|
29
|
+
- Select observed representative profiles and retain their original units.
|
|
30
|
+
- Export profiles, chronological mappings, weights, and errors as plain data
|
|
31
|
+
for other applications.
|
|
32
|
+
|
|
33
|
+
## Installation
|
|
34
|
+
|
|
35
|
+
Python 3.12 or newer is required. Clone the repository and install Vaelchi:
|
|
36
|
+
|
|
37
|
+
```sh
|
|
38
|
+
git clone https://github.com/cacodcar/vaelchi.git
|
|
39
|
+
cd vaelchi
|
|
40
|
+
python -m pip install .
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
For development, install the optional tools:
|
|
44
|
+
|
|
45
|
+
```sh
|
|
46
|
+
python -m pip install -e '.[test,quality,docs]'
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Version 0.1.0 is available from this repository; it has not been published to PyPI.
|
|
50
|
+
You can also install a supplied release wheel in a separate environment:
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
python -m pip install /path/to/vaelchi-0.1.0-py3-none-any.whl
|
|
54
|
+
python -c "import vaelchi; print(vaelchi.__version__)"
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
The printed version should be `0.1.0`. The pre-alpha API may change in later
|
|
58
|
+
releases.
|
|
59
|
+
|
|
60
|
+
## Quick start
|
|
61
|
+
|
|
62
|
+
```python
|
|
63
|
+
|
|
64
|
+
from vaelchi import ahc
|
|
65
|
+
|
|
66
|
+
result = ahc(
|
|
67
|
+
[10, 12, 10, 12, 20, 24, 20, 24],
|
|
68
|
+
periods=2,
|
|
69
|
+
period_length=2,
|
|
70
|
+
selection="nearest_centroid",
|
|
71
|
+
)
|
|
72
|
+
payload = result.to_dict()
|
|
73
|
+
chronological_values = result.reconstruct()
|
|
74
|
+
print(payload["weights"]) # [2, 2]
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Each positional input is one feature. Here, four two-timestep periods become
|
|
78
|
+
two representative periods. `labels` maps each original period to a representative
|
|
79
|
+
row; `weights` counts the original periods assigned to each row. Profiles retain
|
|
80
|
+
input units. The default selection mode is `legacy`, which uses a global
|
|
81
|
+
distance lookup to select profiles. The example explicitly selects
|
|
82
|
+
`nearest_centroid` to choose an observed member of each cluster.
|
|
83
|
+
|
|
84
|
+
## Example and documentation
|
|
85
|
+
|
|
86
|
+
Run the two-feature example from the repository root:
|
|
87
|
+
|
|
88
|
+
```sh
|
|
89
|
+
python examples/representative_days.py
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
The script prints JSON that other applications can read. A matching
|
|
93
|
+
notebook is in `docs/examples/representative_days.ipynb`. For years → days →
|
|
94
|
+
hours, see `docs/examples/multiyear_representative_days.ipynb`, which selects
|
|
95
|
+
20 days per year and explains calendar mappings, weights, and energy accounting.
|
|
96
|
+
Its plots require `matplotlib` in the notebook environment. Documentation uses
|
|
97
|
+
Sphinx Book Theme and includes tutorials, examples, API reference, and project
|
|
98
|
+
information.
|
|
99
|
+
|
|
100
|
+
Build the documentation locally:
|
|
101
|
+
|
|
102
|
+
```sh
|
|
103
|
+
python -m sphinx -W --keep-going -b html docs docs/_build/html
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Open `docs/_build/html/index.html`. For the output contract, see
|
|
107
|
+
[Clustering](https://github.com/cacodcar/vaelchi/blob/main/docs/CLUSTERING.md).
|
|
108
|
+
Quality commands are documented in
|
|
109
|
+
[Quality gates](https://github.com/cacodcar/vaelchi/blob/main/docs/QUALITY_GATES.md).
|
|
110
|
+
|
|
111
|
+
## License and authorship
|
|
112
|
+
|
|
113
|
+
MIT license, copyright Rahul Kakodkar. Original author credits and numerical
|
|
114
|
+
validation records are retained.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
"""Enable automatic function profiles for all repository pytest commands.
|
|
2
|
+
|
|
3
|
+
Ported from Gana cf8f0cd850209db676ee5c04184963de8ab06e2a.
|
|
4
|
+
Vaelchi-specific adaptations retain the shared checking and profiling policy.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
import sys
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
|
|
10
|
+
# The existing quality tools use flat imports from this directory. Loading the
|
|
11
|
+
# plugin by name keeps pytest and mypy consistent without an installed package.
|
|
12
|
+
_TOOLS = str(Path(__file__).resolve().parent / "tools")
|
|
13
|
+
if _TOOLS not in sys.path:
|
|
14
|
+
sys.path.insert(0, _TOOLS)
|
|
15
|
+
pytest_plugins = ["pytest_profile"]
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# Time-series clustering
|
|
2
|
+
|
|
3
|
+
Vaelchi is a standalone package for clustering aligned numeric time series.
|
|
4
|
+
`from vaelchi import ahc, AHCResult` is the public API.
|
|
5
|
+
|
|
6
|
+
```python
|
|
7
|
+
|
|
8
|
+
from vaelchi import ahc
|
|
9
|
+
|
|
10
|
+
result = ahc([10, 11, 12, 11, 20, 21, 22, 21], periods=2)
|
|
11
|
+
reconstructed = result.reconstruct()
|
|
12
|
+
payload = result.to_dict() # JSON-compatible lists/scalars; detached copies.
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Pass one one-dimensional series per positional argument, all equally long and
|
|
16
|
+
aligned. `period_length` is timesteps per period; `parent_length` is original
|
|
17
|
+
periods per independent parent. `periods` is representatives per parent.
|
|
18
|
+
Features retain argument order. Inputs and outputs are positional: labels are
|
|
19
|
+
not timestamps. Callers retain feature names and units outside the result.
|
|
20
|
+
|
|
21
|
+
## Output contract
|
|
22
|
+
|
|
23
|
+
| Field | Shape / meaning |
|
|
24
|
+
| --- | --- |
|
|
25
|
+
| `representatives` | `(representatives, period_length, features)`, original units |
|
|
26
|
+
| `labels` | One zero-based representative-row index per original period |
|
|
27
|
+
| `representative_indices` | Original zero-based period positions, across all parents |
|
|
28
|
+
| `weights` | Original periods assigned to each representative row; sum equals period count |
|
|
29
|
+
| `inertia` | Sum of squared distances to actual centroids in standardized space |
|
|
30
|
+
| `reconstruction_error` | Sum of squared distances to selected profiles in standardized space |
|
|
31
|
+
| `selection` | Representative-selection policy |
|
|
32
|
+
|
|
33
|
+
`reconstruct()` returns `(original_timesteps, features)` by indexing representative
|
|
34
|
+
rows with labels. `to_dict()` preserves the same structure in plain lists and
|
|
35
|
+
scalars. A consumer can use `numpy.asarray(payload["representatives"])[payload[
|
|
36
|
+
"labels"]]` and flatten the first two axes to reconstruct the original chronology.
|
|
37
|
+
Applications can map the columns to their own components and use the weights
|
|
38
|
+
when constructing reduced models.
|
|
39
|
+
|
|
40
|
+
Scaling is per feature/timestep column within each parent. Adjacency is linear,
|
|
41
|
+
without wraparound. The default `selection="legacy"` uses a global distance lookup,
|
|
42
|
+
including repeated or out-of-cluster representatives. Do not deduplicate rows:
|
|
43
|
+
labels and weights address the selected rows independently. The alternative
|
|
44
|
+
`selection="nearest_centroid"` selects a cluster member and resolves numerical
|
|
45
|
+
ties chronologically. One-cluster legacy input uses the existing nearest-member
|
|
46
|
+
fallback. Defaults, error definitions, and numerical choices are unchanged.
|
|
47
|
+
|
|
48
|
+
`vaelchi.functions.legacy` provides the historical standalone squared-distance
|
|
49
|
+
and connectivity helper APIs, including their edge behavior. The newer helpers
|
|
50
|
+
in `vaelchi.functions` remain available. AHC uses its sparse adjacency internally.
|
|
51
|
+
|
|
52
|
+
## Authorship and historical validation
|
|
53
|
+
|
|
54
|
+
Original author credits include Rahul Kakodkar and Efstratios N. Pistikopoulos.
|
|
55
|
+
Revision identifiers and adaptation credits are recorded in the source files.
|
|
56
|
+
|
|
57
|
+
The following measurements describe the historical validation snapshot.
|
|
58
|
+
|
|
59
|
+
- 26 tests passed in Vaelchi's standalone environment.
|
|
60
|
+
- AHC, result and legacy helper modules had 100% statement and branch coverage.
|
|
61
|
+
- Entire Vaelchi coverage was 90.53% of statements and 88% of branches.
|
|
62
|
+
- All functions and classes had Radon A/B complexity, and all modules had
|
|
63
|
+
maintainability rank A.
|
|
64
|
+
- 26 exact comparisons to the saved reference implementation covered five
|
|
65
|
+
historical 8,760-hour datasets, 20/35 representatives, both selection modes,
|
|
66
|
+
and six multi-parent, identity, and single-cluster cases. Labels, indices,
|
|
67
|
+
weights, profiles, reconstruction, and both scalar errors matched exactly
|
|
68
|
+
in the same environment.
|
|
69
|
+
- Ten comparisons to revision `0604a26e` matched legacy indices, weights, and
|
|
70
|
+
profiles exactly. Nearest-centroid membership and independent SSE checks
|
|
71
|
+
passed with SSE relative tolerance `1e-12`.
|
|
72
|
+
|
|
73
|
+
Saved evidence is in `validation/ahc/`. The source hashes identify the original
|
|
74
|
+
tested snapshots. `historical.json` records reference comparisons, and
|
|
75
|
+
`port-parity.json` records the 26 exact comparisons. These reports are historical
|
|
76
|
+
evidence and do not replace validation of the current source and dependencies.
|
|
77
|
+
|
|
78
|
+
Current quality commands and coverage requirements are documented in
|
|
79
|
+
`QUALITY_GATES.md`.
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# Current gate policy
|
|
2
|
+
|
|
3
|
+
The current enforced configuration is documented in [QUALITY_GATES.md](QUALITY_GATES.md).
|
|
4
|
+
The setup descriptions and measurements below record earlier stages and are
|
|
5
|
+
not the current release status. In particular, the old missing-license,
|
|
6
|
+
uncommitted-repository, `.venv` task, and nonblocking-gate descriptions below
|
|
7
|
+
are historical. The MIT license is present, the initial commit is on GitHub,
|
|
8
|
+
and current tasks use `.quality-venv` with blocking gates. Hosted CI and service
|
|
9
|
+
configuration still need independent verification.
|
|
10
|
+
|
|
11
|
+
The November 9, 2026 local validation passed all gates on Python 3.12 and 3.13.
|
|
12
|
+
Its final Python 3.13 run recorded 83 passing tests, 92.92% statement coverage,
|
|
13
|
+
and 92.68% branch coverage. The seven typing errors recorded in October were
|
|
14
|
+
resolved. Dated evidence remains under `quality/runs/`; subsequent release
|
|
15
|
+
checks must retain their own evidence rather than replace those records.
|
|
16
|
+
|
|
17
|
+
# Historical quality setup — September 2026
|
|
18
|
+
|
|
19
|
+
Use Vaelchi's dedicated `.venv` (reference: CPython 3.13.7). From this directory:
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
python3.13 -m venv .venv
|
|
23
|
+
.venv/bin/python -m pip install -e '.[test]'
|
|
24
|
+
.venv/bin/python -m pip check
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
VS Code provides **Vaelchi: All Quality Checks** in `.vscode/tasks.json` and
|
|
28
|
+
individual tasks. Every task uses `.venv/bin/python`; the aggregate runs checks
|
|
29
|
+
independently so a lint failure does not prevent coverage or metrics collection.
|
|
30
|
+
|
|
31
|
+
Equivalent commands:
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
.venv/bin/python -m pytest tests --cov --cov-report=term-missing --cov-report=xml --cov-report=json:quality/reports/coverage.json
|
|
35
|
+
.venv/bin/python -m radon cc src/vaelchi -s -a
|
|
36
|
+
.venv/bin/python -m radon cc src/vaelchi --min B -s -a
|
|
37
|
+
.venv/bin/python -m radon mi src/vaelchi -s
|
|
38
|
+
.venv/bin/python -m radon raw src/vaelchi
|
|
39
|
+
.venv/bin/python -m flake8 src tests
|
|
40
|
+
.venv/bin/python -m ruff check src tests
|
|
41
|
+
.venv/bin/python -m ruff format --check src tests
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Coverage measures both statements and branches, including unimported namespace
|
|
45
|
+
package modules. XML and JSON reports go to ignored `quality/reports/`.
|
|
46
|
+
No arbitrary coverage threshold has been added: compare both measures against
|
|
47
|
+
the recorded baseline and explain regressions. Tests must establish meaningful
|
|
48
|
+
behavior, including historical numerical agreement for AHC ports.
|
|
49
|
+
|
|
50
|
+
Radon reports do not fail on low grades. Review every function against the A/B
|
|
51
|
+
requirement; Ruff's C90 rule additionally enforces McCabe complexity <= 10,
|
|
52
|
+
which is a related measure rather than an exact substitute for Radon.
|
|
53
|
+
Ruff uses the rule selection and exceptions in `ruff.toml`. Explicit `src tests`
|
|
54
|
+
arguments also check tests; Flake8 and formatting checks are non-mutating.
|
|
55
|
+
No type checker was configured in the inspected reference projects.
|
|
56
|
+
|
|
57
|
+
The GitHub workflow checks Python 3.12 and 3.13, fails on lint/format findings,
|
|
58
|
+
and retains coverage artifacts. `.codacy.yaml` configures code analysis.
|
|
59
|
+
The private GitHub repository is `cacodcar/vaelchi`. Remote CI and Codacy
|
|
60
|
+
have not run: no commits or workflow files have been pushed. No publishing
|
|
61
|
+
workflow or upload credentials were added. The referenced LICENSE file remains missing and needs an author
|
|
62
|
+
provided license before release, although editable installation succeeds.
|
|
63
|
+
|
|
64
|
+
## Additional quality gates
|
|
65
|
+
|
|
66
|
+
The following records the gate configuration on 2026-09-28.
|
|
67
|
+
|
|
68
|
+
- `tox.ini` runs test/branch-coverage checks in isolated Python 3.12 and 3.13
|
|
69
|
+
environments. Run `.venv/bin/python -m tox`, or **Vaelchi: Python Version Matrix**.
|
|
70
|
+
Both Python interpreters must be installed. The aggregate VS Code task includes
|
|
71
|
+
the matrix. Each environment writes its own reports under `.tox/`.
|
|
72
|
+
- VS Code pytest discovery is enabled, with unittest discovery disabled.
|
|
73
|
+
- The workflow uploads `quality/reports/coverage.xml` with Codecov's v5 action.
|
|
74
|
+
Upload failures fail CI. A private-project `CODECOV_TOKEN` repository secret
|
|
75
|
+
and the appropriate Codecov repository connection are required; neither was
|
|
76
|
+
provisioned. Coverage remains available as GitHub workflow artifacts.
|
|
77
|
+
- `.githooks/pre-commit` and `.githooks/pre-push` run the shared test/coverage
|
|
78
|
+
gate with `.venv`. They propagate failures, including a missing environment.
|
|
79
|
+
They gate tests/coverage collection; CI separately gates lint and formatting.
|
|
80
|
+
At that stage, Vaelchi had no numeric coverage floor.
|
|
81
|
+
|
|
82
|
+
Hooks are activated in this checkout. After cloning, activate them with:
|
|
83
|
+
|
|
84
|
+
```sh
|
|
85
|
+
git config --local core.hooksPath .githooks
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
The tox matrix passed all 26 tests on each of Python 3.12 and 3.13.
|
|
89
|
+
Expanded tox configuration confirms separate coverage-data paths per environment.
|
|
90
|
+
Direct hook validation ran the test suite successfully (26 tests, exit 0) and
|
|
91
|
+
injected an invalid pytest option into pre-push (exit 4), confirming errors are
|
|
92
|
+
propagated. No commit or push was performed. Shell syntax and YAML/JSON/TOML/INI
|
|
93
|
+
configuration parsing passed. The existing five Flake8 findings, four Ruff
|
|
94
|
+
findings, and two formatting failures remain unchanged. Radon metrics pass;
|
|
95
|
+
A/B ranks remain the required review standard.
|
|
96
|
+
|
|
97
|
+
### Hosted protection limitation
|
|
98
|
+
|
|
99
|
+
GitHub returned HTTP 403 for both Vaelchi rulesets and branch protection with:
|
|
100
|
+
"Upgrade to GitHub Pro or make this repository public to enable this feature."
|
|
101
|
+
Vaelchi was private at the time of this check. Enabling branch protection required
|
|
102
|
+
the GitHub plan capability and an initial branch. Configuration files alone
|
|
103
|
+
do not establish remote protection or connect Codecov/Codacy.
|
|
104
|
+
|
|
105
|
+
Reports for this setup are in `quality/runs/gate-parity/`. The original dated
|
|
106
|
+
baseline below remains unchanged as historical evidence.
|
|
107
|
+
|
|
108
|
+
## Initial baseline: 2026-09-28
|
|
109
|
+
|
|
110
|
+
Raw outputs, commands and exit codes, Python version, exact installed package
|
|
111
|
+
versions, source hashes, and coverage reports are in
|
|
112
|
+
`quality/baselines/2026-09-28/`. This is a measured local snapshot, not Gana's
|
|
113
|
+
platform-specific hash-locked rebuild system. Dependency versions are recorded
|
|
114
|
+
in `requirements.txt`; no claim of cross-platform reproducibility is made.
|
|
115
|
+
Use a new dated directory for future baselines; retain earlier results.
|
|
116
|
+
|
|
117
|
+
- Tests: 1 passed.
|
|
118
|
+
- Statements: 7/23 covered (30.43%). Branches: 2/8 covered (25%).
|
|
119
|
+
- Combined statement/branch coverage: 29.03%.
|
|
120
|
+
- Radon: connectivity_matrix A (2), euclidean_distance A (2), normalize B (10).
|
|
121
|
+
- All modules have maintainability rank A; raw metrics are saved separately.
|
|
122
|
+
- Flake8: six existing findings; same findings as before quality setup.
|
|
123
|
+
- Ruff: five findings in unchanged source/tests (newline, exception message,
|
|
124
|
+
unused pytest import, and two test assertions flagged by S101).
|
|
125
|
+
- Formatting: three existing files would change. No formatter was applied.
|
|
126
|
+
- Dependency consistency and editable package installation passed.
|
|
127
|
+
|
|
128
|
+
The previous 100% report omitted unimported namespace modules. The lower result
|
|
129
|
+
reflects complete measurement, not changed behavior. Source algorithms and tests
|
|
130
|
+
were not rewritten to make these checks green. CI will report the existing
|
|
131
|
+
lint/format failures until they are addressed. Ruff also warns about the inherited
|
|
132
|
+
COM812 rule's possible formatter conflict; it has not been silently disabled.
|