milia.data.synthetic#
Synthetic meter data with known archetypes and planted anomalies.
Every algorithm in milia can be checked end to end against this ground truth: clustering should recover the archetypes, and detectors should flag the planted anomalous days.
Module Attributes
Archetype daily shapes on a 0-1 scale, defined on a 24-hour clock. |
Functions
|
Generate a population of meters drawn from a few daily archetypes. |
Classes
|
A synthetic population. |
- milia.data.synthetic.SHAPES = {'daytime': <function <lambda>>, 'evening': <function <lambda>>, 'morning': <function <lambda>>, 'night': <function <lambda>>}#
Archetype daily shapes on a 0-1 scale, defined on a 24-hour clock.
- class milia.data.synthetic.Synthetic(pivot, labels, archetypes, anomalies, kinds)#
Bases:
objectA synthetic population.
- Variables:
pivot (
DataFrame) – Readings, aDatetimeIndexby meter-column frame.labels (
ndarray) – Archetype index of each meter.archetypes (
tuple[str,...]) – Archetype name of each label.anomalies (
ndarray) – Boolean(meters, days)mask of days with a planted anomaly.kinds (
ndarray) – The anomaly type planted on each flagged day (""elsewhere).
Examples
>>> population = generate(meters=6, days=2, steps=24) >>> population.archetypes ('evening', 'morning', 'daytime')
- milia.data.synthetic.generate(meters=90, days=60, steps=48, archetypes=('evening', 'morning', 'daytime'), noise=0.05, rate=0.0, start='2024-01-01', seed=0, spread=0.3, peak=None, irregular=0, vacant=0, standby=0.02)#
Generate a population of meters drawn from a few daily archetypes.
Each meter follows its archetype’s shape, scaled by its own magnitude, with a small random time shift per day and multiplicative noise. With
rate > 0that share of meter-days receives one planted anomaly: a stuck reading, a dropout to zero, or a drift.- Parameters:
meters (
int) – Number of meters, split evenly across archetypes.days (
int) – Number of days.steps (
int) – Readings per day.noise (
float) – Multiplicative noise level.rate (
float) – Share of meter-days carrying a planted anomaly.start (
str) – First day.seed (
int) – Random seed.spread (
float) – Standard deviation of the log of household size.peak (
float|None) – Median household peak reading to rescale to (kW); the archetype scale when omitted.irregular (
int) – Meters appended with gamma-distributed readings and no daily routine (label-1).vacant (
int) – Meters appended with a constantstandbyreading (label-1).standby (
float) – Constant reading of a vacant meter.
- Return type:
- Returns:
The
Syntheticpopulation.
Examples
>>> population = generate(meters=6, days=3, steps=24, rate=0.5) >>> population.pivot.shape, population.labels.tolist() ((72, 6), [0, 1, 2, 0, 1, 2]) >>> population.anomalies.shape (6, 3) >>> extended = generate(meters=6, days=3, steps=24, peak=1.5, irregular=2, vacant=1) >>> extended.pivot.shape[1], extended.labels[-3:].tolist() (9, [-1, -1, -1])