Datasets#

Example datasets used throughout the documentation. Nothing is shipped with the package: data is downloaded on first use and cached locally, so every example runs after a plain pip install npap.

import npap
from npap.datasets import fetch_pypsa_eur

files = fetch_pypsa_eur()          # downloads once, then reads from cache

manager = npap.PartitionAggregatorManager()
graph = manager.load_data(
    strategy="csv_files",
    node_file=str(files["buses.csv"]),
    edge_file=str(files["lines.csv"]),
)

Fetching#

npap.datasets.fetch_pypsa_eur(data_dir=None, show_progress=True)[source]#

Download the prebuilt PyPSA-Eur network and prepare it for NPAP.

The European high-voltage grid (roughly 6,800 buses across 35 countries), derived from OpenStreetMap. Files are cached after the first call, so subsequent calls return immediately. Column names are harmonised with NPAP’s loader conventions, so the returned paths can be passed straight to load_data().

Parameters:

  • data_dir (str | Path | None) – Cache directory. Defaults to get_data_home().

  • show_progress (bool) – Whether to print download progress. Set to False in scripts and tests.

Returns:

Mapping of filename to local path, with keys "buses.csv", "lines.csv", "transformers.csv", "converters.csv" and "links.csv".

Return type:

dict[str, Path]

Notes

Requires an internet connection on first use. The data is licensed under the ODbL; see the module docstring for attribution and citation details.

Examples

>>> import npap
>>> from npap.datasets import fetch_pypsa_eur
>>> files = fetch_pypsa_eur()
>>> manager = npap.PartitionAggregatorManager()
>>> graph = manager.load_data(
...     strategy="csv_files",
...     node_file=str(files["buses.csv"]),
...     edge_file=str(files["lines.csv"]),
... )

Cache management#

npap.datasets.get_data_home(data_dir=None)[source]#

Return the directory used to cache downloaded datasets.

Resolution order: the explicit data_dir argument, then the NPAP_DATA_HOME environment variable, then a per-user cache directory ($XDG_CACHE_HOME/npap or ~/.cache/npap on Linux and macOS, %LOCALAPPDATA% + /npap on Windows).

The directory is created if it does not exist.

Parameters:

data_dir (str | Path | None) – Explicit cache directory. Overrides every other source.

Returns:

Existing cache directory.

Return type:

Path

npap.datasets.clear_data_home(data_dir=None)[source]#

Delete the dataset cache so the next fetch downloads everything again.

Parameters:

data_dir (str | Path | None) – Cache directory to clear. Defaults to get_data_home().

Return type:

None

The cache location is resolved in this order:

  1. the data_dir argument, when given;

  2. the NPAP_DATA_HOME environment variable;

  3. a per-user cache directory — $XDG_CACHE_HOME/npap or ~/.cache/npap on Linux and macOS, under %LOCALAPPDATA% on Windows.

Note

Cached files never expire on their own. They stay on disk until you remove them, either with clear_data_home() or by deleting the directory. The download is about 20 MB; after the column harmonisation the cache holds roughly 2.7 MB.

Because the Zenodo record is pinned in the source, the cache always matches the dataset version NPAP expects, which keeps examples reproducible. If that pin is ever bumped to a newer record, call clear_data_home() once so the new files are fetched instead of the stale ones.

To keep the data somewhere else — a scratch disk, or a shared location on a cluster — set NPAP_DATA_HOME or pass data_dir explicitly.

Data source and licence#

The network is the prebuilt PyPSA-Eur grid derived from OpenStreetMap:

Xiong, B., Fioriti, D., Neumann, F., Riepin, I., & Brown, T. (2026). Prebuilt electricity network for PyPSA-Eur based on OpenStreetMap data. Zenodo. https://doi.org/10.5281/ZENODO.18619025

Xiong, B., Fioriti, D., Neumann, F., Riepin, I., & Brown, T. (2025). Modelling the high-voltage grid using open data for Europe and beyond. Scientific Data, 12(1). https://doi.org/10.1038/s41597-025-04550-7

The underlying data comes from OpenStreetMap and is licensed under the Open Database License. Credit OpenStreetMap contributors and cite the references above when using it.

On this page