276 docs explain tp page (#291)

* docs: added what is tp page and assets

* chore: added jupyter python3 kernel

* docs: added an intro to home page

* docs: restyled where next section

* docs: change where next section gridded css

* docs: added contributing to jumbrotron; improve contributing notes formatting

* docs: improved homepage styling

* docs: changed site title to package name

* docs: added icons to where next grid

* docs: Small typos

* docs: Minor typos

* fix: Update jumbotron href attributes

* chore: Revert yaml title due to low contrast

* style: Opinionated changes to text. Please review

* docs: modified sentence structure to improve clarity

---------

Co-authored-by: r-leyshon <[email protected]>

.gitignore

@@ -198,6 +198,7 @@ docs/build/
 docs/_sidebar.yml
 docs/reference/
 !docs/_static/tp_logo_white_background.png
+!docs/explanation/what_is_tp/*.PNG
 
 # PyBuilder
 .pybuilder/

_quarto.yml

@@ -159,3 +159,5 @@ quartodoc:
         - defence
         - io
         - raster
+
+jupyter: python3

docs/_static/styles.css

@@ -2,3 +2,64 @@
     max-height: 500px;
     overflow-y: auto;
 }
+
+.jumbotron {
+    border: 1px solid black;
+    padding: 15px;
+    padding-bottom: 0px;
+    text-align: center;
+    align-items: center;
+}
+
+.grid-container {
+    display: grid;
+    gap: 15px;
+}
+
+.item1 {
+    grid-column-start: 1;
+    grid-column-end: 1;
+    grid-row-start: 1;
+    grid-row-end: 1;
+}
+
+.item2 {
+    grid-column-start: 2;
+    grid-column-end: 2;
+    grid-row-start: 1;
+    grid-row-end: 1;
+}
+
+.item3 {
+    grid-column-start: 1;
+    grid-column-end: 1;
+    grid-row-start: 2;
+    grid-row-end: 2;
+}
+
+.item4 {
+    grid-column-start: 2;
+    grid-column-end: 2;
+    grid-row-start: 2;
+    grid-row-end: 2;
+}
+
+.item5 {
+    grid-column-start: 1;
+    grid-column-end: 1;
+    grid-row-start: 3;
+    grid-row-end: 3;
+}
+
+.item6 {
+    grid-column-start: 2;
+    grid-column-end: 2;
+    grid-row-start: 3;
+    grid-row-end: 3;
+}
+
+.jumbotron-icon{
+    font-size: 50px;
+    margin-top: -0.5rem;
+    margin-bottom: -0.5rem;
+}

docs/explanation/what_is_tp/index.qmd

@@ -1,10 +1,62 @@
 ---
-title: 1. What is Transport Performance?
+title: "1. Transport Performance: A Definition"
 description: An insight into what transport performance is and what it tells us about transport networks.
-date-modified: 05/16/2024  # must be in MM/DD/YYYY format
+date-modified: 06/11/2024  # must be in MM/DD/YYYY format
 categories: ["Explanation"]  # see https://diataxis.fr/tutorials-how-to/#tutorials-how-to, delete as appropriate
 toc: true
 date-format: iso
 ---
 
-🚧 Page under construction 🚧
+Transport Performance (TP) is a metric originally developed by the European Commission in their [2020 work on low carbon urban transport accessibility][euro-commission-paper]. TP puts the population at the centre of its definition, by measuring how efficiently a transport network moves the surrounding population to a destination within a certain time frame. A TP value of 100% would mean all the nearby population can travel to a location within the time threshold.
+
+Since TP is bound by a time frame, it is highly dependent on transport modalities; for example, public transit, private vehicle, cycling, and walking. The example discussed on this page considers the public transit network.
+
+TP is also dependent on the surrounding population and the destination itself, making it highly variable across an area. For this reason, it is calculated on a granular scale to build up the TP picture across an area of interest. The example discussed on this page uses populated 200x200m cells.
+
+@fig-tp-definition illustrates how TP is calculated for one cell in the centre of Newport, Wales using a 45 minutes time threshold, an 11.25Km distance limit on the surrounding population, and the public transit network.
+
+::: {.callout-tip}
+
+`transport_performance` is highly configurable. It caters for different modalities and time/distance thresholds (and more!) beyond the configuration presented on this page. See the [tutorials](../../tutorials/index.qmd) and [API reference](../../reference/index.qmd) for more details.
+
+:::
+
+::: {#fig-tp-definition layout-ncol=2}
+
+![Accessible population - the total population that can travel to a cell in central Newport, Wales within 45 minutes by public transit](accessible_pop.PNG){#fig-access}
+
+![Proximity population - the total nearby population to a cell in central Newport, Wales within the distance limit (11.25km)](proximity_pop.PNG){#fig-proxi}
+
+Accessible and proximity population definitions using    200x200m cells and an example destination in the middle of Newport, Wales.<br><span class="figure-source">Source: ONS Data Science Campus, April 2024.</span>
+:::
+
+@fig-tp-definition uses a green marker to denote the destination cell and a red dashed line to illustrate the boundary of the nearby population. The dark pink region in @fig-access represents the **accessible population**. This is the total population that can reach the green marker within the time threshold using the transport network. The dark blue region in @fig-proxi represents the **proximity population**. This is the total nearby population within the distance limit. Then, to calculate the total accessible and proximity populations, we count the population across all highlighted cells respectively. The **transport performance** of the network when travelling to the destination is then the ratio of the accessible and proximity populations (multiplied by 100 to convert to a percentage), as shown in @eq-tp:
+
+$$
+T_i(t_{max}, d_{max}) = 100 \times \frac{P_{access, i}}{P_{proxi, i}}
+$$ {#eq-tp}
+
+Where:
+
+- $T_i$ is the transport performance of destination cell, $i$.
+- $t_{max}$ is the maximum time threshold.
+- $d_{max}$ is the maximum distance threshold (the limit on proximity population from the destination).
+- $P_{access, i}$ is the total population that can travel to destination cell, $i$, within $t_{max}$ and $d_{max}$.
+- $P_{proxi, i}$ is the total population within $d_{max}$ of destination cell, $i$.
+
+This calculation is repeated to construct the transport performance throughout an entire area of interest (in this case across every destination cell within the urban centre). An example of this for the Newport, Wales [urban centre] is shown in @fig-tp-newport.
+
+::: {#fig-tp-newport layout-ncol="1"}
+
+![](newport_tp.PNG){width=100%"}
+
+Transport performance across Newport, Wales. Public transit within 45 minutes. The red line denotes the boundary of the urban centre.<br><span class="figure-source">Source: ONS Data Science Campus, April 2024.</span>
+
+:::
+
+@fig-tp-newport shows how transport performance can vary across an area on a granular scale. The yellow/light green region indicates that ~50-60% of the surrounding population can reach the main city centre of Newport, Wales using public transit within 45 minutes. The transport performance also generally decreases closer to the outskirts of the urban centre. This means a smaller proportion of the surrounding population can reach the dark blue/purple areas using public transit within 45 minutes. Overall, it provides detailed, hyperlocal, insights into how the performance of the transport networks varies throughout an area.
+
+Calculating transport performance requires several stages of input data processing and transport network travel time estimation. The methods and tools used by this Python package are discussed in more detail on the [Transport Performance: An Overview](../calculate_tp/index.qmd) page. For more insights on how to use `transport_performance` itself, check out the [tutorials](../../tutorials/index.qmd) and [API reference](../../reference/index.qmd).
+
+[euro-commission-paper]: https://ec.europa.eu/regional_policy/en/information/publications/working-papers/2022/low-carbon-urban-accessibility
+[urban centre]: https://ec.europa.eu/eurostat/statistics-explained/index.php?title=Glossary:Urban_centre

index.qmd

@@ -1,6 +1,14 @@
 ---
 title: "`transport_performance` documentation"
-toc: false
+title-block-banner: true
+date-format: iso
+description: |
+
+  A Python package bringing together open-source data, tools, and research to
+  make transport network analyses more simple, reproducible, and consistent for
+  everyone.
+toc: true
+toc-title: "On this homepage"
 sidebar: false
 about:
     template: marquee
@@ -10,31 +18,83 @@ about:
           text: GitHub
 ---
 
-![](docs/_static/tp_logo_white_background.png){width="15em" fig-align="center"}
+## What is `transport_performance`?
+
+The performance of transport networks are highly variable throughout and
+between countries. There is often a lack of consistent and comparable data
+which can make it difficult to understand these differences. This is typically
+because of computational complexity, transparency (closed-source and paid
+services), and data consistency (format and availability).
+
+The `transport_performance` Python package helps to reduce barriers to
+transport analysis. It allows developers to:
 
-## What is this and why does it exist?
+- Define an [urban centre] boundary based on population density;
+- Inspect, clean, and process [public transit timetable data][gtfs] and
+[OpenStreetMap data][osm]; and
+- Conduct [multimodal routing][r5py] and calculate a range of
+[transport metrics][eurostat-paper].
 
-Description
+::: {.callout-tip}
+Check out the [transport performance Docker image][tp-docker] 🐳!
+This aims to simplify the dependency installation and end-to-end use of
+`transport_performance`.
+:::
 
 ## Where do I go now?
 
 These docs are structured in accordance with the [Diátaxis][diataxis] framework:
 
-- If you're looking to get started with the package quickly, head over to the [Getting Started](docs/getting_started/index.qmd) page.
-- For more information on the `transport_performance` package, refer to the [Explanation section](docs/explanation/index.qmd).
-- The [How-To](docs/how_to/index.qmd) pages provide you with instructions on things like retrieving input data.
-- If you're interested in learning how to use the package, head over to the [Tutorials](docs/tutorials/index.qmd).
-- The `transport_performance` technical reference can be found here: [API reference](docs/reference/index.qmd).
+<div class="grid-container">
+<div class="grid-item item1 jumbotron">
+<p class="jumbotron-icon">🏁</p>
+<p>Want to get up and running with `transport_performance` quickly?</p>
+<a class="btn btn-primary btn-lg" href="./docs/getting_started/index.html" role="button">Getting Started</a>
+</div>
+<div class="grid-item item2 jumbotron">
+<p class="jumbotron-icon">🔎</p>
+<p>Need more details on the methods/tools used within `transport_performance`?</p>
+<a class="btn btn-primary btn-lg" href="./docs/explanation/index.html" role="button">Explanation</a>
+</div>
+<div class="grid-item item3 jumbotron">
+<p class="jumbotron-icon">🧭</p>
+<p>Looking for guidance on how to get something done (e.g. find input data)?</p>
+<a class="btn btn-primary btn-lg" href="./docs/how_to/index.html" role="button">How-To</a>
+</div>
+<div class="grid-item item4 jumbotron">
+<p class="jumbotron-icon">📝</p>
+<p>Interested in learning how to use `transport_performance` by examples?</p>
+<a class="btn btn-primary btn-lg" href="./docs/tutorials/index.html" role="button">Tutorials</a>
+</div>
+<div class="grid-item item5 jumbotron">
+<p class="jumbotron-icon">📖</p>
+<p>Requiring a technical reference covering the `transport_performance` API?</p>
+<a class="btn btn-primary btn-lg" href="./docs/reference/index.html" role="button">API reference</a>
+</div>
+<div class="grid-item item6 jumbotron">
+<p class="jumbotron-icon">🛠️</p>
+<p>Want to contribute to the development of `transport_performance`?</p>
+<a class="btn btn-primary btn-lg" href="https://github.com/datasciencecampus/transport-network-performance" role="button">GitHub</a>
+</div>
+</div>
 
-::: {.callout-tip}
+::: {.callout-note}
+
+## Notes on contributing...
+
+We hope that the open source and public sector communities will collaborate and
+build on this package. This will help improve both the national and
+international comparability of transport statistics while enabling higher
+frequency and more timely comparisons. You can find the `transport_performance`
+source code on [GitHub](https://github.com/datasciencecampus/transport-network-performance).
 
-Please refer to our [Docker image][tp-docker] 🐳 to see how we reproduce
-analysis with the `transport_performance` package.
 :::
 
+
 [diataxis]: https://diataxis.fr/
 [tp-docker]: https://github.com/datasciencecampus/transport-performance-docker
-
-## Looking to Contribute?
-
-Find the `transport_performance` code on the [GitHub repo](https://github.com/datasciencecampus/transport-network-performance).
+[urban centre]: https://ec.europa.eu/eurostat/statistics-explained/index.php?title=Glossary:Urban_centre
+[gtfs]: https://gtfs.org/schedule/
+[osm]: https://wiki.openstreetmap.org/wiki/Main_Page
+[r5py]: https://r5py.readthedocs.io/en/stable/index.html
+[eurostat-paper]: https://ec.europa.eu/regional_policy/information-sources/publications/working-papers/2020/low-carbon-urban-accessibility_en