bihgrid 0.1.0__py3-none-any.whl

bihgrid/__init__.py

@@ -0,0 +1,18 @@
+"""bihgrid — the Bosnia and Herzegovina transmission grid as a PyG dataset.
+
+Real ≥220 kV grid topology (PyPSA-Eur / OSM) joined with ENTSO-E hourly
+zone-level time series (2015→present), packaged as a
+`torch_geometric.data.InMemoryDataset`.
+
+    from bihgrid import BiHGrid
+    ds = BiHGrid(root="data/bihgrid")
+    data = ds[0]          # static graph + time-series tensors
+    ds.node_generation()  # [T, N] heuristic per-bus generation
+
+See https://github.com/FarukDziho/bih-power-data for sources, licenses and
+the design decisions behind every heuristic (dataset/DESIGN.md).
+"""
+from .dataset import BiHGrid
+
+__version__ = "0.1.0"
+__all__ = ["BiHGrid", "__version__"]

bihgrid/dataset.py

@@ -0,0 +1,229 @@
+"""BiHGrid: torch_geometric InMemoryDataset for the BiH transmission grid."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import torch
+from torch_geometric.data import Data, InMemoryDataset
+
+REPO = "FarukDziho/bih-power-data"
+RAW_FILES = [
+    "nodes.csv",
+    "edges.csv",
+    "gen_bus_weights.csv",
+    "zone_series.parquet",
+    "dataset_summary.json",
+]
+
+# static node features, in x column order
+NODE_FEATURES = [
+    "voltage_kv",
+    "lon",
+    "lat",
+    "is_ba",  # 1 = BA bus, 0 = border bus
+    "plant_coal_mw",
+    "plant_hydro_reservoir_mw",
+    "plant_hydro_pumped_storage_mw",
+    "plant_hydro_ror_mw",
+    "plant_wind_mw",
+]
+# edge features, in edge_attr column order
+EDGE_FEATURES = ["r", "x", "b", "s_nom", "length_km", "circuits",
+                 "is_transformer", "cross_border"]
+
+_PLANT_COLS = {
+    "plant_coal_mw": ["plant_fossil_brown_coal_lignite_mw", "plant_fossil_hard_coal_mw"],
+    "plant_hydro_reservoir_mw": ["plant_hydro_water_reservoir_mw"],
+    "plant_hydro_pumped_storage_mw": ["plant_hydro_pumped_storage_mw"],
+    "plant_hydro_ror_mw": ["plant_hydro_run-of-river_and_poundage_mw",
+                           "plant_hydro_run_of_river_and_poundage_mw"],
+    "plant_wind_mw": ["plant_wind_onshore_mw"],
+}
+
+
+class BiHGrid(InMemoryDataset):
+    """The Bosnia and Herzegovina ≥220 kV transmission grid.
+
+    One static graph (51 buses, 67 per-circuit edges incl. transformers)
+    plus hourly ENTSO-E zone-level series (UTC) and a curated
+    generation→bus weight matrix.
+
+    Args:
+        root: cache directory.
+        revision: git revision of ``FarukDziho/bih-power-data`` to download
+            the dataset files from. A tag like ``"v0.1.0"`` first tries the
+            GitHub-release asset zip, then falls back to raw files at that
+            revision; ``"main"`` (default) uses the latest raw files.
+        transform, pre_transform: standard PyG hooks.
+
+    Node/edge feature orders are ``bihgrid.dataset.NODE_FEATURES`` and
+    ``bihgrid.dataset.EDGE_FEATURES``. The heuristics and their limits are
+    documented in the repo's ``dataset/DESIGN.md`` — read it before using
+    node-level generation as ground truth (it is capacity-weighted
+    zone data, not per-plant metering).
+    """
+
+    def __init__(self, root: str | Path, revision: str = "main",
+                 transform=None, pre_transform=None, force_reload: bool = False):
+        self.revision = revision
+        super().__init__(str(root), transform, pre_transform,
+                         force_reload=force_reload)
+        self.load(self.processed_paths[0])
+        with open(Path(self.processed_dir) / "meta.json") as f:
+            self._meta = json.load(f)
+
+    # ------------------------------------------------------------------ names
+    @property
+    def raw_file_names(self):
+        return RAW_FILES
+
+    @property
+    def processed_file_names(self):
+        return ["data.pt", "meta.json"]
+
+    # ------------------------------------------------------------------ download
+    def download(self):
+        import io
+        import zipfile
+        import requests
+
+        raw_dir = Path(self.raw_dir)
+        if self.revision.startswith("v"):
+            url = (f"https://github.com/{REPO}/releases/download/"
+                   f"{self.revision}/bihgrid-dataset.zip")
+            r = requests.get(url, timeout=300)
+            if r.ok:
+                with zipfile.ZipFile(io.BytesIO(r.content)) as z:
+                    for name in RAW_FILES:
+                        member = next((m for m in z.namelist()
+                                       if m.endswith("dataset/" + name)), None)
+                        if member is None:
+                            break
+                        (raw_dir / name).write_bytes(z.read(member))
+                    else:
+                        return
+        base = (f"https://raw.githubusercontent.com/{REPO}/"
+                f"{self.revision}/dataset/")
+        for name in RAW_FILES:
+            r = requests.get(base + name, timeout=300)
+            r.raise_for_status()
+            (raw_dir / name).write_bytes(r.content)
+
+    # ------------------------------------------------------------------ process
+    def process(self):
+        raw = Path(self.raw_dir)
+        nodes = pd.read_csv(raw / "nodes.csv", dtype={"bus_id": str})
+        edges = pd.read_csv(raw / "edges.csv", dtype={"bus0": str, "bus1": str})
+        weights = pd.read_csv(raw / "gen_bus_weights.csv", dtype={"bus_id": str})
+        zone = pd.read_parquet(raw / "zone_series.parquet")
+        summary = json.loads((raw / "dataset_summary.json").read_text())
+
+        bus_ids = nodes["bus_id"].tolist()
+        idx = {b: i for i, b in enumerate(bus_ids)}
+
+        # ---- static node features
+        feats = pd.DataFrame(index=nodes.index)
+        feats["voltage_kv"] = nodes["voltage"].astype(float)
+        feats["lon"] = nodes["x"].astype(float)
+        feats["lat"] = nodes["y"].astype(float)
+        feats["is_ba"] = (nodes["role"] == "ba").astype(float)
+        for out_col, candidates in _PLANT_COLS.items():
+            cols = [c for c in candidates if c in nodes.columns]
+            feats[out_col] = nodes[cols].sum(axis=1) if cols else 0.0
+        x = torch.tensor(feats[NODE_FEATURES].to_numpy(), dtype=torch.float)
+        pos = torch.tensor(nodes[["x", "y"]].to_numpy(), dtype=torch.float)
+
+        # ---- edges (undirected -> both directions; parallel circuits kept)
+        e = edges.copy()
+        e["is_transformer"] = (e["kind"] == "transformer").astype(float)
+        e["cross_border"] = e["cross_border"].astype(bool).astype(float)
+        for c in ["r", "x", "b", "s_nom", "length_km", "circuits"]:
+            e[c] = pd.to_numeric(e.get(c), errors="coerce").fillna(0.0)
+        src = e["bus0"].map(idx).to_numpy()
+        dst = e["bus1"].map(idx).to_numpy()
+        attr = e[EDGE_FEATURES].to_numpy(dtype=np.float32)
+        edge_index = torch.tensor(np.concatenate([np.stack([src, dst]),
+                                                  np.stack([dst, src])], axis=1),
+                                  dtype=torch.long)
+        edge_attr = torch.tensor(np.concatenate([attr, attr]), dtype=torch.float)
+
+        # ---- generation weight matrix [N, n_types]
+        types = sorted(weights["entsoe_type"].unique())
+        W = np.zeros((len(bus_ids), len(types)), dtype=np.float32)
+        for _, r in weights.iterrows():
+            W[idx[r["bus_id"]], types.index(r["entsoe_type"])] = r["weight"]
+
+        # ---- zone-level hourly series [T, F] (NaN kept as NaN)
+        zone = zone.sort_index()
+        zone_t = torch.tensor(zone.to_numpy(dtype=np.float32))
+        time_unix = torch.tensor(
+            zone.index.view("int64") // 10**9, dtype=torch.long)
+
+        data = Data(x=x, edge_index=edge_index, edge_attr=edge_attr, pos=pos,
+                    gen_weights=torch.tensor(W),
+                    zone_series=zone_t, time_unix=time_unix)
+        data.num_nodes = len(bus_ids)
+        if self.pre_transform is not None:
+            data = self.pre_transform(data)
+        self.save([data], self.processed_paths[0])
+
+        meta = {
+            "bus_ids": bus_ids,
+            "nearest_place": nodes.get("nearest_place",
+                                       pd.Series([None] * len(nodes))).tolist(),
+            "node_features": NODE_FEATURES,
+            "edge_features": EDGE_FEATURES,
+            "gen_weight_types": types,
+            "zone_columns": zone.columns.tolist(),
+            "revision": self.revision,
+            "summary": summary,
+        }
+        (Path(self.processed_dir) / "meta.json").write_text(json.dumps(meta))
+
+    # ------------------------------------------------------------------ helpers
+    @property
+    def meta(self) -> dict:
+        return self._meta
+
+    @property
+    def bus_ids(self) -> list[str]:
+        return self._meta["bus_ids"]
+
+    @property
+    def zone_columns(self) -> list[str]:
+        return self._meta["zone_columns"]
+
+    def zone_dataframe(self) -> pd.DataFrame:
+        """Zone-level hourly series as a pandas DataFrame (UTC index)."""
+        d = self[0]
+        index = pd.to_datetime(d.time_unix.numpy(), unit="s", utc=True)
+        return pd.DataFrame(d.zone_series.numpy(), index=index,
+                            columns=self.zone_columns)
+
+    def node_generation(self, gen_type: str = "Fossil coal (combined)"
+                        ) -> torch.Tensor:
+        """Heuristic per-bus generation series ``[T, N]`` for one type.
+
+        This is zone generation spread over buses by installed-capacity
+        share of *mapped* plants — a documented heuristic, not metering.
+        For ``"Fossil coal (combined)"`` the two ENTSO-E fossil columns are
+        summed first (their classification drifts across years).
+        """
+        d = self[0]
+        types = self._meta["gen_weight_types"]
+        if gen_type not in types:
+            raise ValueError(f"unknown type {gen_type!r}; choose from {types}")
+        w = d.gen_weights[:, types.index(gen_type)]  # [N]
+        cols = self.zone_columns
+        if gen_type == "Fossil coal (combined)":
+            sel = [cols.index("gen_fossil_brown_coal_lignite_mw"),
+                   cols.index("gen_fossil_hard_coal_mw")]
+            zone = d.zone_series[:, sel].nansum(dim=1)  # [T]
+        else:
+            name = ("gen_" + gen_type.lower().replace(" ", "_")
+                    .replace("/", "_").replace("-", "_") + "_mw")
+            zone = d.zone_series[:, cols.index(name)]
+        return zone.unsqueeze(1) * w.unsqueeze(0)

bihgrid-0.1.0.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: bihgrid
+Version: 0.1.0
+Summary: The Bosnia and Herzegovina power grid as a PyTorch Geometric dataset: real >=220kV topology + ENTSO-E hourly time series (2015-present)
+Project-URL: Homepage, https://github.com/FarukDziho/bih-power-data
+Project-URL: Repository, https://github.com/FarukDziho/bih-power-data
+Project-URL: Documentation, https://github.com/FarukDziho/bih-power-data#readme
+Author-email: Faruk Dziho <faruk.dziho@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: Bosnia and Herzegovina,ENTSO-E,dataset,energy,graph-neural-networks,power-grid,pytorch-geometric
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: pyarrow
+Requires-Dist: requests
+Requires-Dist: torch-geometric>=2.4
+Requires-Dist: torch>=2.0
+Description-Content-Type: text/markdown
+
+# bih-power-data
+
+Continuously refreshed dataset and monthly report for the **Bosnia and Herzegovina power system**
+(BA control area, operated by [NOSBiH](https://www.nosbih.ba/en/)), collected from the
+[ENTSO-E Transparency Platform](https://transparency.entsoe.eu/).
+
+**Live report:** `report/index.html` (enable GitHub Pages on this repo to serve it).
+
+## What's collected
+
+| dataset | description |
+|---|---|
+| `load_actual` | actual total load, hourly |
+| `load_forecast` | day-ahead load forecast |
+| `generation_per_type` | actual generation per production type (lignite, hydro ×3, wind, solar…) |
+| `generation_forecast` | day-ahead generation forecast |
+| `installed_capacity` | installed capacity per type (annual) |
+| `flow_BA_XX` / `flow_XX_BA` | cross-border physical flows with HR / RS / ME, both directions |
+| `sched_BA_XX` / `sched_XX_BA` | scheduled commercial exchanges with HR / RS / ME |
+| `day_ahead_prices`, `hydro_reservoir_storage` | attempted; BA may not report these (status noted in `data/state.json`) |
+
+Everything is stored as parquet in `data/`, full history from 2015 where available.
+`data/state.json` tracks coverage and per-dataset status.
+
+## Setup
+
+1. Register (free) at [transparency.entsoe.eu](https://transparency.entsoe.eu/) and generate an
+   API security token in your account settings.
+2. First full collection (locally):
+
+   ```bash
+   pip install -r requirements.txt
+   ENTSOE_TOKEN=your-token python src/collect.py        # full history on first run (takes a while)
+   python src/build_report.py                            # writes report/index.html
+   ```
+
+3. Push to GitHub, then add the token so the weekly refresh works:
+   **Settings → Secrets and variables → Actions → New repository secret** → name `ENTSOE_TOKEN`.
+
+The included workflow (`.github/workflows/refresh.yml`) then re-collects incrementally every
+Monday 03:17 UTC and commits any new data plus a rebuilt report. You can also trigger it manually
+from the Actions tab (**Run workflow**).
+
+## Pipeline test without a token
+
+```bash
+python src/collect.py --demo && python src/build_report.py
+```
+
+generates synthetic data so the whole pipeline and report can be exercised end-to-end.
+
+## Graph-ready dataset
+
+`src/join_graph.py` joins the ENTSO-E time series onto the ≥220 kV topology
+(`topology/out/`) and writes a graph-ready dataset into `dataset/`: hourly
+zone-level series (UTC), 51 buses with `nearest_place` labels and per-type
+plant capacities (from the curated `topology/plants.csv`), 67 per-circuit
+edges with electrical parameters, generation→bus weight vectors, and a
+MultiGraph GraphML. All design decisions (zone-level vs node-level signals,
+plant mapping coverage, cleaning rules) are documented in
+[`dataset/DESIGN.md`](dataset/DESIGN.md). Runs offline from the repo checkout:
+
+```bash
+python src/join_graph.py
+```
+
+## `bihgrid` — PyTorch Geometric package
+
+The dataset ships as a PyG `InMemoryDataset` (auto-downloads from the GitHub
+release or raw files, caches locally):
+
+```bash
+pip install bihgrid
+```
+
+```python
+from bihgrid import BiHGrid
+
+ds = BiHGrid(root="data/bihgrid")        # revision="v0.1.0" pins a release
+data = ds[0]
+data.x           # [51, 9]  voltage, coords, role, per-type plant MW
+data.edge_index  # [2, 134] 67 undirected per-circuit edges, both directions
+data.edge_attr   # [134, 8] r, x, b, s_nom, length_km, circuits, flags
+data.zone_series # [T, 18]  hourly zone signals, UTC (NaN = gap/cleaned)
+ds.zone_dataframe()                       # same as pandas DataFrame
+ds.node_generation("Fossil coal (combined)")  # [T, 51] heuristic — see DESIGN.md
+```
+
+Feature orders: `bihgrid.dataset.NODE_FEATURES` / `EDGE_FEATURES`. Read
+[`dataset/DESIGN.md`](dataset/DESIGN.md) and [`DATASET_CARD.md`](DATASET_CARD.md)
+before treating node-level signals as measurements — they are documented
+heuristics over zone-level data. Tests: `python -m pytest tests/`.
+
+## Releasing
+
+`git tag vX.Y.Z && git push origin vX.Y.Z` → tests, GitHub release with
+dataset zip, PyPI publish, Zenodo DOI. One-time account setup in
+[`PUBLISHING.md`](PUBLISHING.md).
+
+## Roadmap
+
+- [x] Combine with grid topology (PyPSA-Eur / OpenStreetMap extract for BiH) into a
+      graph-ready dataset — candidate for publication. → `dataset/`, `src/join_graph.py`
+- [x] PyG package `bihgrid` (InMemoryDataset, auto-download, PyPI). → `bihgrid/`
+- [x] Zenodo deposit with versioned DOI + dataset card. → `.zenodo.json`,
+      `DATASET_CARD.md`, automated via `release.yml` (one-time setup in `PUBLISHING.md`)
+- [ ] Data paper (Scientific Data / NeurIPS D&B).
+- [ ] Companion collectors for EIA + ERCOT following the same layout.
+
+## License / attribution
+
+Data © ENTSO-E Transparency Platform, reported by NOSBiH; reuse subject to ENTSO-E's
+[terms](https://transparency.entsoe.eu/content/static_content/Static%20content/terms%20and%20conditions/terms%20and%20conditions.html).
+Collection and report code: MIT.

bihgrid-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+bihgrid/__init__.py,sha256=ghc5IUy0dY8sNaOdWqlkAX3rQ_MnfyoEMtLaeItBSvE,680
+bihgrid/dataset.py,sha256=nXpSQVl7aBd6ghLMXGTZfSquqEuEaGTg-9fpgJbxBzc,9598
+bihgrid-0.1.0.dist-info/METADATA,sha256=iTN1oMSJyvpMXepU2JI11cdK_FGYGXMyST6HKa8Lz8Y,6039
+bihgrid-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+bihgrid-0.1.0.dist-info/licenses/LICENSE,sha256=6ZM94bBr-3GCGqd8TveAgtqCiukteHFTWAb_0f0SjBQ,1068
+bihgrid-0.1.0.dist-info/RECORD,,

bihgrid-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

bihgrid-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Faruk Dziho
+
+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.