notebook.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Downloading energy data for a climate-informed power modelling\n",
    "\n",
    "This repository contains a Python static class providing some functions to download fundamental energy time-series (electricity demand, capacity factors, etc.) based on observed data or modelled using meteorological variables ad predictors.\n",
    "\n",
    "## Why\n",
    "I needed a single class able to give the same information from different sources, for example electricity demand from ENTSO-E and from a regression model. \n",
    "\n",
    "## Requirements\n",
    "This class needs the following modules:\n",
    "  - pandas\n",
    "  - [entsoe-py](https://github.com/EnergieID/entsoe-py)\n",
    "\n",
    "## Quick start\n",
    "This code is quite simple and this notebook should be enough to understand how it works. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from metenergy_data import *\n",
    "import pandas as pd\n",
    "import matplotlib.pyplot as plt"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Electricity demand from a regression model (`get_demand_met`)\n",
    "\n",
    "This function returns the hourly electricity demand using a regression model which include heating/cooling degree days and other predictors. \n",
    "The model uses the following predictors:\n",
    "  - Cooling degree hours (`cool`): the positive absolute difference between the air temperature and 24 degrees\n",
    "  - Heating degree hours (`heat`): the negative absolute difference between the air temperature and 15 degrees\n",
    "  - surface solar radiation (`ssr`): hourly GHI \n",
    "  - Is not working day?  (`holTRUE`): a flag that is `True` (1) if the hour is during a not working day (holiday or weekend)\n",
    "  - Hour of the day (`hour01`-`hour24`): a flag that is `True` (1) for a specific hour of the day\n",
    "  - Day of the week (`wday01`-`wday07`): a flag that is `True` (1) for a specific day of the week (Monday = 1)\n",
    "\n",
    "The predictand is the demand obtained after 1) subtracting the minimum and 2) dividing by the maximum (after 1).\n",
    "\n",
    "### Regression\n",
    "The demand is modelled using a linear regression without intercept. \n",
    "The file `coef_table.csv` reports a set of coefficients obtained using a linear regression calibrated on the ENTSO-E demand 2016-2021 (see the file `create_demand_coefs.R`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2022-01-01 00:00:00    1034.464272\n",
       "2022-01-01 01:00:00    1013.314599\n",
       "2022-01-01 02:00:00    1010.004269\n",
       "2022-01-01 03:00:00    1004.980578\n",
       "2022-01-01 04:00:00    1049.500199\n",
       "Freq: H, dtype: float64"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Creating two toy Pandas series for temperature and solar radiation, they must have the same index \n",
    "tmp = pd.Series(data = [25, 24, 25, 25, 32, 16], index = pd.date_range('2022-01-01', periods=6, freq = 'H'))\n",
    "ssr = pd.Series(data = [1000, 1000, 1000, 1000, 1000, 0], index = pd.date_range('2022-01-01', periods=6, freq = 'H'))\n",
    "# Regression coefficients taken from the `coef_table.csv` file\n",
    "coefs = pd.Series({\n",
    "    'cool': 0.0333650197959712,\n",
    "    'heat': 0.0080499097473287,\n",
    "    'holTRUE': -0.0890738157354042,\n",
    "    'hour01': -0.0723833477966008, 'hour10': 0.2787366644750263, 'hour11': 0.335406024306668,\n",
    "    'hour12': 0.3695763069062104,  'hour13': 0.3914698813876043, 'hour14': 0.3643847996129109,\n",
    "    'hour15': 0.3170034432426849,  'hour16': 0.2779672146628518, 'hour17': 0.2492430307469556,\n",
    "    'hour18': 0.2344702584486696,  'hour19': 0.239347665947145,  'hour02': -0.1223000165163405,\n",
    "    'hour20': 0.2521665802832067,  'hour21': 0.2481931604807891, 'hour22': 0.1750528221674458,\n",
    "    'hour23': 0.0749100691347142,  'hour03': -0.1474184730935694,'hour04': -0.1583755042945401,\n",
    "    'hour05': -0.1461127747356147, 'hour06': -0.0767027633079594,'hour07': 0.0253200940451406,\n",
    "    'hour08': 0.1068667070334171,  'hour09': 0.1963906711490293, 'ssrd': -0.0002364300447453748,\n",
    "    'wday01': 0.1693777417222244,  'wday02': 0.3542232743038623, 'wday03': 0.3875902598905701,\n",
    "    'wday04': 0.3925591632067406,  'wday05': 0.3917999830715494, 'wday06': 0.3753863865335905,\n",
    "    'wday07': 0.2496945106926198})\n",
    "\n",
    "out = metenergy_data.get_demand_met(tmp, ssr, coefs, min_load = 1000, max_load = 1200)\n",
    "out.head()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Electricity demand from Zenodo (`get_demand_entsoe_zenodo`)\n",
    "\n",
    "This function can be used to retrieve data for ten countries from the ENTSO-E Transparency Platform accessing a snapshot uploaded on Zenodo (https://zenodo.org/record/7182603). The data is from Jan 2016 to Sep 2022. This function downloads the data (in Parquet format) and returns it as a data frame. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<AxesSubplot:>"
      ]
     },
     "execution_count": 42,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAYQAAAEbCAYAAADajfNFAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjUuMywgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy/NK7nSAAAACXBIWXMAAAsTAAALEwEAmpwYAACIyklEQVR4nO29edhdVXk2fj9nfufMISSBMAWFMAQioDIIouLQggMW20+gtVK8tF+ttr9qJ7WtLeonWuxXKQUFW0UQRHGgigJ+hTKYMAphCBBISMicdzrj3mf9/tjr2XvtfdZae7/JO2fd15Ur591nnX3W3mft9cz3Q0IIODg4ODg45KZ6Ag4ODg4O0wNOIDg4ODg4AHACwcHBwcFBwgkEBwcHBwcATiA4ODg4OEg4geDg4ODgAAAoTPUE9hULFiwQK1asmOppODg4OMworFu3bqcQYqHuvRkrEFasWIG1a9dO9TQcHBwcZhSI6CXTe85l5ODg4OAAwAkEBwcHBwcJJxAcHBwcHADM4BiCg4PDzECr1cLmzZtRr9eneioHFCqVCpYtW4ZisZj5M04gODg4TCg2b96Mvr4+rFixAkQ01dM5ICCEwK5du7B582YcdthhmT/nXEYODg4Tinq9jvnz5zthMIkgIsyfP3/MVlmqQCCiChE9RESPEdGTRPQ5efwmInpU/ttIRI/K4yuIqKa8d7VyrpOJ6Aki2kBEV5FcIURUlufbQEQPEtGKMV2Fg8Msw5a9NWzYPjLV0xg3OGEw+diXe57FQmgAOEcIcQKAEwGcR0SnCSF+RwhxohDiRAC3Avi+8pnn+T0hxOXK8a8DuAzAUfLfefL4hwDsEUIcCeArAL4w5itxcJgC3LpuM25Zt3ncz/uGK+7CuVf+CrtGGuN+7gMVt912G4gITz/9dOrYr371q6hWq/v8Xddffz0+9rGPZT6+PxjPc6YKBBGAVZWi/Bd21ZFa/vsB3Gg7DxEtAdAvhLhfBF15vgXgAvn2+QBukK9vAfBmciqFwwzAJ7/3GP7se49N2Plf2r3vm5JDHDfeeCNOP/10fPe7300du78CYaYiUwyBiPLSJbQdwJ1CiAeVt88AsE0I8Zxy7DAieoSIfkVEZ8hjSwGoqtRmeYzf2wQAQggPwCCA+Zp5XEZEa4lo7Y4dO7JM3cFh2mDdS3vwH/dvHNNndo00J2YyBxhGRkZw33334brrrosJBN/38Wd/9mc47rjjcPzxx+NrX/sarrrqKmzZsgVnn302zj77bABAb29v+JlbbrkFl156KQDgRz/6EU499VSsXr0a5557LrZt27ZP87vyyiuxatUqrFq1Cl/96lfD4xdccAFOPvlkHHvssbjmmmvC49/85jexcuVKnHXWWbjvvvv26Tt1yJRlJITwAZxIRHMA3EZEq4QQv5FvfwBx62ArgEOEELuI6GQAPyCiYwHoNH62NGzvqfO4BsA1ALBmzRrX+9NhSrF7NNqsW34bxbxdv3rv1/8HAPB7px6KXC6bATxcb+37BKchPvejJ/HUlqFxPecxB/fjM791rHXMD37wA5x33nlYuXIl5s2bh4cffhgnnXQSrrnmGrz44ot45JFHUCgUsHv3bsybNw9XXnkl7r77bixYsMB63tNPPx0PPPAAiAjXXnstvvjFL+LLX/7ymOa/bt06fPOb38SDDz4IIQROPfVUnHXWWVi9ejW+8Y1vYN68eajVanjd616H9773vWg2m/jMZz6DdevWYWBgAGeffTZWr149pu80YUxZRkKIvQDugfT9E1EBwHsA3KSMaQghdsnX6wA8D2AlAotgmXK6ZQC2yNebASxXzjkAYPdYL8bBYTKxU/Hv//MvnrOMjGPbsD3zw29Hus5Iwxv7xBw6cOONN+Kiiy4CAFx00UW48cZAh/3FL36Byy+/HIVCoBvPmzdvTOfdvHkz3va2t+G4447Dl770JTz55JNjntu9996Ld7/73ejp6UFvby/e85734L//+78BAFdddRVOOOEEnHbaadi0aROee+45PPjgg3jTm96EhQsXolQq4Xd+53fG/J0mpFoIRLQQQEsIsZeIugCciyjoey6Ap4UQmxPjdwshfCI6HEHw+AUhxG4iGiai0wA8COBiAF+TH7sdwCUA7gfwPgB3yTiDg8O0Rctvh6//5e4N+KOzDkdfJb0IaKjmYcmA+f1qMxIC617ag4tfv2J/pjmtkKbJTwR27dqFu+66C7/5zW9ARPB9H0SEL37xixBCZMrGUceoqZx//Md/jE984hP47d/+bdxzzz347Gc/O+b5mba6e+65B7/4xS9w//33o7u7G29605vC756oEGsWC2EJgLuJ6HEAv0YQQ/ixfO8idAaTzwTwOBE9hiBAfLkQgrX9jwC4FsAGBJbDHfL4dQDmE9EG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",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "out = metenergy_data.get_demand_entsoe_zenodo('ES')\n",
    "out.loc['2022-06'].plot()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>Actual Load</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>2020-01-01 01:00:00+01:00</th>\n",
       "      <td>22162.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2020-01-01 02:00:00+01:00</th>\n",
       "      <td>20891.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2020-01-01 03:00:00+01:00</th>\n",
       "      <td>19708.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2020-01-01 04:00:00+01:00</th>\n",
       "      <td>18960.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2020-01-01 05:00:00+01:00</th>\n",
       "      <td>18697.0</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                           Actual Load\n",
       "2020-01-01 01:00:00+01:00      22162.0\n",
       "2020-01-01 02:00:00+01:00      20891.0\n",
       "2020-01-01 03:00:00+01:00      19708.0\n",
       "2020-01-01 04:00:00+01:00      18960.0\n",
       "2020-01-01 05:00:00+01:00      18697.0"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "out = metenergy_data.get_demand_entsoe(\n",
    "    zone = 'ES', \n",
    "    timeline = pd.date_range('2020-01-01', periods=6, freq = 'H', tz = 'UTC'),\n",
    "    MY_API_KEY=\"YOUR-ENTSOE-API-KEY\"\n",
    "    )\n",
    "out.head()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Wind capacity factor (`get_wind_cf`)\n",
    "The hourly wind capacity function is calculated using hourly wind speed and a specific wind power curve (provided as CSV)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>ws</th>\n",
       "      <th></th>\n",
       "      <th>cf</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>0.0</td>\n",
       "      <td>0</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>0.5</td>\n",
       "      <td>0</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>1.0</td>\n",
       "      <td>0</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>1.5</td>\n",
       "      <td>0</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>2.0</td>\n",
       "      <td>0</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "    ws      cf\n",
       "0  0.0  0  0.0\n",
       "1  0.5  0  0.0\n",
       "2  1.0  0  0.0\n",
       "3  1.5  0  0.0\n",
       "4  2.0  0  0.0"
      ]
     },
     "execution_count": 43,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Toy wind time-series\n",
    "ws = pd.Series(data = [0, 3, 5, 10, 20, 22], index = pd.date_range('2022-01-01', periods=6, freq = 'H'))\n",
    "# Example of the wind power curve\n",
    "pd.read_csv('content/Vestas_v110_2000MW_ECEM_turbine.csv', names = ['ws', '', 'cf'], delimiter= '  ', engine='python').head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>wp</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>2022-01-01 00:00:00</th>\n",
       "      <td>0.0000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2022-01-01 01:00:00</th>\n",
       "      <td>0.0000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2022-01-01 02:00:00</th>\n",
       "      <td>0.1027</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2022-01-01 03:00:00</th>\n",
       "      <td>0.9498</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2022-01-01 04:00:00</th>\n",
       "      <td>0.9000</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                         wp\n",
       "2022-01-01 00:00:00  0.0000\n",
       "2022-01-01 01:00:00  0.0000\n",
       "2022-01-01 02:00:00  0.1027\n",
       "2022-01-01 03:00:00  0.9498\n",
       "2022-01-01 04:00:00  0.9000"
      ]
     },
     "execution_count": 44,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "out = metenergy_data.get_wind_cf(ws, curve_csv_path = 'content/Vestas_v110_2000MW_ECEM_turbine.csv')\n",
    "out.head()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Solar power capacity factor (`get_pv_cf`)\n",
    "The hourly solar capacity function is calculated using hourly solar radiation (GHI) and air temperature. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>sp</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>2022-01-01 00:00:00</th>\n",
       "      <td>0.90000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2022-01-01 01:00:00</th>\n",
       "      <td>0.90378</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2022-01-01 02:00:00</th>\n",
       "      <td>0.90000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2022-01-01 03:00:00</th>\n",
       "      <td>0.90000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2022-01-01 04:00:00</th>\n",
       "      <td>0.87354</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                          sp\n",
       "2022-01-01 00:00:00  0.90000\n",
       "2022-01-01 01:00:00  0.90378\n",
       "2022-01-01 02:00:00  0.90000\n",
       "2022-01-01 03:00:00  0.90000\n",
       "2022-01-01 04:00:00  0.87354"
      ]
     },
     "execution_count": 45,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Creating two toy Pandas series for temperature and solar radiation, they must have the same index \n",
    "tmp = pd.Series(data = [25, 24, 25, 25, 32, 16], index = pd.date_range('2022-01-01', periods=6, freq = 'H'))\n",
    "ssr = pd.Series(data = [1000, 1000, 1000, 1000, 1000, 0], index = pd.date_range('2022-01-01', periods=6, freq = 'H'))\n",
    "\n",
    "\n",
    "out = metenergy_data.get_PV_cf(tmp, ssr)\n",
    "out.head()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Weekly hydropower inflow at country level (`get_inflow_entsoe`)\n",
    "\n",
    "A weekly time-series for hydropower is derived from the data available on the ENTSO-E Transparency Platform. \n",
    "The inflow for the week *w* is estimated as:\n",
    "\n",
    "        inflow(w) = storage_at_end_of_the_week(w) - storage_at_the_beginning_of_the_week(w) + \n",
    "                    hydro_generation(w)\n",
    "        \n",
    "In other words, the inflow (expressed in MWh) for a week is calculated as the difference in the storage (between the end and the beginning of the week) and the generation during that week. \n",
    "\n",
    "The hydropower generation reported in the ENTSO-E TP is for all the hydropower with reservoirs (excluding closed-loop pumping)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "                     Hydro Water Reservoir     storage    lagged    inflow\n",
      "sto_index                                                                 \n",
      "2020-01-05 23:00:00               761910.0   9753093.0  168758.0  930668.0\n",
      "2020-01-12 23:00:00               586164.0   9921851.0   28374.0  614538.0\n",
      "2020-01-19 23:00:00               703633.0   9950225.0  198599.0  902232.0\n",
      "2020-01-26 23:00:00               445274.0  10148824.0  296490.0  741764.0\n",
      "2020-02-02 23:00:00               120358.0  10445314.0       NaN       NaN\n"
     ]
    }
   ],
   "source": [
    "out = metenergy_data.get_inflow_entsoe(\n",
    "    zone = 'ES', \n",
    "    timeline = pd.date_range('2020-01-01', periods=168*5, freq = 'H', tz = 'UTC'),\n",
    "    MY_API_KEY=\"YOUR-ENTSOE-API-KEY\"\n",
    ")\n",
    "out.head()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Installed capacity (`get_capacity_entsoe`)\n",
    "\n",
    "From the ENTSO-E TP API the installed electrical generation capacity (MW) for a zone in a specific year"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<AxesSubplot:>"
      ]
     },
     "execution_count": 41,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "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a68FsrveDzoo+wbCu+++ywEHHMD555/P7rt/+q2KPn360K1bNyZPnkxEcN1113HQQQdRVVW15KJ2zjnn5OZrys9//vMldTTu2y233MLee+/dqk+5eWM78MADufHGG1m8eDEvvfQSzz33HDvvvPNKV765MS3va1Jcfr/99mPChAm88847vPPOO0yYMKHF38RoUkT4xz8d6mfQoEFhVm5z5sypaPsPPfRQADFgwIAYOHBgDBw4MMaNGxcREW+++Wbsvffesfnmm8fee+8db731VkREnHvuudGlS5cl+QcOHBivvfZaRERMnTo1tttuu9hss83ipJNOik8++aRku3n5pkyZEn379o0uXbpE7969Y9ttty1ZftGiRTF8+PDo379/7LTTTvHCCy8sOTdkyJBYd911o3PnztG3b9+45557liqfN7aIiPPOOy8222yz2HLLLePuu+9ekn7cccfF1KlTK1a+4KWXXoq99tqrLK/JmWeeGXfccUez5a+88sro379/9O/fP6666qql2i4o9fcZqIsS/6cqO2fWcdTW1kZdXV2lu2EdzFNPPcU222xT6W6YlUWpv8+SpkVEbeO8XnowMzOzXA4UzMzMLJe/Hmkdzsx59VSPXPrhMXP9bAVbThHhjaGs3WvtLQeeUbDlIukiSacW/T5e0hVFv/9K0g9LFi5d31BJS21WZVZpnTt35q233mr1f7JmK5OI4K233qJz584tLuMZBVtejwBfAy5OT05cl88+HGo34NRW1DcUWED+ZldmFVF4psAbb7xR6a6YLZfOnTuz0UYbtTi/AwVbXpOAi9LxdmSbVvWR1AtYCGwD7CfpUrKdHx8Bvh0RIekU4ETgY7INp0am3xskHQmcDDwNXA5snNo4NSLKu22fWQt06tSJTTfdtNLdMFvhHCjYcomIVyR9LGljstmDR8m2wR5Mtg32DODSiDgHQNL1ZBtc/ZUsMNg0IhZL6hkR70q6HFgQEf+X8v8JuCgiHk5tjCcLPj5D0ghgBEBV9/XadtBmZqsQBwpWDpPIgoTdgF+TBQq7kQUKjwBfkPRjoAvQG5hNFijMAG6QNBYYm1P3PsC2RTeQdZfULSLeK84UEWOAMQBr9tnCi8hmZmXiQMHK4RGywGAA2dLDv4H/Af4DXAVcAdRGxL8ljQIKd9EcAOwJHAicKWm7EnWvBgyO5neuNDOzNuBvPVg5TCJbTng7Ihoi4m2gJ9nyw6Mpz5uSugLDAdKNj/0i4n7gxyl/V+A9oHgz9gkU7XgpqaYtB2JmZp/lQMHKYSbZtx0mN0qrj4g3gT+k38cCU9P5KuCPkmYCT5Ddh/Au2ZLEIZKmS9oDOAWolTRD0hyymx3NzGwF8V4P1uF4rwczs9bzXg9mZmbWag4UzMzMLJcDBTMzM8vlQMHMzMxyOVAwMzOzXA4UzMzMLJcDBTMzM8vlRzhbhzNzXj3VI8dVuhsd3tzRB1S6C2a2AnhGwdqEpDMkzU5PVJwuaZcm8j4gaamHfJiZWeV5RsHKTtJgsr0fdkxbSK8LrFHG+qsioqFc9ZmZWT7PKFhb6AO8GRGLASLizYh4RdIwSU9IminpKklrNi4o6f9JqkuzEWcXpc+VdJakh4GvrbihmJmt2hwoWFuYAPST9KykyyTtJakzcA1wWEQMIJvN+k6JsmekZ43vAOwlaYeicx9ExJCIuLFxIUkjUoBR17CwvvwjMjNbRTlQsLKLiAXAIGAE8AZwE/Bt4KWIeDZluxbYs0Tx/5b0ONmOktsB2xadu6mJNsdERG1E1FZ16VGGUZiZGfgeBWsj6R6CB4AH0lbSRzdXRtKmwGnAThHxjqRrgM5FWd5vg66amVkTPKNgZSdpK0lbFCXVAK8B1ZI2T2nfBCY2KtqdLBiol7QB8KW27quZmTXNMwrWFroCv5XUE/gYeJ5sGeLPwF8krQ5MBS4vLhQRT0p6ApgNvAhMWpbGB/TtQZ2/429mVhaKiEr3waysamtro66urtLdMDNrVyRNSzeTf4aXHszMzCyXAwUzMzPL5UDBzMzMcjlQMDMzs1wOFMzMzCyXAwUzMzPL5UDBzMzMcjlQsA5n5rx6qkeOo3rkuEp3xcys3XOgsAJJ2kjSHZKek/SCpN9IWiOdq5H05aK8oySdVrnetj1JC3LSr5E0fEX3x8zMluZAYQWRJOA2YGxEbAFsSfao45+nLDXAl0uXXqb2qpo450d3m5lZizhQWHH2Bj6IiKthye6KPwC+Jak7cA5wmKTpkg5LZbaV9ICkFyWdUqhI0pGSpqS8vy8EBZIWSDpH0mPA4OLGUz2/kDQR+L6kQZImSpomabykPkX5Lkj1Pytpj5ReJelCSVMlzZD07ZR+maQD0/Htkq5Kx8dJOi8dj03tzJY0olG/fiXpcUn3SVqv8YuW108zM1sxHCisONsB04oTIuI/wL+AauAs4KaIqImIm1KWrYH9gJ2Bn0nqJGkb4DBg94ioARqAI1L+tYFZEbFLRDxcog89I2Iv4BLgt8DwiBgEXMWnMxsAq0fEzsCpwM9S2nFAfUTsBOwEnJC2hX4Q2CPl6Qtsm46HAA+l42+ldmqBUyStU9TfxyNiR7KdJAttASCpUzP9LM47QlKdpLqGhfWlspiZ2TLwFPSKI6DUDlx56QDjImIxsFjS68AGwDBgEDA1W81gLeD1lL8BuLWJPhQCkK2A7YF7Ux1VwPyifLelP6eRBTEAXwR2KLp3oAewBVkwcKqkbYE5QK/0qX8wUJgFOUXSIem4Xyr3FvBJUZ/+WNRuQXP9XCIixgBjANbss4V3OjMzKxMHCivObODQ4oS05NAPeIHs4t/Y4qLjBrL3S8C1EfG/JfJ/kJY08rxfaBqYHRGDc/IV2i20WShzckSMb5xZUi9gf7LZhd7AfwMLIuI9SUOBfYDBEbFQ0gNA55x2G1/gm+unmZm1MS89rDj3AV0kHQVLbjb8FXBNRCwE3gO6tbCe4ZLWT/X0lrRJK/vyDLCepMGpjk6StmumzHjgO2k5AElbSlo7nXuUbJniQbIZhtP4dNmhB/BOChK2BnYtqnM1oDBD8Q2g8XLJsvTTzMzKyDMKK0hERJp+v0zSmWQXybuBn6Qs9wMjJU0Hzm+injmSfgpMkLQa8BFwEvDPVvTlw7SEcImkHmR/Dy4mm/XIcwXZMsTj6RscbwAHp3MPAV+MiOcl/ZNsVqEQKNwDnChpBtmFf3JRne8D20maBtST3XuxvP1kQN8e1I0+oKksZmbWQorwcq51LLW1tVFXV1fpbpiZtSuSpkVEbeN0Lz2YmZlZLgcKZmZmlsuBgpmZmeVyoGBmZma5HCiYmZlZLgcKZmZmlsuBgnU4M+d5rwczs3JxoGBlI2kjSXdIek7SC5J+I2kNSTWSvlyUb5Sk0yrZVzMzaxkHClYW6WmNtwFjI2ILYEugK9lujzXAl/NLt7qtqnLVZWZmTXOgYOWyN9mmVFcDpM2pfgAcD/wSOEzSdEmFxzRvK+kBSS9KKuwyiaQjJU1JeX9fCAokLZB0jqTHyHamNDOzFcCBgpXLdmTbUi8REf8B5gLnATdFRE1EFLaV3hrYD9gZ+Fna8Gkbsv0edo+IGrLdK49I+dcGZkXELhHRePMoMzNrI94UyspFLL1NdFPp4yJiMbBY0uvABsAwsu22p2YrGawFvJ7yNwC35jYujQBGAFR1X28Zh2BmZo05ULBymQ0cWpwgqTvQj+wi39jiouMGsr+LAq6NiP8tkf+DtJxRUkSMAcYArNlnC+90ZmZWJl56sHK5D+gi6ShYcsPhr4BrgNeAbi2sY7ik9VMdvSVt0jbdNTOzlnCgYGUR2X7lhwBfk/Qc8CzwAfAT4H6ymxeLb2YsVccc4KfABEkzgHuBPm3eeTMzy6Xs/3ezjqO2tjbq6uoq3Q0zs3ZF0rSIqG2c7hkFMzMzy+VAwczMzHI5UDAzM7NcDhTMzMwslwMFMzMzy+VAwczMzHI5UDAzM7NcfoSzdTgz59VTPXJcpbvRLswdfUClu2BmKznPKFiTJIWkXxX9fpqkUctY1zWShpetc2Zm1uYcKFhzFgNflbRupTtSIMkzYWZmK4gDBWvOx2S7Mv6g8YnGMwSSFhQd/1jSTElPShpdouwgSRMlTZM0XlKflH6CpKmp3K2SuhS19WtJ9wMXtME4zcysBAcK1hK/A46Q1KMlmSV9CTgY2CUiBgK/bHS+E/BbYHhEDAKuAn6eTt8WETulck8BxxUV3RLYJyL+p0SbIyTVSaprWFjfutGZmVkuT+FasyLiP5KuA04BFrWgyD7A1RGxMJV/u9H5rYDtgXslAVQB89O57SWdB/QEugLji8r9JSIacvo4hmzmgzX7bOGdzszMysSBgrXUxcDjwNVFaR+TZqWUXfHXSOkCmrpYC5gdEYNLnLsGODginpR0DDC06Nz7y9BvMzNbDl56sBZJswI389mlgLnAoHR8ENApHU8AvlV0f0HvRtU9A6wnaXA630nSdulcN2B+Wp44otzjMDOz1nGgYK3xK6D42w9/APaSNAXYhfSJPyLuAe4E6iRNB04rriQiPgSGAxdIehKYDuyWTp8JPAbcCzzdVgMxM7OWUYSXc61jqa2tjbq6ukp3w8ysXZE0LSJqG6d7RsHMzMxyOVAwMzOzXA4UzMzMLJcDBTMzM8vlQMHMzMxyOVAwMzOzXA4UzMzMLJcf4Wwdzsx59VSPHFfpbpit9OaOPqDSXbB2YJWeUSjeFjn9foykS1tRvlrSrOVo/wlJNel4dUnvSzqy6Pw0STs2Uf4ny9p2UR3XSHpJ0vS0tfOw5a2znCRdIWnbSvfDzGxVtUoHCm1FUktnah7h00cXDyTbA2G3VMfawGbAk02Ub3WgIKmqRPKPIqIGOBW4vLV1LmfbTYqI4yNiTjnqMjOz1nOgUIKkbulTdqf0e3dJc9PmRYPSJ+9HgZOKyhwj6S+S/gpMkNRb0lhJMyRNlrRDiaYm8WmgsBvZRbom/b4z8HhENKR6pkmaLWlEam80sFaaCbghpR0paUpK+33hYippgaRzJD0GlNqxseBRoG8qUyXpQklT0xi+ndL7SHowtTFL0h4p/YuSHpX0eHoduqb0uZLOkvQw8OO0L0ThNauWNCMdD0szLDMlXSVpzZT+gKTaVo7DzMzKZFUPFAoX2ulp86JzACLiPeABoLCAdzhwa0R8RLbN8ik5WyQPBo6OiL2Bs4EnImIHsk/+15XIXzyjsBvwILBYUrf0+6R07lsRMQioBU6RtE5EjAQWRURNRBwhaRvgMGD3NDvQwKe7L64NzIqIXSLi4SZej/2Bsen4OKA+InYCdgJOkLQp8A1gfGpjIDBd0rrAT4F9ImJHoA74YVG9H0TEkIg4H1hD0mYp/TDgZkmdybaXPiwiBpDdO/OdEv3LHYekEZLqJNU1LKxvYohmZtYaq3qgULjQ1qQL31lF564Ajk3HxwJXS+oB9IyIiSn9+kb13Zu2YwYYUjgfEf8A1knll4iIuWQXzs8BW5MtPUwl24lxN7JAArLg4ElgMtAP2KLEWIaRbfk8NQU9w8iWLiALGm5t4nW4UNKLwB+BX6S0LwJHpboeA9ZJ7U4FjpU0ChiQgqpdgW2BSSn/0cAmRfXfVHR8M/Df6fiwdG4r4KWIeDalXwvsWaKfueOIiDERURsRtVVdepTKYmZmy8DfesgREZPS1PheQFVEzJLUE2hqu833i45VqtoSaY+Sbbk8PyJC0mRgd7Klh8mShgL7AIMjYqGkB4DOJeoRcG1E/G+Jcx9EREMT/f4RcBtwCtlFelCq7+SIGL9UQ9KeZLMt10u6EHiHLEj6ek79xa/LTcBfJN0GREQ8V7ihswWaG4eZmZXZqj6j0JzrgD+TLTcQEe8C9ZKGpPNH5JSDbBnhCIB0sX8zIv5TIt8k4AdkAQPpz6OAV1N7PYB3UpCwNdmn94KPCvdRAPcBwyWtn9rsLan4U32TIuIT4DfAapL2A8YD3ym6T2NLSWunOl+PiD8AVwI7ks107C5p85S3i6Qtc9p5gWxm4Ew+nWl4GqgulAe+CUwsUdzMzFYwzyg07QbgPLJgoeBY4CpJC8kupnlGkS1XzAAWkk3HlzIJuIgUKETE/HQTYmHZ4R7gxFTPM2QX5YIxwAxJj6f7FH5KdiPlasBHZDdb/rOlg00zGucBPwb2BaqBxyUJeAM4GBgK/EjSR8AC4KiIeEPSMcCfCzchkt2z8Cyl3QRcCGya2v1A0rFkMw2rky1vLPO3Lwb07UGdvx9uZlYWimhqJn3VJmk4cFBEfLPSfbGWq62tjbq6ukp3w8ysXZE0LSJqG6d7RiGHpN8CXwK+XOm+mJmZVYoDhRwRcXKl+2BmZlZpvpnRzMzMcjlQMDMzs1wOFMzMzCyXAwUzMzPL5UDBzMzMcvlbD9bhzJxXT/XIcS3OP9cPZzIzy9XsjIKkBY1+P0bSpS1tIO2XMGtZOpfKD5VUn7YgflrS/y1rXa1oc01Jf0+7Sh7WTN4TJR3V1n1qrda+T20pbTW9bqX7YWZmrVexGQVJq0fExy3M/lBEfEXSWsATkm6PiEnNllp2nwc6pR0lc6UxLPOjhkvU1dLXw8zMbIVY5nsUJHWT9FLRpkHd0yfHTpIGSXpS0qNk+w0Uyhwj6S+S/kq2J0FvSWMlzZA0WdIOTbUZEYuA6UDfVN+S2Q5JwyVdk46vkXSJpEckvZgexVxqDEu1nzZV+iNQk2YU+jcq84CkX0iaCHxf0ihJp0naRtKUonzVaX8G0usxUdI0SeMl9SlVV6N2dk79fyL9uVXRa3ibpHskPSfpl0VljpX0bKpv95wxj5J0vaR/pPInpHRJulDSLEkzCzMpaUbnrqLyl6Z9HQozBWdLejyV2TqlryNpQur77ynaSTO93tMkzZY0oij9uNT3ByT9oTAbImk9SbdKmpp+So7LzMzaRktmFNaSNL3o997AnRHxnrItjw8AxgKHA7dGxEeSribboniism2Iiw0GdoiIt5U9JvmJiDhY0t5kuzXW5HVEUi9gC7KdGZvTBxgCbA3cCdxSIs/ZjduPiBpJxwOnRcRXcuruGRF7pT6NAoiIpyStIWmziHgROAy4OQVSvyXbM+KNdAH+OfCtxnU18jSwZ0R8LGkf4BfAoelcDdmsx2LgmfQ6fpzGMwioB+4Hnsjp/w5ku1CuTTZDM47sfakBBgLrAlMlteR1fjMidpT0XeA04HjgZ8DDEXGOpAOAEUX5v5Xe+7VSG7cCa5LtJrkj8B7wD+DJlP83wEUR8bCkjck24tqmcSdS0DECoKr7ei3otpmZtURLAoVFxVPw6dNkYdOIK8h2GhxLtqviCZJ6kF38CtsEX0+2Z0LBvRHxdjoeQrr4RcQ/0ifRHhFR36gPe6RP51sBoyPi1Rb0e2zaOnmOpA1y8pRsvwV135STfjPw38BoskDhsNTn7YF7JQFUAfNbUFcP4FpJWwABdCo6d1/hNZI0B9iE7OL+QES8kdJvAkpu9QzckWZnFkm6H9iZ7LX4c0Q0AK+lWYmdgFJbYxe7Lf05DfhqOt6zcBwR4yS9U5T/FEmHpON+ZIHf54CJhb8Xkv5S1Pd9gG3TawfQXVK3iHivuBMRMYZsN03W7LOFdzozMyuT5bpHISImpSn2vYCqiJglqSfZhS3P+0XHKnG+VNnCPQpbAg8ru0dheqO8nRuVWdy4HUk/J5sBIQU/zbafZkc+D7wSEYUNot5fqlTmJrKtkm/LmojnJA0AZkfE4JwyeXWdC9wfEYdIqgYeKDpXPLYGPn0fW3qBbJwvKP1aQDZTUbxElfc6F/ejZF8kDSW78A+OiIVpRqpzE22T2h6cAhszM1vByvEcheuAPwNXA0TEu0C9pCHp/BFNlH2wcD5dRN6MiNxPsBHxLHA+cHpKek3ZvQGrAYfklSsqf0ZE1BTNkDTbfkQcm8o0u4tkRLxAdsE8k09nCp4B1pM0OLXTSdJ2zdVFNqMwLx0f04L8jwFD06xIJ+BrTeQ9SFJnSesAQ4GpZK/FYZKqJK1HNiswBfgn2Sf6NdNsy7AW9KX4df0S0KtoTO+kIGFrsuUPUjt7SeolaXU+XWIBmAB8r/CLpJoWtG9mZmVSjm893ACcRxYsFBwLXCVpIdmacp5RwNVpWWEhcHQL2rscOE3SpsBI4C7g38AsoGsr+74s7TfnJuBCYFOAiPhQ2c2Ul6QL7erAxcDsZur5JdnSww/J1uybFBHz0/0Sj5ItbTxOtsxRyhRgHLAxcG5EvCLpdrL7FJ4kmw34cWGJR9LNwAzgOfLveyh2NvBnSY8DE4F/pfR7gBPT6/0MMDn1fZ6kX5AFO68Ac8juswA4BfhdKrM6WRByYlOND+jbgzo/G8HMrCwUsXzLuekieFBEfLM8XbK2lIKJBRHR5s+jaA1JXSNiQZpRuB24KiJuX5a6amtro66urrwdNDPr4CRNi4jaxunLNaOQ7rb/EtDstLxZM0alb3d0JltuGFvZ7piZGSz/zYwnl6sjtmJExKhK96GUiDit0n0wM7OleVMoMzMzy+VAwczMzHI5UDAzM7NcDhTMzMwsV8V2jzRrKzPn1VM9clylu7HCzPUzI8ysDa1SMwoq2m0y/X5MYZfCFpavljRrOdofKqk+7ar4lKSfLWtd5aS0A2aJ9K3Sbo7TU3/HpPQaSf5KrJnZKmCVChTaSnpIUEs9FBGfJ9tY60hJg9qoW+VwCdnOjTURsQ3ZLpiQ7TLZqkChla+RmZmtJBwoAJK6SXop7ZGApO6S5qZ9GQZJelLSo8BJRWWOkfQXSX8FJkjqLWmspBmSJkvaoak2I+J9sh0X+zf+RC9pVpq9qJb0tKQrUtoNkvaRNEnSc5J2TvlHSbpe0j9S+glFdf1I0tTUr7OL0s+Q9Iykv5PtcFlKH+Dloj7PlLQGcA7ZvhDTJR2WN/bUrzGSJgDXpfE8JOnx9LNbyreapMskzZZ0l6S70xM/Sa//REnTJI2X1Kf5d9TMzMplVfuUt5ak6UW/9wbujIj3lO1keADZEwEPB26NiI+U7R55ckRMlHRho/oGAztExNvpKZVPRMTBkvYm2yyrJq8jyjZk2pVsl8htm+jz5mQbPI0g27zpG2RbQh8I/AQ4OOXbIdW3NvCEpHFk21tvQbaNtIA7Je1JtmPl4WS7Yq5Oti/EtBJtXwT8Q9IjZE9LvDoi3pV0FlAbEd9LY2lq7IOAIRGxSFIXYN+I+EDZ9tl/JptZ+SpQDQwA1geeItsrpBPZLMZBEfGGpMOAnwPfauL1MjOzMlrVAoVFRTtHIukYsgsVwBXAj8kChWOBE5Rt4tQzIiamPNeTPbK64N6IeDsdDyHtehgR/1C2i2OPiKjns/aQ9ATwCTA6ImZLamqnx5ciYmbq72zgvogISTPJLq4Fd6StmBdJup8sOBgCfJFPN3LqShY4dANuj4iFqd47SzUcEVdLGg/sDxwEfFvSwBJZS449nbuzaIvoTsClynaAbAC2LCr/l4j4BHg19R+ymY7tgXslQbbJ1fxSfZU0giyYoqr7eqWymJnZMljVAoVcETEpTY3vBVRFxCxJPcl2UszzftGxSlVbIu2hiPhKo7SP+ewyUOei48VFx58U/f4Jn33/GrcVqU/nR8Tvi09IOjWnb0uJiFeAq8g+4c8iu3A31tTYi1+jHwCvAQPJxvtBE+UL6bMjYnAL+jkGGAOwZp8tlm+nMzMzW8L3KHzWdWTT4VcDRMS7QL2kIen8EU2UfbBwXtJQ4M2I+E8L250L7JjK7kjaorqVDpLUOS1pDCVbphgPfEtS11R3X0nrp74eImktSd2A/ypVoaT9i+7b+BywDjAPeI9sVqKgpWPvAcxPMwff5NNtsB8GDk33KmyQ+g/ZVtTrSRqc6u4kabtWvSpmZrZcPKPwWTcA55EFCwXHkn2aXkh24c0zCrha0gxgIXB0K9q9FTgq3T8xFXi2FWULpgDjgI2Bc9NMwCuStgEeTVP3C4AjI+JxSTcB04F/Ag/l1PlF4DeSCp/8fxQRhaWBkam/59PysV8G3JqWWu7n09mGW4FhwKw09seA+oj4MN3UeElaylgduBiY3ZoXxszMlp0iPEtbkC5KB0XENyvdl9aQNApYEBH/V+m+LCtJXSNiQZoRmQLsHhGvLktdtbW1UVdXV94Ompl1cJKmRURt43TPKCTpzv0v0crnA1jZ3JXuCVmDbEZkmYIEMzMrLwcKSUScXOk+LKuIGFXpPiyviBha6T6YmdnSfDOjmZmZ5XKgYGZmZrkcKJiZmVkuBwpmZmaWy4GCmZmZ5fK3HqzDmTmvnuqR40qemzv6gBXcGzOz9s0zCraEpIa0dXThp7oMdW4o6ZZ0PFTSXTn5hkiaomxb7afTJk+FcydKOiodX1PYgtrMzNqeZxSs2Gd21yyH9CjpJi/saR+JPwEHp8dLrwuMlzQvIsZFxOXl7JOZmbWcZxSsSZJqJE2WNEPS7ZJ6pfRTJM1J6TemtL2KZiOekNQt7cg5q5lmTgKuiYjHASLiTbItv0emekdJOq3tRmlmZnkcKFixtYou9LentOuA0yNiB2Am8LOUPhL4fEo/MaWdBpyUZiX2ABa1sN3tgGmN0upSeotIGiGpTlJdw8L6lhYzM7NmOFCwYosioib9HJJ2bOwZERPT+WuBPdPxDOAGSUcCH6e0ScCvJZ2Syn1MywgotTtZi3csi4gxEVEbEbVVXXq0tJiZmTXDgYItqwOA3wGDgGmSVo+I0cDxwFrAZElbt7Cu2UDjHcsGAXPK1VkzM1s2DhQsV0TUA+9I2iMlfROYKGk1oF9E3E92L0FPoKuk/hExMyIuIFs6aGmg8DvgGEk1AGmr6QuAX5ZtMGZmtkz8rQdrztHA5ZK6AC8CxwJVwB/T0oSAiyLiXUnnSvoC0EA2G/A3oE9zDUTE/LSE8QdJ3VKdF0fEX5elwwP69qDOz0swMysLRbR4GdisXaitrY26urpKd8PMrF2RNC0iGi8De+nBzMzM8jlQMDMzs1wOFMzMzCyXAwUzMzPL5UDBzMzMcjlQMDMzs1wOFMzMzCyXH7hkHc7MefVUjxxX6W6s8ub6oVdmHYJnFCpMUkPRjo3TJVWXoc4NJd2SjodKuqtEnqXSJV0jafhytNuSLaWXmbebNjNb8TyjUHmL0rbMZRMRrwDLfMFvqbQRVEt3iDQzs3bIMworIUk1kiZLmiHpdkm9Uvopkuak9BtT2l5FsxFPSOpWjk/2ks6SNFXSLEljJCmlPyDpF5ImAt+XNEjSk5IeBU5qor4fS5qZ8o5uZpwnpLaflHRr2mfCzMwqwIFC5a1VdKG/PaVdB5weETsAM4GfpfSRwOdT+okp7TTgpDQrsQewqBVt71G87AEcWHTu0ojYKSK2J9s2+itF53pGxF4R8SvgauCUiBic14ikLwEHA7tExEA+3RUyb5y3pbYHAk8BxzU3EEkjJNVJqmtYWN+CoZuZWUs4UKi8RRFRk34OSTsy9oyIien8tcCe6XgGcEPaabEw5T8J+LWkU1K51iwFPFTUdg1wZ9G5L0h6TNJMYG9gu6JzNwGU6Ov1Oe3sA1wdEQsBIuLtZsa5vaSHUttHNGq7pIgYExG1EVFb1aVHc9nNzKyFHCi0LwcAvwMGAdPSPQKjgePJPvVPlrT18jYiqTNwGTA8IgYAfwA6F2V5v5AVaMn2oy3NV3AN8L3U9tmN2jYzsxXIgcJKJiLqgXck7ZGSvglMlLQa0C8i7gd+DPQEukrqHxEzI+ICoA5Y7kCBTy/Mb0rqSs6NkRHxLlAvaUhKOiKnvgnAtwr3GkjqnTfOdNwNmC+pUxN1mpnZCuBvPaycjgYuTxfWF4FjgSrgj2nKXsBFEfGupHMlfQFoAOYAfwP6LE/jqd4/kN03MBeY2kT2Y4GrJC0ExufUd4+kGqBO0ofA3cBPcsYJcCbwGPDP1Iduren/gL49qPN3+M3MykIRrZkRNlv51dbWRl1dXaW7YWbWrkiaFhG1jdO99GBmZma5HCiYmZlZLgcKZmZmlsuBgpmZmeVyoGBmZma5HCiYmZlZLgcKZmZmlssPXLIOZ+a8eqpHjqt0N8zMVqi5bfSgOc8orIIkNRTvGimpugx1bijplnQ8VNJdOfl2TltVPyfpcUnjJA1Y3vbNzKxteEZh1bQo7RZZNhHxCjl7QhRI2gC4GfhGRDyS0oYA/cke1WxmZisZzygYAJJqJE2WNEPS7ZJ6pfRTJM1J6TemtL2KZiOekNRNUrWkWc008z3g2kKQABARD0fE2FTvf6WtrZ+Q9PcUWJRsr01eBDMzW4oDhVXTWkUX3ttT2nXA6RGxA9mn+5+l9JHA51P6iSntNOCkNCuxB7Cohe1uBzzexPmHgV0j4vPAjWS7ZLaoPUkjJNVJqmtYWN/C7piZWXMcKKyaFkVETfo5JO1I2TMiCts8XwvsmY5nADdIOhL4OKVNAn4t6ZRU7mOWQZo9eErSb1LSRsB4STOBH5EFFi1qLyLGRERtRNRWdemxLN0xM7MSHChYcw4AfgcMAqZJWj0iRgPHA2sBkyVt3cK6ZgM7Fn6JiF3ItpQuXNl/C1waEQOAbwOdU75lbc/MzJaTAwUjIuqBdyTtkZK+CUyUtBrQLyLuJ1sG6Al0ldQ/ImZGxAVAHdDSC/fvgGMk7VaU1qXouAcwLx0fXUhcjvbMzGw5+VsPVnA0cLmkLsCLwLFAFfDHtDQh4KKIeFfSuZK+ADQAc4C/AX2aayAiXpV0GHCBpL7A68CbwDkpyyjgL5LmAZOBTVP6qSXayzWgbw/q2uj7xGZmqxpFRKX7YFZWtbW1UVdXV+lumJm1K5KmRURt43QvPZiZmVkuBwpmZmaWy4GCmZmZ5XKgYGZmZrkcKJiZmVkuBwpmZmaWy89RsA5n5rx6qkeOWyq9rfZqNzPryDyjYEuR1JA2jHpS0uOFJylK2lDSLZXun5mZrTieUbBSFqWdGpG0H3A+sFdEvAIMr2THzMxsxfKMgjWnO/AOgKRqSbPScWdJV0uaKemJ9IhlJB0jaaykv0p6SdL3JP0w5ZksqXfKd4KkqWnW4tb06GgkfU3SrJT+YErbTtKUNMsxQ9IWFXklzMxWQZ5RsFLWkjSdbPfGPsDeJfKcBBARA9JujhMkbZnObQ98PpV/Hjg9Ij4v6SLgKOBi4LaI+AOApPOA48h2jzwL2C8i5knqmeo7EfhNRNwgaQ2yPSg+Q9IIYARAVff1lm/0Zma2hGcUrJRFEVETEVsD+wPXSVKjPEOA6wEi4mngn0AhULg/It6LiDeAeuCvKX0mUJ2Ot5f0kKSZwBHAdil9EnCNpBP4NCB4FPiJpNOBTSJiUeMOR8SYiKiNiNqqLj0anzYzs2XkQMGaFBGPAusCjT+mNw4cii0uOv6k6PdP+HQW6xrgexExADibbPaBiDgR+CnQD5guaZ2I+BNwILAIGC+p1AyHmZm1AQcK1qS0rFAFvNXo1INkMwGkJYeNgWdaUXU3YL6kToV6Ul39I+KxiDiLbAvqfpI2A16MiEuAO4EdlnU8ZmbWOr5HwUop3KMA2czB0RHR0Gj14TLg8rR08DFwTEQsXnqFIteZwGNkSxYzyQIHgAvTzYoC7gOeBEYCR0r6CHgVOGdZB2ZmZq2jiKh0H8zKqra2Nurq6irdDTOzdkXStIiobZzupQczMzPL5UDBzMzMcjlQMDMzs1y+R8E6HEnv0bpvYLQH65J9C6Qj8ZjaB4+p/VjecW0SEUs9sc7ferCO6JlSN+S0Z5LqPKaVn8fUPnTEMUHbjctLD2ZmZpbLgYKZmZnlcqBgHdGYSnegDXhM7YPH1D50xDFBG43LNzOamZlZLs8omJmZWS4HCmZmZpbLgYJ1GJL2l/SMpOcljax0f5ojaa6kmZKmS6pLab0l3SvpufRnr6L8/5vG9oyk/YrSB6V6npd0iVqxM1cZxnCVpNclzSpKK9sYJK0p6aaU/pik6gqNaZSkeem9mi7py+1sTP0k3S/pKUmzJX0/pbfb96qJMbXb90pSZ0lTJD2ZxnR2Sq/s+xQR/vFPu/8h2wr7BWAzYA2yXSe3rXS/munzXGDdRmm/BEam45HABel42zSmNYFN01ir0rkpwGCyHTf/BnxpBY5hT2BHYFZbjAH4LnB5Oj4cuKlCYxoFnFYib3sZUx9gx3TcDXg29b3dvldNjKndvlep/a7puBPZDru7Vvp98oyCdRQ7A89HxIsR8SFwI3BQhfu0LA4Crk3H1wIHF6XfGBGLI+Il4HlgZ0l9gO4R8Whk//KvKyrT5iLiQeDtRsnlHENxXbcAw9p6xiRnTHnay5jmR8Tj6fg94CmgL+34vWpiTHnaw5giIhakXzuln6DC75MDBeso+gL/Lvr9ZZr+T2NlEMAESdMkjUhpG0TEfMj+IwTWT+l54+ubjhunV1I5x7CkTER8DNQD67RZz5v2PUkz0tJEYeq33Y0pTTV/nuzTaod4rxqNCdrxeyWpStJ04HXg3oio+PvkQME6ilIR8cr+3d/dI2JH4EvASZL2bCJv3vja07iXZQwry/j+H9AfqAHmA79K6e1qTJK6ArcCp0bEf5rKWiJtpRxXiTG16/cqIhoiogbYiGx2YPsmsq+QMTlQsI7iZaBf0e8bAa9UqC8tEhGvpD9fB24nWz55LU0bkv58PWXPG9/L6bhxeiWVcwxLykhaHehBy5cFyiYiXkv/gX8C/IHsvfpM/5KVdkySOpFdUG+IiNtScrt+r0qNqSO8VwAR8S7wALA/FX6fHChYRzEV2ELSppLWILtJ584K9ymXpLUldSscA18EZpH1+eiU7WjgjnR8J3B4umN5U2ALYEqahnxP0q5pnfGoojKVUs4xFNc1HPhHWnNdoQr/SSeHkL1X0E7GlPpwJfBURPy66FS7fa/yxtSe3ytJ60nqmY7XAvYBnqbS71Nb3LnpH/9U4gf4Mtmdzy8AZ1S6P830dTOyu5WfBGYX+ku2Vngf8Fz6s3dRmTPS2J6h6JsNQC3Zf4YvAJeSnri6gsbxZ7Lp3Y/IPqkcV84xAJ2Bv5DdpDUF2KxCY7oemAnMSP/R9mlnYxpCNr08A5iefr7cnt+rJsbUbt8rYAfgidT3WcBZKb2i75Mf4WxmZma5vPRgZmZmuRwomJmZWS4HCmZmZpbLgYKZmZnlcqBgZmZmuRwomJmZWS4HCmZmZpbr/wOwJdAm784X+wAAAABJRU5ErkJggg==",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "cap = metenergy_data.get_capacity_entsoe(\n",
    "    zone = 'ES', \n",
    "    year = 2020,\n",
    "    MY_API_KEY=\"YOUR-ENTSOE-API-KEY\"\n",
    "    )\n",
    "cap[cap > 0].transpose().dropna().plot.barh()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.9.12 ('pyfor')",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.12"
  },
  "orig_nbformat": 4,
  "vscode": {
   "interpreter": {
    "hash": "011d8e80f0f44321a71e6b0e962c9f505973ea91b8430e687597d491e8996346"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}