Metadata-Version: 2.4
Name: gla-data
Version: 0.1.3
Summary: Shared tools for loading, transforming, and visualising the GLA datasets used in City Data analysis.
Author-email: Conor Dempsey <conor.dempsey@london.gov.uk>
License: MIT
Requires-Python: >=3.12
Requires-Dist: geopandas>=1.0
Requires-Dist: pandas>=2.2
Requires-Dist: pandera>=0.32.1
Requires-Dist: pyarrow>=24.0.0
Requires-Dist: pydantic-settings
Requires-Dist: requests>=2.32
Requires-Dist: typer>=0.26.8
Description-Content-Type: text/markdown

# gla-data

Shared tools for loading, transforming, and visualising the GLA datasets used in City Data analysis.

## Installation

### Global install (CLI)

To install `gla-data` globally so the `gla-data` CLI is available anywhere in your terminal, use `uv tool`:

```bash
uv tool install gla-data
```

Normally `pixi global install` would be the preferred approach, but it does not yet support PyPI packages — so `uv tool` is the right choice for now.

If you don't have `uv` installed, you can install it via pixi:

```bash
pixi global install uv
```

### pip

```bash
pip install gla-data
```

### pixi

```bash
pixi add gla-data
```

Pixi pulls geospatial dependencies (geopandas, pyproj, etc.) from conda-forge, which provides reliable pre-built binaries across all platforms and Python versions.

## Usage

### Python API

```python
import gla_data

# Load 2021 LSOA boundaries for London
lsoa_gdf = gla_data.load_boundaries(geography='lsoa', year=2021)

# Load census dwelling counts
dwellings_2021 = gla_data.load_census_dwellings(year=2021)
dwellings_2011 = gla_data.load_census_dwellings(year=2011)

# Crosswalk 2011 dwelling counts onto 2021 LSOA boundaries
dwellings_2011_xw = gla_data.crosswalk(
    dwellings_2011,
    from_year=2011,
    to_year=2021,
    value_cols=['dwellings_total'],
)

# Load an OA → LSOA geography lookup
lookup = gla_data.load_geography_lookup(year=2021, smallest_geography='oa')

# Aggregate OA-level data up to LSOA level
lsoa_totals = gla_data.aggregate(
    df,
    from_geography='oa',
    to_geography='lsoa',
    value_cols=['count'],
    year=2021,
)
```

### CLI

The package installs a `gla-data` command. Run `catalogue` to list all available datasets:

```bash
gla-data catalogue
```

This prints a table of every dataset, the function used to load it, a description, and its access tier (public/S3).

## Development

```bash
git clone <repo-url>
cd gla-data
pixi install

pixi run test       # run tests
pixi run lint       # check code style
pixi run format     # auto-format
pixi run typecheck  # type checking
```
