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 +10 -0
- vaelchi/algorithms/__init__.py +5 -0
- vaelchi/algorithms/ahc.py +265 -0
- vaelchi/functions/generate.py +26 -0
- vaelchi/functions/legacy.py +45 -0
- vaelchi/functions/measure.py +16 -0
- vaelchi/functions/other.py +38 -0
- vaelchi/preprocessing.py +143 -0
- vaelchi/result.py +56 -0
- vaelchi-0.1.0.dist-info/METADATA +113 -0
- vaelchi-0.1.0.dist-info/RECORD +14 -0
- vaelchi-0.1.0.dist-info/WHEEL +5 -0
- vaelchi-0.1.0.dist-info/licenses/LICENSE +21 -0
- vaelchi-0.1.0.dist-info/top_level.txt +1 -0
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,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)
|
vaelchi/preprocessing.py
ADDED
|
@@ -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
|
+

|
|
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,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
|