Metadata-Version: 2.4
Name: sdc-catchment
Version: 0.1.1
Summary: Floating catchment area spatial accessibility (2SFCA, E2SFCA, and variants)
Project-URL: Homepage, https://dads2busy.github.io/Social-Data-Commons/packages/sdc-catchment/
Project-URL: Documentation, https://dads2busy.github.io/Social-Data-Commons/packages/sdc-catchment/
Project-URL: Repository, https://github.com/dads2busy/Social-Data-Commons
Project-URL: Issues, https://github.com/dads2busy/Social-Data-Commons/issues
Project-URL: Changelog, https://github.com/dads2busy/Social-Data-Commons/blob/main/packages/sdc-catchment/CHANGELOG.md
Author-email: Aaron Schroeder <ads7fg@virginia.edu>
License: MIT
Keywords: 2sfca,accessibility,catchment,e2sfca,gis,spatial
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.11
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
Description-Content-Type: text/markdown

# sdc-catchment

Floating catchment area (FCA) spatial-accessibility metrics — 2SFCA, E2SFCA,
KD2SFCA, 3SFCA, modified-2SFCA, balanced FCA, and commute-based FCA, all as
parameter variations of a single `catchment_ratio()`.

Part of the [Social Data Commons](https://github.com/dads2busy/Social-Data-Commons)
toolkit. Extracted from `sdc_core.catchment`; the Python replacement for the R
`catchment` package.

## Install

```bash
uv add sdc-catchment   # or: pip install sdc-catchment
```

## Quickstart

Access of three consumers to two providers, under a gaussian distance-decay:

```python
import numpy as np
import pandas as pd
from sdc_catchment import catchment_ratio, euclidean_cost

consumers = pd.DataFrame({"geoid": ["c1", "c2", "c3"], "value": [100.0, 100.0, 100.0]})
providers = pd.DataFrame({"geoid": ["p1", "p2"], "value": [10.0, 10.0]})
cost = euclidean_cost(np.array([[0, 0], [1, 0], [2, 0]]), np.array([[0, 0], [2, 0]]))

access = catchment_ratio(consumers, providers, cost, weight="gaussian", scale=1.0)
print(access.to_string())
# c1    0.065179
# c2    0.069641
# c3    0.065179
```

The central consumer (`c2`) has the highest access; decay weights each provider
by distance.

## Public API

- `catchment_ratio` — accessibility ratio under a chosen FCA variant.
- `catchment_weight` — distance-decay weight matrix builder.
- `catchment_connections` / `catchment_network` — provider/consumer connectivity.
- `euclidean_cost` — pairwise Euclidean cost matrix.
- `KERNELS`, `WeightSpec` — kernel registry and weight-spec type.

## Documentation

- [Introduction to floating catchment areas](https://dads2busy.github.io/Social-Data-Commons/packages/sdc-catchment/articles/introduction/)
- [Case study](https://dads2busy.github.io/Social-Data-Commons/packages/sdc-catchment/articles/case-study/)
- [API reference](https://dads2busy.github.io/Social-Data-Commons/packages/sdc-catchment/reference/catchment/)
