README.md

metadata

title: Appliance Health & Leakage Monitor
emoji: ⚡
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false

⚡ Appliance Health & Leakage Monitor

A live monitoring dashboard built on the AMPds2 household power dataset. It plays back the records hour-by-hour, builds a per-appliance expected band with TimesFM 2.5, and raises dashboard alerts for two independent problems:

1. Appliance health — an appliance drawing more (wear / fault) or less (under-draw / off) than its healthy rated power.
2. Whole-house leakage — the gap between the metered mains and the sum of all appliances (unaccounted load).

You can inject faults into any appliance (over-draw / under-draw / off) and inject house leakage, then watch the dashboard respond in real time.

Files

File	Purpose
app.py	Gradio dashboard (playback, injection controls, charts, alerts)
engine.py	Simulation + detection logic, TimesFM envelope builder
prepare_data.py	One-time: AMPds2 zip → data/ampds2_hourly.parquet
requirements.txt	Pinned dependencies

Quick start

1. Get the data. Download AMPds2 (dataverse_files.zip) from Harvard Dataverse.

2. Build the compact parquet the app reads (resamples the minutely data to hourly):

python prepare_data.py /path/to/dataverse_files.zip
# -> writes data/ampds2_hourly.parquet

3. Run locally:

pip install -r requirements.txt
python app.py

Deploy to Hugging Face Spaces

1. Create a new Gradio Space.
2. Push app.py, engine.py, prepare_data.py, requirements.txt, README.md.
3. Add the data: commit data/ampds2_hourly.parquet (it's small after hourly resampling), or upload it via the Space's Files tab. (Run prepare_data.py locally first to create it.)
4. The Space builds from requirements.txt. TimesFM 2.5 installs from GitHub and its weights download on first launch.

Hardware: runs on the free CPU tier — first launch takes ~1–2 min while TimesFM loads and forecasts the expected bands. A T4 GPU makes initialization noticeably faster. If timesfm can't be imported, the app automatically falls back to a seasonal (hour-of-day) expected band so it still works.

How to use

1. Set the playback window and healthy context lengths, click Initialize (the context window trains the baselines and TimesFM bands).
2. ▶ Play (or Step) to stream the records; Speed sets hours per tick.
3. Inject an appliance fault: pick an appliance, choose Over-draw / Under-draw / Off, set the magnitude and when in the timeline it begins, then Apply.
4. Inject leakage: set a continuous phantom load (W) and a start point, then Apply.
5. Watch the Alerts & status panel and the two charts react.

How detection works

• Expected band is forecast once by TimesFM 2.5 from the healthy context window, per appliance (shown as the q10–q90 ribbon on the focus chart).
• Over / under / off fire when an appliance's trailing ON-power deviates from its healthy rated value — robust to normal on/off cycling. (The forecast band is the visual evidence; the rated comparison is the trigger, which avoids false alarms on sharp on/off loads.)
• Leakage = mains − Σ(appliances), compared to the normal hour-of-day residual band. Importantly, an appliance fault raises the mains by the same amount, so it does not move the residual — only a true leak does. That keeps the two alert types independent and physically consistent.
• AMPds2 has no real fault/leak labels, so the system is validated by injection — exactly what the controls let you do.

Notes

• Power is in watts; hourly energy in kWh = W / 1000.
• The mains meter is WHE; UNE (unmetered) is excluded from the appliance sum.
• TimesFM is used zero-shot (pretrained, no training on AMPds2).