buildingdata 0.1.0__py3-none-any.whl

buildingdata/__init__.py

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+from .config import write_config
+from .reference import get_census, get_diagnosis, get_districts, get_gas_network
+from .simulation import get_bdtopo, get_era5_climate
+
+
+def configure(bucket=None, cache_dir=None, credentials=None):
+    """Write or update ~/.config/buildingdata/config.ini.
+
+    Args:
+        bucket (str, optional): GCS bucket name.
+        cache_dir (str or pathlib.Path, optional): local cache directory.
+        credentials (str or pathlib.Path, optional): path to GCS service
+            account JSON. Pass None to use Application Default Credentials.
+    """
+    write_config(bucket=bucket, cache_dir=cache_dir, credentials=credentials)

buildingdata/_cli.py

@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+import argparse
+
+from .config import write_config
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="buildingdata",
+        description="Configure the buildingdata package.",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    cfg_parser = sub.add_parser("configure", help="Write ~/.config/buildingdata/config.ini")
+    cfg_parser.add_argument("--bucket", default=None, help="GCS bucket name")
+    cfg_parser.add_argument("--cache-dir", default=None, dest="cache_dir", help="Local cache directory")
+    cfg_parser.add_argument("--credentials", default=None, help="Path to GCS service account JSON")
+
+    args = parser.parse_args()
+
+    if args.command == "configure":
+        write_config(
+            bucket=args.bucket,
+            cache_dir=args.cache_dir,
+            credentials=args.credentials,
+        )
+        print("Configuration saved.")
+    else:
+        parser.print_help()

buildingdata/cache.py

@@ -0,0 +1,92 @@
+# -*- coding: utf-8 -*-
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .config import get_cache_dir
+from .exceptions import CacheError
+
+
+def cache_path(name):
+    """Return the local Path where a named artifact should be cached.
+
+    Args:
+        name (str): logical artifact name, e.g. "census_latest.parquet".
+
+    Returns:
+        pathlib.Path: absolute path under the configured cache dir.
+    """
+    return get_cache_dir() / name
+
+
+def _sidecar_path(name):
+    return get_cache_dir() / (name + ".meta.json")
+
+
+def is_cached(name):
+    """Return True if the artifact file and a valid sidecar both exist.
+
+    Does not contact GCS. Use needs_refresh() for a freshness check.
+
+    Args:
+        name (str): logical artifact name.
+
+    Returns:
+        bool: True if the local copy can be used without downloading.
+    """
+    return cache_path(name).exists() and _sidecar_path(name).exists()
+
+
+def needs_refresh(name, blob):
+    """Return True if the local copy is older than the GCS blob.
+
+    Args:
+        name (str): logical artifact name.
+        blob (google.cloud.storage.Blob): live blob object from GCS.
+
+    Returns:
+        bool: True if the blob generation has advanced past the cached one.
+    """
+    sidecar = _sidecar_path(name)
+    if not sidecar.exists():
+        return True
+    try:
+        with open(sidecar) as f:
+            meta = json.load(f)
+        return int(meta.get("generation", -1)) < blob.generation
+    except Exception:
+        return True
+
+
+def write_sidecar(name, blob):
+    """Write a .meta.json sidecar after a successful download.
+
+    Args:
+        name (str): logical artifact name.
+        blob (google.cloud.storage.Blob): the blob that was downloaded.
+    """
+    sidecar = _sidecar_path(name)
+    meta = {
+        "blob_name": blob.name,
+        "generation": blob.generation,
+        "downloaded_at": datetime.now(timezone.utc).isoformat(),
+    }
+    try:
+        with open(sidecar, "w") as f:
+            json.dump(meta, f, indent=2)
+    except OSError as e:
+        raise CacheError(f"Failed to write cache sidecar {sidecar}: {e}") from e
+
+
+def ensure_subdir(subdir):
+    """Return a subdirectory of the cache dir, creating it if absent.
+
+    Args:
+        subdir (str): subdirectory name, e.g. "bdtopo" or "era5".
+
+    Returns:
+        pathlib.Path: absolute path to the subdirectory.
+    """
+    path = get_cache_dir() / subdir
+    path.mkdir(parents=True, exist_ok=True)
+    return path

buildingdata/config.py

@@ -0,0 +1,119 @@
+# -*- coding: utf-8 -*-
+import configparser
+import hashlib
+import os
+from pathlib import Path
+
+from platformdirs import user_data_dir
+
+_DEFAULT_BUCKET = "building-inference-data"
+_CONFIG_FILE = Path.home() / ".config" / "buildingdata" / "config.ini"
+
+
+def _install_id():
+    """Return a short, stable id for this package installation.
+
+    Derived from the on-disk location of the installed package, so that
+    each install (e.g. a separate virtualenv) maps to a distinct id while
+    reinstalling in place keeps the same one.
+
+    Returns:
+        str: 8-char hex digest identifying this installation.
+    """
+    install_root = str(Path(__file__).resolve().parent)
+    return hashlib.sha256(install_root.encode("utf-8")).hexdigest()[:8]
+
+
+def _default_cache_dir():
+    """Return the per-installation default cache directory.
+
+    Uses the platform user-data dir as the base and namespaces it by
+    installation id so multiple installs do not overwrite each other's
+    cache.
+
+    Returns:
+        pathlib.Path: absolute path to the default cache directory.
+    """
+    return Path(user_data_dir("buildingdata")) / "cache" / _install_id()
+
+
+def _read_config():
+    cfg = configparser.ConfigParser()
+    if _CONFIG_FILE.exists():
+        cfg.read(_CONFIG_FILE)
+    return cfg
+
+
+def get_bucket():
+    """Return the GCS bucket name.
+
+    Precedence: BUILDINGDATA_BUCKET env var → config file → default.
+
+    Returns:
+        str: GCS bucket name without gs:// prefix.
+    """
+    if "BUILDINGDATA_BUCKET" in os.environ:
+        return os.environ["BUILDINGDATA_BUCKET"]
+    cfg = _read_config()
+    return cfg.get("gcs", "bucket", fallback=_DEFAULT_BUCKET)
+
+
+def get_cache_dir():
+    """Return the local cache directory, creating it if absent.
+
+    Precedence: BUILDINGDATA_CACHE_DIR env var → config file → default.
+
+    Returns:
+        pathlib.Path: absolute path to the cache directory.
+    """
+    if "BUILDINGDATA_CACHE_DIR" in os.environ:
+        path = Path(os.environ["BUILDINGDATA_CACHE_DIR"])
+    else:
+        cfg = _read_config()
+        raw = cfg.get("cache", "dir", fallback=str(_default_cache_dir()))
+        path = Path(raw)
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def get_credentials_file():
+    """Return path to a GCS service account JSON, or None for anonymous access.
+
+    When None, the storage client reads public buckets anonymously, with no
+    authentication required.
+
+    Precedence: GOOGLE_APPLICATION_CREDENTIALS env var → config file → None.
+
+    Returns:
+        pathlib.Path or None: path to credentials JSON, or None.
+    """
+    if "GOOGLE_APPLICATION_CREDENTIALS" in os.environ:
+        return Path(os.environ["GOOGLE_APPLICATION_CREDENTIALS"])
+    cfg = _read_config()
+    raw = cfg.get("gcs", "credentials", fallback=None)
+    return Path(raw) if raw else None
+
+
+def write_config(bucket=None, cache_dir=None, credentials=None):
+    """Write or update ~/.config/buildingdata/config.ini.
+
+    Args:
+        bucket (str, optional): GCS bucket name.
+        cache_dir (str or pathlib.Path, optional): local cache directory.
+        credentials (str or pathlib.Path, optional): path to GCS service
+            account JSON. Pass None to leave unchanged.
+    """
+    _CONFIG_FILE.parent.mkdir(parents=True, exist_ok=True)
+    cfg = _read_config()
+    if not cfg.has_section("gcs"):
+        cfg.add_section("gcs")
+    if not cfg.has_section("cache"):
+        cfg.add_section("cache")
+    if bucket is not None:
+        cfg.set("gcs", "bucket", bucket)
+    if credentials is not None:
+        cfg.set("gcs", "credentials", str(credentials))
+    if cache_dir is not None:
+        cfg.set("cache", "dir", str(cache_dir))
+    with open(_CONFIG_FILE, "w") as f:
+        cfg.write(f)

buildingdata/exceptions.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+
+
+class BuildingDataError(Exception):
+    """Base exception for buildingdata errors."""
+
+
+class CacheError(BuildingDataError):
+    """Raised when a cache read or write operation fails."""
+
+
+class RemoteNotAvailableError(BuildingDataError):
+    """Raised when a remote endpoint returns a non-success status."""
+
+
+class ConfigurationError(BuildingDataError):
+    """Raised when required configuration (credentials, API key) is missing."""

buildingdata/gcs.py

@@ -0,0 +1,82 @@
+# -*- coding: utf-8 -*-
+from pathlib import Path
+
+from tqdm import tqdm
+
+from .config import get_bucket, get_credentials_file
+
+
+def get_client():
+    """Return a google.cloud.storage.Client.
+
+    Uses the credentials file from config if one is set. Otherwise returns
+    an anonymous client, which can read public buckets without any
+    authentication or Google Cloud project.
+
+    Returns:
+        google.cloud.storage.Client: storage client.
+    """
+    from google.cloud import storage
+
+    creds_file = get_credentials_file()
+    if creds_file is not None:
+        return storage.Client.from_service_account_json(str(creds_file))
+    return storage.Client.create_anonymous_client()
+
+
+def get_blob(name):
+    """Return the Blob object for a given name, or None if not found.
+
+    Args:
+        name (str): blob name inside the configured bucket.
+
+    Returns:
+        google.cloud.storage.Blob or None.
+    """
+    client = get_client()
+    bucket = client.bucket(get_bucket())
+    blob = bucket.blob(name)
+    blob.reload()
+    return blob if blob.exists() else None
+
+
+def download_blob(name, dest_path, show_progress=True):
+    """Download a blob from the configured bucket to dest_path.
+
+    Args:
+        name (str): blob name inside the bucket, e.g. "census_latest.parquet".
+        dest_path (pathlib.Path): local destination file path.
+        show_progress (bool): display a tqdm progress bar. Defaults to True.
+    """
+    from google.cloud import storage
+
+    dest_path = Path(dest_path)
+    dest_path.parent.mkdir(parents=True, exist_ok=True)
+
+    client = get_client()
+    bucket = client.bucket(get_bucket())
+    blob = bucket.blob(name)
+    blob.reload()
+
+    total = blob.size or 0
+    tmp_path = dest_path.with_suffix(dest_path.suffix + ".tmp")
+
+    with open(tmp_path, "wb") as f:
+        if show_progress:
+            with tqdm(
+                total=total,
+                unit="B",
+                unit_scale=True,
+                desc=name,
+                leave=True,
+            ) as bar:
+                def _callback(chunk):
+                    bar.update(len(chunk))
+
+                blob.download_to_file(f, checksum="md5", raw_download=True)
+                bar.update(total - bar.n)
+        else:
+            blob.download_to_file(f)
+
+    tmp_path.replace(dest_path)
+    return blob

buildingdata/reference/__init__.py

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+from .census import get_census
+from .diagnosis import get_diagnosis
+from .districts import get_districts
+from .gas_network import get_gas_network

buildingdata/reference/census.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+import polars as pl
+
+from ..cache import cache_path, is_cached, needs_refresh, write_sidecar
+from ..exceptions import RemoteNotAvailableError
+from ..gcs import download_blob, get_blob
+
+_BLOB_NAME = "census_latest.parquet"
+
+
+def get_census(city_group_list=None, refresh=False):
+    """Return the processed INSEE census DataFrame, optionally pre-filtered.
+
+    Downloads census_latest.parquet from GCS to the local cache on first call
+    (or when refresh=True). Filtering by city_group_list uses Polars lazy scan
+    so only the needed rows are loaded into memory.
+
+    Args:
+        city_group_list (list of str, optional): EPCI codes to filter on. If
+            None, the full national census is returned. Defaults to None.
+        refresh (bool): force re-download even if the cache is warm.
+            Defaults to False.
+
+    Returns:
+        polars.DataFrame: census records with columns occupancy_type,
+            occupant_status, living_area_class, occupant_count, heating_system,
+            residential_type, construction_year_class, district, city,
+            city_group, department, region, main_cooking_energy,
+            secondary_cooking_energy, ipondl.
+    """
+    dest = cache_path(_BLOB_NAME)
+
+    if refresh or not is_cached(_BLOB_NAME):
+        blob = get_blob(_BLOB_NAME)
+        if blob is None:
+            raise RemoteNotAvailableError(f"Blob {_BLOB_NAME!r} not found in GCS bucket.")
+        download_blob(_BLOB_NAME, dest)
+        write_sidecar(_BLOB_NAME, blob)
+    elif refresh:
+        blob = get_blob(_BLOB_NAME)
+        if blob is not None and needs_refresh(_BLOB_NAME, blob):
+            download_blob(_BLOB_NAME, dest)
+            write_sidecar(_BLOB_NAME, blob)
+
+    lf = pl.scan_parquet(dest)
+    if city_group_list is not None:
+        lf = lf.filter(pl.col("city_group").is_in(city_group_list))
+    return lf.collect()

buildingdata/reference/diagnosis.py

@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+import polars as pl
+
+from ..cache import cache_path, is_cached, needs_refresh, write_sidecar
+from ..exceptions import RemoteNotAvailableError
+from ..gcs import download_blob, get_blob
+
+_BLOB_NAME = "energy_performance_diagnosis_latest.parquet"
+
+# Heating/DHW energies excluded from inference (no meaningful DPE data for coal)
+_EXCLUDED_ENERGIES = ["Charbon"]
+
+
+def get_diagnosis(refresh=False):
+    """Return the cleaned DPE energy performance diagnosis DataFrame.
+
+    Downloads energy_performance_diagnosis_latest.parquet from GCS on first
+    call. Applies the filtering and type casts that previously lived in
+    buildingmodel/io/diagnosis.py so that buildingmodel receives a clean frame.
+
+    Args:
+        refresh (bool): force re-download even if the cache is warm.
+            Defaults to False.
+
+    Returns:
+        polars.DataFrame: DPE records with columns heating_system (Categorical),
+            region (Int64), backup_heating_energy, dhw_energy, and all U-value
+            and efficiency columns used by inference/building_attributes.py.
+    """
+    dest = cache_path(_BLOB_NAME)
+
+    if not is_cached(_BLOB_NAME) or refresh:
+        blob = get_blob(_BLOB_NAME)
+        if blob is None:
+            raise RemoteNotAvailableError(f"Blob {_BLOB_NAME!r} not found in GCS bucket.")
+        if not is_cached(_BLOB_NAME) or needs_refresh(_BLOB_NAME, blob):
+            download_blob(_BLOB_NAME, dest)
+            write_sidecar(_BLOB_NAME, blob)
+
+    df = pl.read_parquet(dest)
+
+    # Remove records with coal heating/DHW — no useful inference data
+    df = df.filter(
+        ~pl.col("backup_heating_energy").is_in(_EXCLUDED_ENERGIES)
+        & ~pl.col("dhw_energy").is_in(_EXCLUDED_ENERGIES)
+    )
+
+    df = df.with_columns([
+        pl.col("heating_system").cast(pl.Categorical),
+        pl.col("region").cast(pl.Int64),
+    ])
+
+    if "living_area" in df.columns:
+        df = df.drop(["living_area"])
+    if "living_area_class" in df.columns:
+        df = df.drop(["living_area_class"])
+
+    return df

buildingdata/reference/districts.py

@@ -0,0 +1,41 @@
+# -*- coding: utf-8 -*-
+import geopandas as gpd
+
+from ..cache import cache_path, is_cached, needs_refresh, write_sidecar
+from ..exceptions import RemoteNotAvailableError
+from ..gcs import download_blob, get_blob
+
+_BLOB_NAME = "districts_latest.parquet"
+
+
+def get_districts(bbox=None, refresh=False):
+    """Return the IRIS district boundary GeoDataFrame in EPSG:2154.
+
+    Downloads districts_latest.parquet from GCS on first call.
+
+    Args:
+        bbox (tuple of float, optional): (minx, miny, maxx, maxy) bounding box
+            in EPSG:2154 passed to geopandas.read_parquet for spatial filtering.
+            If None, the full national layer is returned. Defaults to None.
+        refresh (bool): force re-download even if the cache is warm.
+            Defaults to False.
+
+    Returns:
+        geopandas.GeoDataFrame: IRIS polygons in EPSG:2154 with columns
+            district, city, city_name, city_group, department, region,
+            has_network_city_level, has_network_grdf_data, geometry.
+    """
+    dest = cache_path(_BLOB_NAME)
+
+    if not is_cached(_BLOB_NAME) or refresh:
+        blob = get_blob(_BLOB_NAME)
+        if blob is None:
+            raise RemoteNotAvailableError(f"Blob {_BLOB_NAME!r} not found in GCS bucket.")
+        if not is_cached(_BLOB_NAME) or needs_refresh(_BLOB_NAME, blob):
+            download_blob(_BLOB_NAME, dest)
+            write_sidecar(_BLOB_NAME, blob)
+
+    kwargs = {}
+    if bbox is not None:
+        kwargs["bbox"] = bbox
+    return gpd.read_parquet(dest, **kwargs)

buildingdata/reference/gas_network.py

@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+import geopandas as gpd
+
+from ..cache import cache_path, is_cached, needs_refresh, write_sidecar
+from ..exceptions import RemoteNotAvailableError
+from ..gcs import download_blob, get_blob
+
+_BLOB_NAME = "gas_network_route_latest.gpkg"
+
+
+def get_gas_network(bbox=None, refresh=False):
+    """Return the GRDF gas pipeline network GeoDataFrame in EPSG:2154.
+
+    Downloads gas_network_route_latest.gpkg from GCS on first call (~789 MB).
+    The bbox argument is passed to geopandas.read_file for GDAL-level spatial
+    filtering so that only the local area is loaded from the GeoPackage.
+
+    Args:
+        bbox (tuple of float, optional): (minx, miny, maxx, maxy) in EPSG:2154.
+            If None, the full national layer is returned. Defaults to None.
+        refresh (bool): force re-download even if the cache is warm.
+            Defaults to False.
+
+    Returns:
+        geopandas.GeoDataFrame: gas pipeline routes in EPSG:2154.
+    """
+    dest = cache_path(_BLOB_NAME)
+
+    if not is_cached(_BLOB_NAME) or refresh:
+        blob = get_blob(_BLOB_NAME)
+        if blob is None:
+            raise RemoteNotAvailableError(f"Blob {_BLOB_NAME!r} not found in GCS bucket.")
+        if not is_cached(_BLOB_NAME) or needs_refresh(_BLOB_NAME, blob):
+            download_blob(_BLOB_NAME, dest)
+            write_sidecar(_BLOB_NAME, blob)
+
+    kwargs = {}
+    if bbox is not None:
+        kwargs["bbox"] = bbox
+    return gpd.read_file(dest, **kwargs)

buildingdata/simulation/__init__.py

@@ -0,0 +1,3 @@
+# -*- coding: utf-8 -*-
+from .bdtopo import get_bdtopo
+from .era5 import get_era5_climate

buildingdata/simulation/bdtopo.py

@@ -0,0 +1,87 @@
+# -*- coding: utf-8 -*-
+import geopandas as gpd
+import requests
+
+from ..cache import ensure_subdir
+from ..exceptions import RemoteNotAvailableError
+from ..reference.districts import get_districts
+
+# IGN Géoplateforme WFS endpoint for BDTOPO buildings
+_IGN_BASE_URL = (
+    "https://data.geopf.fr/wfs/ows"
+    "?SERVICE=WFS"
+    "&VERSION=2.0.0"
+    "&REQUEST=GetFeature"
+    "&TYPENAMES=BDTOPO_V3:batiment"
+    "&OUTPUTFORMAT=application/json"
+    "&SRSNAME=EPSG:2154"
+    "&BBOX={minx},{miny},{maxx},{maxy},urn:ogc:def:crs:EPSG::2154"
+)
+
+_TIMEOUT = 120  # seconds
+
+
+def _cache_path(iris_code):
+    subdir = ensure_subdir("bdtopo")
+    return subdir / f"bdtopo_iris_{iris_code}.parquet"
+
+
+def _sidecar_path(iris_code):
+    subdir = ensure_subdir("bdtopo")
+    return subdir / f"bdtopo_iris_{iris_code}.parquet.meta.json"
+
+
+def get_bdtopo(iris_code, refresh=False):
+    """Download BDTOPO buildings for one IRIS from the IGN Géoplateforme WFS.
+
+    The GeoDataFrame is cached as a parquet file under
+    ~/.cache/buildingdata/bdtopo/bdtopo_iris_<iris_code>.parquet.
+    Column names are the raw French BDTOPO attribute names (hauteur,
+    nombre_de_logements, etc.) so the result can be passed directly as
+    building_data to buildingmodel.Simulation.
+
+    Args:
+        iris_code (str): 9-digit IRIS code, e.g. "461290000".
+        refresh (bool): force re-download even if cached. Defaults to False.
+
+    Returns:
+        geopandas.GeoDataFrame: BDTOPO buildings in EPSG:2154.
+
+    Raises:
+        RemoteNotAvailableError: if the IGN endpoint returns a non-200 status
+            or returns no features for the given IRIS code.
+    """
+    dest = _cache_path(iris_code)
+
+    if dest.exists() and not refresh:
+        return gpd.read_parquet(dest)
+
+    # Get the district geometry to derive the bounding box and filter buildings
+    districts = get_districts()
+    iris_geom = districts[districts["district"] == iris_code]
+    if iris_geom.empty:
+        raise RemoteNotAvailableError(f"IRIS code {iris_code!r} not found in districts.")
+
+    district_geom = iris_geom.iloc[0].geometry
+    bbox = district_geom.bounds  # (minx, miny, maxx, maxy)
+
+    url = _IGN_BASE_URL.format(minx=bbox[0], miny=bbox[1], maxx=bbox[2], maxy=bbox[3])
+    response = requests.get(url, timeout=_TIMEOUT)
+    if response.status_code != 200:
+        raise RemoteNotAvailableError(
+            f"IGN Géoplateforme returned HTTP {response.status_code} for IRIS {iris_code!r}."
+        )
+
+    features = response.json()["features"]
+    if not features:
+        raise RemoteNotAvailableError(
+            f"IGN Géoplateforme returned no buildings for IRIS {iris_code!r}."
+        )
+
+    gdf = gpd.GeoDataFrame.from_features(features, crs="EPSG:2154")
+
+    # Filter to keep only buildings that intersect with the district geometry
+    gdf = gdf[gdf.geometry.intersects(district_geom)].copy()
+
+    gdf.to_parquet(dest)
+    return gdf