Metadata-Version: 2.4
Name: buildingdata
Version: 0.3.0
Summary: Data management layer for buildingmodel — reference data download, BDTOPO retrieval, ERA5 weather
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-cloud-storage>=2.0
Requires-Dist: polars>=0.20
Requires-Dist: geopandas>=0.14
Requires-Dist: pyarrow>=14.0
Requires-Dist: tqdm>=4.0
Requires-Dist: requests>=2.28
Requires-Dist: platformdirs>=3.0
Provides-Extra: era5
Requires-Dist: cdsapi>=0.6; extra == "era5"
Requires-Dist: xarray>=2023.0; extra == "era5"
Requires-Dist: pvlib>=0.10; extra == "era5"
Requires-Dist: netcdf4>=1.6; extra == "era5"
Requires-Dist: zarr>=2.18; extra == "era5"
Requires-Dist: dask>=2024.1; extra == "era5"
Provides-Extra: bulk
Requires-Dist: py7zr>=0.20; extra == "bulk"
Provides-Extra: pipeline
Requires-Dist: snakemake>=8.0; extra == "pipeline"
Requires-Dist: openpyxl>=3.0; extra == "pipeline"
Requires-Dist: py7zr>=0.20; extra == "pipeline"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx-autoapi>=3.0; extra == "docs"
Requires-Dist: pydata-sphinx-theme>=0.15; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# buildingdata

[![PyPI](https://img.shields.io/pypi/v/buildingdata.svg)](https://pypi.org/project/buildingdata/)
[![Python](https://img.shields.io/pypi/pyversions/buildingdata.svg)](https://pypi.org/project/buildingdata/)

**Data-management layer for [`buildingmodel`](https://gitlab.com/energytransition).**
`buildingdata` delivers clean, ready-to-use building, demographic and weather
datasets for French building energy inference, and caches everything locally so
repeated calls don't re-download.

```bash
pip install buildingdata
```

## Quick start

```python
import buildingdata as bd

# One-time configuration (bucket, cache dir, credentials).
# The public bucket works anonymously, so this is optional.
bd.configure()

# Reference datasets (downloaded once from Google Cloud Storage, then cached)
census    = bd.get_census()        # INSEE census            -> polars DataFrame
districts = bd.get_districts()     # IRIS district geometry  -> geopandas GeoDataFrame
diagnosis = bd.get_diagnosis()     # ADEME energy diagnoses  -> polars DataFrame
gas       = bd.get_gas_network()   # GRDF gas network routes -> geopandas GeoDataFrame

# On-demand datasets (fetched live from public APIs)
buildings = bd.get_bdtopo("751010101")           # per-IRIS building geometry (IGN WFS)
epw       = bd.get_era5_climate(48.85, 2.35, 2020)  # ERA5 weather -> synthetic EPW
```

You can also configure from the command line:

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

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)**.

## Bulk prefetch for large-scale simulations

The live APIs fetch one IRIS or one grid point at a time. For campaigns over
thousands of IRIS, prefetch whole years and départements into the local cache
once, then read them lock-free from any number of parallel workers:

```bash
buildingdata configure --cds-key YOUR-CDS-KEY   # ERA5 needs Copernicus CDS credentials
buildingdata prefetch era5   --years 2019       # ~1.5 GB/year; one Zarr store over metropolitan France
buildingdata prefetch bdtopo --departments 75 92  # IGN 7z -> per-département GeoParquet
buildingdata cache info                          # sizes + completed bulk partitions
```

```python
import buildingdata as bd

# After the prefetch, the same functions read the bulk cache automatically:
buildings = bd.get_bdtopo("751010101")                 # source="auto" by default
frame     = bd.get_era5_frame(48.85, 2.35, year=2019)  # EPW-format DataFrame, no EPW file

# Many IRIS at once — one partition scan + spatial join per département
frames = bd.get_bdtopo_bulk(["751010101", "751010102", "920020101"])

# Or force the local cache (fails fast instead of hitting the network):
buildings = bd.get_bdtopo("751010101", source="bulk")
```

BDTOPO bulk prefetch needs the `bulk` extra (`pip install "buildingdata[bulk]"`),
ERA5 the `era5` extra. See the documentation page *Bulk prefetch for
large-scale simulations* for source selection (`"auto"`/`"bulk"`/`"wfs"`/`"cds"`),
disk sizes, concurrency guarantees and BDTOPO vintage notes.

## Configuration

Settings are resolved in the following precedence order:
1. Explicit function arguments / CLI options
2. Environment variables (`BUILDINGDATA_BUCKET`, `BUILDINGDATA_CACHE_DIR`, `GOOGLE_APPLICATION_CREDENTIALS`)
3. Global configuration file (`~/.config/buildingdata/config.ini`)
4. Dynamic defaults

Configurable settings:
- **bucket** — GCS bucket holding reference datasets (default: `building-inference-data`)
- **cache directory** — where downloaded data is stored locally
- **credentials** — path to a GCS service-account JSON (omit for anonymous access to the public bucket)

### Cache Behavior & Multi-Project Sharing

- **Default (Unconfigured)**: The cache directory is namespaced per installation (`~/.local/share/buildingdata/cache/<install-id>` on Linux/macOS). Each virtualenv or package installation receives its own unique cache subfolder to prevent collisions between environments.
- **Sharing Across Projects**: To share a single cache directory across multiple repositories, virtualenvs, or Snakemake pipelines, set the `BUILDINGDATA_CACHE_DIR` environment variable or write a global configuration file:

```bash
# Via CLI (writes ~/.config/buildingdata/config.ini):
buildingdata configure --cache-dir /path/to/shared/cache

# Or via environment variable:
export BUILDINGDATA_CACHE_DIR="/path/to/shared/cache"
```

Because `~/.config/buildingdata/config.ini` is stored in your home directory, configuring it once applies globally to all projects and virtual environments for your user account.


## Installation extras

```bash
pip install "buildingdata[era5]"   # ERA5 weather (cdsapi, xarray, pvlib, ...)
pip install "buildingdata[bulk]"   # BDTOPO bulk prefetch (py7zr)
pip install "buildingdata[docs]"   # build the Sphinx documentation
```

Requires **Python ≥ 3.10**.

## License

Released under the [MIT License](LICENSE).
