first code

.idea/.gitignore

@@ -0,0 +1,10 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Ignored default folder with query files
+/queries/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml
+# Editor-based HTTP Client requests
+/httpRequests/

.idea/copilot.data.migration.ask2agent.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Ask2AgentMigrationStateService">
+    <option name="migrationStatus" value="COMPLETED" />
+  </component>
+</project>

.idea/dataSources.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="DataSourceManagerImpl" format="xml" multifile-model="true">
+    <data-source source="LOCAL" name="epc_houses.sqlite" uuid="cca81896-f0bd-4f3b-8734-bd047c28bed3">
+      <driver-ref>sqlite.xerial</driver-ref>
+      <synchronize>true</synchronize>
+      <jdbc-driver>org.sqlite.JDBC</jdbc-driver>
+      <jdbc-url>jdbc:sqlite:$PROJECT_DIR$/data/epc_houses.sqlite</jdbc-url>
+      <working-dir>$ProjectFileDir$</working-dir>
+    </data-source>
+  </component>
+</project>

.idea/epc_only_data_model.iml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="jdk" jdkName="Python 3.12" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

.idea/misc.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Black">
+    <option name="sdkName" value="Python 3.12" />
+  </component>
+  <component name="ProjectRootManager" version="2" project-jdk-name="Python 3.12" project-jdk-type="Python SDK" />
+</project>

.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/epc_only_data_model.iml" filepath="$PROJECT_DIR$/.idea/epc_only_data_model.iml" />
+    </modules>
+  </component>
+</project>

.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

Dockerfile

@@ -0,0 +1,51 @@
+# ------------------------------------------------------------
+# Effici EPC Energy Prediction API
+# ------------------------------------------------------------
+FROM python:3.12-slim
+
+# Prevent Python from writing .pyc files
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+# Set working directory
+WORKDIR /app
+
+# ------------------------------------------------------------
+# System dependencies (minimal)
+# ------------------------------------------------------------
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# ------------------------------------------------------------
+# Install Python dependencies
+# ------------------------------------------------------------
+COPY requirements.txt .
+RUN pip install --no-cache-dir --upgrade pip \
+    && pip install --no-cache-dir -r requirements.txt
+
+# ------------------------------------------------------------
+# Copy application code
+# ------------------------------------------------------------
+COPY app ./app
+COPY src ./src
+
+# Optional: copy .env for local docker testing
+# (Do NOT do this in production images)
+# COPY .env .
+
+# ------------------------------------------------------------
+# Environment variables (runtime configurable)
+# ------------------------------------------------------------
+ENV PORT=8000
+
+# ------------------------------------------------------------
+# Expose port
+# ------------------------------------------------------------
+EXPOSE 8000
+
+# ------------------------------------------------------------
+# Start FastAPI
+# ------------------------------------------------------------
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

app/handler.py

@@ -0,0 +1,102 @@
+import os, sys
+import mlflow
+import mlflow.pyfunc
+import pandas as pd
+from dotenv import load_dotenv
+
+# Load .env BEFORE anything else
+load_dotenv()
+
+# Ensure the project root (which contains 'src') is in sys.path
+# project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), "../.."))
+# if project_root not in sys.path:
+#     sys.path.insert(0, project_root)
+
+
+class FastApiHandler:
+    """Handler for rent price prediction using MLflow pipeline model."""
+
+    def __init__(
+        self,
+    ):
+        self.model = None
+        self.model_uri = None
+
+        self._configure_gcp_credentials()
+        self.load_model()  # Load once at startup
+
+    # -----------------------------------------------------------
+    # Configure Google Cloud authentication
+    # -----------------------------------------------------------
+    @staticmethod
+    def _configure_gcp_credentials():
+        """Loads GCP credentials from HF ENV or system ENV."""
+
+        # Hugging Face Spaces: JSON secret
+        creds_json = os.getenv("GOOGLE_APPLICATION_CREDENTIALS_JSON")
+
+        if creds_json:
+            print("🔐 Configuring GCP credentials from ENV JSON...")
+            with open("/tmp/gcp_creds.json", "w") as f:
+                f.write(creds_json)
+            os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = "/tmp/gcp_creds.json"
+
+        # Local dev or Docker with .env
+        elif os.getenv("GOOGLE_APPLICATION_CREDENTIALS"):
+            print("🔐 Using GOOGLE_APPLICATION_CREDENTIALS from environment")
+
+        else:
+            print("⚠️ WARNING: No GCP credentials provided! GCS model loading may fail.")
+
+    # -----------------------------------------------------------
+    # Load the MLflow model
+    # -----------------------------------------------------------
+    def load_model(self):
+        self.model_uri = os.getenv("MODEL_URI")
+        if not self.model_uri:
+            raise RuntimeError("MODEL_URI env var not set")
+
+        print(f"🔗 Loading MLflow model: {self.model_uri}")
+        self.model = mlflow.pyfunc.load_model(self.model_uri)
+        print("✅ Model loaded successfully")
+
+    # -----------------------------------------------------------
+    # Predict
+    # -----------------------------------------------------------
+    def predict(self, model_params: dict) -> float:
+        if self.model is None:
+            raise RuntimeError("Model not loaded")
+
+        df = pd.DataFrame([model_params])
+        preds = self.model.predict(df)
+        return float(preds[0])
+
+
+    def explain_prediction(self, model_params: dict) -> dict:
+        if self.model is None:
+            raise RuntimeError("Model not loaded")
+
+        df = pd.DataFrame([model_params])
+
+        # 🔥 Unwrap the custom RentPricePipeline
+        python_model = self.model.unwrap_python_model()
+
+        explanation = python_model.explain_predictions(df)
+        return explanation
+
+    # -----------------------------------------------------------
+    # FastAPI-compatible handler
+    # -----------------------------------------------------------
+    def handle(self, params: dict) -> dict:
+        if "model_params" not in params:
+            return {"error": "Missing 'model_params' in request"}
+
+        try:
+            prediction = self.predict(params["model_params"])
+        except Exception as e:
+            return {"error": str(e)}
+
+        return {
+            "prediction": prediction,
+            "inputs": params["model_params"]
+        }

app/main.py

@@ -0,0 +1,82 @@
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel, Field
+from typing import Optional
+from app.handler import FastApiHandler
+
+app = FastAPI(title="Effici EPC Energy Prediction API")
+
+handler = None
+
+
+# ---------- EPC Request Schema ----------
+class EPCPredictRequest(BaseModel):
+    model_params: dict = Field(
+        ...,
+        json_schema_extra={
+            "example": {
+                "PROPERTY_TYPE": "Flat",
+                "BUILT_FORM": "Enclosed End-Terrace",
+                "CONSTRUCTION_AGE_BAND": "England and Wales: 1996-2002",
+
+                "TOTAL_FLOOR_AREA": 70.12,
+                "FLOOR_HEIGHT": 2.32,
+                "FLAT_TOP_STOREY": "N",
+                "FLAT_STOREY_COUNT": 23.0,
+
+                "WINDOWS_DESCRIPTION": "Fully triple glazed",
+                "WALLS_DESCRIPTION": "System built, as built, insulated (assumed)",
+                "ROOF_DESCRIPTION": "(another dwelling above)",
+                "FLOOR_DESCRIPTION": "(other premises below)",
+
+                "MAINHEAT_DESCRIPTION": "Air source heat pump, warm air, electric",
+                "MAINHEAT_ENERGY_EFF": "Average",
+
+                "SECONDHEAT_DESCRIPTION": "Room heaters, electric",
+
+                "HOTWATER_DESCRIPTION": "Electric immersion, standard tariff, no cylinderstat",
+                "HOT_WATER_ENERGY_EFF": "Very Poor",
+
+                "LIGHTING_DESCRIPTION": "No low energy lighting",
+
+                "MECHANICAL_VENTILATION": "natural",
+                "PHOTO_SUPPLY": 0.0
+            }
+        },
+    )
+
+
+
+# ---------- Startup ----------
+@app.on_event("startup")
+def load_model_once():
+    global handler
+    handler = FastApiHandler()
+    print("✅ EPC MLflow model loaded at startup")
+
+
+# ---------- Routes ----------
+@app.get("/")
+def root():
+    return {
+        "message": "🏠 Effici EPC Energy Prediction API is running",
+    }
+
+
+@app.post("/predict")
+def predict(req: EPCPredictRequest):
+    try:
+        result = handler.handle(req.dict())
+        if "error" in result:
+            raise HTTPException(status_code=400, detail=result["error"])
+        return result
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@app.post("/explain")
+def explain(req: EPCPredictRequest):
+    try:
+        explanation = handler.explain_prediction(req.model_params)
+        return explanation
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=str(e))

requirements.txt

@@ -0,0 +1,28 @@
+# --- Core serving ---
+fastapi==0.115.6
+uvicorn[standard]==0.34.0
+python-dotenv==1.0.1
+
+# --- MLflow model loading ---
+mlflow==3.8.1
+cloudpickle==3.1.2
+
+# --- Numerical stack (MUST match training) ---
+numpy==2.0.2
+pandas==2.2.2
+scipy==1.16.3
+scikit-learn==1.6.1
+
+# --- Model ---
+catboost==1.2.8
+
+# --- EPC / SAP feature engineering ---
+openpyxl==3.1.5
+xlrd==2.0.2
+
+# --- Explainability (required for /explain endpoint) ---
+shap==0.50.0
+
+# --- GCP access ---
+google-cloud-storage==2.16.0
+

src/features/build_features.py

@@ -0,0 +1,161 @@
+import pandas as pd
+from dataclasses import dataclass
+from pathlib import Path
+
+from src.features.construction_age_band_sap import normalize_construction_age_band, windows_feature_engineering_vectorised
+from src.features.energy_system import energy_system_feature_engineering_vectorised
+from src.features.floor import floor_feature_engineering_fast
+from src.features.walls import wall_feature_engineering
+from src.features.roofs import roof_feature_engineering
+
+
+def build_age_band_lookup(series: pd.Series):
+    """
+    Build lookup dict:
+    raw EPC CONSTRUCTION_AGE_BAND -> (sap_band_letter, sap_band_label)
+    """
+    unique_vals = series.dropna().unique()
+
+    lookup = {}
+    for v in unique_vals:
+        letter, label = normalize_construction_age_band(v)
+        lookup[v] = (letter, label)
+
+    return lookup
+
+
+def age_band_to_sap_letter(df: pd.DataFrame)-> pd.DataFrame:
+
+    df = df.copy()
+    lookup = build_age_band_lookup(df["CONSTRUCTION_AGE_BAND"])
+    age_df = (
+       pd.DataFrame.from_dict(
+        lookup,
+        orient="index",
+        columns=["sap_band_letter", "sap_band_label"]
+        )
+    )
+    df = df.join(age_df, on="CONSTRUCTION_AGE_BAND")
+
+    return df
+
+
+EFF_MAP = {
+    "very poor": 0.60,
+    "poor": 0.68,
+    "average": 0.75,
+    "good": 0.85,
+    "very good": 0.92
+}
+
+
+DHW_EFF_MAP = {
+    "very poor": 0.65,
+    "poor": 0.72,
+    "average": 0.78,
+    "good": 0.85,
+    "very good": 0.90
+}
+
+energy_system_columns = [
+    "MAIN_HEATING_SYSTEM","SECONDARY_HEATING_SYSTEM",
+    "MAIN_FUEL_TYPE","DHW_SUPPLY_SYSTEM","VENTILATION_SYSTEM",
+    "LIGHTING_FRACTION_LOW_ENERGY","PV_KWP","MAINHEAT_EFF_NUM","ROOF_MM_S9",
+    "HOT_WATER_ENERGY_NUM"
+]
+
+envelop_columns = [
+    "FLOOR_U_VALUE","FLOOR_INSULATION_TYPE","FLOOR_BOUNDARY_TYPE",
+    "WALL_U_VALUE","WALL_TYPE","WALL_INSULATION",
+    "ROOF_U_VALUE","ROOF_CLASS","ROOF_INSULATION_TYPE",
+    "glazing_area_m2","glazing_type"
+]
+
+general_details = [
+    "PROPERTY_TYPE","TOTAL_FLOOR_AREA",
+    "BUILT_FORM","sap_band_letter","FLOOR_HEIGHT"
+]
+
+features = energy_system_columns + envelop_columns + general_details
+
+
+cat_cols = [
+    "MAIN_HEATING_SYSTEM","SECONDARY_HEATING_SYSTEM",
+    "MAIN_FUEL_TYPE","DHW_SUPPLY_SYSTEM","VENTILATION_SYSTEM",
+    "FLOOR_INSULATION_TYPE","FLOOR_BOUNDARY_TYPE",
+    "WALL_TYPE","WALL_INSULATION",
+    "ROOF_CLASS","ROOF_INSULATION_TYPE",
+    "glazing_type",
+    "PROPERTY_TYPE","BUILT_FORM","sap_band_letter"
+]
+
+
+
+@dataclass
+class SAPTables:
+    s3: pd.DataFrame
+    walls_u: pd.DataFrame
+    s9: pd.DataFrame
+    s10: pd.DataFrame
+
+    @classmethod
+    def from_local_dir(cls, base_dir: str) -> "SAPTables":
+        base = Path(base_dir)
+
+        return cls(
+            s3=pd.read_excel(base / "S3_sap.xlsx"),
+            walls_u=pd.read_excel(base / "external_wall_u_values2.xlsx"),
+            s9=pd.read_excel(base / "SAP_Table_ROOF_S9.xlsx"),
+            s10=pd.read_excel(base / "SAP_Table_ROOF_S10.xlsx"),
+        )
+
+
+
+class EPCFeatureEngineer:
+    def __init__(self, sap: SAPTables):
+        self.sap = sap
+
+    def transform(self, df: pd.DataFrame) -> pd.DataFrame:
+        df = df.copy()
+
+        df.replace("", pd.NA, inplace=True)
+
+        df["FLOOR_HEIGHT"] = df["FLOOR_HEIGHT"].fillna(2.5)
+
+        # SAP age bands
+        df = age_band_to_sap_letter(df)
+
+        # Envelope
+        df = windows_feature_engineering_vectorised(df)
+        df = energy_system_feature_engineering_vectorised(df)
+        df = floor_feature_engineering_fast(df, self.sap.s3)
+        df = wall_feature_engineering(df, self.sap.walls_u)
+        df = roof_feature_engineering(df, self.sap.s9, self.sap.s10)
+
+        # Heating efficiency
+        df["MAINHEAT_EFF_NUM"] = (
+            df["MAINHEAT_ENERGY_EFF"]
+            .str.lower()
+            .map(EFF_MAP)
+            .fillna(0.75)
+        )
+
+        # Hot water efficiency
+        df["HOT_WATER_ENERGY_NUM"] = (
+            df["HOT_WATER_ENERGY_EFF"]
+            .str.lower()
+            .map(DHW_EFF_MAP)
+        )
+
+        df.loc[
+            df["HOT_WATER_ENERGY_NUM"].isna() &
+            df["DHW_SUPPLY_SYSTEM"].notna(),
+            "HOT_WATER_ENERGY_NUM"
+        ] = 0.78
+
+        df["HOT_WATER_ENERGY_NUM"] = df["HOT_WATER_ENERGY_NUM"].fillna(0.75)
+
+        # Categoricals
+        df[cat_cols] = df[cat_cols].fillna("UNKNOWN").astype(str)
+
+        return df[features]

src/features/construction_age_band_sap.py

@@ -0,0 +1,379 @@
+import re
+import pandas as pd
+import numpy as np
+
+"""Feature engineering for SAP S1 construction age band from EPC data. p115"""
+
+SAP_AGE_BANDS = [
+    ("A", "pre-1900",    0,    1899),
+    ("B", "1900-1929", 1900,   1929),
+    ("C", "1930-1949", 1930,   1949),
+    ("D", "1950-1966", 1950,   1966),
+    ("E", "1967-1975", 1967,   1975),
+    ("F", "1976-1982", 1976,   1982),
+    ("G", "1983-1990", 1983,   1990),
+    ("H", "1991-1995", 1991,   1995),
+    ("I", "1996-2002", 1996,   2002),
+    ("J", "2003-2006", 2003,   2006),
+    ("K", "2007-2011", 2007,   2011),
+    ("L", "2012+",     2012,   2100)
+]
+
+def assign_sap_band(year):
+    """Map numeric year to SAP S1 band."""
+    for letter, label, y1, y2 in SAP_AGE_BANDS:
+        if y1 <= year <= y2:
+            return letter, label
+    return None, None
+
+
+def normalize_construction_age_band(raw_val):
+    """
+    Convert messy EPC input into SAP S1 age band (A–L)
+    and human-readable label ('1930-1949').
+    """
+    if pd.isna(raw_val):
+        return None, None
+
+    s = str(raw_val).lower().strip()
+    s = s.replace("england and wales:", "").strip()
+
+    # discard invalids
+    if s in ["no data!", "invalid!", "", "none"]:
+        return None, None
+
+    # before XXXX
+    m = re.findall(r"before\s+(\d{4})", s)
+    if m:
+        year = int(m[0]) - 1
+        return assign_sap_band(year)
+
+    # XXXX onwards
+    m = re.findall(r"(\d{4})\s*(onward|onwards)", s)
+    if m:
+        year = int(m[0][0])
+        return assign_sap_band(year)
+
+    # ranges like 1950-1966
+    m = re.findall(r"(\d{4})\D+(\d{4})", s)
+    if m:
+        y1, y2 = map(int, m[0])
+        mid = (y1 + y2) // 2
+        return assign_sap_band(mid)
+
+    # standalone year
+    m = re.findall(r"(\d{4})", s)
+    if m:
+        year = int(m[0])
+        return assign_sap_band(year)
+
+    return None, None
+
+
+def glazing_area_estimate(tfa, sap_band_letter, property_type):
+    """
+    Compute glazing area based on:
+      - ML paper's Table 2
+      - SAP age band (A-L)
+      - Property type (House/Bungalow vs Flat/Maisonette)
+
+    Inputs:
+      tfa : Total Floor Area (float)
+      sap_band_letter : 'A' ... 'L' (SAP band)
+      property_type : 'House', 'Bungalow', 'Flat', 'Maisonette'
+    """
+
+    if pd.isna(tfa) or tfa <= 0:
+        return None
+    if sap_band_letter is None:
+        return None
+    if property_type is None:
+        return None
+
+    # Normalise dwelling class
+    house_group = ["house", "bungalow"]
+    flat_group = ["flat", "maisonette"]
+
+    pt = str(property_type).lower()
+    is_house = pt in house_group
+    is_flat = pt in flat_group
+
+    # Map SAP A–L to glazing formula groups
+    # Based on paper Table 2
+    if sap_band_letter in ["A", "B", "C"]:
+        group = "pre_1900_1949"
+    elif sap_band_letter == "D":
+        group = "1950_1966"
+    elif sap_band_letter == "E":
+        group = "1967_1975"
+    elif sap_band_letter == "F":
+        group = "1976_1982"
+    elif sap_band_letter == "G":
+        group = "1983_1990"
+    elif sap_band_letter == "H":
+        group = "1991_1995"
+    elif sap_band_letter == "I":
+        group = "1996_2002"
+    else:
+        # J, K, L
+        group = "after_2003"
+
+    # Apply formulas (from ML paper)
+    if is_house:
+        if group == "pre_1900_1949":
+            return 0.1220 * tfa + 6.875
+        elif group == "1950_1966":
+            return 0.1294 * tfa + 5.515
+        elif group == "1967_1975":
+            return 0.1239 * tfa + 7.332
+        elif group == "1976_1982":
+            return 0.1252 * tfa + 5.520
+        elif group == "1983_1990":
+            return 0.1356 * tfa + 5.242
+        elif group == "1991_1995":
+            return 0.0948 * tfa + 6.534
+        elif group == "1996_2002":
+            return 0.1382 * tfa - 0.027
+        elif group == "after_2003":
+            return 0.1435 * tfa - 0.403
+
+    elif is_flat:
+        if group == "pre_1900_1949":
+            return 0.0801 * tfa + 5.580
+        elif group == "1950_1966":
+            return 0.0341 * tfa + 8.562
+        elif group == "1967_1975":
+            return 0.0717 * tfa + 6.560
+        elif group == "1976_1982":
+            return 0.1199 * tfa + 1.975
+        elif group == "1983_1990":
+            return 0.0510 * tfa + 4.554
+        elif group == "1991_1995":
+            return 0.0813 * tfa + 3.744
+        elif group == "1996_2002":
+            return 0.1148 * tfa + 0.392
+        elif group == "after_2003":
+            return 0.1148 * tfa + 0.392  # same in paper
+
+    return None
+
+
+def classify_glazing_type(text):
+    """
+    Classify EPC glazing description into SAP/ML-compatible glazing types.
+    """
+
+    if text is None or not isinstance(text, str):
+        return None
+
+    t = text.lower().strip()
+
+    # --- high performance (best class) ---
+    if "high performance" in t:
+        return "high_performance"
+
+    # --- triple glazing ---
+    if "triple" in t:
+        return "triple"
+
+    # --- secondary glazing ---
+    if "secondary" in t:
+        if any(x in t for x in ["partial", "some"]):
+            return "mixed"
+        return "secondary"
+
+    # --- double glazing ---
+    if "double" in t:
+        if any(x in t for x in ["partial", "some", "mostly"]):
+            return "mixed"
+        return "double"
+
+    # --- single glazing ---
+    if "single" in t:
+        return "single"
+
+    # --- fallback ---
+    return None
+
+
+def windows_feature_engineering(df:pd.DataFrame)-> pd.DataFrame:
+    """
+    Apply construction age band and glazing area feature engineering
+    to the given dataframe.
+    """
+    df = df.copy()
+
+    df["glazing_area_m2"] = df.apply(
+        lambda row: glazing_area_estimate(
+            tfa=row["TOTAL_FLOOR_AREA"],
+            sap_band_letter=row["sap_band_letter"],
+            property_type=row["PROPERTY_TYPE"]
+        ),
+        axis=1
+    )
+
+    df["glazing_type"] = df["WINDOWS_DESCRIPTION"].apply(
+        classify_glazing_type
+    )
+
+    return df
+
+# Example of usage:
+GLAZING_COEFFS = {
+    "house": {
+        "pre_1900_1949": (0.1220,  6.875),
+        "1950_1966":     (0.1294,  5.515),
+        "1967_1975":     (0.1239,  7.332),
+        "1976_1982":     (0.1252,  5.520),
+        "1983_1990":     (0.1356,  5.242),
+        "1991_1995":     (0.0948,  6.534),
+        "1996_2002":     (0.1382, -0.027),
+        "after_2003":    (0.1435, -0.403),
+    },
+    "flat": {
+        "pre_1900_1949": (0.0801,  5.580),
+        "1950_1966":     (0.0341,  8.562),
+        "1967_1975":     (0.0717,  6.560),
+        "1976_1982":     (0.1199,  1.975),
+        "1983_1990":     (0.0510,  4.554),
+        "1991_1995":     (0.0813,  3.744),
+        "1996_2002":     (0.1148,  0.392),
+        "after_2003":    (0.1148,  0.392),
+    }
+}
+
+
+SAP_TO_GLAZING_GROUP = {
+    "A": "pre_1900_1949",
+    "B": "pre_1900_1949",
+    "C": "pre_1900_1949",
+    "D": "1950_1966",
+    "E": "1967_1975",
+    "F": "1976_1982",
+    "G": "1983_1990",
+    "H": "1991_1995",
+    "I": "1996_2002",
+    "J": "after_2003",
+    "K": "after_2003",
+    "L": "after_2003",
+}
+
+
+
+
+def compute_glazing_area_vectorised(df: pd.DataFrame) -> pd.Series:
+    """
+    Memory-safe vectorised glazing area calculation.
+    """
+
+    # --- base masks ---
+    tfa = df["TOTAL_FLOOR_AREA"].astype(float)
+    valid = tfa.gt(0)
+
+    pt = df["PROPERTY_TYPE"].str.lower()
+    is_house = pt.isin(["house", "bungalow"])
+    is_flat  = pt.isin(["flat", "maisonette"])
+
+    glazing_group = df["sap_band_letter"].map(SAP_TO_GLAZING_GROUP)
+
+    # initialise result
+    glazing = np.full(len(df), np.nan, dtype="float64")
+
+    # --- compute for houses ---
+    for group, (a, b) in GLAZING_COEFFS["house"].items():
+        mask = valid & is_house & (glazing_group == group)
+        glazing[mask] = a * tfa[mask] + b
+
+    # --- compute for flats ---
+    for group, (a, b) in GLAZING_COEFFS["flat"].items():
+        mask = valid & is_flat & (glazing_group == group)
+        glazing[mask] = a * tfa[mask] + b
+
+    return pd.Series(glazing, index=df.index, name="glazing_area_m2")
+
+
+
+def classify_glazing_type_vectorised_sap(series: pd.Series) -> pd.Series:
+    """
+    SAP-compliant glazing classification.
+    Priority: Triple > High Performance > Double > Secondary > Single
+    Highest performance mentioned wins.
+    """
+
+    s = (
+        series
+        .fillna("")
+        .str.lower()
+        .str.replace(r"\s+", " ", regex=True)
+        .str.strip()
+    )
+
+    out = pd.Series(pd.NA, index=series.index, dtype="object")
+
+    # --- 0. Junk / undefined ---
+    junk = (
+        s.eq("")
+        | s.eq("fully")
+        | s.str.contains("unknown")
+        | s.str.contains("complex")
+        | s.str.contains("other premises")
+        | s.str.fullmatch(r"(mostly|some)")
+    )
+    out[junk] = pd.NA
+
+    # --- 1. TRIPLE ---
+    mask = (
+        s.str.contains("triple")
+        | s.str.contains("gwydrau triphlyg")
+    ) & out.isna()
+    out[mask] = "triple"
+
+    # --- 2. HIGH PERFORMANCE ---
+    mask = (
+        s.str.contains("high performance")
+        | s.str.contains("perfformiad uchel")
+    ) & out.isna()
+    out[mask] = "high_performance"
+
+    # --- 3. DOUBLE (includes multiple glazing) ---
+    mask = (
+        (
+            s.str.contains("double")
+            | s.str.contains("multiple")
+            | s.str.contains("gwydrau dwbl")
+        )
+        & out.isna()
+    )
+    out[mask] = "double"
+
+    # --- 4. SECONDARY ---
+    mask = s.str.contains("secondary") & out.isna()
+    out[mask] = "secondary"
+
+    # --- 5. SINGLE ---
+    mask = (
+        (
+            s.str.contains("single")
+            | s.str.contains("gwydrau sengl")
+        )
+        & out.isna()
+    )
+    out[mask] = "single"
+
+    return out
+
+
+def windows_feature_engineering_vectorised(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Apply construction age band and glazing area feature engineering
+    to the given dataframe, using vectorised operations.
+    """
+    df = df.copy()
+
+    df["glazing_area_m2"] = compute_glazing_area_vectorised(df)
+
+    df["glazing_type"] = classify_glazing_type_vectorised_sap(
+        df["WINDOWS_DESCRIPTION"]
+    )
+
+    return df

src/features/effici.egg-info/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: effici
+Version: 0.1.0
+Summary: Energy modeling & EPC features
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+---
+
+# Project Description
+
+This project automates building energy modeling with EnergyPlus: it modifies model parameters using eppy, runs simulations, and extracts energy consumption results from the SQL output using pandas.
+
+## Main Steps
+
+1. **IDF File Modification**
+   - Change building parameters (e.g. heating setpoint, wall conductivity).
+   - Add `Output:SQLite` and `Output:Meter` objects for required reports.
+
+2. **Run EnergyPlus Simulation**
+   - Use the modified IDF and weather data.
+
+3. **Result Analysis**
+   - Read the SQL output and extract annual electricity and gas consumption.
+
+## Requirements
+
+- Python 3.10+
+- EnergyPlus 25.1.0
+- eppy
+- pandas
+- sqlite3
+
+## Quick Start
+
+1. Install dependencies:
+2. Make sure EnergyPlus is installed and example/weather files are available.
+3. Run simulation preparation and execution:
+4. Analyze results:
+
+## Project Structure
+
+- `src/run_simulation.py` — prepares and runs the EnergyPlus simulation
+- `src/analyze_results.py` — analyzes results from the SQL output
+- `src/config.py` — project paths and parameters
+- `src/utils.py` — helper functions
+- `src/simulation_output/` — EnergyPlus output files
+- `src/test_building.idf` — modified EnergyPlus input file
+
+## Results
+
+The console displays the building's annual electricity and gas consumption (if gas is used in the model).

src/features/effici.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/features/construction_age_band_sap.py
+src/features/roofs.py
+src/features/walls.py
+src/features/effici.egg-info/PKG-INFO
+src/features/effici.egg-info/SOURCES.txt
+src/features/effici.egg-info/dependency_links.txt
+src/features/effici.egg-info/top_level.txt
+tests/test_analysis.py
+tests/test_simulation.py

src/features/effici.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

src/features/effici.egg-info/top_level.txt

@@ -0,0 +1,3 @@
+construction_age_band_sap
+roofs
+walls

src/features/energy_system.py

@@ -0,0 +1,603 @@
+import re
+import numpy as np
+import pandas as pd
+
+def classify_main_heating_system(text):
+    if text is None or not isinstance(text, str):
+        return "other"
+
+    t = text.lower()
+
+    if "community" in t:
+        return "community_heating"
+
+    if "heat pump" in t:
+        return "heat_pump"
+
+    if "boiler" in t:
+        return "boiler"
+
+    if "warm air" in t or "electricaire" in t:
+        return "warm_air"
+
+    if "storage heater" in t or "electric storage" in t:
+        return "storage_heater"
+
+    if "room heaters" in t:
+        return "room_heater"
+
+    if "electric" in t and "heater" in t:
+        return "direct_electric"
+
+    if "sap05" in t:
+        return "other"
+
+    return "other"
+
+
+def classify_secondary_heating(text):
+    if text is None or not isinstance(text, str):
+        return "none"
+
+    t = text.lower()
+
+    # --- explicit none / missing ---
+    if t in ["none", "dim"] or "no system" in t:
+        return "none"
+
+    # --- solid fuels ---
+    if any(x in t for x in [
+        "coal", "anthracite", "wood", "pellet", "chips", "smokeless"
+    ]):
+        return "solid_fuel"
+
+    # --- oil ---
+    if "oil" in t:
+        return "oil_room_heater"
+
+    # --- gas & LPG ---
+    if any(x in t for x in [
+        "mains gas", "lpg", "lng", "bottled gas"
+    ]):
+        return "gas_room_heater"
+
+    # --- electric ---
+    if "electric" in t:
+        return "direct_electric"
+
+    # --- SAP placeholders ---
+    if "sap05" in t:
+        return "other"
+
+    return "other"
+
+
+def classify_main_fuel_type(text):
+    """
+    Classify EPC MAINHEAT_DESCRIPTION into SAP-compatible main fuel types.
+    """
+
+    if text is None or not isinstance(text, str):
+        return "other"
+
+    t = text.lower()
+
+    # --- 1. Community heating ---
+    if "community" in t:
+        return "heat_network"
+
+    # --- 2. Heat pumps (always electricity in EPC) ---
+    if "heat pump" in t:
+        return "electricity"
+
+    # --- 3. Electricity ---
+    if any(x in t for x in [
+        "electric",
+        "electricaire",
+        "storage heater",
+        "electric underfloor",
+        "electric ceiling",
+    ]):
+        return "electricity"
+
+    # --- 4. Mains gas ---
+    if "mains gas" in t or "nwy prif" in t:
+        return "mains_gas"
+
+    # --- 5. LPG ---
+    if any(x in t for x in [
+        "lpg",
+        "bottled lpg",
+        "bottled gas",
+    ]):
+        return "lpg"
+
+    # --- 6. Oil ---
+    if "oil" in t:
+        return "oil"
+
+    # --- 7. Biomass ---
+    if any(x in t for x in [
+        "biomass",
+        "wood pellets",
+        "wood chips",
+    ]):
+        return "biomass"
+
+    # --- 8. Solid fuels ---
+    if any(x in t for x in [
+        "coal",
+        "anthracite",
+        "smokeless",
+        "wood logs",
+        "dual fuel",
+    ]):
+        return "solid_fuel"
+
+    return "other"
+
+
+
+def classify_dhw_system(text):
+    """
+    Classify EPC HOTWATER_DESCRIPTION into SAP / ML compatible DHW system types.
+    """
+
+    if text is None or not isinstance(text, str):
+        return "other"
+
+    t = text.lower()
+
+    # --- SAP placeholders / missing ---
+    if "sap05" in t or "no system present" in t:
+        return "other"
+
+    # --- Community DHW ---
+    if "community" in t:
+        return "community"
+
+    # --- Heat pump DHW ---
+    if "heat pump" in t:
+        return "heat_pump"
+
+    # --- Solar-assisted DHW ---
+    # (still fundamentally main heating or immersion, but solar flag dominates)
+    if "solar" in t:
+        return "solar_assisted"
+
+    # --- Gas instantaneous / multipoint ---
+    if any(x in t for x in [
+        "gas instantaneous",
+        "gas multipoint",
+        "single-point gas",
+    ]):
+        return "gas_instantaneous"
+
+    # --- Electric instantaneous (point of use) ---
+    if "electric instantaneous" in t:
+        return "direct_electric"
+
+    # --- Electric immersion (storage) ---
+    if "electric immersion" in t:
+        return "electric_storage"
+
+    # --- From main / secondary heating system ---
+    if any(x in t for x in [
+        "from main system",
+        "from secondary system",
+        "boiler/circulator",
+        "range cooker",
+        "o'r brif system",
+        "og’r brif system",
+        "second main heating system",
+    ]):
+        return "main_heating"
+
+    return "other"
+
+
+def classify_ventilation_system(text):
+    """
+    SAP / RdSAP 2012 ventilation system classification.
+    """
+
+    if text is None or not isinstance(text, str):
+        return "natural"
+
+    t = text.lower()
+
+    if "heat recovery" in t or "mvhr" in t:
+        return "mvhr"
+
+    if "positive input" in t:
+        return "piv"
+
+    if "supply and extract" in t:
+        return "mech_supply_extract"
+
+    if "extract" in t:
+        return "mech_extract"
+
+    if "mechanical" in t:
+        return "mech_extract"
+
+    # includes 'natural' and 'NO DATA!'
+    return "natural"
+
+
+def extract_low_energy_lighting_fraction(text):
+    """
+    Extract fraction of low-energy lighting from EPC LIGHTING_DESCRIPTION.
+    Returns float in [0,1] or None if unknown.
+    """
+
+    if text is None or not isinstance(text, str):
+        return None
+
+    t = text.lower()
+
+    # --- Explicit none ---
+    if "no low energy lighting" in t:
+        return 0.0
+
+    # --- All outlets ---
+    if "all fixed outlets" in t or "ym mhob" in t:
+        return 1.0
+
+    # --- Percentage extraction (robust) ---
+    m = re.search(r"(\d+(\.\d+)?)\s*%", t)
+    if m:
+        pct = float(m.group(1))
+        return max(0.0, min(pct / 100.0, 1.0))
+
+    # --- Qualitative EPC fallbacks ---
+    if "excellent lighting efficiency" in t or "excelent lighting efficiency" in t:
+        return 1.0
+
+    if "good lighting efficiency" in t:
+        return 0.8
+
+    if "below average lighting efficiency" in t:
+        return 0.2
+
+    # --- SAP placeholders ---
+    if "sap05" in t:
+        return None
+
+    return None
+
+
+def estimate_pv_kwp_from_row(row):
+    """
+    Estimate installed PV capacity (kWp) from a single EPC row
+    using SAP S11(b)-compliant logic.
+
+    Required EPC fields in `row`:
+      - TOTAL_FLOOR_AREA
+      - PROPERTY_TYPE
+      - PHOTO_SUPPLY
+      - FLAT_STOREY_COUNT
+      - ROOF_DESCRIPTION
+    """
+
+    # -------------------------------
+    # 0. Guard clauses
+    # -------------------------------
+    tfa = row.get("TOTAL_FLOOR_AREA")
+    photo_supply = row.get("PHOTO_SUPPLY")
+
+    if (
+        tfa is None or
+        photo_supply is None or
+        tfa <= 0 or
+        photo_supply <= 0
+    ):
+        return 0.0
+
+    property_type = str(row.get("PROPERTY_TYPE", "")).lower()
+    roof_desc = str(row.get("ROOF_DESCRIPTION", "")).lower()
+
+    # -------------------------------
+    # 1. Horizontal roof projection
+    # -------------------------------
+    if property_type == "flat":
+        storeys = row.get("FLAT_STOREY_COUNT")
+        if storeys is None or storeys <= 0:
+            return 0.0  # cannot apportion roof vertically
+        roof_projection = tfa / storeys
+    else:
+        # House, bungalow, maisonette
+        roof_projection = tfa / 2.0
+
+    # -------------------------------
+    # 2. Roof pitch inference (geometry only)
+    # -------------------------------
+    if "flat" in roof_desc:
+        roof_is_pitched = False
+    elif any(x in roof_desc for x in ["pitched", "rafters", "roof room"]):
+        roof_is_pitched = True
+    else:
+        # fallback by property type
+        roof_is_pitched = property_type in ["house", "bungalow", "maisonette"]
+
+    pitch_factor = (
+        1.0 / np.cos(np.deg2rad(35))
+        if roof_is_pitched
+        else 1.0
+    )
+
+    # -------------------------------
+    # 3. PV-covered area (SAP S11)
+    # -------------------------------
+    pv_area = (
+        roof_projection
+        * (photo_supply / 100.0)
+        * pitch_factor
+    )
+
+    # -------------------------------
+    # 4. Convert area → capacity
+    # -------------------------------
+    pv_kwp = 0.12 * pv_area
+
+    return pv_kwp
+
+
+def energy_system_feature_engineering(df):
+
+    df = df.copy()
+    df["MAIN_HEATING_SYSTEM"] = df["MAINHEAT_DESCRIPTION"].apply(classify_main_heating_system)
+    df["SECONDARY_HEATING_SYSTEM"] = df["SECONDHEAT_DESCRIPTION"].apply(classify_secondary_heating)
+    df["MAIN_FUEL_TYPE"] = df["MAINHEAT_DESCRIPTION"].apply(classify_main_fuel_type)
+    df["DHW_SUPPLY_SYSTEM"] = df["HOTWATER_DESCRIPTION"].apply(classify_dhw_system)
+    df["VENTILATION_SYSTEM"] = df["MECHANICAL_VENTILATION"].apply(classify_ventilation_system)
+    df["LIGHTENING_TYPE"] = df["LIGHTING_DESCRIPTION"].apply(extract_low_energy_lighting_fraction)
+    df["PV_KWP"] = df.apply(estimate_pv_kwp_from_row, axis=1)
+
+    return df
+
+
+def classify_main_heating_system_vectorised(series: pd.Series) -> pd.Series:
+    s = series.fillna("").str.lower()
+
+    out = pd.Series("other", index=s.index)
+
+    # IMPORTANT: apply in the SAME ORDER as scalar version
+    mask = out.eq("other") & s.str.contains("community")
+    out[mask] = "community_heating"
+
+    mask = out.eq("other") & s.str.contains("heat pump")
+    out[mask] = "heat_pump"
+
+    mask = out.eq("other") & s.str.contains("boiler")
+    out[mask] = "boiler"
+
+    mask = out.eq("other") & s.str.contains("warm air|electricaire")
+    out[mask] = "warm_air"
+
+    mask = out.eq("other") & s.str.contains("storage heater|electric storage")
+    out[mask] = "storage_heater"
+
+    mask = out.eq("other") & s.str.contains("room heaters")
+    out[mask] = "room_heater"
+
+    mask = out.eq("other") & s.str.contains("electric") & s.str.contains("heater")
+    out[mask] = "direct_electric"
+
+    # sap05 and everything else remain "other"
+    return out
+
+
+def classify_secondary_heating_vectorised(series: pd.Series) -> pd.Series:
+    s = series.fillna("").str.lower().str.strip()
+
+    # SAP default: no secondary heating
+    out = pd.Series("none", index=s.index)
+
+    # Solid fuels (incl. bioethanol, B30K)
+    mask = out.eq("none") & s.str.contains(
+        r"coal|anthracite|wood|pellet|chips|smokeless|bioethanol|b30k"
+    )
+    out[mask] = "solid_fuel"
+
+    # Oil
+    mask = out.eq("none") & s.str.contains("oil")
+    out[mask] = "oil_room_heater"
+
+    # Gas & LPG (English + Welsh)
+    mask = out.eq("none") & s.str.contains(
+        r"mains gas|lpg|lng|bottled gas|nwy prif"
+    )
+    out[mask] = "gas_room_heater"
+
+    # Electric
+    mask = out.eq("none") & s.str.contains("electric")
+    out[mask] = "direct_electric"
+
+    # Everything else stays "none" by design
+    return out
+
+
+def classify_main_fuel_type_vectorised(series: pd.Series) -> pd.Series:
+    s = series.fillna("").str.lower()
+
+    out = pd.Series("other", index=s.index)
+
+    # 1. Community heating (highest priority)
+    m = s.str.contains("community")
+    out[m] = "heat_network"
+
+    # 2. Heat pumps → electricity
+    m = s.str.contains("heat pump") & (out == "other")
+    out[m] = "electricity"
+
+    # 3. Electricity (direct / storage / underfloor)
+    m = s.str.contains(
+        "electric|electricaire|storage heater|electric underfloor|electric ceiling"
+    ) & (out == "other")
+    out[m] = "electricity"
+
+    # 4. Mains gas
+    m = s.str.contains("mains gas|nwy prif") & (out == "other")
+    out[m] = "mains_gas"
+
+    # 5. LPG
+    m = s.str.contains("lpg|bottled lpg|bottled gas") & (out == "other")
+    out[m] = "lpg"
+
+    # 6. Oil
+    m = s.str.contains("oil") & (out == "other")
+    out[m] = "oil"
+
+    # 7. Biomass
+    m = s.str.contains("biomass|wood pellets|wood chips") & (out == "other")
+    out[m] = "biomass"
+
+    # 8. Solid fuels
+    m = s.str.contains("coal|anthracite|smokeless|wood logs|dual fuel") & (out == "other")
+    out[m] = "solid_fuel"
+
+    return out
+
+
+def classify_dhw_system_vectorised(series: pd.Series) -> pd.Series:
+    s = series.fillna("").str.lower()
+
+    out = pd.Series("other", index=s.index)
+
+    # 0. SAP placeholders / missing
+    m = s.str.contains("sap05|no system present")
+    out[m] = "other"
+
+    # 1. Community DHW
+    m = s.str.contains("community") & (out == "other")
+    out[m] = "community"
+
+    # 2. Heat pump DHW
+    m = s.str.contains("heat pump") & (out == "other")
+    out[m] = "heat_pump"
+
+    # 3. Solar-assisted DHW (dominant flag)
+    m = s.str.contains("solar") & (out == "other")
+    out[m] = "solar_assisted"
+
+    # 4. Gas instantaneous / multipoint
+    m = s.str.contains(
+        "gas instantaneous|gas multipoint|single-point gas"
+    ) & (out == "other")
+    out[m] = "gas_instantaneous"
+
+    # 5. Electric instantaneous (point-of-use)
+    m = s.str.contains("electric instantaneous") & (out == "other")
+    out[m] = "direct_electric"
+
+    # 6. Electric immersion (storage)
+    m = s.str.contains("electric immersion") & (out == "other")
+    out[m] = "electric_storage"
+
+    # 7. From main / secondary heating system (fallback)
+    m = s.str.contains(
+        "from main system|from secondary system|boiler/circulator|range cooker|"
+        "o'r brif system|og’r brif system|second main heating system"
+    ) & (out == "other")
+    out[m] = "main_heating"
+
+    return out
+
+
+def classify_ventilation_system_vectorised(series: pd.Series) -> pd.Series:
+    s = series.fillna("").str.lower()
+
+    out = pd.Series("natural", index=s.index)
+
+    # 1. MVHR (explicit, must exclude "without heat recovery")
+    m = (
+        (
+            s.str.contains("mvhr") |
+            (s.str.contains("heat recovery") & ~s.str.contains("without heat recovery"))
+        )
+        & (out == "natural")
+    )
+    out[m] = "mvhr"
+
+    # 2. Positive input ventilation
+    m = s.str.contains("positive input") & (out == "natural")
+    out[m] = "piv"
+
+    # 3. Mechanical supply & extract
+    m = s.str.contains("supply and extract") & (out == "natural")
+    out[m] = "mech_supply_extract"
+
+    # 4. Mechanical extract (fallback)
+    m = s.str.contains("extract|mechanical") & (out == "natural")
+    out[m] = "mech_extract"
+
+    return out
+
+
+def extract_low_energy_lighting_fraction_vectorised(series: pd.Series) -> pd.Series:
+    s = series.fillna("").str.lower()
+
+    out = pd.Series(np.nan, index=s.index)
+
+    # Explicit none
+    out[s.str.contains("no low energy lighting")] = 0.0
+
+    # All outlets
+    out[s.str.contains("all fixed outlets|ym mhob")] = 1.0
+
+    # Qualitative descriptors (handle misspelling)
+    out[s.str.contains("excellent lighting efficiency|excelent lighting efficiency")] = 1.0
+    out[s.str.contains("good lighting efficiency")] = 0.8
+    out[s.str.contains("below average lighting efficiency")] = 0.2
+
+    # Percentage extraction (overrides qualitative if present)
+    pct = s.str.extract(r"(\d+(?:\.\d+)?)\s*%", expand=False).astype(float)
+    out[pct.notna()] = (pct / 100).clip(0, 1)
+
+    return out
+
+
+def estimate_pv_kwp_vectorised(df: pd.DataFrame) -> pd.Series:
+    tfa = df["TOTAL_FLOOR_AREA"]
+    photo = df["PHOTO_SUPPLY"]
+
+    valid = (tfa > 0) & (photo > 0)
+
+    property_type = df["PROPERTY_TYPE"].fillna("").str.lower()
+    roof_desc = df["ROOF_DESCRIPTION"].fillna("").str.lower()
+
+    roof_projection = pd.Series(0.0, index=df.index)
+
+    # Flats
+    flats = property_type.eq("flat")
+    roof_projection[flats] = tfa[flats] / df.loc[flats, "FLAT_STOREY_COUNT"].replace(0, np.nan)
+
+    # Houses / bungalows / maisonettes
+    roof_projection[~flats] = tfa[~flats] / 2.0
+
+    roof_is_pitched = (
+        roof_desc.str.contains("pitched|rafters|roof room") |
+        (~roof_desc.str.contains("flat") & property_type.isin(["house", "bungalow", "maisonette"]))
+    )
+
+    pitch_factor = np.where(roof_is_pitched, 1 / np.cos(np.deg2rad(35)), 1.0)
+
+    pv_area = roof_projection * (photo / 100.0) * pitch_factor
+    pv_kwp = 0.12 * pv_area
+
+    return pv_kwp.where(valid, 0.0).fillna(0.0)
+
+
+def energy_system_feature_engineering_vectorised(df: pd.DataFrame) -> pd.DataFrame:
+    df = df.copy()
+
+    df["MAIN_HEATING_SYSTEM"] = classify_main_heating_system_vectorised(df["MAINHEAT_DESCRIPTION"])
+    df["SECONDARY_HEATING_SYSTEM"] = classify_secondary_heating_vectorised(df["SECONDHEAT_DESCRIPTION"])
+    df["MAIN_FUEL_TYPE"] = classify_main_fuel_type_vectorised(df["MAINHEAT_DESCRIPTION"])
+    df["DHW_SUPPLY_SYSTEM"] = classify_dhw_system_vectorised(df["HOTWATER_DESCRIPTION"])
+    df["VENTILATION_SYSTEM"] = classify_ventilation_system_vectorised(df["MECHANICAL_VENTILATION"])
+    df["LIGHTING_FRACTION_LOW_ENERGY"] = extract_low_energy_lighting_fraction_vectorised(df["LIGHTING_DESCRIPTION"])
+    df["PV_KWP"] = estimate_pv_kwp_vectorised(df)
+
+    return df

src/features/floor.py

@@ -0,0 +1,818 @@
+from __future__ import annotations
+import math
+import pandas as pd
+import re
+import math
+from functools import lru_cache
+from typing import Optional, Tuple
+
+import numpy as np
+import pandas as pd
+
+
+def extract_mm(text):
+    if pd.isna(text):
+        return None
+    m = re.findall(r"(\d+)\s*mm", str(text).lower())
+    return int(m[0]) if m else None
+
+
+def extract_measured_u(text):
+    if pd.isna(text):
+        return None
+    t = str(text).lower()
+    if "average thermal transmittance" not in t:
+        return None
+    nums = re.findall(r"([0-9]*\.?[0-9]+)", t)
+    if not nums:
+        return None
+    u = float(nums[0])
+    return None if u < 0.05 else u  # treat 0.00 etc. as missing
+
+
+def floor_ins_thickness_s11(sap_band_letter):
+    # From Table S11 (England & Wales column)
+    # A,B,C,D,E,F: none; G: 25; H: 75; I:100; J:100; K:100; L:100
+    m = {
+        "A": 0, "B": 0,
+        "C": 0, "D": 0, "E": 0, "F": 0,
+        "G": 0,
+        "H": 0,
+        "I": 25,
+        "J": 75,
+        "K": 100,
+        "L": 100,
+    }
+    return m.get(sap_band_letter, 0)
+
+
+def estimate_B(a, p = None):
+    if p is None:
+        return 0.5 * math.sqrt(a)
+    else:
+        return 2 * a/p
+
+
+def classify_floor_boundary(desc):
+    if pd.isna(desc):
+        return "ground"
+
+    t = str(desc).lower()
+
+    # --- 1. Measured U-value always wins ---
+    if "average thermal transmittance" in t:
+        return "measured_u_value"
+
+    # --- 2. No heat loss ---
+    if any(x in t for x in [
+        "another dwelling below",
+        "other premises below",
+        "same dwelling below",
+        "eiddo arall islaw"
+    ]):
+        return "another_dwelling_below"
+
+    # --- 3. Partially heated space below (S5.7) ---
+    if "partially heated" in t:
+        return "partially_heated_below"
+
+    # --- 4. Exposed to outside air (S5.6) ---
+    if "to external air" in t or "external air" in t:
+        return "exposed"
+
+    # --- 5. Semi-exposed: unheated enclosed space (S5.6) ---
+    if "to unheated space" in t or "unheated space" in t or "garage" in t:
+        return "semi_exposed"
+
+    # --- 6. Default: ground floor (S5.5) ---
+    return "ground"
+
+
+
+def effective_floor_insulation_mm(desc, sap_band_letter):
+    """
+    SAP S11 rule:
+    - if retrofitted insulation → max(50 mm, table value)
+    - otherwise → table value
+    """
+    base_mm = floor_ins_thickness_s11(sap_band_letter)
+    t = str(desc).lower()
+
+    if "insulated" in t:
+        return max(50, base_mm)
+
+    return base_mm
+
+
+def classify_wall_type_s3(desc: str) -> str:
+    if desc is None or not isinstance(desc, str):
+        return "solid brick"  # safe SAP fallback
+
+    t = desc.lower()
+
+    # --- Welsh solid brick ---
+    if "briciau solet" in t:
+        return "solid brick"
+
+    # --- Stone / solid masonry ---
+    if any(x in t for x in [
+        "stone",
+        "sandstone",
+        "limestone",
+        "granite",
+        "whinstone",
+        "whin",
+    ]):
+        return "stone"
+
+    # --- Cob ---
+    if "cob" in t:
+        return "cob"
+
+    # --- Solid brick ---
+    if "solid brick" in t:
+        return "solid brick"
+
+    # --- Cavity ---
+    if "cavity" in t:
+        return "cavity"
+
+    # --- Timber frame ---
+    if "timber frame" in t:
+        return "timber frame"
+
+    # --- System build ---
+    if "system built" in t:
+        return "system build"
+
+    # --- Park home ---
+    if "park home" in t:
+        return "park home"
+
+    # --- Basement walls (SAP treats as solid masonry) ---
+    if "basement wall" in t:
+        return "stone"
+
+    # --- Fallback (SAP-safe) ---
+    return "solid brick"
+
+
+def w_look_up_s3(desc, sap_band_letter, s3):
+    wall_type = classify_wall_type_s3(desc)
+
+    row = s3[
+        (s3["Wall Type"] == wall_type) &
+        (s3["sap_band"] == sap_band_letter)
+    ]
+
+    if row.empty:
+        raise ValueError(
+            f"No S3 wall thickness for wall_type={wall_type}, age={sap_band_letter}"
+        )
+
+    return float(row["thickness_mm"].iloc[0])/ 1000.0
+
+
+
+
+# ---------- S5.5 solid ground floor ----------
+def u_solid_ground_floor(
+    desc_floor,
+    desc_wall,
+    area,
+    sap_band_letter,
+    s3,
+    p=None,
+    lg=1.5
+):
+    """
+    SAP RdSAP 2012 S5.5 – Solid ground floor (ISO 13370)
+    """
+
+    Rsi = 0.17
+    Rse = 0.04
+
+    # wall thickness from Table S3
+    w = w_look_up_s3(desc_wall, sap_band_letter, s3)
+
+    # insulation thickness
+    dins_mm = effective_floor_insulation_mm(desc_floor, sap_band_letter)
+    Rf = 0.001 * dins_mm / 0.035 if dins_mm > 0 else 0.0
+
+    dt = w + lg * (Rsi + Rf + Rse)
+
+    # geometric factor
+    if p is None:
+        # assume square plan: P = 4√A → B = √A / 2
+        B = math.sqrt(area) / 2
+    else:
+        B = 2 * area / p
+
+    if dt < B:
+        return (2 * lg * math.log(math.pi * B / dt + 1.0)) / (math.pi * B + dt)
+    else:
+        return lg / (0.457 * B + dt)
+
+
+def u_suspended_ground_floor(
+    desc_floor,
+    desc_wall,
+    area,
+    sap_band_letter,
+    s3,
+    p=None,
+    lg=1.5
+):
+    """
+    SAP RdSAP 2012 S5.5 – Suspended ground floor
+    """
+
+    Rsi = 0.17
+    Uw = 1.5
+    h = 0.3
+    v = 5.0
+    fw = 0.05
+    e = 0.003
+
+    # wall thickness from S3
+    w = w_look_up_s3(desc_wall, sap_band_letter, s3)
+
+    # insulation resistance
+    dins_mm = effective_floor_insulation_mm(desc_floor, sap_band_letter)
+    if dins_mm > 0:
+        Rf = (0.001 * dins_mm / 0.035) + 0.2
+    else:
+        Rf = 0.2
+
+    dg = w + lg * (Rsi + 0.04)
+
+    # geometry
+    if p is None:
+        B = math.sqrt(area) / 2
+    else:
+        B = 2 * area / p
+
+    Ug = (2 * lg * math.log(math.pi * B / dg + 1.0)) / (math.pi * B + dg)
+
+    Ux = (2 * h * Uw / B) + (1450 * e * v * fw / B)
+
+    return 1.0 / (2 * Rsi + Rf + 1.0 / (Ug + Ux))
+
+
+def bin_floor_insulation_s12(desc, mm):
+    """
+    SAP RdSAP 2012 Table S12 insulation binning.
+    Used ONLY for exposed / semi-exposed floors.
+    """
+
+    t = str(desc).lower()
+
+    # Explicitly uninsulated
+    if "no insulation" in t or "uninsulated" in t or "average thermal transmittance" in t:
+        return "as_built"
+
+
+    # Measured thickness → bin
+    if mm is not None:
+        if mm >= 150:
+            return "150mm"
+        elif mm >= 100:
+            return "100mm"
+        elif mm >= 50:
+            return "50mm"
+        else:
+            return "as_built"
+
+    # Insulated but unknown thickness
+    if "insulated" in t:
+        return "50mm"
+
+    # Default
+    return "as_built"
+
+
+def lookup_s12_u_value(sap_band_letter, insulation_class):
+    """
+    SAP RdSAP 2012 Table S12 (England & Wales).
+    """
+
+    table = {
+        # A–G
+        "A": {"as_built": 1.20, "50mm": 0.50, "100mm": 0.30, "150mm": 0.22},
+        "B": {"as_built": 1.20, "50mm": 0.50, "100mm": 0.30, "150mm": 0.22},
+        "C": {"as_built": 1.20, "50mm": 0.50, "100mm": 0.30, "150mm": 0.22},
+        "D": {"as_built": 1.20, "50mm": 0.50, "100mm": 0.30, "150mm": 0.22},
+        "E": {"as_built": 1.20, "50mm": 0.50, "100mm": 0.30, "150mm": 0.22},
+        "F": {"as_built": 1.20, "50mm": 0.50, "100mm": 0.30, "150mm": 0.22},
+        "G": {"as_built": 1.20, "50mm": 0.50, "100mm": 0.30, "150mm": 0.22},
+
+        # H–I
+        "H": {"as_built": 0.51, "50mm": 0.50, "100mm": 0.30, "150mm": 0.22},
+        "I": {"as_built": 0.51, "50mm": 0.50, "100mm": 0.30, "150mm": 0.22},
+
+        # J
+        "J": {"as_built": 0.25, "50mm": 0.25, "100mm": 0.25, "150mm": 0.22},
+
+        # K
+        "K": {"as_built": 0.22, "50mm": 0.22, "100mm": 0.22, "150mm": 0.22},
+
+        # L
+        "L": {"as_built": 0.22, "50mm": 0.22, "100mm": 0.22, "150mm": 0.22},
+    }
+
+    return table[sap_band_letter][insulation_class]
+
+
+
+def floor_u_value_s12(desc, sap_band_letter):
+    """
+    SAP RdSAP 2012 S5.6 – Exposed / Semi-exposed floors
+    Uses Table S12 only.
+    """
+
+    mm = extract_mm(desc)
+    ins_class = bin_floor_insulation_s12(desc, mm)
+
+    return lookup_s12_u_value(sap_band_letter, ins_class)
+
+
+
+def floors_u_rule(row,s3):
+
+    boundary = classify_floor_boundary(row["FLOOR_DESCRIPTION"])
+    if boundary == "another_dwelling_below":
+        return 0.0
+    if boundary == "partially_heated_below":
+        return 0.7
+    if boundary in ["exposed", "semi_exposed"]:
+        return floor_u_value_s12(
+            desc = row["FLOOR_DESCRIPTION"],
+            sap_band_letter=row["sap_band_letter"]
+        )
+    if boundary == "ground":
+        if "suspended" in str(row["FLOOR_DESCRIPTION"]).lower():
+            return u_suspended_ground_floor(
+                desc_floor=row["FLOOR_DESCRIPTION"],
+                desc_wall=row["WALLS_DESCRIPTION"],
+                area=row["TOTAL_FLOOR_AREA"],
+                sap_band_letter=row["sap_band_letter"],
+                s3=s3
+            )
+        else:
+            return u_solid_ground_floor(
+                desc_floor=row["FLOOR_DESCRIPTION"],
+                desc_wall=row["WALLS_DESCRIPTION"],
+                area=row["TOTAL_FLOOR_AREA"],
+                sap_band_letter=row["sap_band_letter"],
+                s3=s3
+            )
+    if boundary == "measured_u_value":
+        return extract_measured_u(row["FLOOR_DESCRIPTION"])
+    return None
+
+
+def floors_insulation_type(row):
+    mm = extract_mm(row["FLOOR_DESCRIPTION"])
+    desc = row["FLOOR_DESCRIPTION"]
+    return bin_floor_insulation_s12(desc,mm)
+
+
+def floor_feature_engineering(df: pd.DataFrame, s3: pd.DataFrame) -> pd.DataFrame:
+    df = df.copy()
+
+    df["FLOOR_U_VALUE"] = df.apply(lambda row: floors_u_rule(row,s3), axis=1)
+    df["FLOOR_INSULATION_TYPE"] = df.apply(floors_insulation_type, axis=1)
+    df["FLOOR_BOUNDARY_TYPE"] = df["FLOOR_DESCRIPTION"].apply(classify_floor_boundary)
+
+    return df
+
+
+# ============================================================
+# FAST + PHYSICS-PRESERVING FLOOR FEATURE ENGINEERING
+# (no area binning; caches SAP-dependent parameters; vectorized math)
+# ============================================================
+
+
+# -----------------------------
+# Helpers: parsing (vectorized)
+# -----------------------------
+_MM_RE = re.compile(r"(\d+)\s*mm", flags=re.IGNORECASE)
+_U_RE = re.compile(r"([0-9]*\.?[0-9]+)", flags=re.IGNORECASE)
+
+def extract_mm_vectorised(series: pd.Series) -> pd.Series:
+    """Extract first '<int> mm' -> float mm; else NaN."""
+    s = series.fillna("").astype(str).str.lower()
+    mm = s.str.extract(r"(\d+)\s*mm", expand=False)
+    return pd.to_numeric(mm, errors="coerce")
+
+
+def extract_measured_u_vectorised(series: pd.Series) -> pd.Series:
+    """
+    Robust vectorized extraction of measured floor U-values from EPC text.
+    Handles '=', ':', encoding junk, and keeps small non-zero values.
+    """
+
+    s = (
+        series.fillna("")
+        .astype(str)
+        .str.lower()
+        .str.replace("¦", "", regex=False)
+        .str.replace("?", "", regex=False)
+        .str.replace(",", ".", regex=False)
+    )
+
+    mask = s.str.contains("average thermal transmittance")
+
+    # Allow '=', ':' or whitespace before number
+    num = s.where(mask).str.extract(
+        r"average thermal transmittance\s*[:=]?\s*([0-9]*\.?[0-9]+)",
+        expand=False
+    )
+
+    u = pd.to_numeric(num, errors="coerce")
+
+    # Only treat true placeholders as missing
+    u = u.where(~(u.abs() < 1e-9), np.nan)
+
+    return u
+
+
+
+def classify_floor_boundary_vectorised(floor_desc: pd.Series) -> pd.Series:
+    """
+    Vectorized boundary classification.
+    """
+    s = floor_desc.fillna("").astype(str).str.lower()
+
+    out = pd.Series("ground", index=floor_desc.index, dtype="object")
+
+    # 1) measured U wins
+    measured = s.str.contains("average thermal transmittance")
+    out[measured] = "measured_u_value"
+
+    # 2) no heat loss: another dwelling below
+    below = s.str.contains(
+        "another dwelling below|other premises below|same dwelling below|eiddo arall islaw"
+    )
+    out[below & ~measured] = "another_dwelling_below"
+
+    # 3) partially heated
+    ph = s.str.contains("partially heated")
+    out[ph & ~measured & ~below] = "partially_heated_below"
+
+    # 4) exposed
+    exposed = s.str.contains(r"to external air|external air")
+    out[exposed & ~measured & ~below & ~ph] = "exposed"
+
+    # 5) semi-exposed
+    semi = s.str.contains(r"to unheated space|unheated space|garage")
+    out[semi & ~measured & ~below & ~ph & ~exposed] = "semi_exposed"
+
+    # default already ground
+    return out
+
+
+# -----------------------------------------
+# SAP S11: base insulation thickness by band
+# -----------------------------------------
+_S11_BASE_MM = {
+    "A": 0, "B": 0, "C": 0, "D": 0, "E": 0, "F": 0, "G": 0,
+    "H": 0,
+    "I": 25,
+    "J": 75,
+    "K": 100,
+    "L": 100,
+}
+
+def effective_floor_insulation_mm_vectorised(floor_desc: pd.Series, sap_band_letter: pd.Series) -> pd.Series:
+    """
+    SAP S11 rule:
+      - base_mm from S11 map
+      - if 'insulated' in description => max(50, base_mm)
+    Returns float mm.
+    """
+    band = sap_band_letter.fillna("").astype(str).str.strip().str.upper()
+    base = band.map(_S11_BASE_MM).fillna(0).astype(float)
+
+    s = floor_desc.fillna("").astype(str).str.lower()
+    insulated = s.str.contains("insulated")
+    eff = base.copy()
+    eff[insulated] = np.maximum(50.0, base[insulated])
+    return eff
+
+
+# -----------------------------
+# Wall type for S3 thickness map
+# (SAP-safe categorization)
+# -----------------------------
+def classify_wall_type_s3_vectorised(walls_desc: pd.Series) -> pd.Series:
+    s = walls_desc.fillna("").astype(str).str.lower()
+
+    out = pd.Series("solid brick", index=walls_desc.index, dtype="object")
+
+    out[s.str.contains("briciau solet")] = "solid brick"
+
+    stone = s.str.contains("stone|sandstone|limestone|granite|whinstone|\\bwhin\\b")
+    out[stone] = "stone"
+
+    out[s.str.contains("cob")] = "cob"
+    out[s.str.contains("solid brick")] = "solid brick"
+    out[s.str.contains("cavity")] = "cavity"
+    out[s.str.contains("timber frame")] = "timber frame"
+    out[s.str.contains("system built")] = "system build"
+    out[s.str.contains("park home")] = "park home"
+    out[s.str.contains("basement wall")] = "stone"
+
+    return out
+
+
+# -----------------------------
+# Table S12 lookup (fast dict)
+# -----------------------------
+_S12_TABLE = {
+    # A–G
+    "A": {"as_built": 1.20, "50mm": 0.50, "100mm": 0.30, "150mm": 0.22},
+    "B": {"as_built": 1.20, "50mm": 0.50, "100mm": 0.30, "150mm": 0.22},
+    "C": {"as_built": 1.20, "50mm": 0.50, "100mm": 0.30, "150mm": 0.22},
+    "D": {"as_built": 1.20, "50mm": 0.50, "100mm": 0.30, "150mm": 0.22},
+    "E": {"as_built": 1.20, "50mm": 0.50, "100mm": 0.30, "150mm": 0.22},
+    "F": {"as_built": 1.20, "50mm": 0.50, "100mm": 0.30, "150mm": 0.22},
+    "G": {"as_built": 1.20, "50mm": 0.50, "100mm": 0.30, "150mm": 0.22},
+    # H–I
+    "H": {"as_built": 0.51, "50mm": 0.50, "100mm": 0.30, "150mm": 0.22},
+    "I": {"as_built": 0.51, "50mm": 0.50, "100mm": 0.30, "150mm": 0.22},
+    # J
+    "J": {"as_built": 0.25, "50mm": 0.25, "100mm": 0.25, "150mm": 0.22},
+    # K–L
+    "K": {"as_built": 0.22, "50mm": 0.22, "100mm": 0.22, "150mm": 0.22},
+    "L": {"as_built": 0.22, "50mm": 0.22, "100mm": 0.22, "150mm": 0.22},
+}
+
+def bin_floor_insulation_s12_vectorised(floor_desc: pd.Series, mm_measured: pd.Series) -> pd.Series:
+    """
+    SAP RdSAP Table S12 binning (for exposed/semi-exposed).
+    Returns class: as_built, 50mm, 100mm, 150mm
+    """
+    s = floor_desc.fillna("").astype(str).str.lower()
+
+    # start as as_built
+    out = pd.Series("as_built", index=floor_desc.index, dtype="object")
+
+    explicit_unins = s.str.contains("no insulation|uninsulated|average thermal transmittance")
+    out[explicit_unins] = "as_built"
+
+    # measured thickness bins
+    mm = mm_measured
+    out[(mm >= 50) & (mm < 100) & ~explicit_unins] = "50mm"
+    out[(mm >= 100) & (mm < 150) & ~explicit_unins] = "100mm"
+    out[(mm >= 150) & ~explicit_unins] = "150mm"
+
+    # insulated but unknown thickness -> assume 50mm
+    insulated_unknown = s.str.contains("insulated") & mm.isna() & ~explicit_unins
+    out[insulated_unknown] = "50mm"
+
+    return out
+
+def lookup_s12_u_vectorised(sap_band_letter: pd.Series, ins_class: pd.Series) -> pd.Series:
+    band = sap_band_letter.fillna("").astype(str).str.strip().str.upper()
+    # map (band, class) -> value via dict of dicts
+    # faster: create a combined key
+    keys = list(_S12_TABLE.keys())
+    # We'll do row-wise via small map, but without apply on full DF:
+    # Convert to numpy and loop in Python is OK here because only exposed/semi_exposed subset is used.
+    out = np.full(len(band), np.nan, dtype=float)
+    b = band.to_numpy()
+    c = ins_class.to_numpy()
+
+    for i in range(len(out)):
+        bi = b[i]
+        ci = c[i]
+        if bi in _S12_TABLE and ci in _S12_TABLE[bi]:
+            out[i] = _S12_TABLE[bi][ci]
+    return pd.Series(out, index=sap_band_letter.index)
+
+
+# -----------------------------
+# S3 thickness mapping (prebuilt)
+# -----------------------------
+def build_s3_thickness_map(s3: pd.DataFrame) -> dict[tuple[str, str], float]:
+    """
+    Expect s3 columns: ['Wall Type','sap_band','thickness_mm'].
+    Returns meters.
+    """
+    tmp = s3.copy()
+    tmp["Wall Type"] = tmp["Wall Type"].astype(str).str.strip().str.lower()
+    tmp["sap_band"] = tmp["sap_band"].astype(str).str.strip().str.upper()
+    # meters
+    tmp["thickness_m"] = tmp["thickness_mm"].astype(float) / 1000.0
+    return {(r["Wall Type"], r["sap_band"]): r["thickness_m"] for _, r in tmp.iterrows()}
+
+
+# -----------------------------
+# Physics core: vectorized formulas
+# -----------------------------
+def _u_solid_ground_floor_vectorised(B: np.ndarray, dt: np.ndarray, lg: float = 1.5) -> np.ndarray:
+    """
+    Vectorized SAP/RdSAP 2012 S5.5 solid ground floor equation.
+    B, dt arrays in meters.
+    """
+    # two regimes: dt < B else
+    out = np.empty_like(B, dtype=float)
+
+    mask = dt < B
+    # (2*lg*ln(pi*B/dt + 1)) / (pi*B + dt)
+    out[mask] = (2.0 * lg * np.log(np.pi * B[mask] / dt[mask] + 1.0)) / (np.pi * B[mask] + dt[mask])
+
+    # lg / (0.457*B + dt)
+    out[~mask] = lg / (0.457 * B[~mask] + dt[~mask])
+    return out
+
+def _u_suspended_ground_floor_vectorised(B: np.ndarray, dg: np.ndarray, Rf: np.ndarray, lg: float = 1.5) -> np.ndarray:
+    """
+    Vectorized SAP/RdSAP 2012 S5.5 suspended ground floor equation.
+    Uses constants from your function.
+    """
+    Rsi = 0.17
+    Uw = 1.5
+    h = 0.3
+    v = 5.0
+    fw = 0.05
+    e = 0.003
+
+    Ug = (2.0 * lg * np.log(np.pi * B / dg + 1.0)) / (np.pi * B + dg)
+    Ux = (2.0 * h * Uw / B) + (1450.0 * e * v * fw / B)
+
+    return 1.0 / (2.0 * Rsi + Rf + 1.0 / (Ug + Ux))
+
+
+# -----------------------------
+# Cached SAP-dependent parameters (NO area binning)
+# -----------------------------
+def build_floor_param_caches(s3: pd.DataFrame):
+    """
+    Returns two cached functions:
+      - solid_dt(wall_type_s3, sap_band, ins_mm) -> dt
+      - susp_params(wall_type_s3, sap_band, ins_mm) -> (dg, Rf)
+    """
+    thickness_map = build_s3_thickness_map(s3)
+
+    @lru_cache(maxsize=None)
+    def solid_dt(wall_type: str, sap_band: str, ins_mm: int, lg: float = 1.5) -> float:
+        # constants
+        Rsi = 0.17
+        Rse = 0.04
+        w = thickness_map.get((wall_type.lower(), sap_band.upper()))
+        if w is None:
+            # SAP-safe fallback
+            w = thickness_map.get(("solid brick", sap_band.upper()), 0.22)
+
+        # insulation resistance
+        if ins_mm > 0:
+            Rf = 0.001 * ins_mm / 0.035
+        else:
+            Rf = 0.0
+
+        dt = w + lg * (Rsi + Rf + Rse)
+        return float(dt)
+
+    @lru_cache(maxsize=None)
+    def susp_dg_rf(wall_type: str, sap_band: str, ins_mm: int, lg: float = 1.5) -> Tuple[float, float]:
+        Rsi = 0.17
+        w = thickness_map.get((wall_type.lower(), sap_band.upper()))
+        if w is None:
+            w = thickness_map.get(("solid brick", sap_band.upper()), 0.22)
+
+        # insulation resistance
+        if ins_mm > 0:
+            Rf = (0.001 * ins_mm / 0.035) + 0.2
+        else:
+            Rf = 0.2
+
+        dg = w + lg * (Rsi + 0.04)
+        return float(dg), float(Rf)
+
+    return solid_dt, susp_dg_rf
+
+
+# -----------------------------
+# Main pipeline (fast)
+# -----------------------------
+def floor_feature_engineering_fast(df: pd.DataFrame, s3: pd.DataFrame) -> pd.DataFrame:
+    """
+    Fast floor feature engineering:
+      - vectorized boundary classification
+      - measured U extracted vectorized
+      - exposed/semi_exposed uses S12 vectorized + small loop only over subset
+      - ground floors: preserves full area resolution:
+          * precompute B = sqrt(area)/2 (continuous)
+          * cache dt/dg/Rf parameters by (wall_type, band, insulation_mm)
+          * compute U with vectorized numpy formulas
+    Requirements: columns
+      - FLOOR_DESCRIPTION
+      - WALLS_DESCRIPTION
+      - TOTAL_FLOOR_AREA
+      - sap_band_letter
+    """
+    df = df.copy()
+
+    # Ensure band normalized
+    df["sap_band_letter"] = df["sap_band_letter"].astype(str).str.strip().str.upper()
+
+    # 0) Precompute B (continuous, no binning)
+    area = pd.to_numeric(df["TOTAL_FLOOR_AREA"], errors="coerce")
+    df["FLOOR_B"] = np.sqrt(area) / 2.0  # SAP square-plan assumption
+
+    # 1) Boundary type (vectorized)
+    df["FLOOR_BOUNDARY_TYPE"] = classify_floor_boundary_vectorised(df["FLOOR_DESCRIPTION"])
+
+    # 2) Measured U (vectorized)
+    measured_u = extract_measured_u_vectorised(df["FLOOR_DESCRIPTION"])
+
+    # 3) Insulation thickness:
+    #    - For ground floors we use effective S11 rule (vectorized)
+    #    - For exposed/semi-exposed we need measured mm for S12 binning (vectorized)
+    mm_measured = extract_mm_vectorised(df["FLOOR_DESCRIPTION"])
+    eff_mm = effective_floor_insulation_mm_vectorised(df["FLOOR_DESCRIPTION"], df["sap_band_letter"])
+
+    # 4) FLOOR_INSULATION_TYPE (your current approach uses S12 binning)
+    df["FLOOR_INSULATION_TYPE"] = bin_floor_insulation_s12_vectorised(df["FLOOR_DESCRIPTION"], mm_measured)
+
+    # 5) Wall type for S3 thickness (vectorized)
+    df["WALL_TYPE_S3"] = classify_wall_type_s3_vectorised(df["WALLS_DESCRIPTION"])
+
+    # 6) Build cached parameter functions
+    solid_dt_cached, susp_dg_rf_cached = build_floor_param_caches(s3)
+
+    # 7) Assemble FLOOR_U_VALUE (vectorized masks)
+    u = pd.Series(np.nan, index=df.index, dtype=float)
+    boundary = df["FLOOR_BOUNDARY_TYPE"]
+    band = df["sap_band_letter"]
+
+    # a) another dwelling below
+    u[boundary == "another_dwelling_below"] = 0.0
+
+    # b) partially heated below
+    u[boundary == "partially_heated_below"] = 0.7
+
+    # c) measured u
+    u[boundary == "measured_u_value"] = measured_u[boundary == "measured_u_value"]
+
+    # d) exposed / semi-exposed -> S12
+    exp_mask = boundary.isin(["exposed", "semi_exposed"])
+    if exp_mask.any():
+        ins_class = df.loc[exp_mask, "FLOOR_INSULATION_TYPE"]
+        u.loc[exp_mask] = lookup_s12_u_vectorised(band[exp_mask], ins_class).values
+
+    # e) ground floors -> ISO13370-ish SAP formulas (continuous area kept)
+    ground_mask = boundary == "ground"
+    if ground_mask.any():
+        floor_desc = df.loc[ground_mask, "FLOOR_DESCRIPTION"].fillna("").astype(str).str.lower()
+        is_suspended = floor_desc.str.contains("suspended")
+
+        gm_idx = df.index[ground_mask]
+        solid_idx = gm_idx[~is_suspended.to_numpy()]
+        susp_idx = gm_idx[is_suspended.to_numpy()]
+
+        # ---- SOLID GROUND ----
+        if len(solid_idx) > 0:
+            B = df.loc[solid_idx, "FLOOR_B"].to_numpy(dtype=float)
+            wall_t = df.loc[solid_idx, "WALL_TYPE_S3"].astype(str).to_numpy()
+            sb = df.loc[solid_idx, "sap_band_letter"].astype(str).to_numpy()
+            mm = eff_mm.loc[solid_idx].fillna(0).astype(int).to_numpy()
+
+            # cache dt per row (small Python loop, but only computing cache keys;
+            # dt computation itself is cached & cheap, and number of unique keys is small)
+            dt = np.empty(len(solid_idx), dtype=float)
+            for i in range(len(solid_idx)):
+                dt[i] = solid_dt_cached(wall_t[i], sb[i], int(mm[i]))
+
+            u.loc[solid_idx] = _u_solid_ground_floor_vectorised(B, dt)
+
+        # ---- SUSPENDED GROUND ----
+        if len(susp_idx) > 0:
+            B = df.loc[susp_idx, "FLOOR_B"].to_numpy(dtype=float)
+            wall_t = df.loc[susp_idx, "WALL_TYPE_S3"].astype(str).to_numpy()
+            sb = df.loc[susp_idx, "sap_band_letter"].astype(str).to_numpy()
+            mm = eff_mm.loc[susp_idx].fillna(0).astype(int).to_numpy()
+
+            dg = np.empty(len(susp_idx), dtype=float)
+            Rf = np.empty(len(susp_idx), dtype=float)
+            for i in range(len(susp_idx)):
+                dgi, Rfi = susp_dg_rf_cached(wall_t[i], sb[i], int(mm[i]))
+                dg[i] = dgi
+                Rf[i] = Rfi
+
+            u.loc[susp_idx] = _u_suspended_ground_floor_vectorised(B, dg, Rf)
+
+    df["FLOOR_U_VALUE"] = u
+
+    return df
+
+
+# ============================================================
+# Usage example:
+# s3 = pd.read_csv(...) or pd.read_excel(...) with columns:
+#   Wall Type | sap_band | thickness_mm
+# df_total = floor_feature_engineering_fast(df_total, s3)
+# ============================================================
+

src/features/roofs.py

@@ -0,0 +1,516 @@
+import pandas as pd
+import re
+import numpy as np
+
+
+def extract_roof_mm(text):
+    """Return insulation thickness in mm, or None."""
+    if pd.isna(text):
+        return None
+
+    t = str(text).lower()
+
+    # ignore U-value rows
+    if "average thermal transmittance" in t:
+        return None
+
+    # match 300 mm, 300mm, 300+ mm, 300 + mm, 300+mm
+    match = re.findall(r"(\d+)\s*\+?\s*mm", t)
+    if not match:
+        return None
+
+    return int(match[0])
+
+
+def classify_roof_type(text):
+    if "pitched" in str(text).lower():
+        return "pitched"
+    elif "flat" in str(text).lower():
+        return "flat"
+    elif "roof" in str(text).lower():
+        return "roof"
+    elif "above" in str(text).lower():
+        return "above"
+    elif "average thermal transmittance" in str(text).lower():
+        return "measured_u"
+    else:
+        return "UKN"
+
+
+def normalize_mm_to_s9(mm):
+    """
+    Normalize insulation thickness to SAP S9 valid categories.
+    Input:
+        mm : int, float, or None
+    Output:
+        int (SAP mm category) or None
+    SAP S9 valid values:
+        [0, 12, 25, 50, 75, 100, 150, 200, 250, 270, 300, 350, 400]
+    Rules:
+      - None → 0
+      - mm <= 0 → 0
+      - mm >= 400 → 400
+      - otherwise → nearest LOWER category
+    """
+
+    SAP_S9_VALUES = [0, 12, 25, 50, 75, 100, 150, 200, 250, 270, 300, 350, 400]
+
+    # Case: no value → treat as uninsulated
+    if mm is None or (isinstance(mm, float) and np.isnan(mm)):
+        return 0
+
+    # Convert to number
+    mm = float(mm)
+
+    # Negative or zero → uninsulated
+    if mm <= 0:
+        return 0
+
+    # ≥400 mm → use 400 category
+    if mm >= 400:
+        return 400
+
+    # Find largest S9 category <= mm
+    eligible = [v for v in SAP_S9_VALUES if v <= mm]
+    return eligible[-1] if eligible else 0
+
+
+
+def classify_pitched_roof_category(text: str) -> str:
+    """
+    Returns the appropriate U-value category: S9 (Measured) or S10 (Assumed/Other).
+    """
+    text_lower = str(text).lower()
+
+    # --- 1. S10 Triggers (Take precedence over measurement) ---
+    if "rafters" in text_lower:
+        return "S10_RAFTERS"
+
+    # CORRECTED LOGIC: Each string must be checked against text_lower
+    if ("assumed" in text_lower or
+        "unknown loft insulation" in text_lower or
+        "invalid input code" in text_lower):
+        return "S10_JOISTS_UNKNOWN"
+
+    # --- 2. S9 Triggers (Known/Measured Thickness) ---
+    # Check for explicit 'no insulation' (observed) or '0 mm'
+    if "no insulation" in text_lower or re.search(r"\b0\s*mm\b", text_lower):
+        return "S9_NONE"
+
+    # Check for any quantifiable number (mm) or a comparison (e.g., 300+)
+    # This must come *before* the general 'pitched' check.
+    mm_match = re.search(r'(\d+|\d+\+|\>\=\d+)', text_lower)
+    if mm_match:
+        return "S9_MEASURED"
+
+    # --- 3. Default to S10 (General unquantified cases) ---
+    # Catches descriptions like "pitched, loft insulation" or just "pitched"
+    if "pitched" in text_lower:
+        return "S10_JOISTS_UNKNOWN"
+
+    return "NON_PITCHED_OR_UKN"
+
+
+def extract_pitch_u_value(text, sap_band_letter, S9_table, S10_table):
+    """
+    Compute U-value for pitched roof using S9/S10 tables + description text.
+    """
+
+    category = classify_pitched_roof_category(text)
+
+    # ---- S9: No insulation (assumed) ----
+    if category == "S9_NONE":
+        return 2.3
+
+    # ---- S9: Measured insulation thickness ----
+    elif category == "S9_MEASURED":
+        mm = extract_roof_mm(text)
+        mm = normalize_mm_to_s9(mm)
+        value = S9_table.loc[S9_table["mm"] == mm, "slates_tiles"]
+        return float(value.iloc[0]) if not value.empty else None
+
+    # ---- S10: Rafters present ----
+    elif category == "S10_RAFTERS":
+        # Older buildings (A–D) default to uninsulated
+        if sap_band_letter in ["A", "B", "C", "D"]:
+            return 2.3
+        value = S10_table.loc[S10_table["age_band"] == sap_band_letter, "Pitched_rafters"]
+        return float(value.iloc[0]) if not value.empty else None
+
+    # ---- S10: Unknown pitched roof form ----
+    else:
+        if sap_band_letter in ["A", "B", "C", "D"]:
+            return 2.3
+        value = S10_table.loc[S10_table["age_band"] == sap_band_letter, "Pitched_unknown"]
+        return float(value.iloc[0]) if not value.empty else None
+
+
+
+def get_flat_roof_u_value(is_top_floor, sap_band_letter, s10):
+
+    # 1. Not top floor → no heat loss
+    if str(is_top_floor).strip().upper() == "N":
+        return 0.0
+
+    # 2. Missing age band → can't compute
+    if pd.isna(sap_band_letter):
+        return None
+
+    band = str(sap_band_letter).strip().upper()
+
+    # Normalize S10 band column
+    s10_bands = s10["age_band"].astype(str).str.strip().str.upper()
+
+    # 3. Bands A–D → map to merged row "A, B, C, D"
+    if band in ["A", "B", "C", "D"]:
+        row = s10.loc[s10_bands == "A, B, C, D", "Flat_roof"]
+        if not row.empty:
+            return float(row.iloc[0])
+        else:
+            return 2.3  # SAP fallback
+
+    # 4. E–L: direct match
+    row = s10.loc[s10_bands == band, "Flat_roof"]
+    if not row.empty:
+        return float(row.iloc[0])
+
+    # 5. SAP fallback for band L if missing in table
+    if band == "L":
+        return 0.18  # known SAP S10 value
+
+    return None
+
+
+def extract_measured_u(description):
+    if pd.isna(description):
+        return None
+
+    text = str(description).lower()
+
+    if "average thermal transmittance" not in text:
+        return None
+
+    # match integer OR float
+    match = re.search(r"(\d+(?:\.\d+)?)", text)
+    if match:
+        return float(match.group(1))
+
+    return None
+
+
+def get_room_in_roof_u_value(sap_band_letter, s10):
+    # Check for "room in roof" in the description
+    if sap_band_letter in ["A", "B", "C", "D"]:
+        return 2.3
+    else:
+        # Look up the U-value in the s10 DataFrame
+        row = s10[s10["age_band"] == sap_band_letter]
+        if not row.empty:
+            u_value = row["Room_in_roof"].values[0]
+            return u_value
+    return None
+
+
+def calculate_overall_roof_u_value(row,s9,s10):
+    roof_class = classify_roof_type(row["ROOF_DESCRIPTION"])
+    if roof_class == "pitched":
+        return extract_pitch_u_value(row["ROOF_DESCRIPTION"], row["sap_band_letter"], s9, s10)
+    elif roof_class == "flat":
+        return get_flat_roof_u_value(row["FLAT_TOP_STOREY"], row["sap_band_letter"], s10)
+    elif roof_class == "measured_u":
+        return extract_measured_u(row["ROOF_DESCRIPTION"])
+    elif roof_class == "roof":
+        return get_room_in_roof_u_value(row["sap_band_letter"], s10)
+    elif roof_class == "above":
+        return 0.0
+    else:
+        return None
+
+
+
+def extract_roof_insulation(row):
+    desc = row["ROOF_DESCRIPTION"]
+    flat_top = row.get("FLAT_TOP_STOREY")
+    t = str(desc).lower()
+
+    # -------------------------------
+    # 0. ABOVE overrides everything
+    # -------------------------------
+    if "above" in t or (flat_top is not None and str(flat_top).upper() == "N"):
+        return "above"
+
+    # -------------------------------
+    # 1. Measured U-value
+    # -------------------------------
+    if "average thermal transmittance" in t:
+        return "measured"
+
+    # -------------------------------
+    # 2. explicit no insulation
+    # -------------------------------
+    if "no insulation" in t:
+        return "none"
+
+    # -------------------------------
+    # 3. insulation at rafters
+    # -------------------------------
+    if "insulated at rafters" in t:
+        return "rafters"
+
+    # -------------------------------
+    # 4. numerical mm thickness
+    # -------------------------------
+    mm = extract_roof_mm(desc)
+    if mm is not None:
+        if mm == 0:
+            return "none"
+        return "loft_insulation"
+
+    # -------------------------------
+    # 5. generic loft insulation
+    # (no mm, still should count)
+    # -------------------------------
+    if "loft insulation" in t:
+        return "loft_insulation"
+
+    # -------------------------------
+    # 6. UNKNOWN loft insulation
+    # -------------------------------
+    if "unknown" in t and "loft" in t:
+        return "unknown_loft"
+
+    # -------------------------------
+    # 7. thatched roofs
+    # -------------------------------
+    if "thatched" in t:
+        return "thatched"
+
+    # roof room variants with thatch
+    if "roof room" in t and "thatched" in t:
+        return "roof_room_thatched"
+
+    # -------------------------------
+    # 8. limited insulation
+    # -------------------------------
+    if "limited" in t:
+        return "limited"
+
+    # -------------------------------
+    # 9. generic insulated (not rafters)
+    # -------------------------------
+    if "insulated" in t:
+        return "insulated"
+
+    # -------------------------------
+    # 10. roof room (no specific mm)
+    # -------------------------------
+    if "roof room" in t:
+        return "roof_room"
+
+    # -------------------------------
+    # fallback
+    # -------------------------------
+    return "unknown"
+
+
+
+def build_roof_lookup(roof_desc: pd.Series) -> pd.DataFrame:
+    """
+    Parse ROOF_DESCRIPTION once.
+    Returns a lookup table keyed by ROOF_DESCRIPTION.
+    """
+
+    s = roof_desc.fillna("").astype(str).str.lower()
+
+    out = pd.DataFrame({
+        "ROOF_DESCRIPTION": roof_desc,
+        "ROOF_CLASS": pd.NA,          # pitched / flat / above / room / measured
+        "ROOF_MM_RAW": pd.NA,
+        "ROOF_MM_S9": pd.NA,
+        "ROOF_PITCH_CATEGORY": pd.NA, # S9_MEASURED / S9_NONE / S10_RAFTERS / S10_UNKNOWN
+        "ROOF_MEASURED_U": pd.NA,
+        "ROOF_INSULATION_TYPE": pd.NA
+    }).drop_duplicates("ROOF_DESCRIPTION")
+
+    # ---------------------------
+    # ROOF CLASS (priority order)
+    # ---------------------------
+    out.loc[s.str.contains("average thermal transmittance"), "ROOF_CLASS"] = "measured"
+    out.loc[s.str.contains("above"), "ROOF_CLASS"] = "above"
+    out.loc[s.str.contains("roof room"), "ROOF_CLASS"] = "room"
+    out.loc[s.str.contains("flat"), "ROOF_CLASS"] = "flat"
+    out.loc[s.str.contains("pitched"), "ROOF_CLASS"] = "pitched"
+
+    # ---------------------------
+    # MEASURED U-VALUE
+    # ---------------------------
+    m = (
+        s.where(s.str.contains("average thermal transmittance"))
+         .str.extract(r"(\d+(?:\.\d+)?)", expand=False)
+    )
+    out.loc[out["ROOF_CLASS"] == "measured", "ROOF_MEASURED_U"] = pd.to_numeric(m, errors="coerce")
+
+    # ---------------------------
+    # RAW MM EXTRACTION
+    # ---------------------------
+    mm = s.str.extract(r"(\d+)\s*\+?\s*mm", expand=False)
+    out["ROOF_MM_RAW"] = pd.to_numeric(mm, errors="coerce")
+
+    # ---------------------------
+    # NORMALISE TO SAP S9 MM
+    # ---------------------------
+    SAP_S9_VALUES = np.array([0, 12, 25, 50, 75, 100, 150, 200, 250, 270, 300, 350, 400])
+
+    def to_s9(mm):
+        if pd.isna(mm) or mm <= 0:
+            return 0
+        if mm >= 400:
+            return 400
+        return SAP_S9_VALUES[SAP_S9_VALUES <= mm].max()
+
+    out["ROOF_MM_S9"] = out["ROOF_MM_RAW"].map(to_s9)
+
+    # ---------------------------
+    # PITCHED ROOF CATEGORY
+    # ---------------------------
+    pitched = out["ROOF_CLASS"] == "pitched"
+
+    out.loc[pitched & s.str.contains("rafters"), "ROOF_PITCH_CATEGORY"] = "S10_RAFTERS"
+    out.loc[pitched & s.str.contains("no insulation"), "ROOF_PITCH_CATEGORY"] = "S9_NONE"
+    out.loc[pitched & out["ROOF_MM_RAW"].notna(), "ROOF_PITCH_CATEGORY"] = "S9_MEASURED"
+
+    out.loc[
+        pitched &
+        out["ROOF_PITCH_CATEGORY"].isna() &
+        s.str.contains("assumed|unknown|invalid"),
+        "ROOF_PITCH_CATEGORY"
+    ] = "S10_UNKNOWN"
+
+    out.loc[
+        pitched & out["ROOF_PITCH_CATEGORY"].isna(),
+        "ROOF_PITCH_CATEGORY"
+    ] = "S10_UNKNOWN"
+
+    # ---------------------------
+    # INSULATION TYPE (semantic)
+    # ---------------------------
+    out.loc[s.str.contains("rafters"), "ROOF_INSULATION_TYPE"] = "rafters"
+    out.loc[s.str.contains("no insulation"), "ROOF_INSULATION_TYPE"] = "none"
+    out.loc[s.str.contains("thatched"), "ROOF_INSULATION_TYPE"] = "thatched"
+    out.loc[s.str.contains("loft"), "ROOF_INSULATION_TYPE"] = "loft"
+    out.loc[out["ROOF_MM_RAW"].notna(), "ROOF_INSULATION_TYPE"] = "loft"
+
+    return out
+
+
+def build_roof_u_dicts(s9: pd.DataFrame, s10: pd.DataFrame):
+
+    S9_U = dict(zip(s9["mm"], s9["slates_tiles"]))
+
+    S10_PITCHED = dict(zip(s10["age_band"], s10["Pitched_unknown"]))
+    S10_RAFTERS = dict(zip(s10["age_band"], s10["Pitched_rafters"]))
+    S10_FLAT = dict(zip(s10["age_band"], s10["Flat_roof"]))
+    S10_ROOM = dict(zip(s10["age_band"], s10["Room_in_roof"]))
+
+    return S9_U, S10_PITCHED, S10_RAFTERS, S10_FLAT, S10_ROOM
+
+
+def roof_feature_engineering(
+    df: pd.DataFrame,
+    s9: pd.DataFrame,
+    s10: pd.DataFrame
+) -> pd.DataFrame:
+
+    df = df.copy()
+
+    # ----------------------------------
+    # 1. Parse roof descriptions ONCE
+    # ----------------------------------
+    roof_lookup = build_roof_lookup(df["ROOF_DESCRIPTION"]).set_index("ROOF_DESCRIPTION")
+
+    df["ROOF_CLASS"] = df["ROOF_DESCRIPTION"].map(roof_lookup["ROOF_CLASS"])
+    df["ROOF_MM_S9"] = df["ROOF_DESCRIPTION"].map(roof_lookup["ROOF_MM_S9"])
+    df["ROOF_PITCH_CATEGORY"] = df["ROOF_DESCRIPTION"].map(roof_lookup["ROOF_PITCH_CATEGORY"])
+    df["ROOF_MEASURED_U"] = df["ROOF_DESCRIPTION"].map(roof_lookup["ROOF_MEASURED_U"])
+    df["ROOF_INSULATION_TYPE"] = df["ROOF_DESCRIPTION"].map(roof_lookup["ROOF_INSULATION_TYPE"])
+
+    # ----------------------------------
+    # 2. SAP lookup dicts
+    # ----------------------------------
+    S9_U, S10_PITCHED, S10_RAFTERS, S10_FLAT, S10_ROOM = build_roof_u_dicts(s9, s10)
+
+    band = df["sap_band_letter"]
+
+    # ----------------------------------
+    # 3. Vectorised U-value logic
+    # ----------------------------------
+    u = pd.Series(np.nan, index=df.index)
+
+    # ABOVE
+    u[df["ROOF_CLASS"] == "above"] = 0.0
+
+    # MEASURED overrides everything
+    # u[df["ROOF_MEASURED_U"].notna()] = df.loc[
+    #     df["ROOF_MEASURED_U"].notna(), "ROOF_MEASURED_U"
+    # ]
+    mask = df["ROOF_MEASURED_U"].notna()
+    u.loc[mask] = df.loc[mask, "ROOF_MEASURED_U"].astype(float)
+
+    # FLAT (top storey only)
+    mask = (
+    (df["ROOF_CLASS"] == "flat") &
+    (
+        df["FLAT_TOP_STOREY"].isna() |
+        (df["FLAT_TOP_STOREY"].astype(str).str.upper() == "Y")
+       )
+    )
+    u[mask] = band[mask].map(S10_FLAT)
+
+    # FLAT roofs with another dwelling above → no heat loss
+    mask = (
+    (df["ROOF_CLASS"] == "flat") &
+    (df["FLAT_TOP_STOREY"].astype(str).str.upper() == "N")
+        )
+    u[mask] = 0.0
+
+    # ROOM IN ROOF
+    mask = df["ROOF_CLASS"] == "room"
+    u[mask] = band[mask].map(S10_ROOM)
+
+    # PITCHED – S9 MEASURED
+    mask = (
+        (df["ROOF_CLASS"] == "pitched") &
+        (df["ROOF_PITCH_CATEGORY"] == "S9_MEASURED")
+    )
+    u[mask] = df.loc[mask, "ROOF_MM_S9"].map(S9_U)
+
+    # 🔥 FIX: PITCHED – NO INSULATION (S9_NONE)
+    mask = (
+        (df["ROOF_CLASS"] == "pitched") &
+        (df["ROOF_PITCH_CATEGORY"] == "S9_NONE")
+    )
+    u[mask] = 2.3
+
+    # PITCHED – RAFTERS
+    mask = (
+        (df["ROOF_CLASS"] == "pitched") &
+        (df["ROOF_PITCH_CATEGORY"] == "S10_RAFTERS")
+    )
+    u[mask] = band[mask].map(S10_RAFTERS)
+
+    # PITCHED – UNKNOWN
+    mask = (
+        (df["ROOF_CLASS"] == "pitched") &
+        (df["ROOF_PITCH_CATEGORY"] == "S10_UNKNOWN")
+    )
+    u[mask] = band[mask].map(S10_PITCHED)
+
+    # ----------------------------------
+    # 4. SAP fallback for A–D
+    # ----------------------------------
+    fallback = band.isin(["A", "B", "C", "D"]) & u.isna()
+    u[fallback] = 2.3
+
+    df["ROOF_U_VALUE"] = u
+
+    return df

src/features/walls.py

@@ -0,0 +1,376 @@
+import re
+import pandas as pd
+import numpy as np
+
+
+def extract_wall_u_from_text(text: str | float | None) -> float | None:
+    """
+    Extract numeric U-value from WALLS_DESCRIPTION when it contains
+    'Average thermal transmittance ...', which corresponds to the
+    average external wall U-value in SAP/RdSAP EPCs.
+
+    If no numeric value is found or it looks invalid (< 0.05),
+    return None and let Stage 2 handle it.
+    """
+    if pd.isna(text):
+        return None
+
+    s = str(text).lower()
+    if "average thermal transmittance" not in s:
+        return None
+
+    # Find first number in the string (handles '0.30', '1.4', etc.)
+    nums = re.findall(r"([0-9]*\.?[0-9]+)", s)
+    if not nums:
+        return None
+
+    u = float(nums[0])
+
+    # EPC sometimes has '0.00' for missing; treat as unknown
+    if u < 0.05:
+        return None
+
+    return u
+
+
+
+def classify_wall_type(text):
+    """
+    Classify EPC WALLS_DESCRIPTION into BASE wall construction type only.
+
+    This function encodes *construction identity*, NOT insulation state
+    and NOT performance. It is suitable for retrofit inference.
+
+    Final categories:
+        - solid
+        - cavity
+        - filled cavity
+        - timber frame
+        - system build
+        - cob
+        - unknown
+    """
+    if pd.isna(text):
+        return "unknown"
+
+    t = text.lower().strip()
+
+    # --------------------------------------------------------
+    # 0. Direct U-value entry → unknown construction
+    # --------------------------------------------------------
+    if "average thermal transmittance" in t:
+        return "unknown"
+
+    # --------------------------------------------------------
+    # 1. Cob (distinct SAP category)
+    # --------------------------------------------------------
+    if "cob" in t:
+        return "cob"
+
+    # --------------------------------------------------------
+    # 2. Solid masonry (brick / stone)
+    # --------------------------------------------------------
+    if (
+        "briciau solet" in t or
+        any(x in t for x in [
+            "solid brick",
+            "solid stone",
+            "sandstone",
+            "limestone",
+            "granite",
+            "whinstone",
+            "whin"
+        ])
+    ):
+        return "solid"
+
+    # --------------------------------------------------------
+    # 3. Timber frame
+    # --------------------------------------------------------
+    if "timber frame" in t:
+        return "timber frame"
+
+    # --------------------------------------------------------
+    # 4. System build (explicit SAP construction class)
+    # --------------------------------------------------------
+    if "system build" in t or "system built" in t:
+        return "system built"
+
+    # --------------------------------------------------------
+    # 5. Cavity walls
+    # --------------------------------------------------------
+    if "cavity" in t:
+        if "filled cavity" in t:
+            return "filled cavity"
+        else:
+            return "unfilled cavity"
+
+    # --------------------------------------------------------
+    # 6. Basement / retaining walls (not envelope)
+    # --------------------------------------------------------
+    if "basement wall" in t or "retaining wall" in t:
+        return "unknown"
+
+    return "unknown"
+
+
+
+def extract_wall_insulation(text):
+    """
+    Extract wall insulation depth category from WALLS_DESCRIPTION.
+
+    Returns one of:
+        - "as built"
+        - "50 mm"
+        - "100 mm"
+        - "150 mm"
+        - "200 mm"
+        - None  (measured U-value only)
+
+    Insulation state ONLY. No construction identity.
+    """
+    if pd.isna(text):
+        return None
+
+    t = text.lower()
+
+    # --------------------------------------------------------
+    # 0. Direct U-value entry → no insulation category
+    # --------------------------------------------------------
+    if "average thermal transmittance" in t:
+        return None
+
+    # --------------------------------------------------------
+    # 1. Explicit thickness (must come FIRST)
+    # --------------------------------------------------------
+    if "200 mm" in t:
+        return "200 mm"
+    if "150 mm" in t:
+        return "150 mm"
+    if "100 mm" in t:
+        return "100 mm"
+    if "50 mm" in t:
+        return "50 mm"
+
+    # --------------------------------------------------------
+    # 2. Generic insulation statements
+    # --------------------------------------------------------
+    if "internal insulation" in t or "external insulation" in t:
+        return "50 mm"
+
+    if "partial insulation" in t or "insulated" in t:
+        return "50 mm"
+
+    # --------------------------------------------------------
+    # 3. Explicit no insulation
+    # --------------------------------------------------------
+    if "no insulation" in t or "as built" in t:
+        return "as built"
+
+    # --------------------------------------------------------
+    # 4. Default
+    # --------------------------------------------------------
+    return "as built"
+
+
+def lookup_wall_u_value(row, walls_u_values):
+    wall_type = classify_wall_type(row["WALLS_DESCRIPTION"])
+    raw_age = row["sap_band_label"]
+
+    # If EPC gives numeric U-value → use it
+    numeric_u = extract_wall_u_from_text(row["WALLS_DESCRIPTION"])
+    if numeric_u is not None:
+        return numeric_u
+
+    # --------------------------------------------------------
+    # INTERNAL SAP AGE-BAND MAPPING (TABLE S1 – England & Wales)
+    # --------------------------------------------------------
+    AGE_BAND_MAP = {
+        "pre-1900":       "before 1900",
+        "before 1900":    "before 1900",
+
+        "1900-1929":      "1900–1929",
+        "1930-1949":      "1930–1949",
+        "1950-1966":      "1950–1966",
+        "1967-1975":      "1967–1975",
+        "1976-1982":      "1976–1982",
+        "1983-1990":      "1983–1990",
+        "1991-1995":      "1991–1995",
+        "1996-2002":      "1996–2002",
+
+        # Also catch accidental unicode/duplicate variations
+        "1996–2002":      "1996–2002",
+
+        "2003-2006":      "2003–2006",
+        "2007-2011":      "2007–2011",
+
+        "2012+":          "2012 onwards",
+        "2012 onwards":   "2012 onwards",
+    }
+
+    # --------------------------------------------------------
+    # Convert incoming SAP band → exact column name in U-value table
+    # --------------------------------------------------------
+    age_label = AGE_BAND_MAP.get(raw_age, None)
+
+    # If mapping fails, return NaN (should be extremely rare)
+    if age_label is None:
+        return np.nan
+
+    # If wall type is None → cannot assign table U-value
+    if wall_type is None:
+        return np.nan
+
+    # --------------------------------------------------------
+    # U-value lookup (exact match required)
+    # --------------------------------------------------------
+    if age_label in walls_u_values.columns:
+        vals = walls_u_values.loc[
+            walls_u_values["External wall type"] == wall_type,
+            age_label
+        ]
+
+        if len(vals) > 0:
+            return vals.values[0]
+
+    return np.nan
+
+
+
+def prepare_wall_u_table(walls_u_values: pd.DataFrame) -> pd.DataFrame:
+    return walls_u_values.melt(
+        id_vars="External wall type",
+        var_name="WALL_AGE_LABEL",
+        value_name="WALL_U_TABLE"
+    )
+
+
+def build_wall_lookup(walls_desc: pd.Series) -> pd.DataFrame:
+    """
+    Parse each unique WALLS_DESCRIPTION once.
+    """
+    uniq = walls_desc.dropna().unique()
+
+    rows = []
+    for desc in uniq:
+        rows.append({
+            "WALLS_DESCRIPTION": desc,
+            "WALL_TYPE": classify_wall_type(desc),
+            "WALL_INSULATION": extract_wall_insulation(desc),
+            "WALL_U_MEASURED": extract_wall_u_from_text(desc),
+        })
+
+    return pd.DataFrame(rows)
+
+
+AGE_BAND_MAP = {
+    "pre-1900": "before 1900",
+    "before 1900": "before 1900",
+    "1900-1929": "1900–1929",
+    "1930-1949": "1930–1949",
+    "1950-1966": "1950–1966",
+    "1967-1975": "1967–1975",
+    "1976-1982": "1976–1982",
+    "1983-1990": "1983–1990",
+    "1991-1995": "1991–1995",
+    "1996-2002": "1996–2002",
+    "1996–2002": "1996–2002",
+    "2003-2006": "2003–2006",
+    "2007-2011": "2007–2011",
+    "2012+": "2012 onwards",
+    "2012 onwards": "2012 onwards",
+}
+
+
+def merge_wall_type_for_sap(wall_type: str, insulation: str) -> str:
+    """
+    Merge wall base type + insulation into SAP external wall type label.
+    Used ONLY for SAP U-value lookup.
+    """
+
+    if wall_type is None:
+        return None
+
+    if insulation in (None, "as built"):
+        return f"{wall_type}- as built"
+
+    return f"{wall_type}- {insulation} insulation"
+
+
+def wall_feature_engineering(
+    df: pd.DataFrame,
+    walls_u_values: pd.DataFrame,
+) -> pd.DataFrame:
+    """
+    Wall feature engineering using dictionary-based lookups only.
+    No DataFrame merges (memory-safe and consistent with multi-key logic).
+
+    Steps:
+    1. Parse WALLS_DESCRIPTION → wall semantics
+    2. Normalise SAP age band
+    3. Lookup SAP wall U-values via (WALL_TYPE, WALL_AGE_LABEL)
+    4. Final U-value resolution: measured > SAP table
+    """
+
+    df = df.copy()
+
+    # ------------------------------------------------------------
+    # 1. Parse wall descriptions ONCE (dictionary lookup)
+    # ------------------------------------------------------------
+    # build_wall_lookup must return a DataFrame with:
+    # ["WALLS_DESCRIPTION", "WALL_TYPE", "WALL_INSULATION", "WALL_U_MEASURED"]
+    wall_lookup_df = build_wall_lookup(df["WALLS_DESCRIPTION"])
+
+    wall_lookup_dict = {
+        desc: (
+            row["WALL_TYPE"],
+            row["WALL_INSULATION"],
+            row["WALL_U_MEASURED"],
+        )
+        for desc, row in wall_lookup_df.set_index("WALLS_DESCRIPTION").iterrows()
+    }
+
+    parsed = df["WALLS_DESCRIPTION"].map(wall_lookup_dict)
+
+    df["WALL_TYPE"] = parsed.str[0]
+    df["WALL_INSULATION"] = parsed.str[1]
+    df["WALL_U_MEASURED"] = parsed.str[2]
+
+    # ------------------------------------------------------------
+    # 2. Normalise SAP age band (pure map, no join)
+    # ------------------------------------------------------------
+    df["WALL_AGE_LABEL"] = df["sap_band_label"].map(AGE_BAND_MAP)
+
+    # ------------------------------------------------------------
+    # 3. SAP wall U-value lookup via dictionary
+    # ------------------------------------------------------------
+    # Prepare long SAP table once
+    walls_u_long = prepare_wall_u_table(walls_u_values)
+
+    wall_u_dict = {
+        (row["External wall type"], row["WALL_AGE_LABEL"]): row["WALL_U_TABLE"]
+        for _, row in walls_u_long.iterrows()
+    }
+
+    # wall_keys = zip(df["WALL_TYPE"], df["WALL_AGE_LABEL"]) old version
+    # Merge wall type + insulation for SAP key (vectorised)
+    df["WALL_TYPE_SAP"] = [
+        merge_wall_type_for_sap(wt, ins)
+        for wt, ins in zip(df["WALL_TYPE"], df["WALL_INSULATION"])
+    ]
+
+    wall_keys = zip(df["WALL_TYPE_SAP"], df["WALL_AGE_LABEL"])
+
+    df["WALL_U_TABLE"] = [wall_u_dict.get(k) for k in wall_keys]
+
+    # ------------------------------------------------------------
+    # 4. Final U-value resolution (SAP rule)
+    # ------------------------------------------------------------
+    df["WALL_U_VALUE"] = df["WALL_U_MEASURED"].combine_first(df["WALL_U_TABLE"])
+
+    # ------------------------------------------------------------
+    # 5. Optional clean-up
+    # ------------------------------------------------------------
+    df.drop(columns=["WALL_U_TABLE"], inplace=True, errors="ignore")
+
+    return df

src/models/EpcEnergyPipeline.py

@@ -0,0 +1,62 @@
+import mlflow.pyfunc
+import pandas as pd
+import shap
+from catboost import CatBoostRegressor
+import numpy as np
+from src.features.build_features import SAPTables, EPCFeatureEngineer
+
+
+class EpcEnergyPipeline(mlflow.pyfunc.PythonModel):
+    """
+    MLflow-wrapped EPC energy model:
+    - loads CatBoost model
+    - computes SAP-aligned features
+    - predicts energy / CO2 / EPC score
+    """
+
+    def __init__(self, cb_model_path=None,sap_tables=None):
+        self.cb_model_path = cb_model_path
+        self.sap_tables = sap_tables
+        self.explainer = None
+
+
+    def load_context(self, context):
+        model_path = context.artifacts.get("catboost_model", self.cb_model_path)
+        sap_dir = context.artifacts.get("sap_tables", self.sap_tables)
+
+        self.model = CatBoostRegressor()
+        self.model.load_model(model_path)
+
+        self.sap = SAPTables.from_local_dir(sap_dir)
+        self.feature_engineer = EPCFeatureEngineer(self.sap)
+
+        self.explainer = shap.TreeExplainer(self.model)
+
+
+    def build_features(self, model_input):
+        features = self.feature_engineer.transform(model_input)
+        return features
+
+
+    def predict(self, context, model_input):
+        if not isinstance(model_input, pd.DataFrame):
+            model_input = pd.DataFrame(model_input)
+        enriched = self.build_features(model_input)
+        return np.expm1(self.model.predict(enriched))
+
+
+    def explain_predictions(self, model_input):
+        if not isinstance(model_input, pd.DataFrame):
+            model_input = pd.DataFrame(model_input)
+
+        X = self.build_features(model_input)
+        shap_values = self.explainer(X)
+        preds = self.model.predict(X)
+
+        return {
+            "prediction": float(preds[0]),
+            "base_value": float(self.explainer.expected_value),
+            "shap_values": shap_values.values.tolist(),
+            "feature_names": X.columns.tolist(),
+            "data": X.to_dict(orient="records"),
+        }