buildingdata 0.4.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: buildingdata
-Version: 0.4.0
+Version: 0.5.0
 Summary: Data management layer for buildingmodel — reference data download, BDTOPO retrieval, ERA5 weather
 License-Expression: MIT
 Requires-Python: >=3.10
@@ -76,18 +76,25 @@ buildingdata configure --bucket my-bucket --cache-dir ~/.cache/buildingdata
 
 ## What it provides
 
-| Function | Source | Returns |
-| --- | --- | --- |
-| `get_census()` | INSEE census (GCS) | polars `DataFrame` |
-| `get_districts()` | IRIS geometries (GCS) | geopandas `GeoDataFrame` |
-| `get_diagnosis()` | ADEME energy performance diagnoses (GCS) | polars `DataFrame` |
-| `get_gas_network()` | GRDF gas network routes (GCS) | geopandas `GeoDataFrame` |
-| `get_bdtopo(iris_code)` | IGN Géoplateforme WFS (live) | geopandas `GeoDataFrame` |
-| `get_era5_climate(lat, lon, year)` | Copernicus CDS (live) | path to EPW file |
+| Function | Source | Returns | Consumed by |
+| --- | --- | --- | --- |
+| `get_census()` | INSEE census (GCS) | polars `DataFrame` | buildingmodel — dwelling inference |
+| `get_districts()` | IRIS geometries (GCS) | geopandas `GeoDataFrame` | buildingmodel — geocoding; building_eload — district lookup |
+| `get_diagnosis()` | ADEME energy performance diagnoses (GCS) | polars `DataFrame` | buildingmodel — envelope & system inference |
+| `get_gas_network()` | GRDF gas network routes (GCS) | geopandas `GeoDataFrame` | buildingmodel — gas-connection inference |
+| `get_ore()` | Agence ORE annual consumption per IRIS (GCS) | polars `DataFrame` | building_eload — calibration target |
+| `get_enedis_national()` / `get_enedis_regional()` | Enedis conso-inf36 measured consumption (GCS) | polars `DataFrame` | building_eload — validation reference |
+| `get_elmas(table)` | ELMAS non-residential load curves (GCS) | polars `DataFrame` | building_eload — non-residential model |
+| `get_occupant_diaries()` | synthetic occupant activity calendar (GCS) | polars `DataFrame` | building_eload — occupancy models |
+| `get_elecdom()` | Enedis panel Elecdom end-use load curves (GCS) | polars `DataFrame` | provenance only — source of building_eload constants |
+| `get_bdtopo(iris_code)` | IGN Géoplateforme WFS (live) or bulk cache | geopandas `GeoDataFrame` | building_eload → buildingmodel — input geometry |
+| `get_era5_climate(lat, lon, year)` | Copernicus CDS (live) or bulk cache | path to EPW file | buildingmodel — weather boundary condition |
 
 Reference datasets are pulled from a public Google Cloud Storage bucket and
 cached locally with generation-based freshness checks. French geospatial data
-uses CRS **EPSG:2154 (Lambert-93)**.
+uses CRS **EPSG:2154 (Lambert-93)**. The documentation page *Datasets*
+describes each dataset in detail — provenance, schema, units — and how
+`buildingmodel` / `building_eload` consume it.
 
 ## Bulk prefetch for large-scale simulations
 

{buildingdata-0.4.0 → buildingdata-0.5.0}/README.md

@@ -40,18 +40,25 @@ buildingdata configure --bucket my-bucket --cache-dir ~/.cache/buildingdata
 
 ## What it provides
 
-| Function | Source | Returns |
-| --- | --- | --- |
-| `get_census()` | INSEE census (GCS) | polars `DataFrame` |
-| `get_districts()` | IRIS geometries (GCS) | geopandas `GeoDataFrame` |
-| `get_diagnosis()` | ADEME energy performance diagnoses (GCS) | polars `DataFrame` |
-| `get_gas_network()` | GRDF gas network routes (GCS) | geopandas `GeoDataFrame` |
-| `get_bdtopo(iris_code)` | IGN Géoplateforme WFS (live) | geopandas `GeoDataFrame` |
-| `get_era5_climate(lat, lon, year)` | Copernicus CDS (live) | path to EPW file |
+| Function | Source | Returns | Consumed by |
+| --- | --- | --- | --- |
+| `get_census()` | INSEE census (GCS) | polars `DataFrame` | buildingmodel — dwelling inference |
+| `get_districts()` | IRIS geometries (GCS) | geopandas `GeoDataFrame` | buildingmodel — geocoding; building_eload — district lookup |
+| `get_diagnosis()` | ADEME energy performance diagnoses (GCS) | polars `DataFrame` | buildingmodel — envelope & system inference |
+| `get_gas_network()` | GRDF gas network routes (GCS) | geopandas `GeoDataFrame` | buildingmodel — gas-connection inference |
+| `get_ore()` | Agence ORE annual consumption per IRIS (GCS) | polars `DataFrame` | building_eload — calibration target |
+| `get_enedis_national()` / `get_enedis_regional()` | Enedis conso-inf36 measured consumption (GCS) | polars `DataFrame` | building_eload — validation reference |
+| `get_elmas(table)` | ELMAS non-residential load curves (GCS) | polars `DataFrame` | building_eload — non-residential model |
+| `get_occupant_diaries()` | synthetic occupant activity calendar (GCS) | polars `DataFrame` | building_eload — occupancy models |
+| `get_elecdom()` | Enedis panel Elecdom end-use load curves (GCS) | polars `DataFrame` | provenance only — source of building_eload constants |
+| `get_bdtopo(iris_code)` | IGN Géoplateforme WFS (live) or bulk cache | geopandas `GeoDataFrame` | building_eload → buildingmodel — input geometry |
+| `get_era5_climate(lat, lon, year)` | Copernicus CDS (live) or bulk cache | path to EPW file | buildingmodel — weather boundary condition |
 
 Reference datasets are pulled from a public Google Cloud Storage bucket and
 cached locally with generation-based freshness checks. French geospatial data
-uses CRS **EPSG:2154 (Lambert-93)**.
+uses CRS **EPSG:2154 (Lambert-93)**. The documentation page *Datasets*
+describes each dataset in detail — provenance, schema, units — and how
+`buildingmodel` / `building_eload` consume it.
 
 ## Bulk prefetch for large-scale simulations
 

{buildingdata-0.4.0 → buildingdata-0.5.0}/buildingdata/__init__.py

@@ -4,6 +4,7 @@ from .reference import (
     get_census,
     get_diagnosis,
     get_districts,
+    get_elecdom,
     get_elmas,
     get_enedis_national,
     get_enedis_regional,

{buildingdata-0.4.0 → buildingdata-0.5.0}/buildingdata/gcs.py

@@ -27,16 +27,31 @@ def get_client():
 def get_blob(name):
     """Return the Blob object for a given name, or None if not found.
 
+    Returning None on a missing blob is the contract ``ensure_blob_cached``
+    relies on to raise a named
+    :class:`~buildingdata.exceptions.RemoteNotAvailableError` -- which is in
+    turn what every ``get_X`` accessor documents under ``Raises``. ``reload()``
+    is what populates the blob's metadata (``generation``, size) used by the
+    cache freshness check, but it raises ``NotFound`` on a missing object
+    *before* ``exists()`` is ever reached, so it is caught here. Without this,
+    an accessor whose blob has not been staged yet surfaced an opaque
+    ``google.api_core.exceptions.NotFound`` instead of the documented error.
+
     Args:
         name (str): blob name inside the configured bucket.
 
     Returns:
         google.cloud.storage.Blob or None.
     """
+    from google.api_core.exceptions import NotFound
+
     client = get_client()
     bucket = client.bucket(get_bucket())
     blob = bucket.blob(name)
-    blob.reload()
+    try:
+        blob.reload()
+    except NotFound:
+        return None
     return blob if blob.exists() else None
 
 

{buildingdata-0.4.0 → buildingdata-0.5.0}/buildingdata/reference/__init__.py

@@ -2,6 +2,7 @@
 from .census import get_census
 from .diagnosis import get_diagnosis
 from .districts import get_districts
+from .elecdom import get_elecdom
 from .elmas import get_elmas
 from .enedis import get_enedis_national, get_enedis_regional
 from .gas_network import get_gas_network

buildingdata-0.5.0/buildingdata/reference/elecdom.py

@@ -0,0 +1,153 @@
+# -*- coding: utf-8 -*-
+import polars as pl
+
+from ..exceptions import SchemaValidationError
+from ..gcs import download_blob, ensure_blob_cached, get_blob
+from ..validation import require_columns, require_dtype, require_value_range
+
+_BLOB_NAME = "elecdom_daily_load_curves_latest.parquet"
+
+_DATASET = "Enedis panel Elecdom daily load curves"
+
+# The tidy (long) shape the staged blob must have: one row per
+# (period, end use, hour-of-day). See ``doc/pending_uploads.md`` section 5 for
+# the exact transformation from the source CSV.
+_REQUIRED_COLUMNS = (
+    "period_label",
+    "season",
+    "day_type",
+    "end_use",
+    "is_specific_electricity",
+    "hour",
+    "mean_power_w",
+)
+
+_STRING_COLUMNS = ("period_label", "season", "day_type", "end_use")
+
+# 5 season blocks x 3 day types x 10 end uses x 24 hours.
+_EXPECTED_ROWS = 5 * 3 * 10 * 24
+
+_SEASONS = ("december_february", "march_may", "june_august", "september_november", "all_seasons")
+_DAY_TYPES = ("weekday", "weekend", "all_days")
+
+# Plausible band for an hourly panel-mean per-dwelling end-use load, in watts.
+# The published curves peak around 410 W; 20 kW leaves ample headroom while
+# still catching a W <-> kWh/Wh-per-day style rescale.
+_MAX_PLAUSIBLE_W = 20_000.0
+# A W -> kW rescale would leave every value below 1 W and would *not* trip the
+# upper bound, so the lower end of the scale is asserted separately.
+_MIN_PLAUSIBLE_PEAK_W = 1.0
+
+
+def _validate(df):
+    """Assert the Elecdom load-curve blob matches its documented contract."""
+    require_columns(df, _REQUIRED_COLUMNS, _DATASET)
+    require_dtype(df, _STRING_COLUMNS, pl.String, _DATASET)
+    require_dtype(df, ("is_specific_electricity",), pl.Boolean, _DATASET)
+    require_dtype(df, ("hour",), pl.Int64, _DATASET)
+    require_dtype(df, ("mean_power_w",), pl.Float64, _DATASET)
+
+    if df.height != _EXPECTED_ROWS:
+        raise SchemaValidationError(
+            f"{_DATASET}: got {df.height} rows, expected exactly {_EXPECTED_ROWS} "
+            f"({len(_SEASONS)} season blocks x {len(_DAY_TYPES)} day types x 10 end "
+            f"uses x 24 hours). A short frame means the source CSV was partially "
+            f"read or a period/end-use block was dropped during staging."
+        )
+
+    hours = sorted(df["hour"].unique().to_list())
+    if hours != list(range(24)):
+        raise SchemaValidationError(
+            f"{_DATASET}: 'hour' must cover 0..23 exactly, got {hours}. The source "
+            f"publishes 24 left-closed hourly bins '[h,h+1['."
+        )
+    for column, expected in (("season", _SEASONS), ("day_type", _DAY_TYPES)):
+        observed = sorted(df[column].unique().to_list())
+        if observed != sorted(expected):
+            raise SchemaValidationError(
+                f"{_DATASET}: {column!r} must be exactly {sorted(expected)}, got "
+                f"{observed}. The 'Période' parsing at staging time drifted."
+            )
+
+    require_value_range(df, "mean_power_w", 0.0, _MAX_PLAUSIBLE_W, _DATASET)
+    peak = df["mean_power_w"].max()
+    if peak is None or peak < _MIN_PLAUSIBLE_PEAK_W:
+        raise SchemaValidationError(
+            f"{_DATASET}: 'mean_power_w' peaks at {peak}, below "
+            f"{_MIN_PLAUSIBLE_PEAK_W} W. The published curves peak in the hundreds "
+            f"of watts; this looks like a watt-to-kilowatt rescale, which the upper "
+            f"bound cannot catch."
+        )
+    return df
+
+
+def get_elecdom(refresh=False):
+    """Return the Enedis "panel Elecdom" daily end-use load curves (polars).
+
+    **Provenance-only accessor.** Nothing in ``building_eload`` calls this at
+    runtime. The Elecdom study is the published source behind two hand-derived
+    literal constant sets in ``building_eload``
+    (``models/specific.py::ACTIVITY_ELECTRICITY_WEIGHT_TABLE`` and
+    ``models/cooking.py::COOKING_CONFIG``, paper Tab. 1 ref. [37]); those stay
+    the runtime source of truth. This accessor exists so the raw table those
+    constants were transcribed from is versioned, fetchable and schema-checked,
+    making an offline re-derivation reproducible. Its only intended consumer is
+    such a re-derivation script.
+
+    Provenance: Enedis "panel Elecdom" appliance / end-use load study, open
+    dataset *"Courbes de charge journalières horaires par usage"*
+    (`elecdom-courbes-de-charge-journalieres-horaires`), cited as paper Tab. 1
+    ref. [37]. The published table is a panel-mean per-dwelling daily load
+    curve, broken down by season block, day type and end use.
+
+    Shape: tidy/long, one row per (period, end use, hour) -- 5 season blocks
+    x 3 day types x 10 end uses x 24 hours = 3600 rows.
+
+    Columns:
+
+    * ``period_label`` (``str``) -- the verbatim source ``Période`` label, e.g.
+      ``"Mois de Décembre - Février (Jours ouvrées)"``. Kept so a row can be
+      traced back to the raw CSV without reversing the parsing.
+    * ``season`` (``str``) -- one of ``"december_february"``, ``"march_may"``,
+      ``"june_august"``, ``"september_november"``, ``"all_seasons"``.
+    * ``day_type`` (``str``) -- ``"weekday"`` (source *Jours ouvrées*),
+      ``"weekend"`` (*Week-end*), ``"all_days"`` (source's empty parentheses).
+    * ``end_use`` (``str``) -- the verbatim French ``Poste`` label, one of
+      ``Chauffage direct`` (direct electric heating), ``Chauffe eau`` (DHW),
+      ``Cuisson`` (cooking), ``Ventilation``, ``Froid`` (refrigeration),
+      ``Audiovisuel``, ``Informatique/Bureautique``, ``Lavage séchage``
+      (washing/drying), ``Eclairage`` (lighting), ``Autres``. Left untranslated
+      on purpose: this is a provenance artifact, and any English mapping would
+      be an editorial choice the re-derivation script should own.
+    * ``is_specific_electricity`` (``bool``) -- True for the seven end uses the
+      source also republishes under its ``"Electricité spécifique - "`` period
+      prefix (everything except direct heating, DHW and cooking). The prefixed
+      block is a byte-identical duplicate of the base rows, so it is collapsed
+      into this flag rather than duplicated (verified at staging; see
+      ``doc/pending_uploads.md``).
+    * ``hour`` (``Int64``) -- 0..23, the left edge of the source's left-closed
+      hourly bin ``[h, h+1[``.
+    * ``mean_power_w`` (``Float64``) -- **watts**: the panel-mean load over that
+      hour bin, equivalently Wh consumed during the hour. Published values run
+      from a few W to ~410 W.
+
+    Args:
+        refresh (bool): force re-download even if the cache is warm.
+            Defaults to False.
+
+    Returns:
+        polars.DataFrame: the 3600-row tidy Elecdom load-curve table.
+
+    Raises:
+        RemoteNotAvailableError: if the blob is not found in the GCS bucket.
+            The blob is **not staged yet** -- see ``doc/pending_uploads.md``
+            section 5 for the maintainer handoff -- so this is the expected
+            outcome until it is uploaded.
+        SchemaValidationError: if the fetched frame is missing a column, carries
+            a wrong dtype, is not the full 3600-row grid, has an unexpected
+            season/day-type/hour vocabulary, or has implausible watt values.
+    """
+    dest = ensure_blob_cached(
+        _BLOB_NAME, refresh=refresh, get_blob_fn=get_blob, download_blob_fn=download_blob
+    )
+    return _validate(pl.read_parquet(dest))

buildingdata-0.5.0/buildingdata/reference/occupant_diaries.py

@@ -0,0 +1,257 @@
+# -*- coding: utf-8 -*-
+import re
+
+import polars as pl
+
+from ..exceptions import SchemaValidationError
+from ..gcs import download_blob, ensure_blob_cached, get_blob
+from ..validation import require_dtype
+
+_BLOB_NAME = "occupant_diaries_latest.parquet"
+
+_DATASET = "occupant activity diaries"
+
+# The timeline column. The staged blob was written from pandas, which round-trips
+# an unnamed index through parquet as ``__index_level_0__``; that is the name the
+# blob in the bucket actually carries today, and ``building_eload``'s
+# ``load_activity_diaries`` renames it to ``datetime`` on read. Accept either, so
+# a future re-staging that names the index properly keeps validating, but reject
+# anything else -- that rename is load-bearing for the consumer.
+_INDEX_COLUMN_NAMES = ("datetime", "__index_level_0__")
+
+# Every non-timeline column must be an occupant column. ``DwellingProcessor``
+# builds its occupant pool as ``[c for c in columns if c != "datetime"]``, so a
+# stray extra column (a leftover id, a weekday flag) would silently be drawn as
+# if it were an occupant's diary. Pinning the name shape makes that fail loud.
+_OCCUPANT_COLUMN_RE = re.compile(r"^occupant_\d+$")
+
+# The activity-code vocabulary. This mirrors ``building_eload``'s
+# ``models/occupancy.py::DEFAULT_OCCUPANCY_PER_ACTIVITY`` (flattened) -- the only
+# place the vocabulary is enumerated. It is transcribed rather than imported
+# because the dependency runs the other way (``building_eload`` depends on
+# ``buildingdata``), so keep the two in sync when the taxonomy changes.
+#
+# Validating it matters because both consumers of an unknown code fail
+# *silently*: ``set_occupancy_labels`` maps anything unrecognised to
+# ``"is_absent"`` (the occupant vanishes from the load), and ``specific.py``'s
+# left join against ``ACTIVITY_ELECTRICITY_WEIGHT_TABLE`` yields a null weight.
+# The check is a subset test, not equality: a smaller diary book that happens
+# not to use every code is legitimate.
+_ACTIVITY_CODES = frozenset(
+    {
+        # at home
+        "Hygiene",
+        "Other_at_home",
+        "Meal_at_home",
+        "Home_working",
+        "Cooking",
+        "Dish_washing",
+        "Housework",
+        "Clothes_washing",
+        "Ironing",
+        "Home_DIY",
+        "Gardening",
+        "Television",
+        "HiFi",
+        "Video_game",
+        "Computer",
+        "Electronic_Device",
+        # asleep
+        "Sleep",
+        # away
+        "Other_outside",
+        "Meal_outside",
+        "At_work",
+        "At_school",
+        "Shopping",
+        "Work_journey",
+        "Other_journey",
+    }
+)
+
+_SECONDS_PER_DAY = 24 * 60 * 60
+_FULL_YEAR_DAYS = (365, 366)
+
+
+def _index_column(df):
+    """Return the name of the diary's single Datetime timeline column."""
+    datetime_cols = [name for name, dtype in df.schema.items() if dtype == pl.Datetime]
+    if not datetime_cols:
+        raise SchemaValidationError(
+            f"{_DATASET}: no Datetime column found; expected exactly one timeline "
+            f"column named one of {list(_INDEX_COLUMN_NAMES)}. Got dtypes "
+            f"{ {name: str(t) for name, t in list(df.schema.items())[:5]} } (first 5 "
+            f"of {df.width}). Without a timeline the diaries cannot be aligned "
+            f"onto a simulation year."
+        )
+    if len(datetime_cols) > 1:
+        raise SchemaValidationError(
+            f"{_DATASET}: expected exactly one Datetime timeline column, found "
+            f"{datetime_cols}. Consumers treat every non-timeline column as an "
+            f"occupant diary, so a second temporal column would be drawn as one."
+        )
+    name = datetime_cols[0]
+    if name not in _INDEX_COLUMN_NAMES:
+        raise SchemaValidationError(
+            f"{_DATASET}: the timeline column is named {name!r}, expected one of "
+            f"{list(_INDEX_COLUMN_NAMES)}. ``building_eload`` renames "
+            f"``__index_level_0__`` to ``datetime`` on read and would raise on "
+            f"any other name."
+        )
+    return name
+
+
+def _require_complete_timeline(df, index_col):
+    """Assert the timeline is a gap-free regular grid covering a whole year.
+
+    The ELMAS lesson applies here too: a diary book that is one step short, has
+    a duplicated timestamp, or covers ten months instead of twelve does not
+    raise anywhere downstream -- ``align_activity_diaries`` rolls and slices it
+    happily and produces a quietly wrong calendar.
+    """
+    series = df[index_col]
+    if series.null_count():
+        raise SchemaValidationError(
+            f"{_DATASET}: the {index_col!r} timeline has "
+            f"{series.null_count()} null timestamp(s)."
+        )
+    if not series.is_sorted():
+        raise SchemaValidationError(
+            f"{_DATASET}: the {index_col!r} timeline is not sorted ascending; "
+            f"consumers roll the frame positionally and assume calendar order."
+        )
+
+    steps = series.diff().drop_nulls().unique().to_list()
+    if len(steps) != 1:
+        raise SchemaValidationError(
+            f"{_DATASET}: the {index_col!r} timeline is not a regular grid; found "
+            f"{len(steps)} distinct steps {sorted(steps)[:5]} over {df.height} rows. "
+            f"A gap or a duplicated timestamp silently misaligns the calendar roll."
+        )
+    step = steps[0]
+    step_seconds = step.total_seconds()
+    if step_seconds <= 0 or _SECONDS_PER_DAY % step_seconds:
+        raise SchemaValidationError(
+            f"{_DATASET}: timeline step {step} does not divide a calendar day "
+            f"evenly; the diaries cannot be indexed by day-of-week."
+        )
+
+    steps_per_day = int(_SECONDS_PER_DAY // step_seconds)
+    days, remainder = divmod(df.height, steps_per_day)
+    if remainder or days not in _FULL_YEAR_DAYS:
+        raise SchemaValidationError(
+            f"{_DATASET}: {df.height} rows at a {step} step is {df.height / steps_per_day:.4f} "
+            f"days, not a whole year ({' or '.join(str(d) for d in _FULL_YEAR_DAYS)} days, "
+            f"i.e. {' or '.join(str(d * steps_per_day) for d in _FULL_YEAR_DAYS)} rows). "
+            f"A truncated diary book is the exact failure mode this check exists for: "
+            f"it raises nothing downstream, it just yields a wrong year."
+        )
+
+
+def _require_known_activity_codes(df, occupant_cols):
+    """Assert every observed activity code is in the documented vocabulary."""
+    observed = set()
+    for column in occupant_cols:
+        observed.update(df[column].unique().drop_nulls().to_list())
+    unknown = sorted(observed - _ACTIVITY_CODES)
+    if unknown:
+        raise SchemaValidationError(
+            f"{_DATASET}: {len(unknown)} unknown activity code(s) {unknown[:10]}"
+            f"{'...' if len(unknown) > 10 else ''}. The documented vocabulary is "
+            f"{sorted(_ACTIVITY_CODES)}. Unknown codes do not raise downstream -- "
+            f"``set_occupancy_labels`` maps them to 'is_absent' and the specific-"
+            f"electricity weight join yields null -- so they are rejected here. If "
+            f"the taxonomy genuinely grew, extend both ``_ACTIVITY_CODES`` here and "
+            f"``building_eload``'s DEFAULT_OCCUPANCY_PER_ACTIVITY / "
+            f"ACTIVITY_ELECTRICITY_WEIGHT_TABLE."
+        )
+
+
+def _validate(df):
+    """Run the full occupant-diary contract check on a loaded frame."""
+    index_col = _index_column(df)
+
+    occupant_cols = [c for c in df.columns if c != index_col]
+    if not occupant_cols:
+        raise SchemaValidationError(
+            f"{_DATASET}: no occupant column found next to the {index_col!r} "
+            f"timeline; the diary book is empty."
+        )
+    malformed = [c for c in occupant_cols if not _OCCUPANT_COLUMN_RE.match(c)]
+    if malformed:
+        raise SchemaValidationError(
+            f"{_DATASET}: {len(malformed)} non-timeline column(s) do not match "
+            f"'occupant_<n>': {malformed[:10]}{'...' if len(malformed) > 10 else ''}. "
+            f"``DwellingProcessor`` draws every non-timeline column as an occupant "
+            f"profile, so a stray column would be simulated as a person."
+        )
+
+    require_dtype(df, occupant_cols, pl.String, _DATASET)
+
+    null_counts = df.select(pl.col(occupant_cols).null_count()).row(0)
+    nulls = [c for c, n in zip(occupant_cols, null_counts) if n]
+    if nulls:
+        raise SchemaValidationError(
+            f"{_DATASET}: {len(nulls)} occupant column(s) contain null activity "
+            f"codes: {nulls[:10]}{'...' if len(nulls) > 10 else ''}. A null code is "
+            f"treated as 'is_absent' downstream without warning."
+        )
+
+    _require_complete_timeline(df, index_col)
+    _require_known_activity_codes(df, occupant_cols)
+    return df
+
+
+def get_occupant_diaries(refresh=False):
+    """Return the occupant activity-diary calendar DataFrame (polars).
+
+    The occupant-diary "book" is a synthetic, time-indexed activity calendar:
+    one column per simulated occupant holding an activity-code string per
+    timestep, consumed by ``building_eload``'s ``DynamicSimulation`` as the base
+    pool of activity profiles that dwellings draw from. Downloaded from
+    ``occupant_diaries_latest.parquet`` on GCS on first call.
+
+    The canonical blob is the 1000-occupant book that ``DynamicParameters``
+    uses by default (``occupant_book_1000_pers_*.parquet``). Larger books
+    (10k/100k occupants) are separate artifacts staged by the maintainer and
+    passed explicitly via ``DynamicParameters.activity_file``; they are not
+    served here.
+
+    Contract enforced on every call (see ``Raises``):
+
+    * exactly one naive ``Datetime`` timeline column, named ``datetime`` or
+      ``__index_level_0__`` (the pandas-written index name the staged blob
+      currently carries; ``building_eload`` renames it to ``datetime``);
+    * at least one occupant column, and *every* non-timeline column named
+      ``occupant_<n>`` -- consumers draw all of them as occupant profiles;
+    * every occupant column ``String``-typed and null-free;
+    * the timeline a gap-free, ascending, regular grid whose step divides a
+      day, spanning exactly one whole calendar year (365 or 366 days);
+    * every observed activity code in the documented vocabulary (the flattened
+      ``building_eload`` ``DEFAULT_OCCUPANCY_PER_ACTIVITY`` taxonomy, 24 codes).
+      The check is a subset test -- a book that does not use every code passes.
+
+    Vintage note: the blob staged today is a **10-minute** book over leap year
+    2024 (52 704 rows x 1000 occupants). The step is validated generically
+    rather than pinned to 10 minutes, but note that ``building_eload``'s
+    ``align_activity_diaries`` hardcodes ``intervals_per_day = 144``: restaging
+    at another resolution requires a matching change there.
+
+    Args:
+        refresh (bool): force re-download even if the cache is warm.
+            Defaults to False.
+
+    Returns:
+        polars.DataFrame: one ``occupant_<i>`` column per occupant (``str``
+            activity codes) plus a naive ``Datetime`` timeline column, over one
+            full representative calendar year.
+
+    Raises:
+        RemoteNotAvailableError: if the blob is not found in the GCS bucket.
+        SchemaValidationError: if the fetched frame violates any clause of the
+            contract above, naming the offending column(s) or code(s).
+    """
+    dest = ensure_blob_cached(
+        _BLOB_NAME, refresh=refresh, get_blob_fn=get_blob, download_blob_fn=download_blob
+    )
+    return _validate(pl.read_parquet(dest))

buildingdata-0.5.0/buildingdata/tests/test_gcs.py

@@ -0,0 +1,73 @@
+# -*- coding: utf-8 -*-
+"""GCS blob lookup: the None-on-missing contract ensure_blob_cached relies on.
+
+No network: ``get_client`` is replaced by a fake client whose bucket hands back
+a blob stub with a scripted ``reload()``.
+"""
+from unittest.mock import Mock
+
+import pytest
+from google.api_core.exceptions import NotFound
+
+from buildingdata import gcs
+from buildingdata.exceptions import RemoteNotAvailableError
+
+
+class _StubBlob:
+    def __init__(self, name, reload_error=None, exists=True):
+        self.name = name
+        self.generation = 7
+        self.size = 123
+        self._reload_error = reload_error
+        self._exists = exists
+
+    def reload(self):
+        if self._reload_error is not None:
+            raise self._reload_error
+
+    def exists(self):
+        return self._exists
+
+
+def _stub_client(monkeypatch, blob):
+    bucket = Mock()
+    bucket.blob = Mock(return_value=blob)
+    client = Mock()
+    client.bucket = Mock(return_value=bucket)
+    monkeypatch.setattr(gcs, "get_client", lambda: client)
+
+
+def test_get_blob_returns_the_blob_when_present(monkeypatch):
+    blob = _StubBlob("census_latest.parquet")
+    _stub_client(monkeypatch, blob)
+
+    assert gcs.get_blob("census_latest.parquet") is blob
+
+
+def test_get_blob_returns_none_when_reload_raises_not_found(monkeypatch):
+    # Regression: ``reload()`` raises NotFound on a missing object *before*
+    # ``exists()`` is reached, so get_blob used to propagate an opaque
+    # google.api_core NotFound instead of honouring its documented
+    # "or None if not found" contract.
+    blob = _StubBlob("not_staged_yet.parquet", reload_error=NotFound("no such object"))
+    _stub_client(monkeypatch, blob)
+
+    assert gcs.get_blob("not_staged_yet.parquet") is None
+
+
+def test_get_blob_returns_none_when_the_object_does_not_exist(monkeypatch):
+    blob = _StubBlob("gone.parquet", exists=False)
+    _stub_client(monkeypatch, blob)
+
+    assert gcs.get_blob("gone.parquet") is None
+
+
+def test_unstaged_blob_surfaces_as_remote_not_available(monkeypatch):
+    # End-to-end consequence of the fix: an accessor whose blob has not been
+    # staged yet (get_elecdom, get_enedis_regional) raises the named error its
+    # docstring promises, not a raw GCS exception.
+    blob = _StubBlob("not_staged_yet.parquet", reload_error=NotFound("no such object"))
+    _stub_client(monkeypatch, blob)
+
+    with pytest.raises(RemoteNotAvailableError, match="not_staged_yet.parquet"):
+        gcs.ensure_blob_cached("not_staged_yet.parquet")

{buildingdata-0.4.0 → buildingdata-0.5.0}/buildingdata/tests/test_public_api.py

@@ -11,6 +11,7 @@ def test_public_callables_are_exposed():
         "get_diagnosis",
         "get_districts",
         "get_gas_network",
+        "get_elecdom",
         "get_elmas",
         "get_occupant_diaries",
         "get_ore",

{buildingdata-0.4.0 → buildingdata-0.5.0}/buildingdata/tests/test_reference.py

@@ -5,6 +5,7 @@ GCS is never contacted: get_blob/download_blob are replaced per module. The
 download stub writes a small fixture file to the cache so the real read path
 (polars/geopandas) and sidecar bookkeeping still execute.
 """
+from datetime import timedelta
 from unittest.mock import Mock
 
 import geopandas as gpd
@@ -17,6 +18,7 @@ from buildingdata.exceptions import RemoteNotAvailableError, SchemaValidationErr
 from buildingdata.reference import census as census_mod
 from buildingdata.reference import diagnosis as diagnosis_mod
 from buildingdata.reference import districts as districts_mod
+from buildingdata.reference import elecdom as elecdom_mod
 from buildingdata.reference import elmas as elmas_mod
 from buildingdata.reference import enedis as enedis_mod
 from buildingdata.reference import gas_network as gas_mod
@@ -360,21 +362,133 @@ def test_get_elmas_raises_when_blob_absent(monkeypatch):
         elmas_mod.get_elmas(table="clusters")
 
 
+# --- get_elecdom ------------------------------------------------------------
+# Provenance-only accessor: the blob is not staged yet (doc/pending_uploads.md
+# section 5), so these tests build the full documented 3600-row grid.
+
+_ELECDOM_END_USES = (
+    "Chauffage direct",
+    "Ventilation",
+    "Froid",
+    "Audiovisuel",
+    "Informatique/Bureautique",
+    "Lavage séchage",
+    "Cuisson",
+    "Eclairage",
+    "Chauffe eau",
+    "Autres",
+)
+_ELECDOM_SPECIFIC = {
+    "Ventilation",
+    "Froid",
+    "Audiovisuel",
+    "Informatique/Bureautique",
+    "Lavage séchage",
+    "Eclairage",
+    "Autres",
+}
+
+
+def _elecdom_df():
+    rows = []
+    for season in elecdom_mod._SEASONS:
+        for day_type in elecdom_mod._DAY_TYPES:
+            for end_use in _ELECDOM_END_USES:
+                for hour in range(24):
+                    rows.append(
+                        {
+                            "period_label": f"{season} ({day_type})",
+                            "season": season,
+                            "day_type": day_type,
+                            "end_use": end_use,
+                            "is_specific_electricity": end_use in _ELECDOM_SPECIFIC,
+                            "hour": hour,
+                            "mean_power_w": 50.0 + hour,
+                        }
+                    )
+    return pl.DataFrame(rows)
+
+
+def test_get_elecdom_downloads_then_reads(monkeypatch):
+    blob = FakeBlob(elecdom_mod._BLOB_NAME, generation=1)
+    _stub_gcs(monkeypatch, elecdom_mod, blob, lambda dest: _elecdom_df().write_parquet(dest))
+
+    out = elecdom_mod.get_elecdom()
+
+    assert isinstance(out, pl.DataFrame)
+    assert out.height == elecdom_mod._EXPECTED_ROWS
+    assert set(out.columns) == set(elecdom_mod._REQUIRED_COLUMNS)
+    assert cache.is_cached(elecdom_mod._BLOB_NAME)
+
+
+def test_get_elecdom_raises_when_blob_absent(monkeypatch):
+    # This is the expected outcome until the maintainer stages the blob.
+    monkeypatch.setattr(elecdom_mod, "get_blob", lambda name: None)
+    with pytest.raises(RemoteNotAvailableError):
+        elecdom_mod.get_elecdom()
+
+
+def test_get_elecdom_raises_on_missing_required_column(monkeypatch):
+    bad = _elecdom_df().drop("is_specific_electricity")
+    blob = FakeBlob(elecdom_mod._BLOB_NAME, generation=2)
+    _stub_gcs(monkeypatch, elecdom_mod, blob, lambda dest: bad.write_parquet(dest))
+
+    with pytest.raises(SchemaValidationError, match="is_specific_electricity"):
+        elecdom_mod.get_elecdom()
+
+
+def test_get_elecdom_raises_on_wrong_dtype(monkeypatch):
+    # French decimal commas surviving the CSV read leave the values as strings.
+    bad = _elecdom_df().with_columns(pl.col("mean_power_w").cast(pl.String))
+    blob = FakeBlob(elecdom_mod._BLOB_NAME, generation=3)
+    _stub_gcs(monkeypatch, elecdom_mod, blob, lambda dest: bad.write_parquet(dest))
+
+    with pytest.raises(SchemaValidationError, match="mean_power_w"):
+        elecdom_mod.get_elecdom()
+
+
+def test_get_elecdom_raises_on_incomplete_grid(monkeypatch):
+    # A dropped period/end-use block is the silent-truncation failure mode.
+    bad = _elecdom_df().filter(pl.col("end_use") != "Cuisson")
+    blob = FakeBlob(elecdom_mod._BLOB_NAME, generation=4)
+    _stub_gcs(monkeypatch, elecdom_mod, blob, lambda dest: bad.write_parquet(dest))
+
+    with pytest.raises(SchemaValidationError, match="expected exactly 3600"):
+        elecdom_mod.get_elecdom()
+
+
+def test_get_elecdom_raises_on_kilowatt_rescale(monkeypatch):
+    # W -> kW leaves every value under 1 and would sail past an upper bound.
+    bad = _elecdom_df().with_columns(pl.col("mean_power_w") / 1000.0)
+    blob = FakeBlob(elecdom_mod._BLOB_NAME, generation=5)
+    _stub_gcs(monkeypatch, elecdom_mod, blob, lambda dest: bad.write_parquet(dest))
+
+    with pytest.raises(SchemaValidationError, match="kilowatt rescale"):
+        elecdom_mod.get_elecdom()
+
+
 # --- get_occupant_diaries ---------------------------------------------------
+# The fixture is a full non-leap year at an hourly step (8760 rows x 2
+# occupants): the accessor asserts whole-year coverage, so a 3-row stub is not
+# a valid diary book. The real blob is 10-minute over a leap year; the contract
+# accepts any step that divides a day.
 
-def _occupant_df():
-    return pl.DataFrame(
-        {
-            "occupant_0": ["sleep", "home", "away"],
-            "occupant_1": ["home", "away", "sleep"],
-            "datetime": pl.datetime_range(
-                pl.datetime(2023, 1, 1),
-                pl.datetime(2023, 1, 1, 2),
-                interval="1h",
-                eager=True,
-            ),
-        }
+_OCCUPANT_HOURS = 365 * 24
+
+
+def _occupant_df(index_name="datetime", n_occupants=2, hours=_OCCUPANT_HOURS):
+    codes = ["Sleep", "Meal_at_home", "At_work", "Television"]
+    data = {
+        f"occupant_{i}": [codes[(h + i) % len(codes)] for h in range(hours)]
+        for i in range(n_occupants)
+    }
+    data[index_name] = pl.datetime_range(
+        pl.datetime(2023, 1, 1),
+        pl.datetime(2023, 1, 1) + pl.duration(hours=hours - 1),
+        interval="1h",
+        eager=True,
     )
+    return pl.DataFrame(data)
 
 
 def test_get_occupant_diaries_downloads_then_reads(monkeypatch):
@@ -384,16 +498,125 @@ def test_get_occupant_diaries_downloads_then_reads(monkeypatch):
     out = occupant_mod.get_occupant_diaries()
 
     assert isinstance(out, pl.DataFrame)
-    assert out.height == 3
+    assert out.height == _OCCUPANT_HOURS
     assert cache.is_cached(occupant_mod._BLOB_NAME)
 
 
+def test_get_occupant_diaries_accepts_the_pandas_index_column_name(monkeypatch):
+    # The blob staged today carries the pandas-written ``__index_level_0__``
+    # index name (building_eload renames it to ``datetime`` on read). The
+    # validation must not reject the very data it protects.
+    blob = FakeBlob(occupant_mod._BLOB_NAME, generation=2)
+    _stub_gcs(
+        monkeypatch,
+        occupant_mod,
+        blob,
+        lambda dest: _occupant_df(index_name="__index_level_0__").write_parquet(dest),
+    )
+
+    assert occupant_mod.get_occupant_diaries().height == _OCCUPANT_HOURS
+
+
 def test_get_occupant_diaries_raises_when_blob_absent(monkeypatch):
     monkeypatch.setattr(occupant_mod, "get_blob", lambda name: None)
     with pytest.raises(RemoteNotAvailableError):
         occupant_mod.get_occupant_diaries()
 
 
+def _occupant_case(monkeypatch, frame, generation):
+    blob = FakeBlob(occupant_mod._BLOB_NAME, generation=generation)
+    _stub_gcs(monkeypatch, occupant_mod, blob, lambda dest: frame.write_parquet(dest))
+    return occupant_mod.get_occupant_diaries
+
+
+def test_get_occupant_diaries_raises_without_a_datetime_column(monkeypatch):
+    # Index written as an epoch integer: DwellingProcessor would treat it as an
+    # occupant column and align_activity_diaries would crash on .weekday().
+    bad = _occupant_df().with_columns(pl.col("datetime").dt.epoch("s"))
+    call = _occupant_case(monkeypatch, bad, 11)
+    with pytest.raises(SchemaValidationError, match="no Datetime column"):
+        call()
+
+
+def test_get_occupant_diaries_raises_on_misnamed_datetime_column(monkeypatch):
+    bad = _occupant_df().rename({"datetime": "timestamp"})
+    call = _occupant_case(monkeypatch, bad, 12)
+    with pytest.raises(SchemaValidationError, match="timestamp"):
+        call()
+
+
+def test_get_occupant_diaries_raises_on_non_string_occupant_column(monkeypatch):
+    # Activity codes arriving as a categorical *code* (int) rather than the
+    # string label: joins downstream would silently yield nulls.
+    bad = _occupant_df().with_columns(pl.lit(3, dtype=pl.Int64).alias("occupant_1"))
+    call = _occupant_case(monkeypatch, bad, 13)
+    with pytest.raises(SchemaValidationError, match="occupant_1"):
+        call()
+
+
+def test_get_occupant_diaries_raises_on_stray_non_occupant_column(monkeypatch):
+    # Every non-timeline column is drawn as an occupant profile by
+    # DwellingProcessor, so a leftover helper column must fail loud.
+    bad = _occupant_df().with_columns(pl.lit("Mon").alias("weekday"))
+    call = _occupant_case(monkeypatch, bad, 14)
+    with pytest.raises(SchemaValidationError, match="weekday"):
+        call()
+
+
+def test_get_occupant_diaries_raises_on_truncated_year(monkeypatch):
+    # The silent-incompleteness case: a book one day short still rolls and
+    # slices happily downstream, it just yields the wrong calendar.
+    bad = _occupant_df().head(_OCCUPANT_HOURS - 24)
+    call = _occupant_case(monkeypatch, bad, 15)
+    with pytest.raises(SchemaValidationError, match="not a whole year"):
+        call()
+
+
+def test_get_occupant_diaries_raises_on_irregular_timeline(monkeypatch):
+    # A gap-then-catch-up keeps the row count right but breaks the grid.
+    df = _occupant_df()
+    shifted = df["datetime"].to_list()
+    shifted[10] = shifted[10] + timedelta(minutes=17)
+    bad = df.with_columns(pl.Series("datetime", shifted))
+    call = _occupant_case(monkeypatch, bad, 16)
+    with pytest.raises(SchemaValidationError, match="not a regular grid"):
+        call()
+
+
+def test_get_occupant_diaries_raises_on_null_activity_code(monkeypatch):
+    bad = _occupant_df().with_columns(
+        pl.when(pl.int_range(pl.len()) == 5)
+        .then(None)
+        .otherwise(pl.col("occupant_0"))
+        .alias("occupant_0")
+    )
+    call = _occupant_case(monkeypatch, bad, 17)
+    with pytest.raises(SchemaValidationError, match="null activity codes"):
+        call()
+
+
+def test_get_occupant_diaries_raises_on_unknown_activity_code(monkeypatch):
+    # An out-of-vocabulary code is mapped to 'is_absent' downstream without any
+    # warning, so it is rejected here instead.
+    bad = _occupant_df().with_columns(
+        pl.when(pl.int_range(pl.len()) == 5)
+        .then(pl.lit("Teleworking"))
+        .otherwise(pl.col("occupant_0"))
+        .alias("occupant_0")
+    )
+    call = _occupant_case(monkeypatch, bad, 18)
+    with pytest.raises(SchemaValidationError, match="Teleworking"):
+        call()
+
+
+def test_get_occupant_diaries_accepts_a_partial_vocabulary(monkeypatch):
+    # A book that simply never uses every code is legitimate: the vocabulary
+    # check is a subset test, not equality.
+    ok = _occupant_df().with_columns(pl.lit("Sleep").alias("occupant_0"))
+    call = _occupant_case(monkeypatch, ok, 19)
+    assert call().height == _OCCUPANT_HOURS
+
+
 # --- get_ore ----------------------------------------------------------------
 
 def _ore_df():

{buildingdata-0.4.0 → buildingdata-0.5.0}/buildingdata/validation.py

@@ -9,8 +9,10 @@ rather than a silent NaN or wrong-scale value deep inside a simulation.
 
 The helpers are deliberately backend-agnostic: ``require_columns`` works on
 anything exposing a ``columns`` sequence (polars DataFrame, pandas/geopandas
-DataFrame); ``require_value_range`` targets polars frames, where the value
-checks that catch unit swaps live.
+DataFrame); ``require_dtype`` works on anything exposing a ``schema`` mapping
+(polars DataFrame, ``polars.Schema``); ``require_value_range`` targets polars
+frames, where the value checks that catch unit swaps live. None of them import
+polars: dtypes to compare against are supplied by the caller.
 """
 
 from .exceptions import SchemaValidationError
@@ -42,6 +44,54 @@ def require_columns(frame, required, dataset):
         )
 
 
+def require_dtype(frame, columns, dtype, dataset, max_reported=10):
+    """Raise if any of ``columns`` does not carry the expected dtype.
+
+    A column that survives a rename but changes dtype is the quiet half of
+    schema drift: an activity code arriving as an integer index, or a float
+    measurement arriving as a string, does not raise until far downstream (or
+    never -- it just produces nulls after a join). This asserts the dtype at
+    load time instead.
+
+    Args:
+        frame: an object exposing a ``schema`` mapping (polars DataFrame or
+            ``polars.Schema``), or a name -> dtype mapping itself.
+        columns (iterable of str): column names to check.
+        dtype: the expected polars dtype, or a tuple of acceptable dtypes.
+            Dtype *classes* (``pl.Datetime``) match any parameterisation
+            (any time unit / time zone); dtype *instances*
+            (``pl.Datetime("us")``) match exactly.
+        dataset (str): human-readable dataset name for the error message.
+        max_reported (int): cap on how many offending columns are listed in the
+            message, so a 1000-column frame does not produce a 1000-entry error.
+
+    Raises:
+        SchemaValidationError: if a column is absent, or carries another dtype.
+    """
+    schema = getattr(frame, "schema", frame)
+    allowed = dtype if isinstance(dtype, tuple) else (dtype,)
+    columns = list(columns)
+
+    missing = [c for c in columns if c not in schema]
+    if missing:
+        raise SchemaValidationError(
+            f"{dataset}: cannot dtype-check absent column(s) {missing[:max_reported]}"
+            f"{'...' if len(missing) > max_reported else ''}."
+        )
+
+    bad = [(c, schema[c]) for c in columns if not any(schema[c] == d for d in allowed)]
+    if bad:
+        shown = ", ".join(f"{c}={t}" for c, t in bad[:max_reported])
+        more = f" (and {len(bad) - max_reported} more)" if len(bad) > max_reported else ""
+        expected = " or ".join(str(d) for d in allowed)
+        raise SchemaValidationError(
+            f"{dataset}: {len(bad)} column(s) have the wrong dtype; expected "
+            f"{expected}, got {shown}{more}. The upstream file's encoding "
+            f"changed (or the wrong vintage was fetched); downstream joins and "
+            f"casts on these columns would silently produce nulls."
+        )
+
+
 def require_value_range(frame, column, low, high, dataset, allow_null=True):
     """Raise if any value in ``frame[column]`` falls outside ``[low, high]``.
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: buildingdata
-Version: 0.4.0
+Version: 0.5.0
 Summary: Data management layer for buildingmodel — reference data download, BDTOPO retrieval, ERA5 weather
 License-Expression: MIT
 Requires-Python: >=3.10
@@ -76,18 +76,25 @@ buildingdata configure --bucket my-bucket --cache-dir ~/.cache/buildingdata
 
 ## What it provides
 
-| Function | Source | Returns |
-| --- | --- | --- |
-| `get_census()` | INSEE census (GCS) | polars `DataFrame` |
-| `get_districts()` | IRIS geometries (GCS) | geopandas `GeoDataFrame` |
-| `get_diagnosis()` | ADEME energy performance diagnoses (GCS) | polars `DataFrame` |
-| `get_gas_network()` | GRDF gas network routes (GCS) | geopandas `GeoDataFrame` |
-| `get_bdtopo(iris_code)` | IGN Géoplateforme WFS (live) | geopandas `GeoDataFrame` |
-| `get_era5_climate(lat, lon, year)` | Copernicus CDS (live) | path to EPW file |
+| Function | Source | Returns | Consumed by |
+| --- | --- | --- | --- |
+| `get_census()` | INSEE census (GCS) | polars `DataFrame` | buildingmodel — dwelling inference |
+| `get_districts()` | IRIS geometries (GCS) | geopandas `GeoDataFrame` | buildingmodel — geocoding; building_eload — district lookup |
+| `get_diagnosis()` | ADEME energy performance diagnoses (GCS) | polars `DataFrame` | buildingmodel — envelope & system inference |
+| `get_gas_network()` | GRDF gas network routes (GCS) | geopandas `GeoDataFrame` | buildingmodel — gas-connection inference |
+| `get_ore()` | Agence ORE annual consumption per IRIS (GCS) | polars `DataFrame` | building_eload — calibration target |
+| `get_enedis_national()` / `get_enedis_regional()` | Enedis conso-inf36 measured consumption (GCS) | polars `DataFrame` | building_eload — validation reference |
+| `get_elmas(table)` | ELMAS non-residential load curves (GCS) | polars `DataFrame` | building_eload — non-residential model |
+| `get_occupant_diaries()` | synthetic occupant activity calendar (GCS) | polars `DataFrame` | building_eload — occupancy models |
+| `get_elecdom()` | Enedis panel Elecdom end-use load curves (GCS) | polars `DataFrame` | provenance only — source of building_eload constants |
+| `get_bdtopo(iris_code)` | IGN Géoplateforme WFS (live) or bulk cache | geopandas `GeoDataFrame` | building_eload → buildingmodel — input geometry |
+| `get_era5_climate(lat, lon, year)` | Copernicus CDS (live) or bulk cache | path to EPW file | buildingmodel — weather boundary condition |
 
 Reference datasets are pulled from a public Google Cloud Storage bucket and
 cached locally with generation-based freshness checks. French geospatial data
-uses CRS **EPSG:2154 (Lambert-93)**.
+uses CRS **EPSG:2154 (Lambert-93)**. The documentation page *Datasets*
+describes each dataset in detail — provenance, schema, units — and how
+`buildingmodel` / `building_eload` consume it.
 
 ## Bulk prefetch for large-scale simulations
 

{buildingdata-0.4.0 → buildingdata-0.5.0}/buildingdata.egg-info/SOURCES.txt

@@ -19,6 +19,7 @@ buildingdata/reference/__init__.py
 buildingdata/reference/census.py
 buildingdata/reference/diagnosis.py
 buildingdata/reference/districts.py
+buildingdata/reference/elecdom.py
 buildingdata/reference/elmas.py
 buildingdata/reference/enedis.py
 buildingdata/reference/gas_network.py
@@ -35,6 +36,7 @@ buildingdata/tests/conftest.py
 buildingdata/tests/test_bulk.py
 buildingdata/tests/test_cache.py
 buildingdata/tests/test_config.py
+buildingdata/tests/test_gcs.py
 buildingdata/tests/test_pipeline_diagnosis.py
 buildingdata/tests/test_public_api.py
 buildingdata/tests/test_reference.py

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

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

buildingdata-0.4.0/buildingdata/reference/occupant_diaries.py

@@ -1,41 +0,0 @@
-# -*- coding: utf-8 -*-
-import polars as pl
-
-from ..gcs import download_blob, ensure_blob_cached, get_blob
-
-_BLOB_NAME = "occupant_diaries_latest.parquet"
-
-
-def get_occupant_diaries(refresh=False):
-    """Return the occupant activity-diary calendar DataFrame (polars).
-
-    The occupant-diary "book" is a synthetic, time-indexed activity calendar:
-    one column per simulated occupant holding an hourly activity-code string,
-    consumed by ``building_eload``'s ``DynamicSimulation`` as the base pool of
-    activity profiles that dwellings draw from. Downloaded from
-    ``occupant_diaries_latest.parquet`` on GCS on first call.
-
-    The canonical blob is the 1000-occupant book that ``DynamicParameters``
-    uses by default (``occupant_book_1000_pers_*.parquet``). Larger books
-    (10k/100k occupants) are separate artifacts staged by the maintainer and
-    passed explicitly via ``DynamicParameters.activity_file``; they are not
-    served here.
-
-    Args:
-        refresh (bool): force re-download even if the cache is warm.
-            Defaults to False.
-
-    Returns:
-        polars.DataFrame: one ``occupant_<i>`` column per occupant (``str``
-            activity codes) plus a naive ``Datetime`` index column. Rows are
-            hourly over one representative calendar year.
-
-    Raises:
-        RemoteNotAvailableError: if the blob is not found in the GCS bucket.
-    """
-    dest = ensure_blob_cached(
-        _BLOB_NAME, refresh=refresh, get_blob_fn=get_blob, download_blob_fn=download_blob
-    )
-    return pl.read_parquet(dest)
-
-