milia.anomaly.inject#
Synthetic anomalies to inject into otherwise normal profiles.
Real labelled anomalies are rare, so detectors are evaluated by injecting known faults into held-out normal days. Every injector takes one profile (a 1-D array of readings, typically one day) and a numpy generator, and returns a modified copy. Default ranges scale with the profile length and reproduce the anomaly chapter’s settings exactly for 48-step (half-hourly) days.
Module Attributes
Number of trips on a faulty day, and their length in steps, as |
|
Offset of a meter clock that records UTC as local time in Victoria (AEST, UTC+10), in half-hours. |
|
a Level 1 or Level 2 EV charger, a PV array, or both. |
|
Power of a Level 1 charger (2.4 kW) relative to the Level 2 sessions (7 kW) of a session pool. |
|
split into episodes, or moved in time. |
|
Faults of a meter's readings. |
|
Meter faults used by the anomaly chapter's benchmark. |
|
Prosumer behaviours on net load (export negative). |
Functions
|
Add a technology to the readings of each adopter, from a given day to the end of the period. |
|
Inject a behaviour fault into randomly chosen days on which the behaviour occurs. |
|
The readings a meter records for one day when its clock runs |
|
A day recorded by a meter whose clock runs |
|
Multiply by a ramp from 1 to a random end factor: calibration drift. |
|
Set a block of readings to zero: a communication dropout. |
|
Break the export (negative) readings into several short episodes at random times. |
|
Inject one fault into the readings of chosen meters. |
|
Move the export block to an unusual time of day. |
|
Add a scaled shape: a new behaviour such as an EV charger (positive) or PV (negative). |
|
Length range of an injected block, scaled to the profile length when not given. |
|
Multiply a short block by a large factor: a spike. |
|
Hold the reading constant over a block: a stuck meter. |
|
An inverter that trips repeatedly within the export window of one day. |
|
Scale readings down: a meter tampered to under-report. |
- milia.anomaly.inject.span(n, lengths, default)#
Length range of an injected block, scaled to the profile length when not given.
- Parameters:
- Return type:
- Returns:
(low, high)in steps.
Examples
>>> span(48, None, (1 / 8, 1 / 4)) (6, 12)
- milia.anomaly.inject.stuck(profile, rng, lengths=None, latest=None)#
Hold the reading constant over a block: a stuck meter.
- Parameters:
- Return type:
- Returns:
A modified copy of the profile.
Examples
>>> day = np.linspace(1.0, 2.0, 48) >>> out = stuck(day, np.random.default_rng(0)) >>> int((np.diff(out) == 0).sum()) >= 5 True
- milia.anomaly.inject.dropout(profile, rng, lengths=None, latest=None)#
Set a block of readings to zero: a communication dropout.
- Parameters:
- Return type:
- Returns:
A modified copy of the profile.
Examples
>>> day = np.linspace(1.0, 2.0, 48) >>> int((dropout(day, np.random.default_rng(0)) == 0).sum()) >= 4 True
- milia.anomaly.inject.drift(profile, rng, factors=(1.4, 1.8))#
Multiply by a ramp from 1 to a random end factor: calibration drift.
- Parameters:
- Return type:
- Returns:
A modified copy of the profile.
Examples
>>> day = np.linspace(1.0, 2.0, 48) >>> out = drift(day, np.random.default_rng(0)) >>> bool(out[0] == day[0] and out[-1] > 1.4 * day[-1] - 1e-9) True
- milia.anomaly.inject.spike(profile, rng, factors=(2.0, 4.0), width=1)#
Multiply a short block by a large factor: a spike.
- Parameters:
- Return type:
- Returns:
A modified copy of the profile.
Examples
>>> day = np.linspace(1.0, 2.0, 48) >>> bool(spike(day, np.random.default_rng(0)).max() >= 2 * day.min()) True
- milia.anomaly.inject.fragmented(profile, rng, episodes=(4, 7))#
Break the export (negative) readings into several short episodes at random times.
The exported values are split, in order, into non-overlapping episodes placed at random positions, so the total export is kept and only its timing changes. A profile without export is returned unchanged.
- Parameters:
- Return type:
- Returns:
A modified copy of the profile.
Examples
>>> net = np.ones(48) >>> net[20:28] = -2.0 >>> out = fragmented(net, np.random.default_rng(1)) >>> float(out[out < 0].sum()), bool((out != net).any()) (-16.0, True)
- milia.anomaly.inject.offhours(profile, rng, shifts=None)#
Move the export block to an unusual time of day.
- Parameters:
- Return type:
- Returns:
A modified copy of the profile.
Examples
>>> net = np.ones(48) >>> net[20:28] = -2.0 >>> int(np.flatnonzero(offhours(net, np.random.default_rng(1)) < 0)[0]) != 20 True
- milia.anomaly.inject.underreport(profile, rng=None, fraction=0.5)#
Scale readings down: a meter tampered to under-report.
- Parameters:
- Return type:
- Returns:
profile * (1 - fraction).
Examples
>>> underreport([2.0, 4.0], fraction=0.25).tolist() [1.5, 3.0]
- milia.anomaly.inject.shift(profile, rng, shape, scales=(1.0, 1.0))#
Add a scaled shape: a new behaviour such as an EV charger (positive) or PV (negative).
- Parameters:
- Return type:
- Returns:
profile + factor * shape.
Examples
>>> shift(np.ones(3), np.random.default_rng(0), [0.0, 7.0, 0.0], scales=(1.0, 1.0)).tolist() [1.0, 8.0, 1.0]
- milia.anomaly.inject.TRIPS: tuple[tuple[int, int], tuple[int, int]] = ((2, 5), (1, 4))#
Number of trips on a faulty day, and their length in steps, as
[low, high)ranges.
- milia.anomaly.inject.CLOCKSHIFT = 20#
Offset of a meter clock that records UTC as local time in Victoria (AEST, UTC+10), in half-hours.
- milia.anomaly.inject.ADOPTIONS: tuple[str, ...] = ('ev1', 'ev2', 'pv', 'pvev')#
a Level 1 or Level 2 EV charger, a PV array, or both.
- Type:
Technologies an adopter installs
- milia.anomaly.inject.LEVEL1 = 0.34285714285714286#
Power of a Level 1 charger (2.4 kW) relative to the Level 2 sessions (7 kW) of a session pool.
- milia.anomaly.inject.tripping(profile, generator, trips=((2, 5), (1, 4)))#
An inverter that trips repeatedly within the export window of one day.
On its over-voltage or anti-islanding protection the inverter stops exporting for short spells. During each spell the PV output is lost, so the meter records the household’s demand, taken as the median of the day’s import readings, since the demand under the array is not observed. Unlike
fragmented(), the energy of the spells is lost, not moved, and no export appears outside the export window.- Parameters:
- Return type:
- Returns:
A modified copy; a day without export is returned unchanged.
Examples
>>> day = np.full(48, 0.5) >>> day[20:30] = -2.0 >>> tripped = tripping(day, np.random.default_rng(0)) >>> bool((tripped[:20] == day[:20]).all() and (tripped[20:30] > 0).any()) True
- milia.anomaly.inject.clockerror(days, day, shift=20)#
The readings a meter records for one day when its clock runs
shiftsteps behind local time.A meter that records UTC as local time labels every reading early by the time-zone offset, so the readings of a recorded day are those of local times
shiftsteps later, partly from the following day. The fault needs consecutive days, so it is not a one-dayInjector.- Parameters:
- Return type:
- Returns:
The readings recorded for
day.- Raises:
ValueError – If
dayis the last day, whose later readings are not available.
Examples
>>> days = np.arange(12.0).reshape(3, 4) >>> clockerror(days, 0, shift=1).tolist() [1.0, 2.0, 3.0, 4.0]
- milia.anomaly.inject.clockshift(profile, generator=None, shift=20)#
A day recorded by a meter whose clock runs
shiftsteps behind local time, from the day’s own readings.clockerror()needs the readings of the following day. Where days are evaluated one at a time, as byselfbaseline(), the recorded day is approximated by rolling the day’s readings, which is exact when consecutive days are alike: a midday export then appearsshiftsteps earlier, in the night, while the energy and the shape of the day are unchanged.- Parameters:
- Return type:
- Returns:
The recorded day.
Examples
>>> clockshift(np.arange(6.0), shift=2).tolist() [2.0, 3.0, 4.0, 5.0, 0.0, 1.0]
- milia.anomaly.inject.adopt(cube, adopters, technologies, generator, pv, sessions, kwp=(3.0, 8.0), onset=0)#
Add a technology to the readings of each adopter, from a given day to the end of the period.
PV subtracts an array of random size times the output per kWp, so the readings become a net load that is negative while the household exports. Level 2 charging adds a vehicle’s recorded sessions; Level 1 adds them scaled to 2.4 kW.
- Parameters:
cube (
ArrayLike) – Readings in kW, shape(meters, days, steps).adopters (
ArrayLike) – Indices of the adopting meters.generator (
Generator) – Random generator, for the vehicle and the array size.pv (
ArrayLike) – PV output per kWp, shape(days, steps).sessions (
ArrayLike) – Recorded charging of a session pool in kW, shape(vehicles, days, steps).onset (
int) – First day with the technology installed.
- Return type:
- Returns:
A modified copy of the readings.
- Raises:
ValueError – If a technology is not one of
ADOPTIONS.
Examples
>>> cube, pool = np.ones((2, 3, 4)), np.full((1, 3, 4), 7.0) >>> adopted = adopt(cube, [0], ["ev2"], np.random.default_rng(0), np.zeros((3, 4)), pool, onset=1) >>> adopted[0, 0].tolist(), adopted[0, 1].tolist() ([1.0, 1.0, 1.0, 1.0], [8.0, 8.0, 8.0, 8.0])
- milia.anomaly.inject.BEHAVIOURFAULTS: tuple[str, ...] = ('fragmented', 'offhours')#
split into episodes, or moved in time.
- Type:
Faults of a day’s behaviour
- milia.anomaly.inject.METERFAULTS: tuple[str, ...] = ('stuck', 'dropout', 'underreport')#
Faults of a meter’s readings.
- milia.anomaly.inject.behaviourfault(days, kind, fault, count, generator)#
Inject a behaviour fault into randomly chosen days on which the behaviour occurs.
For export (net load, negative while exporting),
"fragmented"istripping()and"offhours"isclockerror(), the physical faults of an inverter and of a meter clock. For charging (power drawn by a charger), they split a session into fragments (fragmented()) or move it in time (offhours()), as a faulty charger or a misconfigured timer would.- Parameters:
- Return type:
- Returns:
The corrupted copy and a boolean label per day.
- Raises:
ValueError – If
kindorfaultis unknown.
Examples
>>> days = np.full((6, 48), 0.5) >>> days[:, 20:30] = -2.0 >>> corrupted, labels = behaviourfault(days, "export", "offhours", 2, np.random.default_rng(0)) >>> int(labels.sum()), bool((corrupted[labels][:, :8] < 0).any()) (2, True)
- milia.anomaly.inject.meterfault(cube, meters, fault, generator, days=30, resolution=0.001, interval=0.5)#
Inject one fault into the readings of chosen meters.
A stuck register or a dropout affects
daysrandom days of each meter. Under-recording hides half of every reading: the stored readings are already rounded to the register’s resolution, so the energy lost to that rounding is restored with a uniform dither within one step before the share is hidden and the register rounds again; halving the rounded readings directly would create ties that no real register produces.- Parameters:
cube (
ArrayLike) – Power in kW, shape(meters, days, steps).meters (
ArrayLike) – Indices of the meters to corrupt.fault (
str) – One ofMETERFAULTS.generator (
Generator) – Random generator.days (
int) – Days corrupted per meter for a stuck register or a dropout.resolution (
float) – The register’s resolution in kWh.interval (
float) – Length of a step in hours.
- Return type:
- Returns:
A corrupted copy of the cube.
- Raises:
ValueError – If
faultis unknown.
Examples
>>> cube = np.full((2, 40, 48), 0.6) >>> faulty = meterfault(cube, [1], "underreport", np.random.default_rng(0)) >>> round(float(faulty[0].mean()), 2), round(float(faulty[1].mean()), 2) (0.6, 0.3)