.. SPDX-FileCopyrightText:  PyPSA-Earth and PyPSA-Eur Authors
..
.. SPDX-License-Identifier: CC-BY-4.0

.. _notebooks:

Examples
===================================

In order to familiarize with the code or investigate the input and outputs of
the rules, a ``notebooks`` folder, as part of the `documentation repository <https://github.com/pypsa-meets-earth/documentation>`_ has been provided.
In order to work with these notebooks, you need to set up the recommended folder structure for pypsa-earth:

Start by creating a folder named pypsa-earth-project by executing the following line in the terminal:

.. code:: bash

  $ mkdir pypsa-earth-project

Change the current directory to that folder:

.. code:: bash

  $ cd pypsa-earth-project

Clone pypsa-earth repository from GitHub into the folder:

.. code:: bash

  $ git clone https://github.com/pypsa-meets-earth/pypsa-earth.git

Finally Clone documentation repository into the folder:

.. code:: bash

  $ git clone https://github.com/pypsa-meets-earth/documentation.git

This setup helps you to start working with the following notebooks:

- ``sample_network_analysis``: introduces a sample analysis for the networks built with pypsa-earth tutorial, gives you a taste of what pypsa-earth can do
- ``network_comparison``: compares the network models developed along the data workflow; useful and interactive plots are generated
- ``osm_build_network_plot``: provides specific plots and outputs for the ``download_osm_data`` rule
- ``osm_data_access``: explains how OSM data are being loaded by using ``download_osm_data``
- ``osm_powermap``: contains nice plots and description of the output of the data downloaded and cleaned by using ``download_osm_data`` and ``clean_osm_data``
- ``solve_network_results``: provides useful plots and textual outputs to investigate the results of the last optimization performed using solve_network
- ``build_bus_regions``: it explores the inputs and outputs of the ``build_bus_regions`` rule,
  namely the bus regions shapes, and the elements of the network (lines, substations, etc.)
- ``build_shapes``: describes the shapes created using the rule ``build_shapes`` for the on-shore and off-shore areas
- ``demand_gegis``: it enables exploring th GeGIS dataset used to perform the analysis.
  These data are obtained using the `GlobalEnergyGIS <https://github.com/niclasmattsson/GlobalEnergyGIS>`_ package for Africa.
- ``shape_comparison``: this notebook enables comparing the shapes used along the data workflow
- ``add_electricity``: it analyzes the outputs of the ``add_electricity`` rule, including the PyPSA model and the RES/demand inputs
- ``base_network``: it eases the visualization and analysis of the output PyPSA network model that the rule ``base_network`` builds
- ``build_cutout``: the notebook analyzes the outputs of the rule ``build_cutout`` rule, which are the solar, wind and hydro time series
  generated with `Atlite <https://github.com/PyPSA/atlite/>`_
- ``build_renewable_profiles``: it enables investigating the specific time series generated by the rule ``build_renewable_profiles``;
  in particular, it shows the potential of selected resources (e.g. solar) and the corresponding time series of renewable energy production
  available for selected buses
- ``landuse-availability``: this notebook aims at showing how ``Atlite`` accounts for land constraints in the analysis