gridshedwatch 1.1.1__tar.gz

gridshedwatch-1.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sam Heiserman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gridshedwatch-1.1.1/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: gridshedwatch
+Version: 1.1.1
+Summary: A benchmark for early warning of grid load sheds, scored the way forecasters score weather warnings
+Author: Sam Heiserman
+License: MIT
+Project-URL: Homepage, https://gotham29.github.io/gridshedwatch
+Project-URL: Repository, https://github.com/gotham29/gridshedwatch
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: pandas>=1.5
+Requires-Dist: pyyaml>=6
+Provides-Extra: lstm
+Requires-Dist: torch>=2.0; extra == "lstm"
+Provides-Extra: chronos
+Requires-Dist: torch>=2.0; extra == "chronos"
+Requires-Dist: chronos-forecasting>=1.4; extra == "chronos"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# GridShedWatch
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23626223.svg)](https://doi.org/10.5281/zenodo.23626223) [![tests](https://github.com/gotham29/gridshedwatch/actions/workflows/tests.yml/badge.svg)](https://github.com/gotham29/gridshedwatch/actions/workflows/tests.yml)
+
+**A benchmark for early warning of grid load sheds, scored the way forecasters score weather warnings.**
+
+Website: **https://gotham29.github.io/gridshedwatch** (built from this repo by `scripts/build_site.py`).
+
+Since 2020, US grid operators have had to cut power for lack of supply eight times. The public
+was warned beforehand in four of them, and in none of the four during Winter Storm Elliott.
+Plenty of methods claim to detect grid trouble early, but there has been no shared test of
+whether a warning would actually have come in time. GridShedWatch is that test: every one of
+those eight load sheds, public hourly data, and one fixed scoring procedure that any method can
+be run through.
+
+The National Weather Service scores every warning it issues on three numbers read together:
+how many events were warned in advance, how much lead time people got, and how often warnings
+were false alarms. GridShedWatch asks the same of grid warnings, at two levels: a **watch**
+(about one a month per grid: something unusual is building) and a **warning** (two a year: act).
+
+## What's in it
+
+| | |
+|---|---|
+| **Events** | 8 supply-shortfall load sheds of at least 250 MW, Jan 2020 to Sep 2026, chosen by a stated rule from NERC's annual lists ([docs/events.md](https://github.com/gotham29/gridshedwatch/blob/main/docs/events.md)) |
+| **Data** | A frozen snapshot of EIA-930 hourly demand, day-ahead forecast and net generation for the 8 grids, 2019-2026, and the five signals built from it ([gridshedwatch/snapshot_v1.0/](https://github.com/gotham29/gridshedwatch/tree/main/gridshedwatch/snapshot_v1.0/), [gridshedwatch/data.py](https://github.com/gotham29/gridshedwatch/blob/main/gridshedwatch/data.py)) |
+| **Rules** | One shared rule that turns per-signal scores into watches and warnings, so methods differ only in how they score each hour ([gridshedwatch/rules.py](https://github.com/gotham29/gridshedwatch/blob/main/gridshedwatch/rules.py)) |
+| **Scoring** | Same alert budget for every method, chosen without looking at the events; events caught, lead time and false alarm ratio, with bootstrap intervals and a chance baseline ([docs/scoring.md](https://github.com/gotham29/gridshedwatch/blob/main/docs/scoring.md)) |
+| **Status quo** | Every operator notice in the week before each event, with times and sources ([gridshedwatch/operator_notices.yaml](https://github.com/gotham29/gridshedwatch/blob/main/gridshedwatch/operator_notices.yaml)) |
+| **Reference methods** | An operator-style rule, a seasonal z-score, an LSTM forecaster, Chronos-Bolt (zero-shot), and HTM ([gridshedwatch/baselines/](https://github.com/gotham29/gridshedwatch/tree/main/gridshedwatch/baselines/)) |
+| **Datasheet** | Motivation, composition, collection, intended uses, known biases and maintenance ([docs/datasheet.md](https://github.com/gotham29/gridshedwatch/blob/main/docs/datasheet.md)) |
+
+| Event | Grid | Shed at its worst | Split |
+|---|---|---|---|
+| Heat wave, Aug 2020 | California (CAISO) | about 1,000 MW | development |
+| Winter Storm Uri, Feb 2021 | Texas (ERCOT) | 20,000 MW | development |
+| Uri | Southwest Power Pool | 2,700 MW | held-out |
+| Uri | MISO (MISO South) | 700 MW | held-out |
+| Winter Storm Elliott, Dec 2022 | Tennessee Valley Authority | 3,000 MW | development |
+| Elliott | Duke Energy Carolinas | up to 1,000 MW | held-out |
+| Elliott | Duke Energy Progress | about 960 MW | held-out |
+| Elliott | LG&E and KU (Kentucky) | about 300 MW | held-out |
+
+## Results, v1.0
+
+<!-- leaderboard:start -->
+| Method | Watches: caught (of 8) | held-out (of 5) | by chance | median lead (h) | Warnings: caught (of 8) | held-out (of 5) | by chance | False alarm ratio (watch / warning) |
+|---|---|---|---|---|---|---|---|---|
+| Operators (public notices) | 4 | 2 | - | 20 | - | - | - | - |
+| Operator-style rule | 5 [3.0-7.0] | 4 | 1.2 | 85 | 2 [0.0-4.0] | 1 | 0.2 | 98% / 94% |
+| Seasonal z-score | 5 [3.0-7.0] | 4 | 1.1 | 105 | 6 [4.0-8.0] | 4 | 0.2 | 98% / 92% |
+| Chronos-Bolt (zero-shot) | 1 [0.0-3.0] | 1 | 0.9 | 9 | 3 [1.0-5.0] | 1 | 0.3 | 100% / 96% |
+| LSTM forecaster | 6.4 [4.6-8.0] | 4.4 | 1.3 | 8 | 4.8 [2.8-6.8] | 2.8 | 0.3 | 99% / 94% |
+| HTM (htm-monitor) | 6 [4.6-7.2] | 4 | 1.4 | 56 | 5.6 [3.8-7.2] | 3.6 | 0.3 | 98% / 93% |
+
+All five reference methods are in the scores track; no alerts-track entries yet. Mean over 5 seeds for the LSTM and HTM. [a-b]: 5th-95th percentile with events resampled. Operators: public notices in the 7 days before onset, scored as watches.
+<!-- leaderboard:end -->
+
+Every method except Chronos's watches catches far more than chance, and none leads at both
+levels. The differences are by kind of emergency: the simple rules caught all three Uri events
+days ahead, the LSTM and HTM caught the Elliott events hours ahead (when the public got no
+warning), and only the operators warned California. With eight events, differences of about one
+event are not meaningful. Per-event results: `results/v1.0/<method>_events.csv`.
+
+## Quick start
+
+```bash
+pip install gridshedwatch                # or, to work on the code:
+git clone https://github.com/gotham29/gridshedwatch && cd gridshedwatch
+pip install -e ".[test]"
+gridshedwatch info                       # the eight events and their timelines
+gridshedwatch score --oprule             # score the built-in operator-style rule
+python examples/my_method.py             # scores track template: writes my_scores/
+gridshedwatch score my_scores --name "My method"
+python examples/my_alerts.py             # alerts track template: writes my_alerts.csv
+gridshedwatch score-alerts my_alerts.csv --name "My rule"
+```
+
+## Add your method
+
+There are two ways in.
+
+**Scores track** (the controlled comparison). Your method says, for every grid, every hour and
+each of the five signals, how unusual that signal is now, as a score in [0, 1], using data up to
+that hour only. Write the scores in the submission layout (`my_scores/s<seed>/<grid>.csv`, see
+[gridshedwatch/submission.py](https://github.com/gotham29/gridshedwatch/blob/main/gridshedwatch/submission.py)) and run `gridshedwatch score`. The
+shared rules, the label-free budget step and the scoring are done for you, so your method
+cannot be tuned toward the eight events. Template: [examples/my_method.py](https://github.com/gotham29/gridshedwatch/blob/main/examples/my_method.py).
+
+**Alerts track** (any method). If your method decides on its own when to raise a watch or a
+warning (a rule, a classifier, a weather-based model, a human forecaster), list when each alert
+started:
+
+```
+grid,level,start_utc,seed
+tx,watch,2021-02-11 03:00,0
+```
+
+and run `gridshedwatch score-alerts alerts.csv --name "My method"`. It is scored exactly like
+the scores track, at the same budget (median grid at most 12 watches and 2 warnings a year, no
+grid above 3 times that). Format: [gridshedwatch/alerts.py](https://github.com/gotham29/gridshedwatch/blob/main/gridshedwatch/alerts.py); template:
+[examples/my_alerts.py](https://github.com/gotham29/gridshedwatch/blob/main/examples/my_alerts.py); worked examples: the five reference methods'
+alerts in [results/v1.0/alerts/](https://github.com/gotham29/gridshedwatch/tree/main/results/v1.0/alerts/), which reproduce the table above.
+
+- Scores track: use the five signals provided (and 2019 for calibration). Alerts track: any data
+  available at the time of each alert. Methods that use data beyond the five signals are listed
+  separately.
+- If your method is random, submit several seeds; results are averaged.
+- To add a result to the table, open a pull request with your scores or alerts (or a link to
+  them), the code that produced them, the output of `--json`, and short answers on the data used
+  and, for the alerts track, which events you looked at while developing
+  ([docs/scoring.md](https://github.com/gotham29/gridshedwatch/blob/main/docs/scoring.md#listing-a-result)). Every result is added, including ones
+  that beat the reference methods.
+
+## Reproducing v1.0
+
+```bash
+python -m pytest -q                      # rebuilds the rule and z-score results from the data
+python scripts/fetch_reference.py        # reference scores for LSTM, Chronos, HTM (about 100 MB)
+python -m pytest -q                      # now also checks those three against results/v1.0/
+python scripts/reproduce_v1.py           # writes results/v1.0/ from scratch
+docker build -t gridshedwatch . && docker run --rm gridshedwatch
+```
+
+The LSTM and Chronos can be rerun with `gridshedwatch baseline lstm|chronos -o DIR` (needs
+`pip install -e ".[lstm]"` or `".[chronos]"`). Neural-network training is not bit-identical
+across platforms and library versions, so a rerun gives close but not identical scores; the
+reference scores are the official v1.0 results. HTM's scores come from
+[htm-monitor](https://github.com/gotham29/htm-monitor), scored here like any other submission.
+
+## Limits
+
+- Eight events, seven from two storms (Uri and Elliott). One storm of a new kind could change
+  the picture.
+- Three events were used to design the shared rules; five were held out and scored once.
+- Reference methods see only five signals from EIA-930: no weather, outage or market data. The
+  alerts track is open to methods that use more.
+- The status quo row covers operators' public notices; their notices to the industry and their
+  false alarms in ordinary years are not yet compiled.
+
+GridShedWatch grows as new events happen: each load shed that meets the rule is added in a new
+version and scored with the rules frozen in v1.0.
+
+## Citation and license
+
+DOI: [10.5281/zenodo.23626223](https://doi.org/10.5281/zenodo.23626223) (archived on Zenodo with every release). See [CITATION.cff](https://github.com/gotham29/gridshedwatch/blob/main/CITATION.cff). Code: MIT. Event list, timelines, documentation and results:
+CC BY 4.0. EIA-930 data: U.S. public domain ([DATA_LICENSE.md](https://github.com/gotham29/gridshedwatch/blob/main/DATA_LICENSE.md)).

gridshedwatch-1.1.1/README.md

@@ -0,0 +1,147 @@
+# GridShedWatch
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23626223.svg)](https://doi.org/10.5281/zenodo.23626223) [![tests](https://github.com/gotham29/gridshedwatch/actions/workflows/tests.yml/badge.svg)](https://github.com/gotham29/gridshedwatch/actions/workflows/tests.yml)
+
+**A benchmark for early warning of grid load sheds, scored the way forecasters score weather warnings.**
+
+Website: **https://gotham29.github.io/gridshedwatch** (built from this repo by `scripts/build_site.py`).
+
+Since 2020, US grid operators have had to cut power for lack of supply eight times. The public
+was warned beforehand in four of them, and in none of the four during Winter Storm Elliott.
+Plenty of methods claim to detect grid trouble early, but there has been no shared test of
+whether a warning would actually have come in time. GridShedWatch is that test: every one of
+those eight load sheds, public hourly data, and one fixed scoring procedure that any method can
+be run through.
+
+The National Weather Service scores every warning it issues on three numbers read together:
+how many events were warned in advance, how much lead time people got, and how often warnings
+were false alarms. GridShedWatch asks the same of grid warnings, at two levels: a **watch**
+(about one a month per grid: something unusual is building) and a **warning** (two a year: act).
+
+## What's in it
+
+| | |
+|---|---|
+| **Events** | 8 supply-shortfall load sheds of at least 250 MW, Jan 2020 to Sep 2026, chosen by a stated rule from NERC's annual lists ([docs/events.md](https://github.com/gotham29/gridshedwatch/blob/main/docs/events.md)) |
+| **Data** | A frozen snapshot of EIA-930 hourly demand, day-ahead forecast and net generation for the 8 grids, 2019-2026, and the five signals built from it ([gridshedwatch/snapshot_v1.0/](https://github.com/gotham29/gridshedwatch/tree/main/gridshedwatch/snapshot_v1.0/), [gridshedwatch/data.py](https://github.com/gotham29/gridshedwatch/blob/main/gridshedwatch/data.py)) |
+| **Rules** | One shared rule that turns per-signal scores into watches and warnings, so methods differ only in how they score each hour ([gridshedwatch/rules.py](https://github.com/gotham29/gridshedwatch/blob/main/gridshedwatch/rules.py)) |
+| **Scoring** | Same alert budget for every method, chosen without looking at the events; events caught, lead time and false alarm ratio, with bootstrap intervals and a chance baseline ([docs/scoring.md](https://github.com/gotham29/gridshedwatch/blob/main/docs/scoring.md)) |
+| **Status quo** | Every operator notice in the week before each event, with times and sources ([gridshedwatch/operator_notices.yaml](https://github.com/gotham29/gridshedwatch/blob/main/gridshedwatch/operator_notices.yaml)) |
+| **Reference methods** | An operator-style rule, a seasonal z-score, an LSTM forecaster, Chronos-Bolt (zero-shot), and HTM ([gridshedwatch/baselines/](https://github.com/gotham29/gridshedwatch/tree/main/gridshedwatch/baselines/)) |
+| **Datasheet** | Motivation, composition, collection, intended uses, known biases and maintenance ([docs/datasheet.md](https://github.com/gotham29/gridshedwatch/blob/main/docs/datasheet.md)) |
+
+| Event | Grid | Shed at its worst | Split |
+|---|---|---|---|
+| Heat wave, Aug 2020 | California (CAISO) | about 1,000 MW | development |
+| Winter Storm Uri, Feb 2021 | Texas (ERCOT) | 20,000 MW | development |
+| Uri | Southwest Power Pool | 2,700 MW | held-out |
+| Uri | MISO (MISO South) | 700 MW | held-out |
+| Winter Storm Elliott, Dec 2022 | Tennessee Valley Authority | 3,000 MW | development |
+| Elliott | Duke Energy Carolinas | up to 1,000 MW | held-out |
+| Elliott | Duke Energy Progress | about 960 MW | held-out |
+| Elliott | LG&E and KU (Kentucky) | about 300 MW | held-out |
+
+## Results, v1.0
+
+<!-- leaderboard:start -->
+| Method | Watches: caught (of 8) | held-out (of 5) | by chance | median lead (h) | Warnings: caught (of 8) | held-out (of 5) | by chance | False alarm ratio (watch / warning) |
+|---|---|---|---|---|---|---|---|---|
+| Operators (public notices) | 4 | 2 | - | 20 | - | - | - | - |
+| Operator-style rule | 5 [3.0-7.0] | 4 | 1.2 | 85 | 2 [0.0-4.0] | 1 | 0.2 | 98% / 94% |
+| Seasonal z-score | 5 [3.0-7.0] | 4 | 1.1 | 105 | 6 [4.0-8.0] | 4 | 0.2 | 98% / 92% |
+| Chronos-Bolt (zero-shot) | 1 [0.0-3.0] | 1 | 0.9 | 9 | 3 [1.0-5.0] | 1 | 0.3 | 100% / 96% |
+| LSTM forecaster | 6.4 [4.6-8.0] | 4.4 | 1.3 | 8 | 4.8 [2.8-6.8] | 2.8 | 0.3 | 99% / 94% |
+| HTM (htm-monitor) | 6 [4.6-7.2] | 4 | 1.4 | 56 | 5.6 [3.8-7.2] | 3.6 | 0.3 | 98% / 93% |
+
+All five reference methods are in the scores track; no alerts-track entries yet. Mean over 5 seeds for the LSTM and HTM. [a-b]: 5th-95th percentile with events resampled. Operators: public notices in the 7 days before onset, scored as watches.
+<!-- leaderboard:end -->
+
+Every method except Chronos's watches catches far more than chance, and none leads at both
+levels. The differences are by kind of emergency: the simple rules caught all three Uri events
+days ahead, the LSTM and HTM caught the Elliott events hours ahead (when the public got no
+warning), and only the operators warned California. With eight events, differences of about one
+event are not meaningful. Per-event results: `results/v1.0/<method>_events.csv`.
+
+## Quick start
+
+```bash
+pip install gridshedwatch                # or, to work on the code:
+git clone https://github.com/gotham29/gridshedwatch && cd gridshedwatch
+pip install -e ".[test]"
+gridshedwatch info                       # the eight events and their timelines
+gridshedwatch score --oprule             # score the built-in operator-style rule
+python examples/my_method.py             # scores track template: writes my_scores/
+gridshedwatch score my_scores --name "My method"
+python examples/my_alerts.py             # alerts track template: writes my_alerts.csv
+gridshedwatch score-alerts my_alerts.csv --name "My rule"
+```
+
+## Add your method
+
+There are two ways in.
+
+**Scores track** (the controlled comparison). Your method says, for every grid, every hour and
+each of the five signals, how unusual that signal is now, as a score in [0, 1], using data up to
+that hour only. Write the scores in the submission layout (`my_scores/s<seed>/<grid>.csv`, see
+[gridshedwatch/submission.py](https://github.com/gotham29/gridshedwatch/blob/main/gridshedwatch/submission.py)) and run `gridshedwatch score`. The
+shared rules, the label-free budget step and the scoring are done for you, so your method
+cannot be tuned toward the eight events. Template: [examples/my_method.py](https://github.com/gotham29/gridshedwatch/blob/main/examples/my_method.py).
+
+**Alerts track** (any method). If your method decides on its own when to raise a watch or a
+warning (a rule, a classifier, a weather-based model, a human forecaster), list when each alert
+started:
+
+```
+grid,level,start_utc,seed
+tx,watch,2021-02-11 03:00,0
+```
+
+and run `gridshedwatch score-alerts alerts.csv --name "My method"`. It is scored exactly like
+the scores track, at the same budget (median grid at most 12 watches and 2 warnings a year, no
+grid above 3 times that). Format: [gridshedwatch/alerts.py](https://github.com/gotham29/gridshedwatch/blob/main/gridshedwatch/alerts.py); template:
+[examples/my_alerts.py](https://github.com/gotham29/gridshedwatch/blob/main/examples/my_alerts.py); worked examples: the five reference methods'
+alerts in [results/v1.0/alerts/](https://github.com/gotham29/gridshedwatch/tree/main/results/v1.0/alerts/), which reproduce the table above.
+
+- Scores track: use the five signals provided (and 2019 for calibration). Alerts track: any data
+  available at the time of each alert. Methods that use data beyond the five signals are listed
+  separately.
+- If your method is random, submit several seeds; results are averaged.
+- To add a result to the table, open a pull request with your scores or alerts (or a link to
+  them), the code that produced them, the output of `--json`, and short answers on the data used
+  and, for the alerts track, which events you looked at while developing
+  ([docs/scoring.md](https://github.com/gotham29/gridshedwatch/blob/main/docs/scoring.md#listing-a-result)). Every result is added, including ones
+  that beat the reference methods.
+
+## Reproducing v1.0
+
+```bash
+python -m pytest -q                      # rebuilds the rule and z-score results from the data
+python scripts/fetch_reference.py        # reference scores for LSTM, Chronos, HTM (about 100 MB)
+python -m pytest -q                      # now also checks those three against results/v1.0/
+python scripts/reproduce_v1.py           # writes results/v1.0/ from scratch
+docker build -t gridshedwatch . && docker run --rm gridshedwatch
+```
+
+The LSTM and Chronos can be rerun with `gridshedwatch baseline lstm|chronos -o DIR` (needs
+`pip install -e ".[lstm]"` or `".[chronos]"`). Neural-network training is not bit-identical
+across platforms and library versions, so a rerun gives close but not identical scores; the
+reference scores are the official v1.0 results. HTM's scores come from
+[htm-monitor](https://github.com/gotham29/htm-monitor), scored here like any other submission.
+
+## Limits
+
+- Eight events, seven from two storms (Uri and Elliott). One storm of a new kind could change
+  the picture.
+- Three events were used to design the shared rules; five were held out and scored once.
+- Reference methods see only five signals from EIA-930: no weather, outage or market data. The
+  alerts track is open to methods that use more.
+- The status quo row covers operators' public notices; their notices to the industry and their
+  false alarms in ordinary years are not yet compiled.
+
+GridShedWatch grows as new events happen: each load shed that meets the rule is added in a new
+version and scored with the rules frozen in v1.0.
+
+## Citation and license
+
+DOI: [10.5281/zenodo.23626223](https://doi.org/10.5281/zenodo.23626223) (archived on Zenodo with every release). See [CITATION.cff](https://github.com/gotham29/gridshedwatch/blob/main/CITATION.cff). Code: MIT. Event list, timelines, documentation and results:
+CC BY 4.0. EIA-930 data: U.S. public domain ([DATA_LICENSE.md](https://github.com/gotham29/gridshedwatch/blob/main/DATA_LICENSE.md)).

gridshedwatch-1.1.1/gridshedwatch/alerts.py

@@ -0,0 +1,77 @@
+"""Alerts track: read, check and write a method's watch and warning start times.
+
+File format (CSV), one row per alert episode:
+    grid,level,start_utc[,seed]
+    tx,watch,2021-02-11 03:00,0
+grid: one of gridshedwatch.data.grids(); level: watch or warning; start_utc: when the alert
+episode began, UTC (ISO format; minutes allowed); seed: optional, for methods with randomness
+(default 0). Starts must fall in the scored period: after the first week of the run (warm-up)
+and before the end of the run. A grid with no rows has no alerts.
+
+An episode is one alert, however long it lasts: if your method raises an alert and keeps it on,
+list the time it came on. Alerts must be issued using data up to that time only.
+"""
+from pathlib import Path
+
+import pandas as pd
+
+from . import data
+
+LEVELS = ("watch", "warning")
+COLUMNS = ["grid", "level", "start_utc"]
+
+
+def scored_period(grid: str) -> tuple:
+    tb = data.timebase(grid)
+    s = tb.loc[tb.in_warmup == 0, "timestamp"]
+    return s.iloc[0], s.iloc[-1]
+
+
+def check(df: pd.DataFrame) -> pd.DataFrame:
+    missing = [c for c in COLUMNS if c not in df]
+    if missing:
+        raise ValueError(f"missing columns {missing}; need grid, level, start_utc (and optionally seed)")
+    df = df.copy()
+    if "seed" not in df:
+        df["seed"] = 0
+    bad = sorted(set(df.grid) - set(data.grids()))
+    if bad:
+        raise ValueError(f"unknown grids {bad}; use {data.grids()}")
+    bad = sorted(set(df.level) - set(LEVELS))
+    if bad:
+        raise ValueError(f"unknown levels {bad}; use watch or warning")
+    try:
+        df["start_utc"] = pd.to_datetime(df.start_utc, utc=True).dt.tz_localize(None)
+    except (ValueError, TypeError) as e:
+        raise ValueError(f"start_utc must be UTC timestamps: {e}") from None
+    df["seed"] = df.seed.astype(int)
+    for g, x in df.groupby("grid"):
+        lo, hi = scored_period(g)
+        out = x[(x.start_utc < lo) | (x.start_utc > hi)]
+        if len(out):
+            raise ValueError(f"{g}: {len(out)} starts outside the scored period {lo} to {hi}, e.g. {out.start_utc.iloc[0]}")
+    dup = df.duplicated(["seed", "grid", "level", "start_utc"])
+    if dup.any():
+        raise ValueError(f"{dup.sum()} duplicate rows (same seed, grid, level and start)")
+    return df
+
+
+def load(path) -> dict:
+    """{seed: {grid: {level: [Timestamp, ...]}}}"""
+    df = check(pd.read_csv(path))
+    out = {}
+    for (k, g, lv), x in df.groupby(["seed", "grid", "level"]):
+        out.setdefault(int(k), {}).setdefault(g, {})[lv] = sorted(x.start_utc)
+    return out or {0: {}}
+
+
+def from_rows(rows: pd.DataFrame) -> pd.DataFrame:
+    """Alert file rows from a scored Result's rows (to export a scores-track method's alerts)."""
+    recs = [dict(grid=r.grid, level=r.level, start_utc=pd.Timestamp(t).strftime("%Y-%m-%d %H:%M"), seed=int(r.seed))
+            for r in rows.itertuples() for t in str(r.starts).split("|") if t and t != "nan"]
+    return pd.DataFrame(recs, columns=COLUMNS + ["seed"]).sort_values(["seed", "grid", "level", "start_utc"])
+
+
+def write(df: pd.DataFrame, path) -> None:
+    Path(path).parent.mkdir(parents=True, exist_ok=True)
+    df.to_csv(path, index=False)

gridshedwatch-1.1.1/gridshedwatch/baselines/__init__.py

@@ -0,0 +1,14 @@
+"""Reference methods. Each turns the five signals into per-signal scores p in [0, 1], except the
+operator-style rule, which raises alerts directly from demand and its day-ahead forecast."""
+import bisect
+
+import numpy as np
+
+
+def to_p(score: np.ndarray) -> np.ndarray:
+    """Causal empirical CDF: share of strictly earlier scores that are <= the current one."""
+    seen, p = [], np.zeros(len(score))
+    for t, s in enumerate(score):
+        p[t] = bisect.bisect_right(seen, s) / len(seen) if seen else 0.0
+        bisect.insort(seen, s)
+    return p

gridshedwatch-1.1.1/gridshedwatch/baselines/chronos.py

@@ -0,0 +1,39 @@
+"""Chronos-Bolt, zero-shot (Ansari et al., 2024). Needs: pip install gridshedwatch[chronos].
+
+Per grid and signal, the pretrained model forecasts the next hour from the previous 512 (the 2019
+tail supplies the context for the first run hours); score = |actual - median forecast|. No
+training or tuning, so it is deterministic. Caveat: the pretraining corpus includes public
+electricity data, so overlap with 2020-2026 EIA-930 cannot be ruled out.
+"""
+import numpy as np
+import pandas as pd
+
+from .. import data
+from ..config import SIGNALS
+from . import to_p
+
+CTX = 512
+MODEL = "amazon/chronos-bolt-small"
+
+
+def scores(grid: str, model: str = MODEL, device: str = "cpu", batch: int = 1024) -> pd.DataFrame:
+    try:
+        import torch
+        from chronos import BaseChronosPipeline
+    except ImportError as e:                      # pragma: no cover
+        raise ImportError("the Chronos baseline needs: pip install gridshedwatch[chronos]") from e
+    pipe = BaseChronosPipeline.from_pretrained(model, device_map=device, torch_dtype=torch.float32)
+    X = data.signals(grid)
+    cal_all = data.calibration(grid)
+    out = {}
+    for f in SIGNALS:
+        cal = cal_all[f].dropna().to_numpy(float)
+        run = np.nan_to_num(X[f].to_numpy(float), nan=float(np.nanmedian(cal)))
+        full = np.concatenate([cal[-CTX:], run]).astype(np.float32)
+        W = np.lib.stride_tricks.sliding_window_view(full, CTX + 1)
+        raw = np.empty(len(W), dtype=np.float32)
+        for a in range(0, len(W), batch):
+            q, _ = pipe.predict_quantiles(torch.tensor(W[a:a + batch, :CTX]), prediction_length=1, quantile_levels=[0.5])
+            raw[a:a + batch] = np.abs(W[a:a + batch, CTX] - q[:, 0, 0].numpy())
+        out[f"p_{f}"] = np.round(to_p(raw), 6)
+    return pd.DataFrame(out)

gridshedwatch-1.1.1/gridshedwatch/baselines/lstm.py

@@ -0,0 +1,88 @@
+"""LSTM forecaster (LSTM-AD, Malhotra et al., ESANN 2015). Needs: pip install gridshedwatch[lstm].
+
+Per grid and signal, a 2-layer, 64-unit LSTM reads the previous 24 hours and predicts the next;
+the score is the absolute error. Signals are scaled by their 2019 0.1-99.9th percentile range.
+Trained on 2019 only (Adam 1e-3, batch 64, up to 50 epochs, early stopping on the last 10% of
+2019), then frozen. Seed k uses torch seed 42 + 1000 k. Settings are common defaults, not tuned
+on events. Expect about an hour per seed on a laptop CPU.
+"""
+import numpy as np
+import pandas as pd
+
+from .. import data
+from ..config import SIGNALS
+from . import to_p
+
+L = 24
+SEED_BASE = 42
+
+
+def _torch():
+    try:
+        import torch
+        from torch import nn
+    except ImportError as e:                      # pragma: no cover
+        raise ImportError("the LSTM baseline needs torch: pip install gridshedwatch[lstm]") from e
+    return torch, nn
+
+
+def scores(grid: str, seed: int = 0, threads: int = 1) -> pd.DataFrame:
+    torch, nn = _torch()
+    torch.set_num_threads(threads)
+
+    class Net(nn.Module):
+        def __init__(self, hidden=64, layers=2):
+            super().__init__()
+            self.lstm = nn.LSTM(1, hidden, num_layers=layers, batch_first=True)
+            self.head = nn.Linear(hidden, 1)
+
+        def forward(self, x):
+            out, _ = self.lstm(x)
+            return self.head(out[:, -1]).squeeze(-1)
+
+    def windows(x):
+        W = np.lib.stride_tricks.sliding_window_view(x, L + 1)
+        return torch.tensor(W[:, :L, None], dtype=torch.float32), torch.tensor(W[:, L], dtype=torch.float32)
+
+    def fit(model, X, y, s, max_epochs=50, patience=5):
+        torch.manual_seed(s)
+        n_val = max(1, len(X) // 10)
+        Xtr, ytr, Xva, yva = X[:-n_val], y[:-n_val], X[-n_val:], y[-n_val:]
+        opt = torch.optim.Adam(model.parameters(), lr=1e-3)
+        best, state, bad = np.inf, None, 0
+        g = torch.Generator().manual_seed(s)
+        for _ in range(max_epochs):
+            model.train()
+            for idx in torch.randperm(len(Xtr), generator=g).split(64):
+                opt.zero_grad()
+                nn.functional.mse_loss(model(Xtr[idx]), ytr[idx]).backward()
+                opt.step()
+            model.eval()
+            with torch.no_grad():
+                v = nn.functional.mse_loss(model(Xva), yva).item()
+            if v < best - 1e-6:
+                best, state, bad = v, {k: t.clone() for k, t in model.state_dict().items()}, 0
+            else:
+                bad += 1
+                if bad >= patience:
+                    break
+        model.load_state_dict(state)
+        return model
+
+    X = data.signals(grid)
+    cal_all = data.calibration(grid)
+    b = data.bounds_2019(grid)
+    out = {}
+    for f in SIGNALS:
+        lo, hi = b[f]
+        cal = (cal_all[f].dropna().to_numpy(float) - lo) / (hi - lo)
+        run = np.nan_to_num((X[f].to_numpy(float) - lo) / (hi - lo), nan=0.0)
+        net = fit(Net(), *windows(cal), SEED_BASE + 1000 * seed)
+        full = np.concatenate([cal, run])
+        Xw, yw = windows(full[len(cal) - L:])
+        net.eval()
+        with torch.no_grad():
+            pred = torch.cat([net(x) for x in Xw.split(4096)])
+        raw = (pred - yw).abs().numpy()
+        out[f"p_{f}"] = np.round(to_p(raw), 6)
+    return pd.DataFrame(out)

gridshedwatch-1.1.1/gridshedwatch/baselines/oprule.py

@@ -0,0 +1,32 @@
+"""Operator-style rule: no per-signal model and no groups. An hour is hot when demand runs above
+the day-ahead forecast by more than the trailing year's q-th percentile of percent forecast error
+(q = the benchmark threshold); an alert is on after `persistence` hot hours in a row."""
+from functools import lru_cache
+
+import numpy as np
+import pandas as pd
+
+from .. import data
+
+
+@lru_cache(maxsize=None)
+def hot(grid: str, q: float) -> np.ndarray:
+    w = data.clean_eia930(grid)
+    pct = ((w["D"] - w["DF"]) / w["DF"].where(w["DF"] > 0) * 100).asfreq("h")
+    thr = pct.shift(1).rolling(8760, min_periods=24 * 90).quantile(q)
+    ts = data.timebase(grid)["timestamp"]
+    p, th = pct.reindex(ts).to_numpy(), thr.reindex(ts).to_numpy()
+    return np.nan_to_num(p, nan=-np.inf) > np.nan_to_num(th, nan=np.inf)
+
+
+def alerts(grid: str, level: str, threshold: float, persistence: int, seed: int = 0) -> np.ndarray:
+    h = hot(grid, threshold)
+    warm = data.timebase(grid)["in_warmup"].to_numpy()
+    a, run = np.zeros(len(h), dtype=int), 0
+    for i, x in enumerate(h):
+        if warm[i]:
+            run = 0
+            continue
+        run = run + 1 if x else 0
+        a[i] = int(run >= persistence)
+    return a

gridshedwatch-1.1.1/gridshedwatch/baselines/zscore.py

@@ -0,0 +1,24 @@
+"""Seasonal z-score: how far each signal sits from the median of its past 30 days, in robust
+standard deviations (median absolute deviation x 1.4826). Deterministic."""
+import numpy as np
+import pandas as pd
+
+from .. import data
+from ..config import SIGNALS
+from . import to_p
+
+WINDOW_H = 720
+
+
+def robust_z(x: np.ndarray, W: int = WINDOW_H) -> np.ndarray:
+    s = pd.Series(x)
+    past = s.shift(1)
+    med = past.rolling(W, min_periods=24).median()
+    mad = (past - med).abs().rolling(W, min_periods=24).median()
+    z = (s - med).abs() / (1.4826 * mad.replace(0, np.nan))
+    return z.fillna(0).to_numpy()
+
+
+def scores(grid: str) -> pd.DataFrame:
+    X = data.signals(grid)
+    return pd.DataFrame({f"p_{f}": to_p(robust_z(X[f].to_numpy(float))) for f in SIGNALS})