Skip to content

Commit d091122

Browse files
TheFamousRatTheFamousRat
authored
Changes from previous repo (#1)
1 parent b9b1269 commit d091122

File tree

117 files changed

+175925
-2
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

117 files changed

+175925
-2
lines changed

‎.github/workflows/python-package.yml

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: Tests
2+
3+
on: push
4+
5+
concurrency:
6+
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
7+
cancel-in-progress: true
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
strategy:
13+
matrix:
14+
python-version: ["3.10"]
15+
16+
steps:
17+
- name: Check out repository code
18+
uses: actions/checkout@v4
19+
- name: Setup Python
20+
uses: actions/setup-python@v5
21+
with:
22+
python-version: ${{ matrix.python-version }}
23+
- name: Install dependencies
24+
run: |
25+
python -m pip install --upgrade pip
26+
python -m pip install poetry
27+
poetry install --with dev
28+
- name: Run tests
29+
run: |
30+
poetry run pytest
31+
- name: Run examples
32+
run: |
33+
poetry run python hierarchical_urban_systems/examples/run_examples.py

‎.gitignore

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
src/tmpNiceFormatting.sql
2+
*.gpkg-shm
3+
*.gpkg-wal
4+
*.png
5+
*.png~
6+
*.shp
7+
*.shx
8+
*.prj
9+
*.dbf
10+
*.cpg
11+
*.shp.*
12+
*.pyc
13+
__pycache__/*
14+
.idea/*
15+
**/debug_output/*

‎CITATION.cff

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# This CITATION.cff file was generated with cffinit.
2+
# Visit https://bit.ly/cffinit to generate yours today!
3+
4+
cff-version: 1.2.0
5+
title: Hierarchical Urban Systems
6+
message: >-
7+
If you use this software, please cite it using the
8+
metadata from this file.
9+
type: software
10+
authors:
11+
- given-names: Guillaume
12+
family-names: Roy
13+
email: gm.roy.aq@gmail.com
14+
repository-code: 'https://github.com/TheFamousRat/HierarchicalUrbanSystems'
15+
abstract: >-
16+
Method for iteratively detecting and hierarchically
17+
organizing centers as urban regions, within a commuting
18+
network.
19+
license: GPL-3.0
20+
version: 1.0.0
21+
identifiers:
22+
- type: doi
23+
value: 10.5281/zenodo.14605989
24+
date-released: '2025-01-06'

‎LICENSE

+674
Large diffs are not rendered by default.

‎README.md

+188-2
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,188 @@
1-
# HierarchicalUrbanSystems
2-
Method for iteratively detecting and hierarchically organizing centers as urban regions, within a commuting network.
1+
<p align="center">
2+
<img src="img/usa_new_england_10.jpg" width="32.8%">
3+
<img src="img/usa_new_england_7.jpg" width="32.8%">
4+
<img src="img/usa_new_england_4.jpg" width="32.8%">
5+
<i>Centers detected from commuting flows in the Northeastern USA, at center levels 10, 7 and 4 (from left to right).</i>
6+
</p>
7+
8+
<h1 align="center">Hierarchical Urban Systems</h1>
9+
10+
![Tests](https://github.com/TheFamousRat/HierarchicalUrbanSystems/actions/workflows/python-package.yml/badge.svg)
11+
[![DOI](https://zenodo.org/badge/805814944.svg)](https://doi.org/10.5281/zenodo.14605988)
12+
13+
<h2>Table of Contents</h2>
14+
15+
- [Overview](#overview)
16+
- [Introduction](#introduction)
17+
- [Algorithm](#algorithm)
18+
- [Getting Started](#getting-started)
19+
- [How to Use](#how-to-use)
20+
- [Detecting centres on local data](#detecting-centres-on-local-data)
21+
- [Detecting centres on custom data](#detecting-centres-on-custom-data)
22+
- [Citing this repository](#citing-this-repository)
23+
- [Gallery](#gallery)
24+
- [Credits](#credits)
25+
- [References](#references)
26+
- [Data Sources](#data-sources)
27+
28+
## Overview
29+
30+
We propose a novel approach to detecting and characterizing urban areas. Our algorithm produces a hierarchical assignment of the nodes in a commuting system, thus representing urban regions as the union of smaller local centres. This approach has proved experimentally robust on commuting datasets from different countries using different administrative systems.
31+
32+
In this repository, you will find:
33+
- The complete source code of a memory-efficient implementation of our algorithm.
34+
- Commuting data sources from various countries, used for development and readily available. The countries are France, Belgium, Italy, Switzerland, and the United States. The raw data as well as the scripts used to format it are also present.
35+
- Up-to-date examples on how to use the algorithm in this repository to detect hierarchical urban systems in either custom or provided commuting data.
36+
- A detailed walk through the concepts and method used by our algorithm (link [here](docs/ALGORITHM.md)).
37+
- Tests and CI elements of the various components of this repository.
38+
39+
## Introduction
40+
41+
Modern cities exert influence over vast areas surrounding the core centre, leading to the establishment of vast urban regions. Due to the relatively recent emergence of these regions, their extent often reaches far beyond the administrative limits of the urban cores [(Cardoso et al., 2021)](#Cardoso2021). Furthermore, urban regions are not consistently represented and characterized between countries, leading to challenges in comparison and governance. Determining the boundaries of these urban regions is thus of particular interest.
42+
43+
The movement of goods and people is an actively explored source to delineate the boundaries of urban regions. By capturing the exchanges between residential, working and commercial places, it is possible to highlight hubs of intense attractivity. The combination of these areas of high attractivity with their dependent areas allows for the definition of individual Functional Urban Regions. By focusing on where people interact and move to the most, FUR allow for the identification of typical urban structures, as well as that of complex, polycentric systems. A popular approach to define these areas is through commuting flows [(Moreno-Monroy et al., 2021)](#Moreno-Monroy2021) [(Bosker et al., 2021)](#Bosker2021) [(Duranton et al., 2015)](#Duranton2015), but other sources such as cellphone data have been explored [(Chen et al., 2022)](#Chen2022). One notable method is the definition of Functional Urban Areas [(Dijkstra et al., 2019)](#Dijkstra2019), which delimits urban regions by identifying commuting zones around densely populated urban cores. This definition has been adopted by the OECD and by some of its member countries as the standard for characterizing urban areas.
44+
45+
While a large body of work is devoted to determining the boundaries of an urban region, so far the characterization of these regions' structures is not a well-explored topic. Urban regions are heterogeneous in nature, comprising extensive interactions between fundamentally different entities, from dense urban cores to suburban areas, and secondary cities to rural places [(Hall et al., 2013)](#Hall2013). Despite belonging to the same urban region, such spaces all present their own challenges and economic disparities that need to be addressed through effective governance [(Qian et al., 2020)](#QIAN2020) [(Band et al., 2005)](#BAND2005). As such, characterizing the underlying structures of urban regions is key to their understanding.
46+
47+
In this repository, we propose a novel method aimed at characterizing these structures. Our algorithm uses only commuting flows between the various nodes (typically administrative units) of a system. It works by first finding the centres that best represent local commuting flows. We then iteratively merge these centres based on their indirect commuting flows, which grow in scope at every step. The end result is a levelled centre assignment for every node, where the lower levels represent local centres and the higher levels represent wider urban regions. Urban regions are thus built as hierarchical systems, describing a wider zone of interaction between local systems.
48+
49+
Our method works by finding the best fitting centre for every previously detected centre at every step. It is parameterless, ensuring adaptability to different datasets. It has proved experimentally robust on commuting datasets originating from various countries using significantly different administrative structures. Our contributions are the following:
50+
51+
* A flexible and parameter-less algorithm, able to detect urban systems of any size, relying only on commuting data.
52+
* A cohesive hierarchical structure detailing the relationship of smaller centres to larger urban systems.
53+
* Comparable results across commuting systems of different structures between different countries, at the same assignment level.
54+
* A novel metric to measure the cohesion and representation of nodes in their clusters.
55+
* An efficient algorithm implementation leveraging the inherent sparsity of commuting flow matrices, making it possible to process very large node networks.
56+
57+
<p align="center">
58+
<img src="img/fua_france.jpg" align="middle" width="49%">
59+
<img src="img/france_3_5.jpg" align="middle" width="49%">
60+
<i>Urban Systems in metropolitan France, following the OECD definition of Functional Urban Areas (left) and by our approach at center level 3 and 5 (right). Since our approach does not rely on density criteria, it is able to identify centers in rural areas, as well as in highly polycentric urban systems. Furthermore, large urban areas such as Paris (center-north) and Lyon (center-east) are decomposed according to the distinct, interconnected cities making up the urban region.</i>
61+
</p>
62+
63+
## Algorithm
64+
65+
The details of the algorithm as well as the concepts used to elaborate it can be found [here](docs/ALGORITHM.md).
66+
67+
## Getting Started
68+
69+
Clone the repository locally into an appropriate folder.
70+
71+
```bash
72+
git clone https://github.com/TheFamousRat/HierarchicalUrbanSystems.git
73+
```
74+
75+
You can then move into the downloaded folder by running
76+
77+
```bash
78+
cd HierarchicalUrbanSystems
79+
```
80+
81+
The Python dependencies are defined in the [pyproject.toml](pyproject.toml). We recommend the use of `poetry` to install the dependencies. If you do not yet have `poetry`, please follow the link here for installation instructions: https://python-poetry.org/docs/main/#installing-with-the-official-installer.
82+
83+
Once poetry has been installed, simply run
84+
85+
```bash
86+
poetry install
87+
```
88+
89+
to install the dependencies cached in `poetry.lock`. This step will create a virtual environment for the project. You can activate it by running:
90+
91+
```bash
92+
source .venv/bin/activate
93+
```
94+
95+
If all the steps above worked successfully, it should be possible to interact with the code directly. Running one of the example files would then be done like so
96+
97+
```bash
98+
python hierarchical_urban_systems/examples/detect_and_save_centers_assignment_switzerland.py
99+
```
100+
101+
## How to Use
102+
103+
We provide examples on various use cases for our algorithm. Please refer to them if you want to get started in using this repository in a project. To ensure that these examples stay up-to-date, we do not include them directly in this README, please find them in the examples folder (link [here](hierarchical_urban_systems/examples)).
104+
105+
### Detecting centres on local data
106+
107+
This repository already contains datasets of the commuting flows from various countries. An example on how to read one such dataset, extract centers from it and save them locally can be found [here](hierarchical_urban_systems/examples/detect_and_save_centers_assignment_switzerland.py).
108+
109+
### Detecting centres on custom data
110+
111+
It is also of course possible to use the algorithm with custom data. The only required input to the algorithm is a sparse matrix containing the flows between the nodes. It is also possible to provide information on the nodes, such as the postal code or name of the unit they correspond to. We provide an example of how to extract and save centres from such flows [here](hierarchical_urban_systems/examples/detect_centers_in_custom_flows.py).
112+
113+
## Citing this repository
114+
115+
If this repository has been helpful to you, please cite it. We have included a [CITATION.cff file](CITATION.cff) for a recommended citation style as well as relevant information regarding this codebase. A citation can directly be obtained and copied to the clipboard in APA or BibTeX format by clicking **"Cite this repository"** on this repository's sidebar. Find more information on Github citations [here](https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files).
116+
117+
## Gallery
118+
119+
<p align="center">
120+
<img src="img/usa_7_northeast.jpg" width="49%">
121+
</p>
122+
<p align="center">
123+
<em>Northeast United States, centers of level 7 with commuter flows.</em>
124+
</p>
125+
126+
<p align="center">
127+
<img src="img/switzerland_7.jpg" width="32%">
128+
<img src="img/switzerland_5.jpg" width="32%">
129+
<img src="img/switzerland_3.jpg" width="32%">
130+
<i>Centers detected from commuting flows in Switzerland, at center levels 7, 5 and 3 (from left to right).</i>
131+
</p>
132+
133+
## Credits
134+
135+
### References
136+
137+
<a id="Hall2013"></a>
138+
HALL, Peter. Looking backward, looking forward: The city region of the mid-21st century. In : The futures of the city region. Routledge, 2013. p. 15-29.
139+
140+
<a id="Dijkstra2019"></a>
141+
DIJKSTRA, Lewis, POELMAN, Hugo, et VENERI, Paolo. The EU-OECD definition of a functional urban area. 2019.
142+
143+
<a id="Moreno-Monroy2021"></a>
144+
MORENO-MONROY, Ana I., SCHIAVINA, Marcello, et VENERI, Paolo. Metropolitan areas in the world. Delineation and population trends. Journal of Urban Economics, 2021, vol. 125, p. 103242.
145+
146+
<a id="Bosker2021"></a>
147+
BOSKER, Maarten, PARK, Jane, et ROBERTS, Mark. Definition matters. Metropolitan areas and agglomeration economies in a large-developing country. Journal of Urban Economics, 2021, vol. 125, p. 103275.
148+
149+
<a id="Chen2022"></a>
150+
CHEN, Zifeng et YEH, Anthony Gar-On. Delineating functional urban areas in Chinese mega city regions using fine-grained population data and cellphone location data: A case of Pearl River Delta. Computers, environment and urban systems, 2022, vol. 93, p. 101771.
151+
152+
<a id="Duranton2015"></a>
153+
DURANTON, Gilles. A proposal to delineate metropolitan areas in Colombia. Desarrollo y Sociedad, 2015, no 75, p. 223-264.
154+
155+
<a id="Cardoso2020"></a>
156+
CARDOSO, Rodrigo et MEIJERS, Evert. The process of metropolization in megacity-regions. In : Handbook of megacities and megacity-regions. Edward Elgar Publishing, 2020. p. 360-375.
157+
158+
<a id="Cardoso2021"></a>
159+
CARDOSO, Rodrigo et MEIJERS, Evert. Metropolization processes and intra-regional contrasts: The uneven fortunes of English secondary cities. In : Secondary Cities. Bristol University Press, 2021. p. 103-132.
160+
161+
<a id="Derudder2022"></a>
162+
DERUDDER, Ben, MEIJERS, Evert, HARRISON, John, et al. Polycentric urban regions: Conceptualization, identification and implications. Regional Studies, 2022, vol. 56, no 1, p. 1-6.
163+
164+
<a id="GLAESER2011"></a>
165+
GLAESER, Edward. Cities, productivity, and quality of life. Science, 2011, vol. 333, no 6042, p. 592-594.
166+
167+
<a id="BAND2005"></a>
168+
BAND, Larry E., CADENASSO, Mary L., GRIMMOND, C. Susan, et al. Heterogeneity in urban ecosystems: patterns and process. Ecosystem function in heterogeneous landscapes, 2005, p. 257-278.
169+
170+
<a id="QIAN2020"></a>
171+
QIAN, Yuguo, ZHOU, Weiqi, PICKETT, Steward TA, et al. Integrating structure and function: Mapping the hierarchical spatial heterogeneity of urban landscapes. Ecological Processes, 2020, vol. 9, p. 1-11.
172+
173+
<a id="Ahrend2015"></a>
174+
Rudiger Ahrend, Emily Farchy, Ioannis Kaplanis, Alexander C. Lembcke WHAT MAKES CITIES MORE PRODUCTIVE? EVIDENCE ON THE ROLE OF URBAN GOVERNANCE FROM FIVE OECD COUNTRIES
175+
176+
<a id="Nelles2013"></a>
177+
NELLES, Jen. Cooperation and capacity? Exploring the sources and limits of city‐region governance partnerships. International Journal of Urban and Regional Research, 2013, vol. 37, no 4, p. 1349-1367.
178+
179+
180+
### Data Sources
181+
182+
- **France** : INSEE, Mobilités professionnelles en 2020 : déplacements domicile - lieu de travail, https://www.insee.fr/fr/statistiques/7630376
183+
- **Belgium** : Statbel, Census 2011 - Matrice des déplacements domicile-travail par sexe, https://statbel.fgov.be/fr/open-data/census-2011-matrice-des-deplacements-domicile-travail-par-sexe
184+
- **Switzerland** : Federal Statistical Office, Employed persons by commune of residence and work, 2014, 2018 and 2020, https://www.bfs.admin.ch/asset/en/27885394
185+
- **Italy** : Istat, Matrici del pendolarismo 2011, https://www.istat.it/non-categorizzato/matrici-del-pendolarismo/
186+
- **United States** : United States Census, 2016-2020 5-Year ACS Commuting Flows, https://www.census.gov/data/tables/2020/demo/metro-micro/commuting-flows-2020.html
187+
188+

‎countries_data/Belgium/belgium.qgz

163 KB
Binary file not shown.

0 commit comments

Comments
 (0)