Energetic

Automated building energy efficiency descriptor generation, model training, and deployment — similar to Mordred for chemical descriptors and Jaqpotpy for model deployment, but purpose-built for building energy analysis.

Features

• 200+ automated descriptors from building geometry, context, envelope, and time-series data
• Minimal input required — pass a GeoJSON, Shapefile, CityJSON, or DataFrame with WKT geometries
• ML model training with XGBoost, RandomForest, LightGBM, and Neural Networks
• Hyperparameter optimization via Optuna
• Model packaging and upload to custom deployment platforms
• Open dataset integration (ASHRAE, Building Data Genome, NYC LL84, OSM)
• Meteorological data enrichment for expanded feature sets

Installation

pip install -e .

# With ML extras (XGBoost, LightGBM, Optuna)
pip install -e ".[ml]"

# Full installation

Quick Start

Generate Descriptors

from energetic import EnergyFeaturizer

featurizer = EnergyFeaturizer(descriptors="all", cache=True, n_jobs=-1)
features = featurizer.fit_transform("buildings.geojson")

print(f"Generated {len(featurizer.get_feature_names())} descriptors")
featurizer.to_csv("features.csv")

Train a Model

from energetic import EnergyFeaturizer, EnergyModelTrainer
import pandas as pd

featurizer = EnergyFeaturizer()
features = featurizer.fit_transform("buildings.geojson")

X = features.drop("building_id", axis=1)
y = pd.read_csv("eui_targets.csv")["eui"]

trainer = EnergyModelTrainer(task="regression", model="xgboost")
metrics = trainer.train(X, y, optimization_trials=50)
trainer.save("model.joblib")

Upload to Platform

from energetic import ModelUploader

uploader = ModelUploader(
    endpoint_url="https://your-platform.example.com",
    api_key="your-api-key",
)
model_id = uploader.upload(trainer, featurizer, metadata, "office_eui_v1")

CLI

# Generate descriptors
energetic featurize buildings.geojson -o features.csv

# Train model
energetic train features.csv targets.csv -o model.joblib -m xgboost

# Show descriptor info
energetic info --descriptors

# End-to-end pipeline
energetic pipeline buildings.geojson targets.csv -o output/

Descriptor Categories

Input Formats

• GeoJSON — .geojson, .json
• Shapefile — .shp
• CityJSON — .city.json
• CSV/DataFrame — WKT geometry column
• Python dicts — list of building dictionaries

Keeping your own fields

Your input usually carries identifiers and attributes that are not descriptor inputs — a BBL, an address, a portfolio key, an OSM id. keep= carries them through to the output so results join straight back to your source rows.

featurizer = EnergyFeaturizer(keep=["bbl", "address"])
features = featurizer.fit_transform("buildings.geojson")
# -> building_id | src_bbl | src_address | morph_* | env_* | ...

model = EnergyRegressor(
    dataset=df, target=y, name="eui",
    keep=["bbl", "address"],       # or keep="all"
)
model.fit()
model.predict(df)
# -> building_id | src_bbl | src_address | prediction

Kept fields are read from your GeoJSON properties / CSV columns, prefixed with src_ so they can never shadow a computed descriptor, and echoed back by the packaged model on the inference API.

They are passengers, never features. Passthrough columns are attached after the feature set is fixed, so they cannot reach the estimator — you can safely keep the target column itself. Use keep_prefix="" for verbatim names (a genuine collision then raises rather than silently overwriting).

Open Datasets

from energetic.datasets import OpenDatasetLoader

loader = OpenDatasetLoader()

# NYC LL84 — live Socrata API (no auth required)
nyc = loader.load("nyc_building_energy", max_records=1000, property_type="Office")

# ASHRAE / BDG2 — Kaggle API (requires ~/.kaggle/kaggle.json)
ashrae = loader.load("ashrae_great_energy_predictor")
bdgp = loader.load("building_data_genome", components=["metadata", "electricity"])

# OSM footprints — Overpass API or OSMnx
osm = loader.load("openstreetmap_buildings", latitude=40.75, longitude=-73.98, radius_m=300)

# Run standardized benchmarks
result = loader.run_benchmark("nyc_site_eui", model="random_forest")
print(result["test_metrics"])

License

MIT