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.
Files changed (66) hide show
  1. vaelchi-0.1.0/.coveragerc +12 -0
  2. vaelchi-0.1.0/.readthedocs.yml +22 -0
  3. vaelchi-0.1.0/CHANGELOG.md +24 -0
  4. vaelchi-0.1.0/LICENSE +21 -0
  5. vaelchi-0.1.0/MANIFEST.in +13 -0
  6. vaelchi-0.1.0/PKG-INFO +113 -0
  7. vaelchi-0.1.0/README-PYPI.md +54 -0
  8. vaelchi-0.1.0/README.md +114 -0
  9. vaelchi-0.1.0/conftest.py +15 -0
  10. vaelchi-0.1.0/docs/CLUSTERING.md +79 -0
  11. vaelchi-0.1.0/docs/QUALITY.md +132 -0
  12. vaelchi-0.1.0/docs/QUALITY_GATES.md +143 -0
  13. vaelchi-0.1.0/docs/RELEASING.md +35 -0
  14. vaelchi-0.1.0/docs/_static/custom.css +86 -0
  15. vaelchi-0.1.0/docs/_static/vaelchi-logo-dark.png +0 -0
  16. vaelchi-0.1.0/docs/_static/vaelchi-logo-light.png +0 -0
  17. vaelchi-0.1.0/docs/api.rst +29 -0
  18. vaelchi-0.1.0/docs/changelog.rst +5 -0
  19. vaelchi-0.1.0/docs/conf.py +71 -0
  20. vaelchi-0.1.0/docs/examples/multiyear_representative_days.ipynb +1005 -0
  21. vaelchi-0.1.0/docs/examples/representative_days.ipynb +97 -0
  22. vaelchi-0.1.0/docs/examples/script.rst +20 -0
  23. vaelchi-0.1.0/docs/index.rst +58 -0
  24. vaelchi-0.1.0/docs/license.rst +5 -0
  25. vaelchi-0.1.0/docs/tutorials/filling_missing_values.rst +50 -0
  26. vaelchi-0.1.0/docs/tutorials/getting_started/clustering.rst +46 -0
  27. vaelchi-0.1.0/docs/tutorials/getting_started/index.rst +8 -0
  28. vaelchi-0.1.0/docs/tutorials/getting_started/installation.rst +43 -0
  29. vaelchi-0.1.0/docs/validation/ahc/README.md +11 -0
  30. vaelchi-0.1.0/docs/validation/ahc/historical.json +13124 -0
  31. vaelchi-0.1.0/docs/validation/ahc/port-parity.json +161 -0
  32. vaelchi-0.1.0/docs/validation/ahc/source-hashes.json +6 -0
  33. vaelchi-0.1.0/examples/representative_days.py +33 -0
  34. vaelchi-0.1.0/pyproject.toml +88 -0
  35. vaelchi-0.1.0/requirements/quality-macos-x86_64-py313.json +161 -0
  36. vaelchi-0.1.0/requirements/quality-macos-x86_64-py313.lock +151 -0
  37. vaelchi-0.1.0/ruff.toml +37 -0
  38. vaelchi-0.1.0/setup.cfg +4 -0
  39. vaelchi-0.1.0/src/vaelchi/__init__.py +10 -0
  40. vaelchi-0.1.0/src/vaelchi/algorithms/__init__.py +5 -0
  41. vaelchi-0.1.0/src/vaelchi/algorithms/ahc.py +265 -0
  42. vaelchi-0.1.0/src/vaelchi/functions/generate.py +26 -0
  43. vaelchi-0.1.0/src/vaelchi/functions/legacy.py +45 -0
  44. vaelchi-0.1.0/src/vaelchi/functions/measure.py +16 -0
  45. vaelchi-0.1.0/src/vaelchi/functions/other.py +38 -0
  46. vaelchi-0.1.0/src/vaelchi/preprocessing.py +143 -0
  47. vaelchi-0.1.0/src/vaelchi/result.py +56 -0
  48. vaelchi-0.1.0/src/vaelchi.egg-info/PKG-INFO +113 -0
  49. vaelchi-0.1.0/src/vaelchi.egg-info/SOURCES.txt +64 -0
  50. vaelchi-0.1.0/src/vaelchi.egg-info/dependency_links.txt +1 -0
  51. vaelchi-0.1.0/src/vaelchi.egg-info/requires.txt +41 -0
  52. vaelchi-0.1.0/src/vaelchi.egg-info/top_level.txt +1 -0
  53. vaelchi-0.1.0/tests/__init__.py +0 -0
  54. vaelchi-0.1.0/tests/ahc_test.py +208 -0
  55. vaelchi-0.1.0/tests/generate_test.py +29 -0
  56. vaelchi-0.1.0/tests/preprocessing_test.py +177 -0
  57. vaelchi-0.1.0/tests/result_test.py +54 -0
  58. vaelchi-0.1.0/tools/profile_context.py +182 -0
  59. vaelchi-0.1.0/tools/profile_stats.py +339 -0
  60. vaelchi-0.1.0/tools/pytest_profile.py +198 -0
  61. vaelchi-0.1.0/tools/quality.py +432 -0
  62. vaelchi-0.1.0/tools/quality_checks.py +62 -0
  63. vaelchi-0.1.0/tools/quality_lock.py +178 -0
  64. vaelchi-0.1.0/tools/test_profile.py +372 -0
  65. vaelchi-0.1.0/tools/test_quality.py +99 -0
  66. vaelchi-0.1.0/tox.ini +12 -0
@@ -0,0 +1,12 @@
1
+ # measure complete source and branches.
2
+ [run]
3
+ source = src/vaelchi
4
+ branch = True
5
+ relative_files = True
6
+
7
+ [report]
8
+ show_missing = True
9
+ include_namespace_packages = True
10
+
11
+ [xml]
12
+ output = quality/reports/coverage.xml
@@ -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
+ ![Vaelchi](https://raw.githubusercontent.com/cacodcar/vaelchi/main/docs/_static/vaelchi-logo-light.png)
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
+ ![Vaelchi](https://raw.githubusercontent.com/cacodcar/vaelchi/main/docs/_static/vaelchi-logo-light.png)
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.
@@ -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
+ [![Version](https://img.shields.io/badge/version-0.1.0--pre--alpha-orange)](https://github.com/cacodcar/vaelchi/blob/main/CHANGELOG.md)
8
+ [![Python Versions](https://img.shields.io/badge/python-3.12%2B-blue)](https://github.com/cacodcar/vaelchi/blob/main/pyproject.toml)
9
+ [![Documentation](https://img.shields.io/badge/docs-source-blue)](https://github.com/cacodcar/vaelchi/tree/main/docs)
10
+
11
+ <!-- Quality and development -->
12
+ [![Quality](https://github.com/cacodcar/vaelchi/actions/workflows/quality.yml/badge.svg)](https://github.com/cacodcar/vaelchi/actions/workflows/quality.yml)
13
+ [![Coverage](https://codecov.io/gh/cacodcar/vaelchi/graph/badge.svg)](https://codecov.io/gh/cacodcar/vaelchi)
14
+ [![License](https://img.shields.io/github/license/cacodcar/vaelchi)](https://github.com/cacodcar/vaelchi/blob/main/LICENSE)
15
+ [![Last Commit](https://img.shields.io/github/last-commit/cacodcar/vaelchi)](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.