Skip to content

[Internal review] Add BattLeDIM dataset - #1

Closed
etienneRV wants to merge 10 commits into
mainfrom
feature/kios-battledim
Closed

etienneRV wants to merge 10 commits into
mainfrom
feature/kios-battledim

Conversation

@etienneRV

@etienneRV etienneRV commented Nov 19, 2026 •

Copy link
Copy Markdown
Owner

Description

Adds kios/battledim, a connector for BattLeDIM 2020, the Battle of the Leakage Detection and Isolation Methods (Zenodo 4017659, CC BY 4.0).

  • Data: two years of SCADA data from the L-Town water distribution network, every 5 minutes: 33 pressure sensors, 3 flow sensors, 1 tank level and 82 automated meter readings.
  • Labels: the 33 leaks the data contains, with pipe, start, end, hole size and type.

Why it matters:

  • Water utilities lose a large share of treated water to leaks, and most leaks are found late.
  • With this dataset, a time-series language model can learn to say which leak started, when, how big it is, and near which sensor.
  • Every statement can be checked against the published ground truth.

The connector downloads 13 of the record's files from Zenodo. Each one is pinned by sha256; the full download is about 190 MB.

Mapping

Record: one Record for the continuous recording, 2018-01-01 00:00 → 2019-12-31 23:55, 210,240 steps.

  • Sources: one per sensor type, holding 119 lazy float64 signals.
  • Signal names: the EPANET ids of L-TOWN.inp.
  • Units (from the release README): pressure head in m, flow in m³/h, tank level in m, demand in L/h.

Leaks: each leak becomes one dataset annotation (leak, value = pipe id), with type, start, end, peak, hole size, peak outflow and repaired status as metadata. They are deliberately not on the record: every task reads the record, and loaders such as TimeFTorchDataset return a record's annotations in each item, so the record holds only sensor signals.

Windows: two-week windows, one every 7 days (103 windows; 98 after the embargo below). Each gives four tasks about its last week, all scoped to the window:

Task Target
ClassificationTask multi-label {abrupt, incipient}: the types of leaks starting in the target week, empty if none
TemporalLocalizationTask (exhaustive) the start of every leak in the target week
ScalarPredictionTask mean_leak_outflow over the target week, in m³/h
AnswerTask a short text: pipe, start, sudden vs. growing, hole size, outflow, and the nearest pressure sensor by network links; repairs too

The text targets come from fixed templates filled from the configuration, the leak tables and L-TOWN.inp. No model writes them. The README quotes the templates verbatim. A text never states a fact from after its window: an incipient leak whose peak falls later is described as still growing.

Decisions

  • Split: grouped by calendar block (four ISO weeks), 8/1/1 with StratifiedSplitter, seed 42.

    • The competition used 2018 for training and 2019 for evaluation. But 74 of the 82 meter series of 2019 repeat 2018 exactly.
    • So the year difference of the inflow equals the year difference of the leak outflow (slope 1.00, daily correlation 0.989).
    • Grouping by calendar block keeps the same calendar weeks of both years in one partition.
    • Embargo: windows overlap by one week, so a window whose context week is a validation or test target week of another partition gets no tasks (5 training windows).
    • Result: train 74 windows, validation 8, test 16.
    • Limitation: 2019 weekdays fall one day later than 2018, so one day of demand background can repeat across each block boundary (documented in the README).
  • Time zone: the release's naive timestamps are read as UTC; it states no zone.

  • Strict reading: the build fails on a gap, a missing or non-finite value, or any disagreement between:

    • the configuration, the leak tables and the repair report;
    • the sensors or leak pipes and the network model.

    Nothing is filled. The release passes all checks.

Source issues documented in the README

  • The data is simulated: the release's configuration names the network model that generated it.
  • At least one leak is active in 97.8 % of 2018 and in 100 % of 2019, so there is almost no leak-free baseline.
  • An incipient leak's first non-zero outflow comes 3 h to 2.5 days after its configured start. The connector keeps the configured start.
  • p800's outflow ends 5 minutes after its configured end. The connector keeps the configured end.

Files

packages/timenet-connectors/src/timenet_connectors/datasets/kios/__init__.py
packages/timenet-connectors/src/timenet_connectors/datasets/kios/battledim/__init__.py
packages/timenet-connectors/src/timenet_connectors/datasets/kios/battledim/connector.py   # download + record + annotations
packages/timenet-connectors/src/timenet_connectors/datasets/kios/battledim/source.py      # CSV/YAML/INP readers and checks
packages/timenet-connectors/src/timenet_connectors/datasets/kios/battledim/tasks.py       # windows, split, task and text rules
packages/timenet-connectors/src/timenet_connectors/datasets/kios/battledim/dataset.yaml
packages/timenet-connectors/src/timenet_connectors/datasets/kios/battledim/README.md
packages/timenet-connectors/src/timenet_connectors/datasets/kios/battledim/tests/__init__.py
packages/timenet-connectors/src/timenet_connectors/datasets/kios/battledim/tests/test_connector.py

No requirements.txt: the connector uses only core dependencies (numpy, pyarrow, PyYAML via timenet[build]). The test writes a synthetic release, so the repo ships no dataset bytes.

How to load

import timenet

tn = timenet.TimeNet()
timenet.build("kios/battledim")  # or: timenet-build build kios/battledim
with tn.open("kios/battledim") as reader:
    dataset = reader.read()
train = dataset.get_train()

Validation

Check Result
make check (ruff format, ruff check, ty) passed
make check-ci (all pre-commit hooks + ty on 3.11) passed
make test-unit 1655 passed
make test 2895 passed, 1 failed: test_an_isolated_build_records_its_environment. It fails identically on clean upstream/main on our machine, because the isolated build picks a local conda interpreter that has pytest installed. Unrelated to this PR.
make test-connectors all 13 connectors passed (pytest + ty), incl. kios/battledim
make license-check passed
Connector tests (synthetic release, incl. storage round trip, embargo and 10 corruption cases) 20 passed
timenet-build build kios/battledim on the real release built 1.0.0, 44 MB

Read-back of the built release:

  • 1 record, 119 signals × 210,240 values, 0 non-finite values.
  • 33 dataset leak annotations; 0 annotations on the record.
  • 392 tasks: train 296, validation 32, test 64. The splits sum to the total.
  • Classification targets: none 65, incipient 18, abrupt 15.
  • No calendar block or target week appears in two partitions.
  • Every leak start and repair falls in exactly one target week (33 and 17); after the embargo, two repairs (p514, p142) appear in no task.
Source Signals Unit Min Max
Pressure sensors 33 m 25.67 56.97
Flow sensors 3 m³/h 0.00 205.44
Tank level sensor 1 m 1.95 3.90
Automated meter readings 82 L/h 0.00 37,795.88

Example (target week 2018-03-05):

  • classification → ["abrupt"]
  • temporal_localization → TimePoint(2018-03-05 15:45)
  • mean_leak_outflow → 47.578 m³/h
  • answer → "A sudden leak started on pipe p673 on 2018-03-05 15:45, with a hole of 22.9 mm and an outflow of up to 28.4 m3/h in this window. The nearest pressure sensor is n229, 2 links away. At the end of the window 4 leaks are active, with a total outflow of 52.8 m3/h."

Licence and citation

The data is CC BY 4.0 (Zenodo record and KIOS-Research/BattLeDIM). Cite:

Vrachimis, S. G., et al. (2022). Battle of the Leakage Detection and Isolation Methods. Journal of
Water Resources Planning and Management
, 148(12). doi:10.1061/(ASCE)WR.1943-5452.0001601.
Dataset: doi:10.5281/zenodo.4017659.

Limitations

  • Simulated data from one network, with 33 leak events.
  • Small validation and test partitions: 8 and 16 windows, with 3 new leaks each.
  • Text targets are rule-generated, not expert explanations. Some statements (active leaks, outflow) are only indirectly observable from the sensors.

Contributed by Team RAMadan during the TimeNet hackathon, Round 1 (November 2026).

Checklist

There is no PR template in the repo; this mirrors CONTRIBUTING.md and AGENTS.md.

  • Conventional Commits, Conventional Branch (feature/kios-battledim)
  • make check, make check-ci, make test-unit, make license-check pass
  • make test-connectors passes; make test passes except one environment-dependent test that also fails on clean main locally (see Validation)
  • Google-style docstrings; ty green
  • Source pinned by URL + sha256; no raw data committed
  • Card validates against dataset-card-v1; licence, citation and source URL set
  • Source-data problems raise TimeNetConnectorError; nothing is filled
  • Label area:connectors: we can't add labels on this repo, so could a maintainer add it? Thanks!

Parse the BattLeDIM 2020 SCADA and leak tables (semicolon-separated,
decimal comma, 5-minute grid), the leak list of the generating
configuration, the 2018 repair report and the L-Town EPANET links.
Joining the two years checks the grid, the sensor lists and the agreement
between the configuration, the leak tables, the repair report and the
network model, and raises TimeNetConnectorError on any mismatch.
Download 13 files of Zenodo record 4017659, each pinned by sha256, and
build one record of the 2018-2019 recording: 119 float64 signals (33
pressure heads, 3 flows, 1 tank level, 82 metered demands) on a 5-minute
grid, with every leak as record annotations over its active interval.

Two-week windows, one every 7 days, give four tasks about their last
week: the types of new leaks, their start times, the mean leak outflow,
and a rule-generated text that names each new or repaired leak, its size
and the nearest pressure sensor by network links. Windows split 8/1/1 by
calendar block across both years, because 2019 repeats most of the 2018
metered demands.
Write a two-year synthetic release in the source layout and check the
record, the leak annotations, the window tasks and their text, the
calendar-block split, a storage round trip, and that a gap, a missing
value or a disagreement between the source files raises.
@etienneRV

Copy link
Copy Markdown
Owner Author

Reviewer checklist

  • Format matches existing TimeNet datasets (compare datadog/arfbench, physionet/sleep_edfx)
  • Loads with the quickstart code (timenet-build build kios/battledim, then TimeNet().open("kios/battledim"))
  • Metadata, licence (CC BY 4.0) and citation correct (dataset.yaml, README.md)
  • Labels and text targets make sense (spot-check 5 examples; notes/validate_battledim.py prints one)
  • Splits have no leakage (calendar blocks; see README "The split")
  • Dataset card is clear to an outsider
  • No large or private files (9 files, 1,321 lines, no data)

@etienneRV
etienneRV force-pushed the feature/kios-battledim branch from c133e79 to 6b2e2ad Compare November 19, 2026 20:48
@etienneRV
etienneRV marked this pull request as draft November 19, 2026 21:07
… more of the release

- The text no longer states an incipient leak's peak when it falls after
  the window; it says the leak was still growing. Zero rounded outflow
  reads as "no measurable outflow yet".
- Active leaks at the end of a window come from the leak list, not from
  rounded outflow, so the text cannot contradict its own new leaks.
- The build fails if a leak start or repair falls outside every target
  week, if the repair report misses or repeats a 2018 repair, if a sensor
  is listed twice, or if a CSV cell is not a timestamp or a number.
- Share one microsecond conversion and drop dead code.
…embargo overlapping windows

- The leaks become dataset annotations instead of record annotations.
  Every task reads the record, and loaders return a record's annotations
  with each item, so the record now holds sensor signals only.
- A window whose context week is a validation or test target week of
  another partition gets no tasks, so training never sees the signals of
  a held-out target week.
- Small outflows keep their second decimal; only zero reads as no outflow.
- Only p800 may keep outflow one step past its configured end, abrupt
  leaks must peak at their start, and malformed configuration sections
  raise TimeNetConnectorError.
- Compute the total outflow once, keep the window geometry in one place,
  return a Table from the year join and read headers as utf-8-sig.
@etienneRV etienneRV self-assigned this Nov 19, 2026
@etienneRV
etienneRV marked this pull request as ready for review November 19, 2026 21:48
@etienneRV

Copy link
Copy Markdown
Owner Author

Closing: we switched to the SWE-agent trajectories dataset (#2).

@etienneRV etienneRV closed this Nov 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant