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

SHAPES

Archetype daily shapes on a 0-1 scale, defined on a 24-hour clock.

Functions

generate([meters, days, steps, archetypes, ...])

Generate a population of meters drawn from a few daily archetypes.

Classes

Synthetic(pivot, labels, archetypes, ...)

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: object

A synthetic population.

Variables:
  • pivot (DataFrame) – Readings, a DatetimeIndex by 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 > 0 that 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.

  • archetypes (tuple[str, ...]) – Names from SHAPES.

  • 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 constant standby reading (label -1).

  • standby (float) – Constant reading of a vacant meter.

Return type:

Synthetic

Returns:

The Synthetic population.

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])