octoanalytics 0.0.3

Quantitative analysis for power markets

octoanalytics is an Python package by Octopus Energy that provides tools for quantitative analysis and risk calculation on energy data. It helps to analyze time series energy consumption data, extract relevant features, and predict future consumption using machine learning models.

Key Features

• Time-based Feature Engineering: Extract hourly, daily, and yearly features, as well as detect holidays using a calendar.
• Forecasting Model: Utilizes XGBoost regression models to predict hourly energy consumption.
• Model Evaluation: Computes MAPE (Mean Absolute Percentage Error) on the validation and test datasets.

Installation

To install octoanalytics, you can use pip:

pip install octoanalytics

Requirements

• Python 3.7 or higher
• pandas
• numpy
• xgboost
• sklearn
• holidays

These dependencies will be automatically installed when you install octoanalytics.

Usage

1. Importing the package

To use octoanalytics, import the eval_forecast module as shown below:

from octoanalytics import eval_forecast

2. Input Data Format

The data required for the function must be a DataFrame with the following columns:

• 'date': A column containing date-time values in datetime format.
• 'consumption': A column containing energy consumption values (the target variable).

Example of how the input data should look:

import pandas as pd

data = pd.DataFrame({
    'date': ['2025-01-01 00:00', '2025-01-01 01:00', '2025-01-01 02:00', ...],
    'consumption': [120.5, 115.3, 113.7, ...]
})

data['date'] = pd.to_datetime(data['date'])

3. Main Function: eval_forecast

The eval_forecast function trains a machine learning model to forecast energy consumption using XGBoost. Here's how to use it:

model, y_test_pred, y_test, test_mape, y_val_pred, val_mape = eval_forecast(data, country_code='FR')

Parameters

• data (pd.DataFrame): A DataFrame containing the columns date and consumption.
• country_code (str): The ISO code for the country to detect holidays (default is 'FR' for France).

Return Values

• model: The trained XGBoost model.
• y_test_pred: The model's predictions on the test set.
• y_test: The actual values of the test set.
• test_mape: The Mean Absolute Percentage Error (MAPE) of the model on the test set.
• y_val_pred: The model's predictions on the validation set.
• val_mape: The MAPE of the model on the validation set.

4. Example Usage

import pandas as pd
from octoanalytics import eval_forecast

# Example data (replace with your actual dataset)
data = pd.DataFrame({
    'date': ['2025-01-01 00:00', '2025-01-01 01:00', '2025-01-01 02:00'],
    'consumption': [120.5, 115.3, 113.7]
})
data['date'] = pd.to_datetime(data['date'])

# Run the forecast function
model, y_test_pred, y_test, test_mape, y_val_pred, val_mape = eval_forecast(data)

# Print the results
print(f"Validation MAPE: {val_mape:.2f}%")
print(f"Test MAPE: {test_mape:.2f}%")

Detailed Description of eval_forecast

The eval_forecast function is used to train a forecasting model for energy consumption using the XGBoost algorithm. Here's how it works:

1. Data Preprocessing: The function extracts time-based features such as hour, day of the week, month, year, and week of the year. It also adds a binary feature indicating whether a given date is a holiday in the specified country.

2. Data Splitting: The data is split into three sets:

   • Training set: 60% of the data.
   • Validation set: 20% of the data.
   • Test set: 20% of the data.

3. Training the XGBoost Model: The model is trained on the training set, with early stopping based on validation data to prevent overfitting.

4. Model Evaluation: The MAPE (Mean Absolute Percentage Error) is computed on both the validation and test sets.

XGBoost Model Parameters

• n_estimators: The number of boosting rounds (default is 100).
• learning_rate: The learning rate for adjusting tree weights (default is 0.1).
• max_depth: The maximum depth of the decision trees (default is 5).

These parameters can be adjusted by modifying the call to the XGBRegressor model in the eval_forecast function.

Model Evaluation

The MAPE (Mean Absolute Percentage Error) is calculated on both the validation and test sets. It is expressed as a percentage and provides an indication of how well the model is performing. A lower MAPE value indicates better model performance.

Developer

• Author: Jean Bertin
• Email: [e-mail]
• Status: In development (planning)

License

This project is licensed under the MIT License. See the LICENSE file for more details.

Contributions

Contributions are welcome! If you would like to suggest a feature or report a bug, please open an issue or submit a pull request.