vaelchi 0.1.0__py3-none-any.whl

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/__init__.py ADDED
@@ -0,0 +1,10 @@
1
+ """General time-series clustering with explicit representative mappings."""
2
+
3
+ from .algorithms.ahc import ahc
4
+ from .preprocessing import fill_missing_values
5
+ from .result import AHCResult
6
+
7
+ __all__ = ["AHCResult", "ahc", "fill_missing_values"]
8
+
9
+ # public package version.
10
+ __version__ = "0.1.0"
@@ -0,0 +1,5 @@
1
+ """Time-series clustering algorithms."""
2
+
3
+ from .ahc import ahc
4
+
5
+ __all__ = ["ahc"]
@@ -0,0 +1,265 @@
1
+ """Chronology-constrained aggregation of aligned time series.
2
+
3
+ Standardize profiles, apply adjacent-period Ward clustering, and select
4
+ observed profiles. Historical reference implementation revision 0604a26e.
5
+ Original author: Rahul Kakodkar. Original credits also include
6
+ Efstratios N. Pistikopoulos (Multi-parametric Optimization & Control Lab).
7
+ """
8
+
9
+ from numbers import Integral
10
+ from typing import Literal
11
+
12
+ import numpy as np
13
+ import pandas as pd
14
+ from numpy.typing import ArrayLike
15
+ from scipy.sparse import diags
16
+ from sklearn.cluster import AgglomerativeClustering
17
+ from sklearn.neighbors import NearestCentroid
18
+ from sklearn.preprocessing import StandardScaler
19
+
20
+ from vaelchi.result import AHCResult
21
+
22
+
23
+ def _positive_integer(value: int, name: str) -> int:
24
+ """Require a positive integer while rejecting booleans and fractions."""
25
+ if isinstance(value, bool) or not isinstance(value, Integral) or value < 1:
26
+ message = f"{name} must be a positive integer"
27
+ raise ValueError(message)
28
+ return int(value)
29
+
30
+
31
+ def _legacy_selection(scaled, assignments):
32
+ """Reproduce 0604a26e's centroid labeling and global distance lookup.
33
+
34
+ Keep pandas ordering and Python distance summation as in the historical
35
+ code. This compatibility policy deliberately retains its selection quirks;
36
+ error metrics are still calculated from the actual cluster memberships.
37
+ """
38
+ frame = pd.DataFrame(scaled)
39
+ centroids = NearestCentroid().fit(scaled, assignments).centroids_
40
+ frame["cluster_no"] = assignments
41
+ distances = []
42
+ for centroid, label in zip(centroids, frame["cluster_no"].unique()):
43
+ for point in scaled[assignments == label]:
44
+ distances.append(
45
+ sum((a - b) ** 2 for a, b in zip(point, centroid)),
46
+ )
47
+ frame["ED"] = distances
48
+ selected = pd.DataFrame(
49
+ {
50
+ "label": frame["cluster_no"].value_counts().index.values,
51
+ },
52
+ )
53
+ selected["representative"] = [
54
+ int(
55
+ frame.index[
56
+ frame["ED"]
57
+ == frame.loc[
58
+ frame["cluster_no"] == label,
59
+ "ED",
60
+ ].min()
61
+ ][0],
62
+ )
63
+ for label in selected["label"]
64
+ ]
65
+ selected = selected.sort_values("representative")
66
+ return [
67
+ (np.flatnonzero(assignments == label), int(representative))
68
+ for label, representative in selected.itertuples(
69
+ index=False,
70
+ name=None,
71
+ )
72
+ ]
73
+
74
+
75
+ def _validated_series(data):
76
+ """Convert aligned input series and reject empty or nonfinite values."""
77
+ if not data:
78
+ message = "provide at least one time series"
79
+ raise ValueError(message)
80
+ series = [np.asarray(values, dtype=float) for values in data]
81
+ if any(values.ndim != 1 or not values.size for values in series):
82
+ message = "each time series must be nonempty and one-dimensional"
83
+ raise ValueError(message)
84
+ if any(len(values) != len(series[0]) for values in series):
85
+ message = "time series must have equal lengths"
86
+ raise ValueError(message)
87
+ if any(not np.isfinite(values).all() for values in series):
88
+ message = "time series must contain only finite values"
89
+ raise ValueError(message)
90
+ return series
91
+
92
+
93
+ def _prepare_profiles(data, periods, period_length, parent_length, selection):
94
+ """Validate aggregation dimensions and build complete parent profiles."""
95
+ periods = _positive_integer(periods, "periods")
96
+ period_length = _positive_integer(period_length, "period_length")
97
+ if selection not in ("nearest_centroid", "legacy"):
98
+ message = "selection must be 'nearest_centroid' or 'legacy'"
99
+ raise ValueError(message)
100
+ series = _validated_series(data)
101
+ if len(series[0]) % period_length:
102
+ message = "time series must contain complete periods"
103
+ raise ValueError(message)
104
+ profiles = np.column_stack(series).reshape(-1, period_length, len(series))
105
+ count = len(profiles)
106
+ parent_length = (
107
+ count
108
+ if parent_length is None
109
+ else _positive_integer(
110
+ parent_length,
111
+ "parent_length",
112
+ )
113
+ )
114
+ if count % parent_length:
115
+ message = "time series must contain complete parent groups"
116
+ raise ValueError(message)
117
+ if periods > parent_length:
118
+ message = "periods cannot exceed the original periods per parent"
119
+ raise ValueError(message)
120
+ return profiles, periods, parent_length
121
+
122
+
123
+ def _cluster_parent(block, periods, selection):
124
+ """Standardize one parent and cluster with linear temporal adjacency."""
125
+ parent_length = len(block)
126
+ if selection == "legacy":
127
+ # Match historical feature-major arithmetic order as well as values.
128
+ block = block.transpose(0, 2, 1)
129
+ scaled = StandardScaler().fit_transform(block.reshape(parent_length, -1))
130
+ if periods == 1:
131
+ assignments = np.zeros(parent_length, dtype=np.int64)
132
+ elif periods == parent_length and selection != "legacy":
133
+ assignments = np.arange(parent_length)
134
+ else:
135
+ connectivity = diags(
136
+ # Both off-diagonals contain identical unit weights. A single
137
+ # array also expresses SciPy's documented rectangular input.
138
+ np.ones((2, parent_length - 1)),
139
+ offsets=[-1, 1],
140
+ shape=(parent_length, parent_length),
141
+ format="csr",
142
+ )
143
+ assignments = AgglomerativeClustering(
144
+ n_clusters=periods,
145
+ linkage="ward",
146
+ connectivity=connectivity,
147
+ compute_full_tree=True if selection == "legacy" else "auto",
148
+ ).fit_predict(scaled)
149
+ return scaled, assignments
150
+
151
+
152
+ def _cluster_choices(scaled, assignments, periods, selection):
153
+ """Order clusters and supply historical representatives when requested."""
154
+ if selection == "legacy" and periods > 1:
155
+ return _legacy_selection(scaled, assignments)
156
+ # Cluster ids from sklearn are arbitrary; order by first original member.
157
+ cluster_ids = np.unique(assignments)
158
+ clusters = [np.flatnonzero(assignments == c) for c in cluster_ids]
159
+ clusters.sort(key=lambda members: members[0])
160
+ return [(members, None) for members in clusters]
161
+
162
+
163
+ def _representative_statistics(scaled, members, representative):
164
+ """Select the earliest nearest member if needed and compute cluster
165
+ errors."""
166
+ centroid = scaled[members].mean(axis=0)
167
+ distances = ((scaled[members] - centroid) ** 2).sum(axis=1)
168
+ if representative is None:
169
+ # Members are chronological, so the first numerical tie is the
170
+ # earliest.
171
+ tied = np.flatnonzero(
172
+ np.isclose(
173
+ distances,
174
+ distances.min(),
175
+ rtol=1e-12,
176
+ atol=1e-12,
177
+ ),
178
+ )
179
+ representative = members[tied[0]]
180
+ inertia = float(distances.sum())
181
+ reconstruction_error = float(
182
+ ((scaled[members] - scaled[representative]) ** 2).sum(),
183
+ )
184
+ return representative, inertia, reconstruction_error
185
+
186
+
187
+ def ahc(
188
+ *data: ArrayLike,
189
+ periods: int,
190
+ period_length: int = 1,
191
+ parent_length: int | None = None,
192
+ selection: Literal["nearest_centroid", "legacy"] = "legacy",
193
+ ) -> AHCResult:
194
+ """Cluster aligned one-dimensional series into representative periods.
195
+
196
+ :param data: One or more finite numeric series with equal lengths. Features
197
+ retain their argument order; inputs are aligned positionally.
198
+ :param periods: Number of representative periods **per parent group**.
199
+ :param period_length: Timesteps in each original period, e.g. 24 for days
200
+ sampled hourly. All periods must be complete and equally long.
201
+ :param parent_length: Original periods per independent parent group, e.g.
202
+ 365 days per year. Defaults to all periods in one group. All parent
203
+ groups must be complete; clustering never crosses their boundaries.
204
+ :param selection: Defaults to ``legacy``. ``nearest_centroid`` selects
205
+ the nearest cluster member,
206
+ breaking numerical ties with the earliest period. ``legacy`` reproduces
207
+ historical centroid-label association and representative lookup,
208
+ including
209
+ possible repeated or out-of-cluster representatives. Both policies
210
+ retain
211
+ the corrected error metrics. For a single cluster, where the historical
212
+ NearestCentroid call cannot run, use nearest-member selection.
213
+
214
+ Each feature/timestep column is standardized across periods within its
215
+ parent group, matching the legacy profile scaling. Ward linkage uses a
216
+ linear adjacency graph (no wraparound). Legacy representative selection is
217
+ the default; nearest-centroid selection is an explicit alternative.
218
+ Inputs are not modified. This function does not construct a reduced model.
219
+ """
220
+ profiles, periods, parent_length = _prepare_profiles(
221
+ data,
222
+ periods,
223
+ period_length,
224
+ parent_length,
225
+ selection,
226
+ )
227
+ count = len(profiles)
228
+ labels = np.empty(count, dtype=np.int64)
229
+ selected: list[int] = []
230
+ weights: list[int] = []
231
+ inertia = reconstruction_error = 0.0
232
+ for start in range(0, count, parent_length):
233
+ # Scaling and clustering stay within each parent's chronological
234
+ # boundary.
235
+ stop = start + parent_length
236
+ scaled, assignments = _cluster_parent(
237
+ profiles[start:stop],
238
+ periods,
239
+ selection,
240
+ )
241
+ choices = _cluster_choices(scaled, assignments, periods, selection)
242
+ for members, preset_representative in choices:
243
+ statistics = _representative_statistics(
244
+ scaled,
245
+ members,
246
+ preset_representative,
247
+ )
248
+ representative, cluster_inertia, cluster_error = statistics
249
+ # Translate parent-local positions into the full input's mapping.
250
+ labels[start + members] = len(selected)
251
+ selected.append(start + representative)
252
+ weights.append(len(members))
253
+ inertia += cluster_inertia
254
+ reconstruction_error += cluster_error
255
+
256
+ indices = np.asarray(selected, dtype=np.int64)
257
+ return AHCResult(
258
+ labels=labels,
259
+ representative_indices=indices,
260
+ weights=np.asarray(weights, dtype=np.int64),
261
+ representatives=profiles[indices].copy(),
262
+ inertia=inertia,
263
+ reconstruction_error=reconstruction_error,
264
+ selection=selection,
265
+ )
@@ -0,0 +1,26 @@
1
+ """Generate (matrices and such)"""
2
+
3
+ from numpy import eye, ndarray
4
+
5
+
6
+ def connectivity_matrix(size: int, cyclic: bool = False) -> ndarray:
7
+ """
8
+ Generates a connectivity matrix to maintain chronology [..1,0,1..]
9
+
10
+ :param size: length of the scale
11
+ :type size: int
12
+ :param cyclic: whether to create a cyclic matrix, defaults to False
13
+ :type cyclic: bool, optional
14
+
15
+ :returns: connectivity matrix
16
+ :rtype: numpy.ndarray
17
+ """
18
+
19
+ _matrix = eye(size, k=1, dtype=int) + eye(size, k=-1, dtype=int)
20
+
21
+ if cyclic:
22
+ # if cyclic last period, cycles to first
23
+ _matrix[0, size - 1] = 1
24
+ _matrix[size - 1, 0] = 1
25
+
26
+ return _matrix
@@ -0,0 +1,45 @@
1
+ """Historical numeric helpers for distance and connectivity calculations."""
2
+
3
+ import numpy
4
+
5
+
6
+ # Adapted from revision e7704752 by OpenAI Codex (GPT-6).
7
+ def find_euclidean_distance(a: list, b: list) -> float:
8
+ """
9
+ finds euclidean distances between two cluster nodes
10
+
11
+ :param a: coordinates of cluster node a
12
+ :type a: list
13
+ :param b: coordinates of cluster node b
14
+ :type b: list
15
+
16
+ :returns: euclidean distance
17
+ :rtype: float
18
+ """
19
+ distance_ = [(a - b) ** 2 for a, b in zip(a, b)]
20
+ return sum(distance_)
21
+
22
+
23
+ # Adapted from revision e7704752 by OpenAI Codex (GPT-6).
24
+ def generate_connectivity_matrix(scale_len) -> numpy.ndarray:
25
+ """
26
+ Generates a connectivity matrix to maintain chronology [..1,0,1..]
27
+
28
+ :param scale_len: length of the scale
29
+ :type scale_len: int
30
+
31
+ :returns: connectivity matrix
32
+ :rtype: numpy.array
33
+ """
34
+ connect_ = numpy.zeros((scale_len, scale_len), dtype=int)
35
+ for i_ in range(len(connect_)):
36
+ if i_ == 0:
37
+ # connect_[i,364] = 1 #uncomment these to generate a cyclic matrix
38
+ connect_[i_, 1] = 1
39
+ elif i_ == scale_len - 1:
40
+ connect_[i_, scale_len - 2] = 1
41
+ # connect_[i,0] = 1
42
+ else:
43
+ connect_[i_, i_ - 1] = 1
44
+ connect_[i_, i_ + 1] = 1
45
+ return connect_
@@ -0,0 +1,16 @@
1
+ """Measures (of distances usually)"""
2
+
3
+
4
+ def euclidean_distance(a: list, b: list) -> float:
5
+ """
6
+ finds euclidean distances between two cluster nodes
7
+
8
+ :param a: coordinates of cluster node a
9
+ :type a: list
10
+ :param b: coordinates of cluster node b
11
+ :type b: list
12
+
13
+ :returns: euclidean distance
14
+ :rtype: float
15
+ """
16
+ return sum([(a - b) ** 2 for a, b in zip(a, b)])
@@ -0,0 +1,38 @@
1
+ """Other Functions"""
2
+
3
+
4
+ def normalize(data: list, how: str = "max") -> list:
5
+ """
6
+ min max normalization of data
7
+
8
+ :param data: time-series data
9
+ :type data: list
10
+ :param how: min-max or max, defaults to "max"
11
+ :type how: str, optional
12
+
13
+ :return: normalized data
14
+ :rtype: list
15
+ """
16
+ if all(isinstance(i, tuple) for i in data):
17
+ # lower bound
18
+ lb = [i[0] for i in data]
19
+ # upper bound
20
+ ub = [i[1] for i in data]
21
+ # normalize lower and upper bounds individually
22
+ lb_norm = normalize(lb, how=how)
23
+ ub_norm = normalize(ub, how=how)
24
+ return list(zip(lb_norm, ub_norm))
25
+
26
+ if how == "min_max":
27
+ min_ = min(data)
28
+ max_ = max(data)
29
+ return [(i - min_) / (max_ - min_) for i in data]
30
+
31
+ if how == "max":
32
+ return [
33
+ normalize(i) if isinstance(i, list) else i / max(data)
34
+ for i in data
35
+ ]
36
+
37
+ message = "Invalid normalization method. Use 'min_max' or 'max'."
38
+ raise ValueError(message)
@@ -0,0 +1,143 @@
1
+ """Calendar-aware preparation of general timestamped time series."""
2
+
3
+ from numbers import Integral
4
+ from typing import Literal, TypeVar
5
+
6
+ import pandas as pd
7
+
8
+ TimeData = TypeVar("TimeData", pd.Series, pd.DataFrame)
9
+ FillMethod = Literal["ffill", "bfill", "time"]
10
+
11
+
12
+ def _validate_data(data: TimeData) -> TimeData:
13
+ """Validate timestamps and return a sorted independent object."""
14
+ if not isinstance(data, (pd.Series, pd.DataFrame)):
15
+ message = "data must be a pandas Series or DataFrame"
16
+ raise TypeError(message)
17
+ if not isinstance(data.index, pd.DatetimeIndex):
18
+ message = "data must have a DatetimeIndex"
19
+ raise TypeError(message)
20
+ if data.empty:
21
+ message = "data must contain at least one observation"
22
+ raise ValueError(message)
23
+ if data.index.hasnans or not data.index.is_unique:
24
+ message = "timestamps must be unique and must not contain NaT"
25
+ raise ValueError(message)
26
+ return data.sort_index().copy()
27
+
28
+
29
+ def _validate_options(method: FillMethod, limit: int | None) -> None:
30
+ """Reject unknown policies and invalid consecutive-missing-row limits."""
31
+ if method not in ("ffill", "bfill", "time"):
32
+ message = "method must be 'ffill', 'bfill', or 'time'"
33
+ raise ValueError(message)
34
+ if limit is not None and (
35
+ isinstance(limit, bool) or not isinstance(limit, Integral) or limit < 1
36
+ ):
37
+ message = "limit must be a positive integer or None"
38
+ raise ValueError(message)
39
+
40
+
41
+ def _boundary(
42
+ value: str | pd.Timestamp | None,
43
+ default: pd.Timestamp,
44
+ ) -> pd.Timestamp:
45
+ """Interpret naive bounds in the data's timezone; retain aware times."""
46
+ if value is None:
47
+ return default
48
+ stamp = pd.Timestamp(value)
49
+ if pd.isna(stamp):
50
+ message = "calendar bounds must not be NaT"
51
+ raise ValueError(message)
52
+ if default.tz is None:
53
+ if stamp.tz is not None:
54
+ message = "timezone-aware bounds require timezone-aware data"
55
+ raise ValueError(message)
56
+ return stamp
57
+ if stamp.tz is None:
58
+ return stamp.tz_localize(default.tz)
59
+ return stamp.tz_convert(default.tz)
60
+
61
+
62
+ def _calendar_window(
63
+ data: TimeData,
64
+ freq: str,
65
+ start: str | pd.Timestamp | None,
66
+ end: str | pd.Timestamp | None,
67
+ ) -> TimeData:
68
+ """Complete the requested grid without silently dropping off-grid rows."""
69
+ lower = _boundary(start, data.index[0])
70
+ upper = _boundary(end, data.index[-1])
71
+ if lower > upper:
72
+ message = "start must not be after end"
73
+ raise ValueError(message)
74
+ offset = pd.tseries.frequencies.to_offset(freq)
75
+ if offset.n <= 0:
76
+ message = "freq must advance time"
77
+ raise ValueError(message)
78
+ calendar = pd.date_range(lower, upper, freq=offset, name=data.index.name)
79
+ window = data.loc[(data.index >= lower) & (data.index <= upper)]
80
+ if not window.index.isin(calendar).all():
81
+ message = "observations do not align with the requested calendar"
82
+ raise ValueError(message)
83
+ return window.reindex(calendar)
84
+
85
+
86
+ def fill_missing_values(
87
+ data: TimeData,
88
+ *,
89
+ freq: str = "D",
90
+ start: str | pd.Timestamp | None = None,
91
+ end: str | pd.Timestamp | None = None,
92
+ method: FillMethod = "ffill",
93
+ limit: int | None = None,
94
+ ) -> TimeData:
95
+ """Complete a calendar and fill absent rows and existing missing values.
96
+
97
+ Parameters
98
+ ----------
99
+ data : pandas.Series or pandas.DataFrame
100
+ Observations with a unique DatetimeIndex. Values and column names
101
+ have no domain-specific meaning; no unit conversion is performed.
102
+ freq : str, default "D"
103
+ Positive pandas calendar frequency. Use "D" to include weekends and
104
+ holidays, or "h" for an hourly grid. This is not an aggregation tool:
105
+ off-grid observations within the requested window are rejected.
106
+ start, end : str or pandas.Timestamp, optional
107
+ Inclusive calendar bounds, defaulting to the first and last input
108
+ timestamps. Only observations within these bounds can supply values.
109
+ Naive bounds use the data's timezone. Leap days follow the calendar.
110
+ method : {"ffill", "bfill", "time"}, default "ffill"
111
+ Carry the previous observation forward, use the next observation,
112
+ or interpolate numeric values by elapsed time between observations.
113
+ Forward fill leaves leading gaps missing; backward fill leaves
114
+ trailing gaps missing. Time interpolation fills interior gaps only.
115
+ Backward fill and interpolation explicitly use future observations.
116
+ limit : int, optional
117
+ Maximum consecutive missing calendar rows filled per column. For
118
+ interpolation, pandas applies this limit in the forward direction.
119
+
120
+ Returns
121
+ -------
122
+ pandas.Series or pandas.DataFrame
123
+ A new object with the same container type, names and timezone, sorted
124
+ onto the requested grid. Observed nonmissing values are preserved.
125
+ Dtypes may change when missing values are introduced. The input is
126
+ unchanged; unresolved gaps remain missing, including all-missing
127
+ columns and windows containing no observations.
128
+
129
+ Notes
130
+ -----
131
+ No holiday database is needed: the policy applies to all missing grid
132
+ values, regardless of whether the cause was a weekend, holiday or outage.
133
+ It does not infer whether filling a particular gap is physically valid.
134
+ """
135
+ _validate_options(method, limit)
136
+ ordered = _validate_data(data)
137
+ aligned = _calendar_window(ordered, freq, start, end)
138
+ count = None if limit is None else int(limit)
139
+ if method == "ffill":
140
+ return aligned.ffill(limit=count)
141
+ if method == "bfill":
142
+ return aligned.bfill(limit=count)
143
+ return aligned.interpolate(method="time", limit=count, limit_area="inside")
vaelchi/result.py ADDED
@@ -0,0 +1,56 @@
1
+ """Framework-independent clustering output in original input units."""
2
+
3
+ from dataclasses import dataclass
4
+
5
+ import numpy as np
6
+ from numpy.typing import NDArray
7
+
8
+
9
+ @dataclass
10
+ class AHCResult:
11
+ """Representative profiles and their mapping to the original periods.
12
+
13
+ ``labels`` maps every original period to a row in ``representatives``.
14
+ ``representative_indices`` identifies those periods in the original input.
15
+ ``weights`` counts represented periods, not timesteps or elapsed hours.
16
+ Representatives have shape (clusters, period_length, features) in original
17
+ units. Nearest-centroid selection orders clusters chronologically. Legacy
18
+ selection
19
+ orders by selected period and can select outside a cluster or repeat a
20
+ representative, preserving historical behavior. Errors are sums of squared
21
+ distances in standardized profile
22
+ space: to centroids (``inertia``) and to selected profiles
23
+ (``reconstruction_error``). Each parent is standardized independently.
24
+ """
25
+
26
+ labels: NDArray[np.int64]
27
+ representative_indices: NDArray[np.int64]
28
+ weights: NDArray[np.int64]
29
+ representatives: NDArray[np.float64]
30
+ inertia: float
31
+ reconstruction_error: float
32
+ selection: str = "legacy"
33
+
34
+ def reconstruct(self) -> NDArray[np.float64]:
35
+ """Expand representatives to (original timesteps, features)."""
36
+ return self.representatives[self.labels].reshape(
37
+ -1,
38
+ self.representatives.shape[-1],
39
+ )
40
+
41
+ def to_dict(self) -> dict:
42
+ """Export detached, JSON-compatible values without framework objects.
43
+
44
+ Lists retain the array axis order documented on this class. Labels and
45
+ representative indices are zero-based, and weights count periods. The
46
+ consumer retains responsibility for feature names and physical units.
47
+ """
48
+ return {
49
+ "labels": self.labels.tolist(),
50
+ "representative_indices": self.representative_indices.tolist(),
51
+ "weights": self.weights.tolist(),
52
+ "representatives": self.representatives.tolist(),
53
+ "inertia": float(self.inertia),
54
+ "reconstruction_error": float(self.reconstruction_error),
55
+ "selection": self.selection,
56
+ }
@@ -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,14 @@
1
+ vaelchi/__init__.py,sha256=10CW8fRjEFRqZufTMvddnvMzV1jdNi2H47GrgfxWAd0,291
2
+ vaelchi/preprocessing.py,sha256=p86VgCjDwLxem1pcbwz1851Y24odAReNPCu2kWBAwQg,5815
3
+ vaelchi/result.py,sha256=uyL9lrR-2SKI85peSloa2ng-LpCtni-W2fsqES1JhIA,2252
4
+ vaelchi/algorithms/__init__.py,sha256=Lbof7ylJWX5AISppmN1R7eMbA78Sd0tOETZzXS5SvZk,82
5
+ vaelchi/algorithms/ahc.py,sha256=lI2pCnb_cgFfrAAcw183QYTRl8hLWFXkOKLiBXbnrXU,10503
6
+ vaelchi/functions/generate.py,sha256=kzuyXPQiAS3ali9W-DM5UQjN7TStoC-9kPl94oWoQ88,670
7
+ vaelchi/functions/legacy.py,sha256=pu7byB6SiRlLxsGYbnQ8vpd74Yy301WGrdpeixjw2f8,1318
8
+ vaelchi/functions/measure.py,sha256=ujf-S53jdfDNK_NlX4TPnwdjtFjciJlIyrr3tedIEvU,393
9
+ vaelchi/functions/other.py,sha256=2Uo-exuqTM3tJUxbNl10Zn0o2kDsaBOWKXOyIXjMyfQ,1027
10
+ vaelchi-0.1.0.dist-info/licenses/LICENSE,sha256=p7QCnNBt-wXq1kCd5SHrG8wATKIm14akeJSsN4483j8,1076
11
+ vaelchi-0.1.0.dist-info/METADATA,sha256=kKg8phF8HdbmcAj_Gs7Zi_qDLHqTGg_kfIXOxzydpdg,4226
12
+ vaelchi-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
13
+ vaelchi-0.1.0.dist-info/top_level.txt,sha256=o-I7JZ9IY3UViLONvjQAqJTk1qEAZFpA4Zpjc05AiPE,8
14
+ vaelchi-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -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 @@
1
+ vaelchi