Metadata-Version: 2.4
Name: hextraj
Version: 2026.8.21.3
Summary: Hex labelling of trajectory data
Author-email: Willi Rath <wrath@geomar.de>
License-Expression: MIT
Project-URL: Homepage, https://github.com/willirath/hextraj
Project-URL: Documentation, https://willirath.github.io/hextraj/
Project-URL: Repository, https://github.com/willirath/hextraj
Project-URL: DOI, https://doi.org/10.5281/zenodo.22040740
Keywords: hexagonal grid,trajectory analysis,connectivity,oceanography,geospatial,xarray,dask
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
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
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Oceanography
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pyproj
Requires-Dist: xarray
Requires-Dist: geopandas
Requires-Dist: shapely
Provides-Extra: full
Requires-Dist: dask; extra == "full"
Requires-Dist: scipy; extra == "full"
Requires-Dist: cartopy; extra == "full"
Provides-Extra: dev
Requires-Dist: hextraj[full]; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

# hextraj

[![PyPI](https://img.shields.io/pypi/v/hextraj)](https://pypi.org/project/hextraj/)
[![License:MIT](https://img.shields.io/badge/License-MIT-lightgray.svg?style=flt-square)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://willirath.github.io/hextraj/)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22040740.svg)](https://doi.org/10.5281/zenodo.22040740)

Hex labelling of trajectory data.

| Hex region | OD connectivity |
|:---:|:---:|
| ![Hex region example](figures/hex_region_example.png) | ![OD connectivity example](figures/hex_conn_dask_example.png) |
| [hex_aggregation.ipynb](notebooks/hex_aggregation.ipynb) | [hex_conn_dask.ipynb](notebooks/hex_conn_dask.ipynb) |

Maps lon/lat positions to a projected hexagonal grid and provides tools for aggregation and connectivity analysis.

- `hex_counts` — heat maps and density aggregation
- `hex_connectivity` — origin-destination matrices
- `hex_connectivity_power` — multi-generation transport probabilities
- `hex_connectivity_dask` — lazy dask-native connectivity for large datasets
- Full dask support throughout

## Getting started

Explore the notebooks:

- [`hex_conn.ipynb`](notebooks/hex_conn.ipynb) — Label NW Shelf trajectories, compute OD connectivity, visualise choropleth + edge overlay.
- [`hex_aggregation.ipynb`](notebooks/hex_aggregation.ipynb) — Grid construction, choropleth aggregation, and weighted edges.
- [`hex_grid_construction.ipynb`](notebooks/hex_grid_construction.ipynb) — Rectangle and region hex grids.
- [`hex_analysis.ipynb`](notebooks/hex_analysis.ipynb) — Analysis functions (`hex_counts`, `hex_connectivity`, `hex_connectivity_power`).
- [`hex_conn_dask.ipynb`](notebooks/hex_conn_dask.ipynb) — Dask-native connectivity for large datasets.

## Installation

```shell
pip install hextraj
```

With dask, scipy, and cartopy:

```shell
pip install hextraj[full]
```

Or from source:

```shell
pip install git+https://github.com/willirath/hextraj.git@main
```

## Quick example

```python
from hextraj import HexProj

hp = HexProj(lon_origin=-3.0, lat_origin=54.0, hex_size_meters=50_000)

# Label positions → int64 hex IDs
hex_ids = hp.label(lon, lat)

# Build a GeoDataFrame with Polygon geometries
gdf = hp.to_geodataframe(hp.region_of_hexes(region_polygon))
gdf["count"] = counts.reindex(gdf.index).fillna(0)
gdf.plot(column="count", cmap="YlOrRd")
```

## Citing

Cite hextraj through its DOI. `10.5281/zenodo.22040740` is the concept DOI, and it resolves to the most recent release. Zenodo mints a separate DOI for each release, so use that one to pin an exact version.

[`CITATION.cff`](https://github.com/willirath/hextraj/blob/main/CITATION.cff) holds the same metadata. GitHub renders it as BibTeX or APA under "Cite this repository".
