buildingdata 0.5.0__tar.gz → 0.7.0__tar.gz

{buildingdata-0.5.0 → buildingdata-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: buildingdata
-Version: 0.5.0
+Version: 0.7.0
 Summary: Data management layer for buildingmodel — reference data download, BDTOPO retrieval, ERA5 weather
 License-Expression: MIT
 Requires-Python: >=3.10

{buildingdata-0.5.0 → buildingdata-0.7.0}/buildingdata/reference/diagnosis.py

@@ -56,7 +56,7 @@ def get_diagnosis(refresh=False):
               ``dhw_energy``, ``heating_mode``/``dhw_mode`` (individual /
               collective / mixed), the ``*_efficiency`` and ``*_scop`` pairs,
               ``intermittency_factor``, ``backup_heating_share``,
-              ``dhw_storage_volume``;
+              ``dhw_storage_volume``, ``heating_emitter_type``;
             * observed performance — ``energy_class``, ``ghg_class`` and the
               ``annual_*_per_area`` intensities, for calibrating simulated
               output against the diagnosis itself.
@@ -69,6 +69,16 @@ def get_diagnosis(refresh=False):
             understates heat-pump performance roughly threefold, hence the two
             columns.
 
+            ``heating_system`` stays the coarse, census-joinable class — every
+            heat pump collapses to ``"electric heat pump"``. ``heat_pump_type``
+            (``air/air``, ``air/water``, ``water/water``, ``brine/water``,
+            ``geothermal``, ``hybrid``) and ``heat_pump_installation_period``
+            recover the configuration detail the census join key cannot carry,
+            and are **non-null only for heat-pump records**.
+            ``heating_emitter_type`` (``air``, ``floor heating``,
+            ``radiator low/medium``, ``radiator high``) is populated for every
+            system.
+
     Raises:
         RemoteNotAvailableError: if the blob is not found in the GCS bucket.
         SchemaValidationError: if the fetched frame is missing one of the

{buildingdata-0.5.0 → buildingdata-0.7.0}/buildingdata/simulation/bdtopo.py

@@ -55,6 +55,47 @@ _TIMEOUT = 120  # seconds
 # Server-side maximum WFS page size. Requesting more is silently capped here.
 _PAGE_SIZE = 5000
 
+# Minimum share of a footprint's area that must fall inside the IRIS polygon for
+# the footprint to belong to that IRIS. At 0.5 a footprint belongs to whichever
+# IRIS holds most of it -- and, in the measure-zero case of an exactly even
+# split, to both, which is the pre-existing behaviour for a shared border
+# building and the safe side of the tie (a strict > 0.5 would drop it from
+# every IRIS).
+#
+# The BBOX query returns everything around the IRIS, so the result has to be
+# filtered down to the IRIS itself. Filtering on `intersects` keeps every
+# footprint straddling the boundary, and a consumer that attributes each
+# footprint to the district holding most of its area then sees a handful of
+# *neighbouring* district codes in what is meant to be one IRIS's stock --
+# enough, in buildingmodel, for one straddling footprint to import a whole
+# neighbouring IRIS's census housing stock (buildingmodel#55). A footprint
+# belongs to the IRIS holding at least half of it, which is the same rule
+# buildingcalibration's BuildingLoader applies downstream.
+_MEMBERSHIP_THRESHOLD = 0.5
+
+
+def _filter_to_district(gdf, district_geom):
+    """Keep the footprints the IRIS polygon holds at least half of.
+
+    Zero-area geometries (points, lines -- test doubles and the occasional
+    degenerate BDTOPO record) have no area share to compute, so they fall back
+    to plain intersection.
+
+    Args:
+        gdf (geopandas.GeoDataFrame): candidate buildings, EPSG:2154.
+        district_geom (shapely geometry): the IRIS polygon, EPSG:2154.
+
+    Returns:
+        geopandas.GeoDataFrame: the subset belonging to the IRIS.
+    """
+    area = gdf.geometry.area
+    inside = gdf.geometry.intersection(district_geom)
+    share = inside.area.where(area > 0.0, 0.0) / area.where(area > 0.0, 1.0)
+    belongs = (share >= _MEMBERSHIP_THRESHOLD) | (
+        (area <= 0.0) & gdf.geometry.intersects(district_geom)
+    )
+    return gdf[belongs]
+
 
 def _fetch_all_wfs_features(base_url, iris_code):
     """Page a BDTOPO WFS GetFeature query to completion.
@@ -157,8 +198,8 @@ def _fetch_wfs(iris_code, district_geom):
         district_geom (shapely geometry): the IRIS polygon (EPSG:2154).
 
     Returns:
-        geopandas.GeoDataFrame: buildings intersecting the district polygon,
-        EPSG:2154, raw French attribute names.
+        geopandas.GeoDataFrame: the buildings the district polygon holds at
+        least half of, EPSG:2154, raw French attribute names.
 
     Raises:
         RemoteNotAvailableError: on a non-200 WFS status or an empty result.
@@ -182,13 +223,18 @@ def _fetch_wfs(iris_code, district_geom):
 
     require_columns(gdf, _REQUIRED_COLUMNS, f"BDTOPO buildings (IRIS {iris_code})")
 
-    # Filter to keep only buildings that intersect with the district geometry
-    return gdf[gdf.geometry.intersects(district_geom)].copy()
+    return _filter_to_district(gdf, district_geom).copy()
 
 
 def get_bdtopo(iris_code, refresh=False, source="auto"):
     """Return BDTOPO buildings for one IRIS, from the bulk cache or the WFS.
 
+    A footprint belongs to the IRIS holding at least half of its area, so a
+    footprint straddling the boundary no longer carries a neighbouring
+    district code into the result. Note this tightened in 0.7.0 (it was a
+    plain ``intersects`` before): a cache written by an earlier version still
+    holds the straddlers, pass ``refresh=True`` once to rewrite it.
+
     The GeoDataFrame is cached as a parquet file under
     ~/.cache/buildingdata/bdtopo/bdtopo_iris_<iris_code>.parquet — the same
     cache file whichever source produced it. Column names are the raw French
@@ -212,8 +258,8 @@ def get_bdtopo(iris_code, refresh=False, source="auto"):
     ``nombre_de_logements`` a dwelling count.
 
     Returns:
-        geopandas.GeoDataFrame: BDTOPO buildings in EPSG:2154, raw French
-            attribute names preserved.
+        geopandas.GeoDataFrame: the BDTOPO buildings the IRIS holds at least
+            half of, EPSG:2154, raw French attribute names preserved.
 
     Raises:
         ValueError: if ``source`` is not one of "auto", "bulk", "wfs".
@@ -267,7 +313,7 @@ def get_bdtopo(iris_code, refresh=False, source="auto"):
         # Lock-free bulk read; read_department raises CacheError with the
         # prefetch hint when source="bulk" and the partition is missing.
         gdf = bdtopo_bulk.read_department(department, bbox=district_geom.bounds)
-        gdf = gdf[gdf.geometry.intersects(district_geom)].copy().reset_index(drop=True)
+        gdf = _filter_to_district(gdf, district_geom).copy().reset_index(drop=True)
         require_columns(gdf, _REQUIRED_COLUMNS, f"BDTOPO buildings (IRIS {iris_code})")
 
         with file_lock(lock_file):

{buildingdata-0.5.0 → buildingdata-0.7.0}/buildingdata/simulation/bdtopo_bulk.py

@@ -44,7 +44,7 @@ from ..exceptions import (
     RemoteNotAvailableError,
 )
 from ..validation import require_columns
-from .bdtopo import _REQUIRED_COLUMNS
+from .bdtopo import _REQUIRED_COLUMNS, _filter_to_district
 
 # IGN Géoplateforme téléchargement endpoints (confirmed live 2026-08-06):
 #   * catalog: Atom feed at <resource>?zone=D0XX&page=N, paged via the
@@ -523,9 +523,11 @@ def get_bdtopo_bulk(iris_codes):
     Groups the requested IRIS by département, then per département performs a
     single bbox-pushdown partition read over the codes' combined bounds and a
     single spatial join against all the IRIS polygons — sharing the (costly)
-    file scan across the IRIS instead of paying it once per IRIS. A building
-    straddling two requested IRIS appears in both results (same semantics as
-    the per-IRIS ``intersects`` filter of :func:`~.bdtopo.get_bdtopo`).
+    file scan across the IRIS instead of paying it once per IRIS. A footprint
+    belongs to the IRIS holding at least half of its area, so a building
+    straddling two requested IRIS appears in the one holding most of it, and
+    in both only when the split is exactly even (same semantics as
+    :func:`~.bdtopo.get_bdtopo`).
 
     Source: local GeoParquet partitions built by :func:`prefetch_bdtopo` from
     the IGN départemental editions (vintage recorded in the bulk manifest);
@@ -536,9 +538,9 @@ def get_bdtopo_bulk(iris_codes):
             départements.
 
     Returns:
-        dict[str, geopandas.GeoDataFrame]: IRIS code -> buildings intersecting
-        that IRIS, EPSG:2154, raw French attribute names, same schema as the
-        WFS path (no join helper columns).
+        dict[str, geopandas.GeoDataFrame]: IRIS code -> the buildings that IRIS
+        holds at least half of, EPSG:2154, raw French attribute names, same
+        schema as the WFS path (no join helper columns).
 
     Raises:
         BuildingDataError: if an IRIS code is unknown to the districts layer.
@@ -569,11 +571,10 @@ def get_bdtopo_bulk(iris_codes):
         joined = gpd.sjoin(gdf, join_frame, how="inner", predicate="intersects")
         drop = [c for c in ("_iris", "index_right") if c in joined.columns]
         for code in dep_codes:
-            sub = (
-                joined[joined["_iris"] == code]
-                .drop(columns=drop)
-                .reset_index(drop=True)
-            )
+            sub = joined[joined["_iris"] == code].drop(columns=drop)
+            sub = _filter_to_district(
+                sub, dep_sel[dep_sel["district"] == code].geometry.iloc[0]
+            ).reset_index(drop=True)
             require_columns(
                 sub, _REQUIRED_COLUMNS, f"BDTOPO bulk buildings (IRIS {code})"
             )

{buildingdata-0.5.0 → buildingdata-0.7.0}/buildingdata/tests/test_bulk.py

@@ -530,7 +530,8 @@ def test_get_bdtopo_bulk_splits_multi_iris_and_shares_border_buildings(
     assert set(results) == {IRIS_A, IRIS_B}
     assert sorted(results[IRIS_A]["hauteur"]) == [9.0, 12.0]
     assert sorted(results[IRIS_B]["hauteur"]) == [6.0, 12.0]
-    # The border building (hauteur=12) appears in both IRIS frames.
+    # The border building (hauteur=12) is split exactly evenly between the two
+    # IRIS, so the >= 0.5 membership rule leaves it in both frames.
     for frame in results.values():
         assert 12.0 in set(frame["hauteur"])
         # sjoin helper columns must not leak into the results.
@@ -539,6 +540,39 @@ def test_get_bdtopo_bulk_splits_multi_iris_and_shares_border_buildings(
         assert frame.crs.to_epsg() == 2154
 
 
+def test_get_bdtopo_bulk_gives_a_border_building_to_the_iris_holding_most_of_it(
+    monkeypatch, tmp_path
+):
+    """A footprint 70 % inside IRIS_A must not appear in IRIS_B's stock.
+
+    Filtering on `intersects` used to hand every straddling footprint to both
+    IRIS, which lets a consumer read a neighbouring district code out of what
+    is meant to be one IRIS's building stock (buildingmodel#55).
+    """
+    frame = gpd.GeoDataFrame(
+        {
+            "hauteur": [9.0],
+            "nombre_de_logements": [4],
+            "usage_1": ["Résidentiel"],
+        },
+        # 100 m wide, 70 m of it on the IRIS_A side of x = 652000.
+        geometry=[box(651930, 6860400, 652030, 6860500)],
+        crs="EPSG:2154",
+    )
+    frame.to_parquet(bdtopo_bulk.partition_path(DEP), write_covering_bbox=True)
+    bulk.update_manifest(
+        "bdtopo", DEP, {"status": "complete", "vintage": "BDTOPO_TEST_EDITION"}
+    )
+    monkeypatch.setattr(
+        "buildingdata.reference.districts.get_districts", _bulk_districts
+    )
+
+    results = bdtopo_bulk.get_bdtopo_bulk([IRIS_A, IRIS_B])
+
+    assert sorted(results[IRIS_A]["hauteur"]) == [9.0]
+    assert results[IRIS_B].empty
+
+
 def test_get_bdtopo_bulk_rejects_unknown_iris(monkeypatch):
     monkeypatch.setattr(
         "buildingdata.reference.districts.get_districts", _bulk_districts
@@ -581,6 +615,48 @@ def test_bdtopo_auto_falls_back_to_wfs_without_a_partition(monkeypatch):
     assert len(gdf) == 1
 
 
+def test_bdtopo_wfs_drops_a_footprint_mostly_outside_the_iris(monkeypatch):
+    """The BBOX query reaches past the IRIS; only its own footprints come back.
+
+    A footprint whose majority lies in the neighbouring IRIS used to be kept by
+    the `intersects` filter, and downstream carried that neighbour's district
+    code into the frame (buildingmodel#55).
+    """
+    monkeypatch.setattr(bdtopo_mod, "get_districts", _bulk_districts)
+    collection = {
+        "features": [
+            {
+                "type": "Feature",
+                "geometry": {
+                    "type": "Polygon",
+                    # 100 m wide, only 30 m of it on the IRIS_A side.
+                    "coordinates": [
+                        [
+                            [651970.0, 6860400.0],
+                            [652070.0, 6860400.0],
+                            [652070.0, 6860500.0],
+                            [651970.0, 6860500.0],
+                            [651970.0, 6860400.0],
+                        ]
+                    ],
+                },
+                "properties": {
+                    "hauteur": 9.0,
+                    "nombre_de_logements": 4,
+                    "usage_1": "Résidentiel",
+                },
+            }
+        ]
+    }
+    monkeypatch.setattr(
+        bdtopo_mod.requests, "get", Mock(return_value=FakeResponse(200, collection))
+    )
+
+    gdf = bdtopo_mod.get_bdtopo(IRIS_A, source="wfs")
+
+    assert gdf.empty
+
+
 def test_bdtopo_source_bulk_without_partition_raises_with_prefetch_hint(monkeypatch):
     monkeypatch.setattr(bdtopo_mod, "get_districts", _bulk_districts)
     with pytest.raises(CacheError, match="prefetch bdtopo"):

{buildingdata-0.5.0 → buildingdata-0.7.0}/buildingdata/tests/test_pipeline_diagnosis.py

@@ -99,6 +99,8 @@ UPSTREAM_DEFAULTS = {
     "rendement_regulation_systeme_1": 0.99,
     "i0_systeme_1": 0.9,
     "conso_ch_systeme_1": 8000.0,
+    "temp_distribution_ch_systeme_1": "moyenne",
+    "type_emission_distribution_systeme_1": "Radiateurs à eau chaude - robinet thermostatique",
     # heating system 2 (a wood stove backing up the boiler)
     "type_energie_systeme_2": "Bois – Bûches",
     "rendement_generation_systeme_2": 0.5,
@@ -175,6 +177,83 @@ def test_a_heat_pump_gets_a_scop_and_no_efficiency(script):
     assert out["main_heating_system_scop"][0] == pytest.approx(3.0 * 0.95 * 0.95 * 0.99)
 
 
+def test_heat_pump_detail_is_parsed_from_the_generator_label(script):
+    out = _run(
+        script,
+        {
+            "type_generateur_ch_systeme_1": "PAC air/eau installée après 2017",
+            "rendement_generation_systeme_1": None,
+            "scop_systeme_1": 3.0,
+        },
+    )
+
+    assert out["heat_pump_type"][0] == "air/water"
+    assert out["heat_pump_installation_period"][0] == "[2017, 2100]"
+
+
+def test_a_hybrid_heat_pump_label_is_not_swallowed_by_the_air_water_pattern(script):
+    # The 3 hybrid records' label is "pompe à chaleur hybride : partie pompe à
+    # chaleur PAC air/eau installée après 2017" (real 11-12-2025 vintage) — it
+    # contains "air/eau" too, so "hybride" must be tested first or the hybrid
+    # reading is lost.
+    out = _run(
+        script,
+        {
+            "type_generateur_ch_systeme_1": (
+                "pompe à chaleur hybride : partie pompe à chaleur PAC air/eau"
+                " installée après 2017"
+            ),
+            "rendement_generation_systeme_1": None,
+            "scop_systeme_1": 3.0,
+        },
+    )
+
+    assert out["heat_pump_type"][0] == "hybrid"
+
+
+def test_heat_pump_detail_is_null_for_a_non_heat_pump_record(script):
+    out = _run(script)
+
+    assert out["heating_system"][0] != "electric heat pump"
+    assert out["heat_pump_type"][0] is None
+    assert out["heat_pump_installation_period"][0] is None
+
+
+def test_heating_emitter_type_is_air_when_there_is_no_distribution_loop(script):
+    # The bulk of air/air heat pumps report no distribution network at all.
+    out = _run(
+        script,
+        {
+            "type_generateur_ch_systeme_1": "PAC air/air installée à partir de 2015",
+            "rendement_generation_systeme_1": None,
+            "scop_systeme_1": 3.0,
+            "temp_distribution_ch_systeme_1": "abscence de réseau de distribution",
+            "type_emission_distribution_systeme_1": "Soufflage d'air chaud",
+        },
+    )
+
+    assert out["heating_emitter_type"][0] == "air"
+
+
+def test_heating_emitter_type_separates_floor_heating_from_a_radiator_loop(script):
+    # Both configurations report "moyenne" in the coarse temperature column —
+    # only the fine emission label tells them apart.
+    floor, radiator = _run(
+        script,
+        {"type_emission_distribution_systeme_1": "Plancher chauffant basse température"},
+        {"type_emission_distribution_systeme_1": "Radiateurs à eau chaude - robinet thermostatique"},
+    )["heating_emitter_type"]
+
+    assert floor == "floor heating"
+    assert radiator == "radiator low/medium"
+
+
+def test_heating_emitter_type_maps_the_high_temperature_class(script):
+    out = _run(script, {"temp_distribution_ch_systeme_1": "haute"})
+
+    assert out["heating_emitter_type"][0] == "radiator high"
+
+
 def test_a_multi_building_gas_plant_is_classified_as_a_heat_network(script):
     # "Chaudière(s) gaz multi bâtiment modélisée comme un réseau de chaleur"
     # matches both a gas and a heat-network pattern. ADEME reports the fuel as
@@ -273,11 +352,17 @@ def test_every_published_column_is_populated(script):
     out = _run(script)
 
     assert set(out.columns) == set(script.COLUMN_SELECTION)
-    # The SCOP columns are null by construction for a non-heat-pump record.
-    scop_columns = {"main_heating_system_scop", "backup_heating_system_scop"}
+    # The SCOP columns, and the heat-pump detail columns, are null by
+    # construction for the default non-heat-pump record.
+    expected_null_columns = {
+        "main_heating_system_scop",
+        "backup_heating_system_scop",
+        "heat_pump_type",
+        "heat_pump_installation_period",
+    }
     unexpected_nulls = [
         column
         for column in out.columns
-        if column not in scop_columns and out[column].null_count()
+        if column not in expected_null_columns and out[column].null_count()
     ]
     assert unexpected_nulls == []

{buildingdata-0.5.0 → buildingdata-0.7.0}/buildingdata.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: buildingdata
-Version: 0.5.0
+Version: 0.7.0
 Summary: Data management layer for buildingmodel — reference data download, BDTOPO retrieval, ERA5 weather
 License-Expression: MIT
 Requires-Python: >=3.10

{buildingdata-0.5.0 → buildingdata-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "buildingdata"
-version = "0.5.0"
+version = "0.7.0"
 description = "Data management layer for buildingmodel — reference data download, BDTOPO retrieval, ERA5 weather"
 
 readme = "README.md"