=============================================================================================================================================

This is the README file for the code and data folder for the paper: 
"Beyond Walking and Biking: Expanding the 15-Minute City Area through Public Transport" 
by Manuela Canestrini (manuela.canestrini@geo.tuwien.ac.at) and Ioannis Giannopoulos

=============================================================================================================================================

Programming Language: Python (Version 3.10)
Most important libraries with versions: 
- pandas==2.2
- networkx==3.2
- numpy==1.26
- scipy==1.12
- geopandas==0.14
- shapely==2.0
- contextily==1.5
- matplotlib==3.8

e.g. create a conda environment in the Anaconda Prompt like this:
conda create -n myenv python=3.10 pandas=2.2 networkx=3.2 numpy=1.26 scipy=1.12 geopandas=0.14 shapely=2.0  contextily=1.5 matplotlib=3.8

The libraries with versions are also listed in the requirements.txt file for automatic installation.

The zip folder is structured as follow: 

   1. code: Includes script files essential for conducting the analysis. The scripts are written in Python.
   2. data: Contains the datasets for the analysis.
   3. results: Includes the outcomes showcased in the associated paper.

******************** To ensure that the scripts run smoothly, it's important to maintain the folder structure unchanged! ********************

** code:
   This folder includes all scripts to do the 15-minute city analysis and to produce results and plots.
   The following scripts need to be run individually and in this order:
	- a_extract_pois.py (1x)
	- b_accessibility_mp.py (1x) --> only showcasing the accessibility computation, actual results precomputed and provided in folder ** results\accessibility 
	- c_analysis.py (2x - different user input)
	- d_plots.py (1x)
   Run all four scripts from within this folder 'code'. At the end of this README, each of the Python scripts and their input/output is explained in detail.
   Additionally, the two files 'helpers.py' and 'ref_systems.py' include parameters and functions for other scripts. They should not be touched.

** data:
   This folder includes the data needed to run the provided Python scripts.
	- BEZIRKSGRENZEOGD
		- district boundaries of Vienna, downloaded from https://www.data.gv.at
		. BEZIRKSGRENZEOGDPolygon.shp: shapefile containing the district boundaries of Vienna
		. additional meta-files
	- graphs_small
		- all necessary graphs, derived from OpenStreetMap, restricted to a small extent of the ROI (due to other publications in progress)
		. bike.p: bike graph
		. walk.p: walk graph
		. walk_PT.p: walk and public transport (bus, tram, subway, train) graph
	- osm
		- OSM data
		. nodes.csv
		. relations.csv
		. ways.csv
	- tags
		. key-value lists for OSM tags, all POI categories, derived from the supplementary information of Bruno et al. (2024)
		. culture.csv
		. education.csv
		. ...
		. transport.csv

** results:
   This folder contains all results which are generated from the provided Python scripts plus one folder ('accessibility') with precomputed results.
	- accessibility (provided for the whole ROI)
	- accessibility_small
	- analysis
	- plots
	- pois

********************************* PYTHON SCRIPTS *********************************

** a_extract_pois.py
	- script to derive Points of Interest (POIs) from OpenStreetMap (OSM) data for all nine POI categories
	- input from user: none
	- input data: three .csv files with OSM ('data\osm\<nodes ways relations>.csv') and nine .csv files with key-value pairs ('data\tags\<POI category>.csv')
	- output data: nine .csv files (one for each POI category) with POI id, location, tags and type
	- output path: 'results\pois\<POI category>.csv'

** b_accessibility_mp.py
	- script for the computation of hexagon-level accessibility for all modes and all nine POI categories
	- input from user: yes or no (to select the speed model)
	- input data: POI .csv files, shapefile with boundaries of Vienna and the necessary graphs
	- output data: nine .csv files for each mode ('walk', 'bike', 'walk_PT') and speed model 'terrain_yes'
	- output path: 'results\accessibility_small\<mode>\terrain_yes\<POI category>.csv'
	NOTE: This script showcases the accessibility computation for the provided small graph extent, NOT for the whole ROI;
	the scripts 'c_analysis.py' and 'd_plots.py' are then based on the provided accessibility results 'results\accessibility' for the whole ROI.
	The correctness of the computed output can be checkt against the provided results by matching the first column.

** c_analysis.py
	- script for the analysis of the accessibility results
	- input from user: yes or no (to select the speed model) --> thus run two times!
	- input data: accesibility results
	- output data: 10 .csv files (3 for average - Table 1, 3 for median - Table 2, 4 for 15min city hexagons - Table 3)
	- output path: 'results\analysis\<result>.csv'
	-> Table 1-3 in publication

** d_plots.py
	- script to create the plots in the paper
	- input from user: none
	- input data: accesibility results (slope-dependent speed model only) and shapefile with boundaries of Vienna
	- output data: five plots (3 heatmaps and 2 lineplots)
	- output path: 'results\plots\<figure>.png'
	-> Figure 1-5 in publication

