BatiClust 🏘️

BatiClust is a Python framework designed to generate and validate building stock archetypes. It leverages unsupervised machine learning to segment residential dwellings into representative groups and provides a rigorous external validation suite using Energy Performance Certificate (EPC) data.
Unlike static typologies, BatiClust allows researchers to define archetypes at any level of granularity, quantifying the trade-off between model simplicity and its accuracy in representing national energy signatures.

It is built on top of Polars for high-performance data manipulation and uses Faiss and Fastcluster for efficient clustering.

Key Features

• Stratified Subsampling: Automatically split large building databases into homogeneous subsamples based on categorical attributes (e.g., construction era, heating system) before clustering.
• Scalable Clustering: Implements flexible clustering algorithms (K-Means via Faiss, Hierarchical via Fastcluster) to identify natural archetypes within building stocks.
• External Validation: A dedicated module to compare cluster-derived distributions against real-world energy performance data.
• Medoid Selection: Identifies representative building archetypes (medoids) for each cluster.

Installation

pip install baticlust

Note: This package requires polars, numpy, faiss-cpu, fastcluster, scipy, matplotlib, and scikit-learn.

Quick Start

1. Data Preparation

Prepare your dataset with descriptive features and target performance metrics. BatiClust uses Polars DataFrames.

import polars as pl
from baticlust import scale_features

# Load your data
df = pl.read_parquet("housing_stock.parquet")

# Define features
strata_cols = ['construction_year_class', 'heating_energy_type']
features = ['living_area', 'wall_insulation_thickness']

# Scale numerical features
df_scaled = scale_features(df, features, method="standard")

2. Stratified Clustering

BatiClust splits your database into strategic subsamples before applying clustering.

from baticlust import generate_archetypes

# Generate archetypes
clustered_df = generate_archetypes(
    df_scaled,
    strata_cols=strata_cols,
    features=features,
    method="kmeans",
    total_n_clusters=1000,
    niter=20,
    verbose=True
)

# The result is the original DataFrame with a new 'cluster_id' column
print(clustered_df.head())

3. Medoid Selection & Validation

Identify representative archetypes and validate them against actual performance data.

from baticlust import select_medoids, validate_typology_with_medoids

# Create a unique cluster identifier if needed (combining strata and cluster_id)
clustered_df = clustered_df.with_columns(
    pl.concat_str([pl.col(c) for c in strata_cols] + [pl.col("cluster_id").cast(pl.Utf8)], separator="_")
    .alias("unique_cluster_id")
)

# Select medoids (representative buildings)
medoids_df = select_medoids(clustered_df, "unique_cluster_id", features)

# Validate using a target column (e.g., energy consumption)
metrics = validate_typology_with_medoids(
    clustered_df,
    medoids_df,
    cluster_col="unique_cluster_id",
    target_col="energy_consumption"
)

print(f"Wasserstein Distance: {metrics['wasserstein_distance']}")
print(f"KS Statistic: {metrics['ks_statistic']}")

Methodology

The BatiClust workflow follows the methodology established in recent building stock research:

1. Pre-processing: Cleaning and scaling of building characteristics using Polars.
2. Stratification: Subdividing the stock into logical categories to ensure rare but important building types are not lost.
3. Clustering: Applying algorithms like K-Means (Faiss) or Hierarchical Clustering (Fastcluster) to find representative centroids within each stratum.
4. Validation: Using Kolmogorov-Smirnov tests and Wasserstein distance to verify if the clusters accurately mirror the energy performance distribution of the original stock.

Citing BatiClust

If you use this package in your research, please cite the following paper:
A Scalable Framework for Generating and Validating Dwelling Archetypes: A Clustering Approach for Energy Performance Analysis (2026). [Link to Paper]

License

This project is licensed under the MIT License - see the LICENSE file for details.