chore: merged with dev

.gitignore

@@ -73,6 +73,11 @@ outputs/*
 *.jpeg
 *.svg
 
+# specific rules for README images
+!/www/cardiff-street-map.png
+!/www/tp-explained.png
+!/www/transport-performance-newport.png
+
 # The following was created by https://www.toptal.com/developers/gitignore/api/macos,windows,r,python
 # Edit at https://www.toptal.com/developers/gitignore?templates=macos,windows,r,python
 

CONTRIBUTING.md

@@ -76,9 +76,21 @@ following dependencies installed on macos:
 * `brew install boost`
 * `brew install cmake`
 
-### Pre-commit
+### Pre-commit actions
+This repository contains a configuration of pre-commit hooks. These are language agnostic and focussed on repository security (such as detection of passwords and API keys). If approaching this project as a developer, you are encouraged to install and enable `pre-commits` by running the following in your shell:
+   1. Install `pre-commit`:
 
-*Placeholder section*
+      ```
+      pip install pre-commit
+      ```
+   2. Enable `pre-commit`:
+
+      ```
+      pre-commit install
+      ```
+Once pre-commits are activated, whenever you commit to this repository a series of checks will be executed. The pre-commits include checking for security keys, large files and unresolved merge conflict headers. The use of active pre-commits are highly encouraged and the given hooks can be expanded with Python or R specific hooks that can automate the code style and linting. For example, the `flake8` and `black` hooks are useful for maintaining consistent Python code formatting.
+
+**NOTE:** Pre-commit hooks execute Python, so it expects a working Python build.
 
 ### Note on Issues, Feature Requests, and Pull Requests
 
@@ -100,12 +112,8 @@ We mainly follow the [Quality Assurance of Code for Analysis and Research](https
 
 ## Testing
 
-*Placeholder section*
+Testing with [`pytest`](https://pytest.org/en/latest/getting-started.html).
 
 ## Code coverage
 
-*Placeholder section*
-
-## Documentation
-
-*Placeholder section*
+Coverage with [Coverage.py](https://coverage.readthedocs.io/en/7.4.1/)

README.md

@@ -7,58 +7,150 @@
 
 # transport-network-performance
 
-> :warning: This repository is still in the development phase. Caution should be taken before using or referencing this work in any way - use it at your own risk.
+> :warning: This repository is still in the development phase. Caution should
+be taken before using or referencing this work in any way - use it at your own
+risk.
 
-# Introduction
-## About
-*Describe what this repo contains and what the project is.*
+## Introduction
+<!-- *Describe what this repo contains and what the project is.* -->
+
+`transport_performance` provides a method for analysing the efficiency of
+moving people into and around urban centres. The method employed here builds
+upon that established by [Poelman *et al*, European Commission 2020](https://ec.europa.eu/regional_policy/sources/work/012020_low_carbon_urban.pdf). Specifically, this python package provides
+features useful for:
+
+- Defining an urban centre boundary based upon contiguous population density.
+- Inspecting, cleaning and filtering public transit data in [GTFS format](https://gtfs.org/).
+- Inspecting and filtering Open Street Map data in [PBF format](https://wiki.openstreetmap.org/wiki/PBF_Format).
+- Multimodal routing with r5 [using r5py](https://r5py.readthedocs.io/en/stable/)
+to create travel time matrices.
+- Calculation of transport performance statistics.
 
 ## Developers
-We welcome contributions from others. Please check out our [code of conduct](CODE_OF_CONDUCT.md) and [contributing guidance](CONTRIBUTING.md###Set-up).
+We welcome contributions from others. Please check out our
+[code of conduct](CODE_OF_CONDUCT.md) and
+[contributing guidance](CONTRIBUTING.md###Set-up).
 
 ## Installation
 *Describe technical set-up. Such as the required dependencies.*
 
-### Pre-commit actions
-This repository contains a configuration of pre-commit hooks. These are language agnostic and focussed on repository security (such as detection of passwords and API keys). If approaching this project as a developer, you are encouraged to install and enable `pre-commits` by running the following in your shell:
-   1. Install `pre-commit`:
+This package is designed to work with python 3.9.13. Full functionality is
+tested on macos only. Other operating systems may be incompatible with
+`transport_performance.osm` specifically.
 
-      ```
-      pip install pre-commit
-      ```
-   2. Enable `pre-commit`:
+The transport modelling features in `transport_performance.analyse_network`
+depends upon a compatible Java Development Kit (JDK). Please consult the
+[r5py installation docs](https://r5py.readthedocs.io/en/stable/user-guide/installation/installation.html#dependencies)
+and our [Contributing Guidance](/./CONTRIBUTING.md) for more on configuring a
+JDK.
 
-      ```
-      pre-commit install
-      ```
-Once pre-commits are activated, whenever you commit to this repository a series of checks will be executed. The pre-commits include checking for security keys, large files and unresolved merge conflict headers. The use of active pre-commits are highly encouraged and the given hooks can be expanded with Python or R specific hooks that can automate the code style and linting. For example, the `flake8` and `black` hooks are useful for maintaining consistent Python code formatting.
+## Usage
+<!-- *Explain how to use the things in the repo.* -->
 
-**NOTE:** Pre-commit hooks execute Python, so it expects a working Python build.
+### Installation
 
-## Usage
-*Explain how to use the things in the repo.*
+Currently, `transport_performance` is not published to PyPI or Conda Forge. To
+use the code, we suggest forking the repository and cloning the fork to your
+development environment.
+
+```
+git clone <INSERT_CLONE_URL>/transport-network-performance.git
+```
 
-### Workflow
-*You may wish to consider generating a graph to show your project workflow. GitHub markdown provides native support for [mermaid](https://mermaid.js.org/syntax/flowchart.html), an example of which is provided below:*
+We recommend running the package with a virtual environment such as
+[conda](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html)
+or [venv](https://docs.python.org/3/library/venv.html).
 
-```mermaid
-flowchart TD
-   id1[(Some data)] --> id2(Some processing)
-   id3[(More data)] --> id2
-   id2 --> id4[Some output]
+With conda:
 ```
+conda create -n transport-performance python=3.9.13 -y
+```
+Once completed, activate the environment:
+```
+conda activate transport-performance
+```
+Install the python requirements:
+```
+pip install -r requirements.txt
+```
+Additional Java dependencies are required for full functionality. See the
+[contributing guidance](./CONTRIBUTING.md) for assistance.
+
+### Required Data
+
+You will need the following data, appropriate to the territory that you wish to
+analyse:
+
+* [Open Street Map data](https://download.geofabrik.de/) in PBF format.
+* [Public Transport Schedule data](https://data.bus-data.dft.gov.uk/downloads/)
+in GTFS format.
+* [Global Human Settlement Layer](https://ghsl.jrc.ec.europa.eu/download.php)
+population estimates.
+
+### Usage
+
+For guidance on how to use the `transport_performance` package, consult the
+[end to end notebooks](/./notebooks/e2e/). These notebooks demonstrate the
+workflow required to calculate transport performance in a number of urban
+centres.
+
+![Transport performance folium map of Newport, South Wales.](/./www/transport-performance-newport.png)
+
+## Understanding Transport Performance
+
+Transport performance is a statistic developed by The European Commission that
+allows measurement and comparison of how efficiently people move through
+transport networks.
+
+In the example below, transport performance is visualised for a single location
+in Cardiff.
+
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+  width: 50%;
+
+![Google (2021) A4161 Cardiff. Available at: http://maps.google.co.uk (Accessed: 11 December 2023).](/./www/cardiff-street-map.png)
+
+Using this location as the journey origin, travel times to the surrounding
+neighbourhood within 45 minutes can be calculated. The proximal population that
+can be reached is summed. This population would be reachable from the journey
+origin if travel at 15 km/h in a straight line were possible. This assumption
+is coherent with the European Commission’s assumption of average travel speed
+by public transport.
+
+The accessible population for the same journey duration is also calculated.
+This is the number of people reachable from the journey origin by public
+transport and walking modes.
+
+To calculate the transport performance statistic, the ratio of accessible to
+proximal population is taken.
 
+![Breakdown of Transport Performance statistic.](/./www/tp-explained.png)
 
-# Data Science Campus
-At the [Data Science Campus](https://datasciencecampus.ons.gov.uk/about-us/) we apply data science, and build skills, for public good across the UK and internationally. Get in touch with the Campus at [[email protected]]([email protected]).
+The transport performance statistic is calculated for every 200 m<sup>2</sup>
+cell in the urban centre. As the journey departure time is known to affect the
+available public transport services, varying the departure time results in
+differing transport performance. In order to produce a less volatile statistic,
+the transport performance for every cell is calculated at 1 minute interval
+departure times between 08:00 and 09:00 on a single day. The chosen date in
+this example is Wednesday 22<sup>nd</sup> November 2023, a day that is
+representative of average public transport service in the public transport
+schedules.
 
-# License
+## Data Science Campus
+At the [Data Science Campus](https://datasciencecampus.ons.gov.uk/about-us/) we
+apply data science, and build skills, for public good across the UK and
+internationally. Get in touch with the Campus at
+[[email protected]]([email protected]).
 
-<!-- Unless stated otherwise, the codebase is released under [the MIT Licence][mit]. -->
+## License
+<!-- Unless stated, the codebase is released under [the MIT Licence][mit]. -->
 
 The code, unless otherwise stated, is released under [the MIT Licence][mit].
 
-The documentation for this work is subject to [© Crown copyright][copyright] and is available under the terms of the [Open Government 3.0][ogl] licence.
+The documentation for this work is subject to [© Crown copyright][copyright]
+and is available under the terms of the [Open Government 3.0][ogl] licence.
 
 [mit]: LICENCE
 [copyright]: http://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/crown-copyright/