odflows 0.1.0__tar.gz

odflows-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-09
+### Added
+- `ODMatrix`: square OD matrix with zone labels; long/matrix conversion, outflows,
+  inflows, intrazonal flows, net / gross / symmetric flows, asymmetry index, subsets.
+- Readers and writers: long and matrix CSV, zone centroids from GeoJSON (points or
+  polygon area centroids) or CSV, GeoJSON, flowmap.blue `locations`/`flows` CSVs,
+  kepler.gl arc-layer CSV.
+- `desire_lines`: directed, net or gross desire lines; straight, curved (quadratic
+  Bezier) or offset geometry separating the two directions of a pair.
+- `ZoneLookup` and `reaggregate`: (dis)aggregation between zone systems with
+  row-normalised weighted lookups, including area weights from polygons (shapely).
+- Filters: minimum flow, top-k, share of origin/destination/total, cumulative share,
+  dominant flows.
+- Indicators: degree and strength, supply- and demand-side self-containment, commuting
+  job ratio, net balance, zone and matrix summaries.
+- Tao & Thill flow distance and dissimilarity, flow neighbour counts, agglomerative
+  (single/complete/average) and DBSCAN flow clustering, volume-weighted flow bundling.
+- `intramax`: Masser & Brown Intramax hierarchy with optional contiguity, region
+  self-containment summary.
+- `odflows` command-line interface.
+- Optional pandas helpers `from_dataframe` / `to_dataframe`.

odflows-0.1.0/CITATION.cff

@@ -0,0 +1,20 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+  - family-names: "Eminoğlu"
+    given-names: "Yusuf"
+    email: "geospacephilo@gmail.com"
+    orcid: "https://orcid.org/0009-0005-6000-2934"
+title: "odflows"
+version: "0.1.0"
+date-released: "2026-11-09"
+license: "MIT"
+repository-code: "https://github.com/YusufEminoglu/odflows_sdk"
+url: "https://pypi.org/project/odflows/"
+abstract: "Origin-destination flow toolkit for mobility and commuting analysis: OD tables, desire lines with curved two-way lines, area-weighted re-aggregation between zone systems, net and gross flows, flow filtering, Tao and Thill flow distance with hierarchical and DBSCAN flow clustering, self-containment and job-ratio indicators, Intramax functional regions, and export to GeoJSON, flowmap.blue and kepler.gl."
+keywords:
+  - origin-destination
+  - commuting
+  - mobility
+  - functional regions
+  - flow mapping

odflows-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yusuf Eminoğlu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

odflows-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CITATION.cff
+include pyproject.toml
+include src/odflows/py.typed
+recursive-include src/odflows *.py
+recursive-include tests *.py
+recursive-include examples *.py *.csv *.geojson

odflows-0.1.0/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: odflows
+Version: 0.1.0
+Summary: Origin-destination flow toolkit for mobility and commuting analysis: OD tables, desire lines, zone re-aggregation, net/gross flows, filtering, Tao & Thill flow clustering, self-containment indicators, Intramax functional regions, and flowmap.blue / kepler.gl export.
+Author-email: Yusuf Eminoğlu <geospacephilo@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/YusufEminoglu/odflows_sdk
+Project-URL: Repository, https://github.com/YusufEminoglu/odflows_sdk
+Project-URL: Issues, https://github.com/YusufEminoglu/odflows_sdk/issues
+Project-URL: Changelog, https://github.com/YusufEminoglu/odflows_sdk/blob/main/CHANGELOG.md
+Keywords: origin-destination,od-matrix,flows,desire-lines,commuting,mobility,functional-regions,intramax,self-containment,flow-clustering,flowmap,kepler-gl,geojson,gis,transport-planning
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.3.0; extra == "pandas"
+Provides-Extra: geo
+Requires-Dist: shapely>=2.0; extra == "geo"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# odflows
+
+[![PyPI version](https://img.shields.io/pypi/v/odflows.svg)](https://pypi.org/project/odflows/)
+[![Python versions](https://img.shields.io/pypi/pyversions/odflows.svg)](https://pypi.org/project/odflows/)
+[![CI](https://github.com/YusufEminoglu/odflows_sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/YusufEminoglu/odflows_sdk/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/YusufEminoglu/odflows_sdk/blob/main/LICENSE)
+
+**Origin-destination flow toolkit for mobility and commuting analysis.**
+
+`odflows` covers the usual steps of an OD study in one small package that needs only
+numpy:
+
+- **Read** OD tables in long form (`origin,destination,flow`) or as a square matrix, and
+  zone centroids from GeoJSON (points, or area centroids of polygons) or CSV.
+- **Desire lines** as GeoJSON LineStrings: directed, net or gross; straight, **curved**
+  or **offset**, so both directions of a two-way pair stay visible.
+- **Change zone systems**: aggregate and disaggregate with weighted lookup tables,
+  including area weights computed from two polygon layers (optional `shapely`).
+- **Net and gross flows**, symmetric part, asymmetry index, intrazonal handling.
+- **Filter** flows: minimum size, top-k, share of origin / destination / total,
+  cumulative share, dominant (largest outgoing) flows.
+- **Cluster and bundle** flows with the Tao & Thill flow distance: agglomerative
+  (single / complete / average linkage) and DBSCAN, in pure numpy.
+- **Indicators**: in/out degree and strength, supply- and demand-side
+  self-containment, commuting job ratio, net balance.
+- **Functional regions** (commuting zones) with **Intramax** (Masser & Brown 1975),
+  optionally contiguity-constrained.
+- **Export** to GeoJSON, **flowmap.blue** (`locations` + `flows` sheets) and a
+  **kepler.gl** arc-layer CSV.
+- A command-line tool, `odflows`.
+
+```bash
+pip install odflows            # numpy only
+pip install "odflows[pandas]"  # + DataFrame helpers
+pip install "odflows[geo]"     # + shapely, for area-weighted lookups from polygons
+```
+
+Requires Python 3.9 or newer.
+
+## Quick start
+
+```python
+from odflows import (
+    ODMatrix, read_od_csv, centroids_from_geojson, desire_lines, write_geojson,
+    zone_summary, intramax, region_summary, filter_top_k,
+)
+
+od = read_od_csv("commute.csv")                 # origin,destination,flow
+zones = centroids_from_geojson("zones.geojson", id_field="zone")
+
+for row in zone_summary(od):                     # self-containment, job ratio, ...
+    print(row["zone"], round(row["supply_sc"], 3), round(row["job_ratio"], 2))
+
+lines = desire_lines(filter_top_k(od, 20), zones, style="curved")
+write_geojson(lines, "desire_lines.geojson")
+
+hierarchy = intramax(od)                         # full Intramax hierarchy
+membership = hierarchy.membership(n_regions=4)   # cut it at 4 regions
+print(region_summary(od, membership))
+```
+
+A runnable example with synthetic data is in
+[`examples/quickstart.py`](examples/quickstart.py).
+
+Matrices can also be built in memory:
+
+```python
+od = ODMatrix.from_long([("A", "B", 120), ("B", "A", 40), ("A", "A", 300)])
+od = ODMatrix(["A", "B"], [[300, 120], [40, 0]])  # rows = origins, columns = destinations
+od.net().to_long()   # [('A', 'B', 80.0)]
+```
+
+## Command line
+
+```bash
+odflows summary commute.csv -o zones.csv              # per-zone indicators
+odflows summary commute.csv --json                    # matrix statistics
+odflows lines commute.csv --centroids zones.geojson --id-field zone \
+        --style curved --min-flow 50 -o lines.geojson
+odflows filter commute.csv --min-share 0.1 --basis origin -o main_flows.csv
+odflows transform commute.csv net -o net.csv          # net | gross | symmetric | ...
+odflows aggregate commute.csv --lookup lookup.csv -o districts.csv
+odflows regions commute.csv -n 5 -o regions.csv --summary regions_sc.csv
+odflows cluster commute.csv --centroids zones.geojson --id-field zone \
+        --n-clusters 8 -o bundles.geojson
+odflows export commute.csv --centroids zones.geojson --id-field zone \
+        --format flowmap -o mymap                       # mymap-locations.csv, mymap-flows.csv
+```
+
+Every command accepts `--matrix` for square-matrix input and `--origin-col`,
+`--dest-col`, `--flow-col` for other column names. Centroids may be a GeoJSON file or a
+CSV (`--id-field`, `--x-col`, `--y-col`).
+
+## API overview
+
+| Area | Functions / classes |
+|---|---|
+| Container | `ODMatrix` (`from_long`, `to_long`, `outflows`, `inflows`, `intrazonal`, `without_intrazonal`, `net`, `gross`, `symmetric`, `transpose`, `asymmetry_index`, `subset`) |
+| Input / output | `read_od_csv`, `read_matrix_csv`, `write_od_csv`, `write_matrix_csv`, `centroids_from_geojson`, `read_centroids_csv`, `geometry_centroid`, `write_geojson` |
+| Desire lines | `desire_lines`, `line_coordinates`, `haversine_km` |
+| Zone systems | `ZoneLookup` (`from_records`, `from_mapping`, `from_csv`, `from_geojson`), `reaggregate`, `aggregate` |
+| Filtering | `filter_min_flow`, `filter_top_k`, `filter_share`, `filter_cumulative`, `dominant_flows` |
+| Indicators | `degree`, `self_containment`, `job_ratio`, `net_balance`, `zone_summary`, `matrix_summary` |
+| Clustering | `FlowSet`, `flow_distance_matrix`, `flow_neighbour_counts`, `hierarchical_clusters`, `flow_dbscan`, `bundle_flows` |
+| Regions | `intramax`, `IntramaxResult`, `region_summary` |
+| Visualisation export | `write_flowmap_blue`, `write_kepler_csv` |
+| pandas | `from_dataframe`, `to_dataframe` |
+
+All filters and transformations return a new `ODMatrix`, so they chain:
+`filter_top_k(filter_share(od, 0.1), 50).without_intrazonal()`.
+
+## Methods and sources
+
+**Conventions.** `T[i, j]` is the flow from zone `i` to zone `j`. For commuting, rows
+are places of residence and columns places of work, so `O_i = Σ_j T_ij` are resident
+workers and `D_j = Σ_i T_ij` are jobs; both include intrazonal flows `T_ii`.
+
+**Net and gross flows.** Gross `G_ij = T_ij + T_ji`; net `N_ij = max(T_ij − T_ji, 0)`.
+The asymmetry index is `Σ_{i<j} |T_ij − T_ji| / Σ_{i<j} (T_ij + T_ji)`.
+
+**Desire lines.** Curved lines are quadratic Bézier curves whose control point is the
+midpoint moved to the right of the direction of travel by `bend × length`; offset lines
+are the segment shifted to the right by the same amount. A→B and B→A therefore fall on
+opposite sides. Lengths are haversine kilometres for longitude/latitude centroids
+(mean Earth radius 6371.0088 km) and planar units otherwise.
+
+**Polygon centroids** use the shoelace (area-weighted) formula on the exterior ring
+minus holes, treating coordinates as planar.
+
+**Zone re-aggregation.** With a row-normalised lookup `W` (`W[s, t]` = share of source
+zone `s` in target zone `t`), `T' = Wᵀ T W`. Flows are split assuming origins and
+destinations are spread within each source zone in proportion to the weights - areal
+weighting (Goodchild & Lam 1980). Different origin and destination lookups (e.g.
+population vs. employment weights) are supported; totals are preserved.
+
+**Filtering.** `filter_share(basis="origin")` keeps `T_ij / O_i ≥ s`;
+`dominant_flows` keeps each origin's largest outgoing flow, the first step of nodal
+region analysis (Nystuen & Dacey 1961).
+
+**Flow distance.** Tao & Thill (2016) define, for flows `i` and `j` with origin
+distance `d_O` and destination distance `d_D`,
+`FD = sqrt(α d_O² + β d_D²)` with `α + β = 2`, and the length-normalised
+dissimilarity `FDS = sqrt((α d_O² + β d_D²) / (L_i L_j))`. Coordinates must be
+projected. `flow_neighbour_counts` gives the local counting term of their flow
+K-function (no edge correction or significance test).
+
+**Clustering.** Agglomerative clustering uses the Lance-Williams (1967) update for
+single, complete and average (UPGMA) linkage; DBSCAN follows Ester et al. (1996), with
+an option to count flow volume instead of flow numbers. `bundle_flows` replaces every
+cluster by the flow from its volume-weighted mean origin to its volume-weighted mean
+destination.
+
+**Self-containment.** Supply-side `SC_s = T_ii / O_i` (share of resident workers who
+work locally) and demand-side `SC_d = T_ii / D_i` (share of local jobs filled by
+residents), as used for local labour market areas (Goodman 1970; Casado-Díaz 2000).
+The commuting job ratio is `D_i / O_i`.
+
+**Intramax.** Hierarchical aggregation (Masser & Brown 1975) that repeatedly merges
+the pair of current regions maximising `T_ij / (O_i D_j) + T_ji / (O_j D_i)` on the
+aggregated matrix; merged flows become intrazonal. The full hierarchy is stored and can
+be cut at any number of regions. An optional contiguity constraint only merges adjacent
+regions (Drobne & Lakner 2016). This is Intramax, not a modularity / Louvain method.
+
+**Export formats.** flowmap.blue reads a Google Sheet with a `locations` sheet
+(`id,name,lat,lon`) and a `flows` sheet (`origin,dest,count`); `write_flowmap_blue`
+writes one CSV per sheet. `write_kepler_csv` writes `origin_lat/origin_lng` and
+`dest_lat/dest_lng` column pairs, which kepler.gl detects as point fields for its arc
+and line layers.
+
+### References
+
+- Casado-Díaz, J. M. (2000). Local labour market areas in Spain: a case study. *Regional Studies*, 34(9), 843-856.
+- Drobne, S., & Lakner, M. (2016). Use of constraints in the hierarchical aggregation procedure Intramax. *Business Systems Research*, 7(2), 5-22.
+- Ester, M., Kriegel, H.-P., Sander, J., & Xu, X. (1996). A density-based algorithm for discovering clusters in large spatial databases with noise. *Proceedings of KDD-96*, 226-231.
+- Goodchild, M. F., & Lam, N. S.-N. (1980). Areal interpolation: a variant of the traditional spatial problem. *Geo-Processing*, 1, 297-312.
+- Goodman, J. F. B. (1970). The definition and analysis of local labour markets: some empirical problems. *British Journal of Industrial Relations*, 8(2), 179-196.
+- Lance, G. N., & Williams, W. T. (1967). A general theory of classificatory sorting strategies: 1. Hierarchical systems. *The Computer Journal*, 9(4), 373-380.
+- Masser, I., & Brown, P. J. B. (1975). Hierarchical aggregation procedures for interaction data. *Environment and Planning A*, 7(5), 509-523.
+- Nystuen, J. D., & Dacey, M. F. (1961). A graph theory interpretation of nodal regions. *Papers of the Regional Science Association*, 7, 29-42.
+- Tao, R., & Thill, J.-C. (2016). Spatial cluster detection in spatial flow data. *Geographical Analysis*, 48(4), 355-372.
+
+## Limitations
+
+- Centroids, Bézier offsets, polygon centroids and the flow distance are planar. Use a
+  projected CRS for clustering and for exact curve shapes; `desire_lines` guesses
+  longitude/latitude from coordinate ranges (override with `geographic=`), which can
+  misfire for small projected coordinates.
+- Re-aggregation assumes uniform spreading within source zones (areal weighting).
+  Use population or employment weights where you have them.
+- Intramax and agglomerative clustering are O(n³); fine for hundreds of zones and a few
+  thousand flows, not for full national matrices. Pairs with no interaction are never
+  merged, so Intramax may stop before reaching the requested number of regions.
+- Flow statistics stop at the flow distance, dissimilarity and neighbour counts: the
+  flow K-function with edge correction, and significance testing, are not implemented.
+- No travel-to-work-area (TTWA) thresholds are built in; check region self-containment
+  against the criteria of your own study.
+
+## Academic citation
+
+If you use `odflows` in research, please cite it:
+
+```bibtex
+@software{eminoglu_odflows,
+  author  = {Eminoğlu, Yusuf},
+  title   = {odflows},
+  year    = {2026},
+  version = {0.1.0},
+  url     = {https://github.com/YusufEminoglu/odflows_sdk}
+}
+```
+
+See also [`CITATION.cff`](CITATION.cff).
+
+## License
+
+MIT © 2026 Yusuf Eminoğlu. Contact: geospacephilo@gmail.com

odflows-0.1.0/README.md

@@ -0,0 +1,216 @@
+# odflows
+
+[![PyPI version](https://img.shields.io/pypi/v/odflows.svg)](https://pypi.org/project/odflows/)
+[![Python versions](https://img.shields.io/pypi/pyversions/odflows.svg)](https://pypi.org/project/odflows/)
+[![CI](https://github.com/YusufEminoglu/odflows_sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/YusufEminoglu/odflows_sdk/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/YusufEminoglu/odflows_sdk/blob/main/LICENSE)
+
+**Origin-destination flow toolkit for mobility and commuting analysis.**
+
+`odflows` covers the usual steps of an OD study in one small package that needs only
+numpy:
+
+- **Read** OD tables in long form (`origin,destination,flow`) or as a square matrix, and
+  zone centroids from GeoJSON (points, or area centroids of polygons) or CSV.
+- **Desire lines** as GeoJSON LineStrings: directed, net or gross; straight, **curved**
+  or **offset**, so both directions of a two-way pair stay visible.
+- **Change zone systems**: aggregate and disaggregate with weighted lookup tables,
+  including area weights computed from two polygon layers (optional `shapely`).
+- **Net and gross flows**, symmetric part, asymmetry index, intrazonal handling.
+- **Filter** flows: minimum size, top-k, share of origin / destination / total,
+  cumulative share, dominant (largest outgoing) flows.
+- **Cluster and bundle** flows with the Tao & Thill flow distance: agglomerative
+  (single / complete / average linkage) and DBSCAN, in pure numpy.
+- **Indicators**: in/out degree and strength, supply- and demand-side
+  self-containment, commuting job ratio, net balance.
+- **Functional regions** (commuting zones) with **Intramax** (Masser & Brown 1975),
+  optionally contiguity-constrained.
+- **Export** to GeoJSON, **flowmap.blue** (`locations` + `flows` sheets) and a
+  **kepler.gl** arc-layer CSV.
+- A command-line tool, `odflows`.
+
+```bash
+pip install odflows            # numpy only
+pip install "odflows[pandas]"  # + DataFrame helpers
+pip install "odflows[geo]"     # + shapely, for area-weighted lookups from polygons
+```
+
+Requires Python 3.9 or newer.
+
+## Quick start
+
+```python
+from odflows import (
+    ODMatrix, read_od_csv, centroids_from_geojson, desire_lines, write_geojson,
+    zone_summary, intramax, region_summary, filter_top_k,
+)
+
+od = read_od_csv("commute.csv")                 # origin,destination,flow
+zones = centroids_from_geojson("zones.geojson", id_field="zone")
+
+for row in zone_summary(od):                     # self-containment, job ratio, ...
+    print(row["zone"], round(row["supply_sc"], 3), round(row["job_ratio"], 2))
+
+lines = desire_lines(filter_top_k(od, 20), zones, style="curved")
+write_geojson(lines, "desire_lines.geojson")
+
+hierarchy = intramax(od)                         # full Intramax hierarchy
+membership = hierarchy.membership(n_regions=4)   # cut it at 4 regions
+print(region_summary(od, membership))
+```
+
+A runnable example with synthetic data is in
+[`examples/quickstart.py`](examples/quickstart.py).
+
+Matrices can also be built in memory:
+
+```python
+od = ODMatrix.from_long([("A", "B", 120), ("B", "A", 40), ("A", "A", 300)])
+od = ODMatrix(["A", "B"], [[300, 120], [40, 0]])  # rows = origins, columns = destinations
+od.net().to_long()   # [('A', 'B', 80.0)]
+```
+
+## Command line
+
+```bash
+odflows summary commute.csv -o zones.csv              # per-zone indicators
+odflows summary commute.csv --json                    # matrix statistics
+odflows lines commute.csv --centroids zones.geojson --id-field zone \
+        --style curved --min-flow 50 -o lines.geojson
+odflows filter commute.csv --min-share 0.1 --basis origin -o main_flows.csv
+odflows transform commute.csv net -o net.csv          # net | gross | symmetric | ...
+odflows aggregate commute.csv --lookup lookup.csv -o districts.csv
+odflows regions commute.csv -n 5 -o regions.csv --summary regions_sc.csv
+odflows cluster commute.csv --centroids zones.geojson --id-field zone \
+        --n-clusters 8 -o bundles.geojson
+odflows export commute.csv --centroids zones.geojson --id-field zone \
+        --format flowmap -o mymap                       # mymap-locations.csv, mymap-flows.csv
+```
+
+Every command accepts `--matrix` for square-matrix input and `--origin-col`,
+`--dest-col`, `--flow-col` for other column names. Centroids may be a GeoJSON file or a
+CSV (`--id-field`, `--x-col`, `--y-col`).
+
+## API overview
+
+| Area | Functions / classes |
+|---|---|
+| Container | `ODMatrix` (`from_long`, `to_long`, `outflows`, `inflows`, `intrazonal`, `without_intrazonal`, `net`, `gross`, `symmetric`, `transpose`, `asymmetry_index`, `subset`) |
+| Input / output | `read_od_csv`, `read_matrix_csv`, `write_od_csv`, `write_matrix_csv`, `centroids_from_geojson`, `read_centroids_csv`, `geometry_centroid`, `write_geojson` |
+| Desire lines | `desire_lines`, `line_coordinates`, `haversine_km` |
+| Zone systems | `ZoneLookup` (`from_records`, `from_mapping`, `from_csv`, `from_geojson`), `reaggregate`, `aggregate` |
+| Filtering | `filter_min_flow`, `filter_top_k`, `filter_share`, `filter_cumulative`, `dominant_flows` |
+| Indicators | `degree`, `self_containment`, `job_ratio`, `net_balance`, `zone_summary`, `matrix_summary` |
+| Clustering | `FlowSet`, `flow_distance_matrix`, `flow_neighbour_counts`, `hierarchical_clusters`, `flow_dbscan`, `bundle_flows` |
+| Regions | `intramax`, `IntramaxResult`, `region_summary` |
+| Visualisation export | `write_flowmap_blue`, `write_kepler_csv` |
+| pandas | `from_dataframe`, `to_dataframe` |
+
+All filters and transformations return a new `ODMatrix`, so they chain:
+`filter_top_k(filter_share(od, 0.1), 50).without_intrazonal()`.
+
+## Methods and sources
+
+**Conventions.** `T[i, j]` is the flow from zone `i` to zone `j`. For commuting, rows
+are places of residence and columns places of work, so `O_i = Σ_j T_ij` are resident
+workers and `D_j = Σ_i T_ij` are jobs; both include intrazonal flows `T_ii`.
+
+**Net and gross flows.** Gross `G_ij = T_ij + T_ji`; net `N_ij = max(T_ij − T_ji, 0)`.
+The asymmetry index is `Σ_{i<j} |T_ij − T_ji| / Σ_{i<j} (T_ij + T_ji)`.
+
+**Desire lines.** Curved lines are quadratic Bézier curves whose control point is the
+midpoint moved to the right of the direction of travel by `bend × length`; offset lines
+are the segment shifted to the right by the same amount. A→B and B→A therefore fall on
+opposite sides. Lengths are haversine kilometres for longitude/latitude centroids
+(mean Earth radius 6371.0088 km) and planar units otherwise.
+
+**Polygon centroids** use the shoelace (area-weighted) formula on the exterior ring
+minus holes, treating coordinates as planar.
+
+**Zone re-aggregation.** With a row-normalised lookup `W` (`W[s, t]` = share of source
+zone `s` in target zone `t`), `T' = Wᵀ T W`. Flows are split assuming origins and
+destinations are spread within each source zone in proportion to the weights - areal
+weighting (Goodchild & Lam 1980). Different origin and destination lookups (e.g.
+population vs. employment weights) are supported; totals are preserved.
+
+**Filtering.** `filter_share(basis="origin")` keeps `T_ij / O_i ≥ s`;
+`dominant_flows` keeps each origin's largest outgoing flow, the first step of nodal
+region analysis (Nystuen & Dacey 1961).
+
+**Flow distance.** Tao & Thill (2016) define, for flows `i` and `j` with origin
+distance `d_O` and destination distance `d_D`,
+`FD = sqrt(α d_O² + β d_D²)` with `α + β = 2`, and the length-normalised
+dissimilarity `FDS = sqrt((α d_O² + β d_D²) / (L_i L_j))`. Coordinates must be
+projected. `flow_neighbour_counts` gives the local counting term of their flow
+K-function (no edge correction or significance test).
+
+**Clustering.** Agglomerative clustering uses the Lance-Williams (1967) update for
+single, complete and average (UPGMA) linkage; DBSCAN follows Ester et al. (1996), with
+an option to count flow volume instead of flow numbers. `bundle_flows` replaces every
+cluster by the flow from its volume-weighted mean origin to its volume-weighted mean
+destination.
+
+**Self-containment.** Supply-side `SC_s = T_ii / O_i` (share of resident workers who
+work locally) and demand-side `SC_d = T_ii / D_i` (share of local jobs filled by
+residents), as used for local labour market areas (Goodman 1970; Casado-Díaz 2000).
+The commuting job ratio is `D_i / O_i`.
+
+**Intramax.** Hierarchical aggregation (Masser & Brown 1975) that repeatedly merges
+the pair of current regions maximising `T_ij / (O_i D_j) + T_ji / (O_j D_i)` on the
+aggregated matrix; merged flows become intrazonal. The full hierarchy is stored and can
+be cut at any number of regions. An optional contiguity constraint only merges adjacent
+regions (Drobne & Lakner 2016). This is Intramax, not a modularity / Louvain method.
+
+**Export formats.** flowmap.blue reads a Google Sheet with a `locations` sheet
+(`id,name,lat,lon`) and a `flows` sheet (`origin,dest,count`); `write_flowmap_blue`
+writes one CSV per sheet. `write_kepler_csv` writes `origin_lat/origin_lng` and
+`dest_lat/dest_lng` column pairs, which kepler.gl detects as point fields for its arc
+and line layers.
+
+### References
+
+- Casado-Díaz, J. M. (2000). Local labour market areas in Spain: a case study. *Regional Studies*, 34(9), 843-856.
+- Drobne, S., & Lakner, M. (2016). Use of constraints in the hierarchical aggregation procedure Intramax. *Business Systems Research*, 7(2), 5-22.
+- Ester, M., Kriegel, H.-P., Sander, J., & Xu, X. (1996). A density-based algorithm for discovering clusters in large spatial databases with noise. *Proceedings of KDD-96*, 226-231.
+- Goodchild, M. F., & Lam, N. S.-N. (1980). Areal interpolation: a variant of the traditional spatial problem. *Geo-Processing*, 1, 297-312.
+- Goodman, J. F. B. (1970). The definition and analysis of local labour markets: some empirical problems. *British Journal of Industrial Relations*, 8(2), 179-196.
+- Lance, G. N., & Williams, W. T. (1967). A general theory of classificatory sorting strategies: 1. Hierarchical systems. *The Computer Journal*, 9(4), 373-380.
+- Masser, I., & Brown, P. J. B. (1975). Hierarchical aggregation procedures for interaction data. *Environment and Planning A*, 7(5), 509-523.
+- Nystuen, J. D., & Dacey, M. F. (1961). A graph theory interpretation of nodal regions. *Papers of the Regional Science Association*, 7, 29-42.
+- Tao, R., & Thill, J.-C. (2016). Spatial cluster detection in spatial flow data. *Geographical Analysis*, 48(4), 355-372.
+
+## Limitations
+
+- Centroids, Bézier offsets, polygon centroids and the flow distance are planar. Use a
+  projected CRS for clustering and for exact curve shapes; `desire_lines` guesses
+  longitude/latitude from coordinate ranges (override with `geographic=`), which can
+  misfire for small projected coordinates.
+- Re-aggregation assumes uniform spreading within source zones (areal weighting).
+  Use population or employment weights where you have them.
+- Intramax and agglomerative clustering are O(n³); fine for hundreds of zones and a few
+  thousand flows, not for full national matrices. Pairs with no interaction are never
+  merged, so Intramax may stop before reaching the requested number of regions.
+- Flow statistics stop at the flow distance, dissimilarity and neighbour counts: the
+  flow K-function with edge correction, and significance testing, are not implemented.
+- No travel-to-work-area (TTWA) thresholds are built in; check region self-containment
+  against the criteria of your own study.
+
+## Academic citation
+
+If you use `odflows` in research, please cite it:
+
+```bibtex
+@software{eminoglu_odflows,
+  author  = {Eminoğlu, Yusuf},
+  title   = {odflows},
+  year    = {2026},
+  version = {0.1.0},
+  url     = {https://github.com/YusufEminoglu/odflows_sdk}
+}
+```
+
+See also [`CITATION.cff`](CITATION.cff).
+
+## License
+
+MIT © 2026 Yusuf Eminoğlu. Contact: geospacephilo@gmail.com

odflows-0.1.0/examples/commute.csv

@@ -0,0 +1,21 @@
+origin,destination,flow
+Centre,Centre,900
+Centre,North,60
+Centre,East,80
+Centre,South,40
+Centre,West,30
+North,Centre,420
+North,North,300
+North,East,50
+North,West,20
+East,Centre,380
+East,North,40
+East,East,350
+East,South,25
+South,Centre,260
+South,East,30
+South,South,280
+South,West,90
+West,Centre,210
+West,South,110
+West,West,240

odflows-0.1.0/examples/quickstart.py

@@ -0,0 +1,67 @@
+"""odflows quick start on a small synthetic commuting matrix.
+
+    python examples/quickstart.py
+
+Reads ``commute.csv`` (rows = residence, columns = workplace) and ``zones.geojson``
+(five fictional square zones in projected metres), prints zone indicators and an
+Intramax regionalisation, and writes curved desire lines and flow bundles to
+``examples/out/``. All data are synthetic.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from odflows import (
+    FlowSet,
+    bundle_flows,
+    centroids_from_geojson,
+    desire_lines,
+    filter_share,
+    flow_distance_matrix,
+    hierarchical_clusters,
+    intramax,
+    matrix_summary,
+    read_od_csv,
+    region_summary,
+    write_geojson,
+    zone_summary,
+)
+
+HERE = Path(__file__).parent
+OUT = HERE / "out"
+
+
+def main() -> None:
+    od = read_od_csv(HERE / "commute.csv")
+    centroids = centroids_from_geojson(HERE / "zones.geojson", id_field="zone")
+    print(od)
+    print({k: round(v, 3) for k, v in matrix_summary(od).items()})
+
+    print("\nzone        SC(supply) SC(demand) job ratio")
+    for row in zone_summary(od):
+        print(
+            f"{row['zone']:<10} {row['supply_sc']:>10.3f} {row['demand_sc']:>10.3f}"
+            f" {row['job_ratio']:>9.3f}"
+        )
+
+    hierarchy = intramax(od)
+    for step in hierarchy.steps:
+        print(f"Intramax: {step.absorbed} -> {step.region} (score {step.score:.5f})")
+    membership = hierarchy.membership(2)
+    for row in region_summary(od, membership):
+        print(f"region {row['region']}: {row['n_zones']} zones, supply SC {row['supply_sc']:.3f}")
+
+    OUT.mkdir(exist_ok=True)
+    main_flows = filter_share(od, 0.05)  # flows >= 5 % of their origin's outflow
+    lines = desire_lines(main_flows, centroids, style="curved", geographic=False)
+    write_geojson(lines, OUT / "desire_lines.geojson")
+
+    flows = FlowSet.from_od(od, centroids)
+    labels = hierarchical_clusters(flow_distance_matrix(flows), threshold=8000.0)
+    write_geojson(bundle_flows(flows, labels), OUT / "bundles.geojson")
+    print(f"\n{len(lines['features'])} desire lines, {labels.max() + 1} flow bundles -> {OUT}")
+
+
+if __name__ == "__main__":
+    main()