Metadata-Version: 2.4
Name: baticlust
Version: 0.1.0
Summary: Building stock archetype generation using stratified clustering
Author-email: Yassine Abdelouadoud <yassine.abdelouadoud@gmail.com>
License-Expression: MIT
Project-URL: Repository, https://gitlab.com/energytransition/baticlust
Keywords: buildings,archetypes,clustering,energy,building stock
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: polars
Requires-Dist: numpy
Requires-Dist: faiss-cpu
Requires-Dist: fastcluster
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: scikit-learn
Requires-Dist: joblib
Requires-Dist: tqdm
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# **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**

```bash
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.

```python
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.

```python
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.

```python
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.
