DemandCast

Global hourly electricity demand forecasting

A project developed by

Supported by

About

DemandCast is a Python-based project focused on collecting, processing, and forecasting hourly electricity demand data. The aim of this project is to support energy planning studies by using machine learning models to generate hourly time series of future electricity demand or for countries without available data.

Features

• Retrieval of open hourly and sub-hourly electricity demand data from public sources (ETL).
• Retrieval of weather and socio-economic data (ETL).
• Forecasting using machine learning models (models).
• Modular design for adding new countries or data sources.
• Support for reproducible, containerized development.

Feature roadmap

The project is in active development and we are always looking for suggestions and contributions. Below is a non-exhaustive list of planned features:

• Add support to forecast electricity demand in user-defined subnational regions.
• Enhance model training by integrating new datasets:
  • New countries and subdivisions with available electricity demand data,
  • Sectoral electricity demand (agriculture, industry, transport, buildings),
  • Adoption of EVs, air conditioning, and heat pumps.
• Add and test new machine learning models for forecasting (e.g., timesfm).
• Add quality checks of electricity demand time series.
• Improve validation by considering simultaneity of peaks between actual and forecast electricity demand.
• Package the project for easier installation and usage.

Repository structure

demandcast/
├── .github/                # Github specifics such as actions
├── ETL/                    # Scripts for extracting, transforming, and loading data
├── models/                 # Machine learning models for demand forecasting
├── webpage/                # Documentation website files (MkDocs)
├── .gitattributes          # Git attributes for handling line endings
├── .gitignore              # File lists that git ignores
├── .pre-commit-config.yaml # Pre-commit configuration
├── CONTRIBUTING.md         # Guide to contributing
├── LICENSE                 # License file
├── README.md               # Project overview and instructions
├── ruff.toml               # Ruff configuration
└── security.md             # Security policy

DemandCast structure

Data sources

The table below provides an overview of the data sources currently used in DemandCast for hourly and sub-hourly electricity demand, weather, and socio-economic data for both historical and forecasted periods.

Data type	Historical data source	Forecast data source
Hourly and sub-hourly electricity demand	Various public sources listed in the Awesome Electricity Demand repository	DemandCast
Temperature	ERA5	CMIP6
Gridded population	SEDAC GPW v4	Wang X. et al. (2022)
National population	World Bank	IIASA SSP Database
Gridded GDP, PPP	Wang T. et al. (2022)	Wang T. et al. (2022)
National GDP per capita, PPP	World Bank, IMF	IIASA SSP Database
National annual electricity demand per capita	Ember, World Bank	IIASA SSP Database

The map below shows the countries and subdivisions for which retrieval modules of electricity demand data are currently available in DemandCast.

Find the code that we used to retrieve the data in their respective files inside the ETL/retrievals folder.

Getting started

1. Clone the repository

git clone https://github.com/open-energy-transition/demandcast.git
cd demandcast

2. Set up your environment

This project uses uv as a package manager to install the required dependencies and create an environment stored in .venv.

uv can be used within the provided Dockerfile or installed standalone (see installing uv).

The ETL folder and each subfolder in the models directory—each representing a separate model—contain their own pyproject.toml files that define the dependencies for that module.

To set up the environment, run:

cd path/to/folder
uv sync

Alternatively, you may use a package manager of your choice (e.g., conda) to install the dependencies listed in the respective pyproject.toml. If you choose this approach, please adjust the commands below to align with the conventions of your selected package manager.

3. Run scripts

Scripts can be run directly using:

cd path/to/folder
uv run script.py

Jupyter notebooks (details) can be launched with:

cd path/to/folder
uv run --with jupyter jupyter lab --allow-root

Development workflow

Run tests and check test coverage

cd path/to/folder
uv run pytest --cov=utils --cov-report=term-missing

Pre-commit and lint code

To ensure code quality, we use pre-commit hooks. These hooks automatically run checks on your code before committing changes. Among the pre-commit hooks, we also use ruff to enforce code style and linting. All the pre-commit hooks are defined in the .pre-commit-config.yaml file.

To run pre-commit hooks, you can use:

uvx pre-commit

Documentation

The documentation is currently hosted on GitHub pages connected to this repository. It is built with mkdocs.

To run it locally:

cd webpage
uv run mkdocs serve

Maintainers

The project is maintained by the Open Energy Transition team. The team members currently involved in this project are:

• Kevin Steijn (kevin.steijn at openenergytransition dot org)
• Vamsi Priya Goli (goli.vamsi at openenergytransition dot org)
• Enrico Antonini (enrico.antonini at openenergytransition dot org)

Contributing

We welcome contributions in the form of:

• Country-specific ETL modules
• New or improved forecasting models
• Documentation and testing enhancements

Please follow the repository’s structure and submit your changes via pull request.

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).