docs: add osm basemap (#1424)

* docs: add osm basemap

* split data section

* rename base network

* add full screen link

doc/conf.py

@@ -20,6 +20,22 @@
 import os
 import sys
 
+import requests
+
+
+def get_basemap(app):
+    url = "https://zenodo.org/records/14144752/files/map.html?download=1"
+    response = requests.get(url)
+
+    build_path = os.path.join(app.builder.outdir, "base-network-raw.html")
+    with open(build_path, "w") as f:
+        f.write(response.text)
+
+
+def setup(app):
+    app.connect("builder-inited", get_basemap)
+
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.

doc/data-base-network.rst

@@ -0,0 +1,45 @@
+..
+  SPDX-FileCopyrightText: 2024 The PyPSA-Eur Authors
+
+  SPDX-License-Identifier: CC-BY-4.0
+
+#############
+Base network
+#############
+
+.. raw:: html
+
+   <iframe src="base-network-raw.html" width="100%" height="600px"></iframe>
+
+The map might take a moment to load. To view it in full screen, click `here <base-network-raw.html>`__.
+
+``data/osm-prebuilt``
+
+- **Source:** OpenStreetMap; Xiong, B., Neumann, F., & Brown, T. (2024).
+  Prebuilt Electricity Network for PyPSA-Eur based on OpenStreetMap Data (0.5)
+  [Data set]. Zenodo. https://doi.org/10.5281/zenodo.13981528
+- **Link:** https://zenodo.org/records/13981528
+- **License:** ODbL (`reference <https://zenodo.org/records/13981528>`)
+- **Description:** Pre-built data of high-voltage transmission grid in Europe from OpenStreetMap.
+
+This dataset contains a topologically connected representation of the European
+high-voltage grid (220 kV to 750 kV) constructed using OpenStreetMap data. Input data
+was retrieved using the `Overpass turbo API <https://overpass-turbo.eu/>`__. A heurisitic
+cleaning process was used to for lines and links where electrical parameters are
+incomplete, missing, or ambiguous. Close substations within a radius of 500 m are
+aggregated to single buses, exact locations of underlying substations is preserved.
+Unique identifiers for lines and links are preserved.
+
+A detailed explanation on the background, methodology, and validation of this dataset
+can be found in `this paper <https://doi.org/10.48550/arXiv.2408.17178>`__ preprint
+currently under peer-review.
+
+Countries included in the dataset:
+
+Albania (AL), Austria (AT), Belgium (BE), Bosnia and Herzegovina (BA), Bulgaria (BG),
+Croatia (HR), Czech Republic (CZ), Denmark (DK), Estonia (EE), Finland (FI), France
+(FR), Germany (DE), Greece (GR), Hungary (HU), Ireland (IE), Italy (IT), Kosovo (XK),
+Latvia (LV), Lithuania (LT), Luxembourg (LU), Moldova (MD), Montenegro (ME), Netherlands
+(NL), North Macedonia (MK), Norway (NO), Poland (PL), Portugal (PT), Romania (RO), Serbia
+(RS), Slovakia (SK), Slovenia (SI), Spain (ES), Sweden (SE), Switzerland (CH), Ukraine
+(UA), United Kingdom (GB)

doc/data-bundle.rst

@@ -0,0 +1,108 @@
+..
+  SPDX-FileCopyrightText: 2024 The PyPSA-Eur Authors
+
+  SPDX-License-Identifier: CC-BY-4.0
+
+###################
+Zenodo data bundle
+###################
+
+Data in this section is downloaded and extracted from the Zenodo data bundle
+(https://zenodo.org/records/12760663). Files included in the data bundle are too
+large to be placed directly in the repository, have been reduced in spatial
+scope to reduce file size, or are not provided through stable URLs elsewhere.
+
+``data/bundle/je-e-21.03.02.xls``
+
+- **Source:** Swiss Federal Statistics Office
+- **Link:** https://www.bfs.admin.ch/bfs/en/home/news/whats-new.assetdetail.7786557.html#context-sidebar
+- **License:**  `custom (OPEN BY ASK) <https://www.bfs.admin.ch/bfs/en/home/fso/swiss-federal-statistical-office/terms-of-use.html>`__
+- **Description:** Population and GDP data for Swiss Cantons.
+
+``data/bundle/NUTS_2013_60M_SH``
+
+- **Source:** GISCO
+- **Link:** https://gisco-services.ec.europa.eu/distribution/v2/nuts/download/
+- **License:** `custom <https://ec.europa.eu/eurostat/web/gisco/geodata/reference-data/administrative-units-statistical-units>`__
+- **Description:** Europe's NUTS administrative regions.
+
+``data/bundle/nama_10r_3popgdp.tsv.gz``
+
+- **Source:** Eurostat
+- **Link:** https://ec.europa.eu/eurostat/databrowser/view/NAMA_10R_3POPGDP/default/table?lang=en
+- **License:** `custom <https://ec.europa.eu/eurostat/about-us/policies/copyright>`__
+- **Description:** Average annual population to calculate regional GDP data (thousand persons) by NUTS 3 regions.
+
+``data/bundle/nama_10r_3gdp.tsv.gz``
+
+- **Source:** Eurostat
+- **Link:** https://ec.europa.eu/eurostat/databrowser/view/nama_10r_3gdp/default/table?lang=en
+- **License:** `custom <https://ec.europa.eu/eurostat/about-us/policies/copyright>`__
+- **Description:** Gross domestic product (GDP) at current market prices by NUTS 3 regions.
+
+``data/bundle/corine``
+
+- **Source:** European Environment Agency (EEA)
+- **Link:** https://sdi.eea.europa.eu/catalogue/copernicus/api/records/a84ae124-c5c5-4577-8e10-511bfe55cc0d
+- **License:** `custom <https://sdi.eea.europa.eu/catalogue/copernicus/api/records/a84ae124-c5c5-4577-8e10-511bfe55cc0d>`__
+- **Description:** CORINE Land Cover (CLC) database.
+
+``data/bundle/eea``
+
+- **Source:** European Environment Agency (EEA)
+- **Link:** https://www.eea.europa.eu/en/datahub/datahubitem-view/3b7fe76c-524a-439a-bfd2-a6e4046302a2
+- **License:** CC-BY 4.0 (`reference <https://www.eea.europa.eu/en/legal-notice#copyright-notice>`__)
+- **Description:** Total GHG emissions and removals in the EU.
+
+``data/bundle/emobility``
+
+- **Source:** German Federal Highway Research Institute (BASt)
+- **Link:** https://www.bast.de/DE/Verkehrstechnik/Fachthemen/v2-verkehrszaehlung/zaehl_node.html
+- **License:** CC-BY 4.0 (`reference <https://www.bast.de/DE/Verkehrstechnik/Fachthemen/v2-verkehrszaehlung/Nutzungsbedingungen.html?nn=1819490>`__)
+- **Description:** Contains data from permanent automatic counting stations on highways and federal roads in Germany.
+
+``data/bundle/h2_salt_caverns_GWh_per_sqkm.geojson``
+
+- **Source:** Dilara Gulcin Caglayan, Nikolaus Weber, Heidi U. Heinrichs, Jochen
+  Linßen, Martin Robinius, Peter A. Kukla, Detlef Stolten, Technical potential
+  of salt caverns for hydrogen storage in Europe, International Journal of
+  Hydrogen Energy, Volume 45, Issue 11, 2020, Pages 6793-6805.
+- **Link:** https://doi.org/10.1016/j.ijhydene.2019.12.161
+- **License:** CC-BY 4.0
+- **Description:** Contains geological hydrogen storage potentials for Europe.
+
+``data/bundle/natura``
+
+- **Source:** European Environment Agency (EEA)
+- **Link:** https://www.eea.europa.eu/en/datahub/datahubitem-view/6fc8ad2d-195d-40f4-bdec-576e7d1268e4
+- **License:** CC-BY 4.0 (`reference <https://www.eea.europa.eu/en/legal-notice#copyright-notice>`__)
+- **Description:** Natura 2000 natural protection areas.
+
+``data/bundle/gebco``
+
+- **Source:** GEBCO
+- **Link:** https://www.gebco.net/data_and_products/gridded_bathymetry_data/version_20141103/
+- **License:** CC0 (`reference <https://www.bodc.ac.uk/data/documents/nodb/301801/>`__)
+- **Description:** Bathymetric dataset (2014 version).
+
+``data/bundle/GDP_per_capita_PPP_1990_2015_v2.nc``
+
+- **Source:** Kummu, M., Taka, M. & Guillaume, J. Gridded global datasets for
+  Gross Domestic Product and Human Development Index over 1990-2015. Sci Data 5,
+  180004 (2018). https://doi.org/10.1038/sdata.2018.4
+- **Link:** https://datadryad.org/stash/dataset/doi:10.5061/dryad.dk1j0
+- **License:** CC0 (`reference <https://datadryad.org/stash/dataset/doi:10.5061/dryad.dk1j0>`__)
+- **Description:** Gridded GDP data.
+
+``data/bundle/ppp_2013_1km_Aggregated.tif``
+
+- **Source:** WorldPop (www.worldpop.org - School of Geography and Environmental
+  Science, University of Southampton; Department of Geography and Geosciences,
+  University of Louisville; Departement de Geographie, Universite de Namur) and
+  Center for International Earth Science Information Network (CIESIN), Columbia
+  University (2018). Global High Resolution Population Denominators Project -
+  Funded by The Bill and Melinda Gates Foundation (OPP1134076).
+  https://dx.doi.org/10.5258/SOTON/WP00647
+- **Link:** https://hub.worldpop.org/doi/10.5258/SOTON/WP00647
+- **License:** CC-BY 4.0 (`reference <https://hub.worldpop.org/geodata/summary?id=24770>`__)
+- **Description:** Gridded population data.