Upload france-electricity-demand-forecaster model

README.md

@@ -0,0 +1,148 @@
+---
+language:
+- en
+- fr
+license: apache-2.0
+tags:
+- time-series-forecasting
+- energy-forecasting
+- electricity-demand
+- day-ahead-prices
+- lightgbm
+- tabular-regression
+- conformal-prediction
+- france
+- europe
+- entsoe
+pipeline_tag: tabular-regression
+datasets:
+- hsilvosa/entsoe-day-ahead
+metrics:
+- mae
+- rmse
+- pinball_loss
+- winkler_score
+model-index:
+- name: france-demand-forecaster
+  results:
+  - task:
+      type: tabular-regression
+      name: Electricity Demand Forecasting
+    dataset:
+      name: ENTSO-E France Bidding Zone (FR)
+      type: hsilvosa/entsoe-day-ahead
+    metrics:
+    - name: MAE
+      type: mae
+      value: 408.157
+    - name: RMSE
+      type: rmse
+      value: 708.353
+    - name: Empirical Interval Coverage (80% Nominal)
+      type: coverage
+      value: 80.3%
+---
+# Electricity Demand Forecaster for France (FR)
+
+High-accuracy calibrated quantile LightGBM model for forecasting France **demand**.
+Resolution: 15-minute intervals. Trained on multi-year data (2023–2026) from **ENTSO-E**,
+featuring multi-scale lags, cyclical encodings, and **conformal calibration**
+for well-calibrated 80% prediction intervals ($P10, P50, P90$).
+
+## Model Highlights
+
+- **Country / Zone**: France (`FR`)
+- **Target**: Electricity Demand in `MW`
+- **Resolution**: 15-minute intervals
+- **Outputs**: Point forecast ($P50$), 80% prediction interval ($P10$ to $P90$)
+- **Algorithm**: LightGBM Multi-Quantile Regressor with Conformal Calibration & Monotonicity
+- **Dataset**: ENTSO-E European Transparency Platform (Zone: `FR`)
+- **Training Samples**: 91,987 observations (2023–2026)
+
+## Performance & Benchmark Comparison
+
+Evaluated on out-of-sample test sets against official seasonal persistence benchmarks:
+
+| Metric | LightGBM Forecaster | 7-Day Seasonal Persistence | Improvement |
+|---|---:|---:|---:|
+| **MAE** | **408.157 MW** | 15273.335 MW | **+97.3%** |
+| **RMSE** | **708.353 MW** | — | — |
+- **WAPE**: 0.79%
+| **P10 Pinball Loss** | 291.061 | — | — |
+| **P90 Pinball Loss** | 162.497 | — | — |
+| **P10–P90 Interval Coverage** | **80.3%** | — | Target: 75–85% |
+| **Winkler Score** | 4535.580 | — | — |
+
+## Quickstart: Python Inference
+
+```python
+import pandas as pd
+from huggingface_hub import hf_hub_download
+import joblib
+
+# 1. Download model artifacts
+model_path = hf_hub_download(repo_id="ORGANIZATION/france-demand-forecaster", filename="models.joblib")
+models = joblib.load(model_path)
+
+# 2. Predict P10, P50 (point), and P90 quantiles
+X_test = pd.read_csv("sample_input.csv")
+p10 = models[0.1].predict(X_test)
+p50 = models[0.5].predict(X_test)
+p90 = models[0.9].predict(X_test)
+
+print("Forecast Point Estimate:", p50[:5])
+print("80% Lower Bound (P10):", p10[:5])
+print("80% Upper Bound (P90):", p90[:5])
+```
+
+## Features Used
+
+The model uses 37 leakage-safe features:
+- `hour`
+- `quarter`
+- `day_of_week`
+- `day_of_year`
+- `month`
+- `is_weekend`
+- `is_holiday`
+- `is_morning_peak`
+- `is_evening_peak`
+- `sin_hour`
+- `cos_hour`
+- `sin_day_of_week`
+- `cos_day_of_week`
+- `sin_day_of_year`
+- `cos_day_of_year`
+- `lag_1h`
+- `lag_2h`
+- `lag_3h`
+- `lag_4h`
+- `lag_24h`
+- `lag_48h`
+- `lag_7d`
+- `lag_14d`
+- `diff_1h`
+- `diff_2h`
+- `diff_24h`
+- `diff_7d`
+- `acceleration_1h`
+- `ema_4step`
+- `ema_12step`
+- `rolling_std_4step`
+- `rolling_mean_24h`
+- `rolling_std_24h`
+- `rolling_min_24h`
+- `rolling_max_24h`
+- `rolling_mean_7d`
+- `rolling_std_7d`
+
+## Intended Use & Advisory
+
+This model is intended for research, energy market analytics, grid load planning,
+and educational forecasting demonstrations. It is advisory only and not intended
+for automated trading execution or real-time grid dispatch.
+
+## Citation & Attribution
+
+Data published under the ENTSO-E Transparency framework:
+- Transparency Platform: https://transparency.entsoe.eu/

config.json

@@ -0,0 +1,68 @@
+{
+  "target": "demand",
+  "country_code": "FR",
+  "zone_key": "FR",
+  "model_name": "lightgbm-quantile",
+  "model_version": "20260820180914",
+  "feature_names": [
+    "hour",
+    "quarter",
+    "day_of_week",
+    "day_of_year",
+    "month",
+    "is_weekend",
+    "is_holiday",
+    "is_morning_peak",
+    "is_evening_peak",
+    "sin_hour",
+    "cos_hour",
+    "sin_day_of_week",
+    "cos_day_of_week",
+    "sin_day_of_year",
+    "cos_day_of_year",
+    "lag_1h",
+    "lag_2h",
+    "lag_3h",
+    "lag_4h",
+    "lag_24h",
+    "lag_48h",
+    "lag_7d",
+    "lag_14d",
+    "diff_1h",
+    "diff_2h",
+    "diff_24h",
+    "diff_7d",
+    "acceleration_1h",
+    "ema_4step",
+    "ema_12step",
+    "rolling_std_4step",
+    "rolling_mean_24h",
+    "rolling_std_24h",
+    "rolling_min_24h",
+    "rolling_max_24h",
+    "rolling_mean_7d",
+    "rolling_std_7d"
+  ],
+  "n_estimators": 180,
+  "learning_rate": 0.04,
+  "num_leaves": 31,
+  "training_rows": 91987,
+  "start_year": 2023,
+  "end_year": 2026,
+  "metrics": {
+    "mae": 408.15715759237435,
+    "rmse": 708.3532520573091,
+    "wape": 0.00790732786036686,
+    "pinball_p10": 291.0610674208522,
+    "pinball_p90": 162.49693713866475,
+    "interval_coverage": 0.8026613324056358,
+    "winkler_score": 4535.580045595169,
+    "mape": 0.7792602020415149
+  },
+  "baseline_mae": 15273.335233845017,
+  "calibrator": {
+    "is_fitted": true,
+    "q_correction": 40.1751966649681,
+    "target_coverage": 0.8
+  }
+}

inference.py

@@ -0,0 +1,29 @@
+# Standalone inference helper for Demand Forecaster
+import json
+from pathlib import Path
+import numpy as np
+import pandas as pd
+import joblib
+
+def load_forecaster(model_dir="."):
+    path = Path(model_dir)
+    config = json.loads((path / "config.json").read_text())
+    models = joblib.load(path / "models.joblib")
+    features = config["feature_names"]
+    q_correction = config["calibrator"]["q_correction"] if config.get("calibrator") else 0.0
+
+    def predict(df_features, apply_calibration=True):
+        X = df_features[features]
+        p10 = models[0.1].predict(X)
+        p50 = models[0.5].predict(X)
+        p90 = models[0.9].predict(X)
+        stacked = np.sort(np.vstack([p10, p50, p90]), axis=0)
+        p10, p50, p90 = stacked[0], stacked[1], stacked[2]
+        if apply_calibration:
+            p10 -= q_correction
+            p90 += q_correction
+            stacked_cal = np.sort(np.vstack([p10, p50, p90]), axis=0)
+            p10, p50, p90 = stacked_cal[0], stacked_cal[1], stacked_cal[2]
+        return pd.DataFrame({"p10": p10, "p50_point": p50, "p90": p90}, index=df_features.index)
+
+    return predict

models.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c21231eb4b9839d69e7504fb5137ff5c399e5509f6cd5e706456bf489e85cfbd
+size 1574269

sample_input.csv

@@ -0,0 +1,25 @@
+hour,quarter,day_of_week,day_of_year,month,is_weekend,is_holiday,is_morning_peak,is_evening_peak,sin_hour,cos_hour,sin_day_of_week,cos_day_of_week,sin_day_of_year,cos_day_of_year,lag_1h,lag_2h,lag_3h,lag_4h,lag_24h,lag_48h,lag_7d,lag_14d,diff_1h,diff_2h,diff_24h,diff_7d,acceleration_1h,ema_4step,ema_12step,rolling_std_4step,rolling_mean_24h,rolling_std_24h,rolling_min_24h,rolling_max_24h,rolling_mean_7d,rolling_std_7d
+6,2,3,331,11,0,0,0,0,1.0,6.123233995736766e-17,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,60900.27,57968.22,58365.61,60092.41,64357.83,60387.71,62806.7,48319.67,2932.0499999999956,2534.659999999996,3970.1200000000026,14487.029999999999,3329.439999999995,63174.20243688599,61157.695451043895,1996.1660041320933,66714.33072916667,4468.917972874269,57810.71,73962.35,65069.09491071427,5235.944443691829
+6,3,3,331,11,0,0,0,0,1.0,6.123233995736766e-17,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,61561.66,58041.63,57946.29,59267.56,65710.18,62003.88,64366.39,49712.44,3520.030000000006,3615.3700000000026,3706.2999999999956,14653.949999999997,3424.6900000000096,64467.0814621316,61965.188458575605,2108.6183531580896,66735.67,4462.433436028771,57810.71,73962.35,65074.451607142866,5235.467760381128
+7,0,3,331,11,0,0,0,0,0.9659258262890683,-0.25881904510252063,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,63614.58,59433.95,57917.47,59152.26,67451.03,63793.73,66319.91,51193.96,4180.630000000005,5697.110000000001,3657.2999999999956,15125.950000000004,2664.1500000000087,65968.61287727897,62927.60715725628,1936.333234788651,66761.8234375,4463.717237956881,57810.71,73962.35,65080.1875,5236.802168049207
+7,1,3,331,11,0,0,0,0,0.9659258262890683,-0.25881904510252063,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,65280.77,60011.66,57810.71,58616.3,68796.77,65353.82,67557.73,52167.48,5269.109999999993,7470.059999999998,3442.9500000000044,15390.249999999993,3068.159999999989,67455.91572636738,63967.493748447625,1947.8225451520511,66785.11343750001,4473.173981031185,57810.71,73962.35,65085.19785714285,5239.5999883915765
+7,2,3,331,11,0,0,0,0,0.9659258262890683,-0.25881904510252063,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,66406.4,60900.27,57968.22,58365.61,69459.64,66081.81,68161.2,52691.54,5506.129999999997,8438.179999999993,3377.8300000000017,15469.659999999996,2574.0800000000017,68951.71343582045,65079.48086407106,2046.560705264623,66810.09927083334,4491.191543641187,57810.71,73962.35,65090.611071428575,5244.035484820901
+7,3,3,331,11,0,0,0,0,0.9659258262890683,-0.25881904510252063,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,68220.91,61561.66,58041.63,57946.29,70373.73,66847.09,68843.14,53098.86,6659.25,10179.280000000006,3526.6399999999994,15744.279999999999,3139.219999999994,70049.46406149228,66097.42073113706,1571.5412659251995,66833.395625,4510.837101630912,57810.71,73962.35,65095.871324404754,5248.890823221263
+8,0,3,331,11,0,0,1,0,0.8660254037844387,-0.4999999999999998,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,69686.87,63614.58,59433.95,57917.47,70956.7,67322.95,69017.41,53213.13,6072.289999999994,10252.919999999998,3633.75,15804.280000000006,1891.659999999989,70971.88243689538,67060.20369557751,1135.2549125654043,66854.03916666667,4531.696263900249,57810.71,73962.35,65101.0980654762,5254.373750254827
+8,1,3,331,11,0,0,1,0,0.8660254037844387,-0.4999999999999998,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,71195.41,65280.77,60011.66,57810.71,71465.09,67575.83,69311.02,53262.99,5914.640000000007,11183.75,3889.2599999999948,16048.030000000006,645.5300000000134,71542.44146213723,67881.4462039502,575.4088049908311,66869.055625,4547.794006308107,57810.71,73962.35,65106.12912202381,5259.745046763013
+8,2,3,331,11,0,0,1,0,0.8660254037844387,-0.4999999999999998,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,71696.09,66406.4,60900.27,57968.22,71777.59,67826.5,69698.27,53217.15,5289.690000000002,10795.82,3951.0899999999965,16481.120000000003,-216.43999999999505,71916.89287728234,68588.69601872709,360.97091331629053,66879.61270833333,4559.736027581634,57810.71,73962.35,65110.84273809523,5264.935719522331
+8,3,3,331,11,0,0,1,0,0.8660254037844387,-0.4999999999999998,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,72355.51,68220.91,61561.66,58041.63,71913.73,67782.21,69556.91,53164.59,4134.599999999991,10793.849999999991,4131.5199999999895,16392.320000000007,-2524.6500000000087,72072.9117263694,69160.73355430753,72.788745479288,66885.12677083333,4566.037187792248,57810.71,73962.35,65114.724687500006,5269.283087496665
+9,0,3,331,11,0,0,1,0,0.7071067811865476,-0.7071067811865475,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,72398.28,69686.87,63614.58,59433.95,71862.16,67533.13,69448.15,52923.64,2711.4100000000035,8783.699999999997,4329.029999999999,16524.509999999995,-3360.87999999999,72195.21503582165,69655.80069979868,70.56680712940012,66889.96989583333,4571.670196973926,57810.71,73962.35,65118.923735119046,5273.9505547139
+9,1,3,331,11,0,0,1,0,0.7071067811865476,-0.7071067811865475,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,72478.57,71195.41,65280.77,60011.66,71923.37,67742.92,69504.55,52845.21,1283.1600000000035,7197.80000000001,4180.449999999997,16659.340000000004,-4631.480000000003,72221.721021493,70056.67443829119,94.65297812800436,66894.12947916667,4576.421013024361,57810.71,73962.35,65123.110238095236,5278.506903195661
+9,2,3,331,11,0,0,1,0,0.7071067811865476,-0.7071067811865475,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,72306.94,71696.09,66406.4,60900.27,71778.78,67779.73,69469.46,52858.54,610.8500000000058,5900.540000000008,3999.050000000003,16610.920000000006,-4678.8399999999965,72257.4286128958,70403.49221701562,48.299003805209175,66898.1671875,4581.073575613038,57810.71,73962.35,65127.28648809524,5283.08679061801
+9,3,3,331,11,0,0,1,0,0.7071067811865476,-0.7071067811865475,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,72378.67,72355.51,68220.91,61561.66,71585.13,67582.03,69334.53,52702.44,23.160000000003492,4157.759999999995,4003.100000000006,16632.089999999997,-4111.439999999988,72218.59716773749,70673.77802978246,91.90059263669153,66902.141875,4585.516104680754,57810.71,73962.35,65131.29078869048,5287.400848321206
+10,0,3,331,11,0,0,1,0,0.49999999999999994,-0.8660254037844387,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,72261.48,72398.28,69686.87,63614.58,71477.33,67521.13,69017.74,52505.05,-136.8000000000029,2574.6100000000006,3956.199999999997,16512.690000000002,-2848.2100000000064,72221.4943006425,70912.55679443132,63.36442115818302,66908.8159375,4592.864159364788,57810.71,73962.35,65135.59333333333,5292.000649412468
+10,1,3,331,11,0,0,1,0,0.49999999999999994,-0.8660254037844387,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,72310.99,72478.57,71195.41,65280.77,71092.73,67395.91,68651.56,51925.07,-167.58000000000175,1115.5800000000017,3696.8199999999924,16726.489999999998,-1450.7400000000052,72198.7765803855,71105.19421067266,70.35011136278187,66915.97604166667,4600.590565756636,57810.71,73962.35,65140.27630952381,5296.831335877224
+10,2,3,331,11,0,0,1,0,0.49999999999999994,-0.8660254037844387,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,72160.35,72306.94,71696.09,66406.4,70826.52,67099.0,68435.75,52357.93,-146.5899999999965,464.2600000000093,3727.520000000004,16077.82,-757.4400000000023,72099.81794823131,71235.37663979994,119.91251558497798,66924.9203125,4609.622118319168,57810.71,73962.35,65145.18675595238,5301.618726657386
+10,3,3,331,11,0,0,1,0,0.49999999999999994,-0.8660254037844387,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,72225.84,72378.67,72355.51,68220.91,70414.55,66870.31,68550.28,52168.45,-152.83000000000175,-129.66999999999825,3544.2400000000052,16381.830000000002,-175.99000000000524,72045.2707689388,71347.38792598457,139.66256141383218,66936.76333333334,4621.197570470784,57810.71,73962.35,65150.436309523815,5306.625993636114
+11,0,3,331,11,0,0,1,0,0.258819045102521,-0.9659258262890682,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,72164.7,72261.48,72398.28,69686.87,70366.42,66856.21,68760.97,51983.8,-96.77999999999884,-233.58000000000175,3510.209999999992,16777.17,40.020000000004075,71862.39446136329,71384.4174758331,240.05777442306908,66948.98760416667,4632.033502165105,57810.71,73962.35,65154.95684523809,5310.81876540342
+11,1,3,331,11,0,0,1,0,0.258819045102521,-0.9659258262890682,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,71951.38,72310.99,72478.57,71195.41,70030.85,66975.19,68515.31,51928.44,-359.6100000000006,-527.1900000000023,3055.6600000000035,16586.869999999995,-192.02999999999884,71686.83667681798,71390.43017185878,269.3085412581988,66959.99885416667,4641.489713126158,57810.71,73962.35,65158.91894345238,5314.504916378583
+11,2,3,331,11,0,0,1,0,0.258819045102521,-0.9659258262890682,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,71963.45,72160.35,72306.94,71696.09,69974.66,67188.58,68477.84,52117.29,-196.90000000000873,-343.49000000000524,2786.0800000000017,16360.549999999996,-50.310000000012224,71488.3660060908,71359.69629926511,325.1790175605088,66972.08020833333,4651.066540749927,57810.71,73962.35,65162.90011904763,5318.023893978706
+11,3,3,331,11,0,0,1,0,0.258819045102521,-0.9659258262890682,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,71588.08,72225.84,72378.67,72355.51,70568.63,67409.33,69218.66,52527.09,-637.7599999999948,-790.5899999999965,3159.300000000003,16691.570000000007,-484.929999999993,71458.1556036545,71367.87225322431,163.15390066905127,66987.06125000001,4663.140136390342,57810.71,73962.35,65167.267678571436,5321.954196788695
+12,0,3,331,11,0,0,0,0,1.2246467991473532e-16,-1.0,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,71423.5,72164.7,72261.48,72398.28,70763.31,67627.95,69495.16,52776.96,-741.1999999999971,-837.9799999999959,3135.3600000000006,16718.200000000004,-644.4199999999983,71353.6693621927,71341.5749834975,129.63851512455034,66993.60614583333,4668.657584200368,57810.71,73962.35,65170.211547619045,5324.745003858992
+12,1,3,331,11,0,0,0,0,1.2246467991473532e-16,-1.0,0.43388373911755823,-0.900968867902419,-0.5556819724760489,0.8313949395234058,71190.66,71951.38,72310.99,72478.57,70229.17,67268.06,69201.97,52607.24,-760.7200000000012,-1120.3300000000017,2961.1100000000006,16594.730000000003,-401.1100000000006,71258.82161731563,71306.95575526712,127.7232714197629,66997.28572916666,4671.798081387234,57810.71,73962.35,65172.62433035715,5327.07451075865

sample_prediction.json

@@ -0,0 +1,80 @@
+{
+  "p10": [
+    56861.02,
+    56861.02,
+    56861.02,
+    56861.02,
+    56861.02,
+    56861.02,
+    56861.02,
+    56861.02,
+    56861.02,
+    56861.02,
+    56861.02,
+    56861.02,
+    56861.02,
+    56861.02,
+    56861.02,
+    56861.02,
+    56861.02,
+    56861.02,
+    56861.02,
+    56861.02,
+    56861.02,
+    56861.02,
+    56861.02,
+    56861.02
+  ],
+  "p50_point": [
+    66331.64,
+    67627.07,
+    69391.4,
+    70741.93,
+    71532.89,
+    72350.42,
+    72325.92,
+    72463.92,
+    72872.21,
+    72866.23,
+    72430.05,
+    72013.62,
+    71897.35,
+    71698.82,
+    71721.85,
+    71831.2,
+    71862.18,
+    71861.72,
+    71853.81,
+    71771.8,
+    71097.91,
+    71087.7,
+    70952.08,
+    70920.28
+  ],
+  "p90": [
+    66651.85,
+    68099.35,
+    69862.34,
+    71170.34,
+    72285.5,
+    73144.71,
+    73088.09,
+    73017.45,
+    73544.69,
+    73205.13,
+    72826.91,
+    72326.89,
+    72252.08,
+    72014.8,
+    72011.05,
+    72056.68,
+    72162.07,
+    72194.6,
+    72239.85,
+    72128.33,
+    71576.75,
+    71629.06,
+    71653.62,
+    71537.78
+  ]
+}