.. _example-energy-consumption:

==================
Energy Consumption
==================

This example demonstrates Tabular Regression using the Energy Consumption dataset.

.. contents:: On this page
   :local:
   :depth: 2

Problem Description
===================

**Goal:** Predict the energy consumption of a house based on environmental factors.

**Input Features (5):**

1. Temperature difference (inside vs. outside)
2. Wind direction
3. Wind speed
4. Sunshine intensity
5. Relative humidity

**Output (1):**

- Energy consumption

Dataset
=======

The dataset is split into training and test sets:

- ``x_train.csv`` — Training inputs (5 features)
- ``y_train.csv`` — Training outputs (energy consumption)
- ``x_test.csv`` — Test inputs
- ``y_test.csv`` — Test outputs (for evaluation)

.. note::

   These files ship in the ``EnergyConsumption`` example folder of the NeurEco
   installation (see :doc:`index` for the location). Extract that folder and run
   the commands below from inside it so the relative paths resolve.

Building the Model
==================

.. tabs::

   .. tab:: GUI

      1. Launch NeurEco and select **Tabular Regression**
      2. Load ``x_train.csv`` as input and ``y_train.csv`` as output
      3. Optionally load test files for automatic evaluation
      4. Click **BUILD**
      5. Monitor training progress
      6. Once complete, evaluate and export

   .. tab:: Python API

      .. code-block:: python

         from NeurEco import NeurEcoTabular as Tabular
         import numpy as np

         # Load data
         x_train = np.genfromtxt("x_train.csv", delimiter=";", skip_header=True)
         y_train = np.genfromtxt("y_train.csv", delimiter=";", skip_header=True)
         y_train = np.reshape(y_train, (-1, 1))

         x_test = np.genfromtxt("x_test.csv", delimiter=";", skip_header=True)
         y_test = np.genfromtxt("y_test.csv", delimiter=";", skip_header=True)
         y_test = np.reshape(y_test, (-1, 1))

         # Create and build model
         model = Tabular.Regressor()

         config = Tabular.RegressorBuildConfig(
             input_data=x_train,
             output_data=y_train,
             write_model_to="./energy_model/energy.ednn",
             checkpoint_address="./energy_model/energy.checkpoint",
             valid_percentage=33.33,
             inputs_shifting="min_centered",
             inputs_scaling="max_centered",
         )

         model.build(config)

         # Evaluate
         predictions = model.evaluate(x_test)
         l2_error = np.sqrt(np.sum((predictions - y_test) ** 2) / np.sum(y_test ** 2))
         print(f"L2 Relative Error: {l2_error:.6f}")

         # Export
         model.export_onnx("./energy_model/energy.onnx", precision="float32")

         # Cleanup
         model.delete()

   .. tab:: CLI

      Create ``build_energy.conf``:

      .. code-block:: json

         {
             "neurecoRegression_build": {
                 "DevSettings": {
                     "valid_percentage": 33.33
                 },
                 "exc_filenames": ["x_train.csv"],
                 "output_filenames": ["y_train.csv"],
                 "test_exc_filenames": ["x_test.csv"],
                 "test_output_filenames": ["y_test.csv"],
                 "input_normalization": {
                     "shift_type": "min_centered",
                     "scale_type": "max_centered",
                     "normalize_per_feature": true
                 },
                 "output_normalization": {
                     "shift_type": "auto",
                     "scale_type": "auto",
                     "normalize_per_feature": true
                 },
                 "write_model_to": "./energy_model/energy.ednn",
                 "checkpoint_address": "./energy_model/energy.checkpoint"
             }
         }

      Run:

      .. code-block:: shell

         neureco Regression build build_energy.conf

Expected Results
================

After training, you should observe:

- **Small, parsimonious network**
- **Quick training** — Usually completes within minutes

Key Takeaways
=============

This example demonstrates:

1. **Data efficiency** — NeurEco achieves good results with modest training data
2. **Automatic architecture** — No need to manually design the network
3. **Checkpoint availability** — Multiple models saved during training
4. **Easy export** — One command to export for deployment

Variations to Try
=================

- Adjust ``valid_percentage`` to see its effect on model selection
- Try different normalization settings
- Limit model size with ``links_maximum_number``
- Compare different checkpoints' performance on test data