diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml index 4566d0f..a849870 100644 --- a/.github/workflows/deploy.yaml +++ b/.github/workflows/deploy.yaml @@ -1,41 +1,48 @@ # https://github.com/rust-lang/mdBook/wiki/Automated-Deployment%3A-GitHub-Actions#github-pages-deploy -name: Deploy +name: Render on: push: branches: - main + pull_request: + branches: + - main jobs: - deploy: + + render: + runs-on: ubuntu-latest + permissions: contents: write # To push a branch pull-requests: write # To create a PR from that branch + steps: + - uses: actions/checkout@v3 with: fetch-depth: 0 - - name: Install latest mdbook + + - name: Install Python dependencies + uses: py-actions/py-dependency-install@v4 + with: + path: "requirements.txt" + + - name: make docs and cname run: | - tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name') - url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz" - mkdir mdbook - curl -sSL $url | tar -xz --directory=./mdbook - echo `pwd`/mdbook >> $GITHUB_PATH + make html + echo 'docs.urbananalyst.city' > _build/html/CNAME + + - name: Upload artifaces + uses: actions/upload-artifact@v4 + with: + name: html-docs + path: _build/html/ + - name: Deploy GitHub Pages - run: | - # This assumes your book is in the root of your repository. - # Just add a `cd` here if you need to change to another directory. - mdbook build - git worktree add gh-pages - git config user.name "Deploy from CI" - git config user.email "" - cd gh-pages - # Delete the ref to avoid keeping history. - git update-ref -d refs/heads/gh-pages - rm -rf * - mv ../book/* . - echo 'docs.urbananalyst.city' > CNAME - git add . - git commit -m "Deploy $GITHUB_SHA to gh-pages" - git push --force --set-upstream origin gh-pages + uses: peaceiris/actions-gh-pages@v3 + if: github.ref == 'refs/heads/main' + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: _build/html diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/book.toml b/book.toml deleted file mode 100644 index fe5c6c8..0000000 --- a/book.toml +++ /dev/null @@ -1,6 +0,0 @@ -[book] -authors = ["mpadge"] -language = "en" -multilingual = false -src = "src" -title = "Urban Analyst" diff --git a/conf.py b/conf.py new file mode 100644 index 0000000..1082ef8 --- /dev/null +++ b/conf.py @@ -0,0 +1,75 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'urban analyst docs' +copyright = '2024, Mark Padgham' +author = 'Mark Padgham' + +# The full version, including alpha/beta/rc tags +release = '0.0.1' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'myst_parser', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosectionlabel', + 'sphinx.ext.autosummary', + 'sphinx.ext.duration', + 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', +] + +myst_enable_extensions = [ + 'colon_fence', +] + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3/', None), + 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), +} +intersphinx_disabled_domains = ['std'] + + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README.md', 'aaa*'] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +#html_theme = 'alabaster' +html_theme = 'sphinx_rtd_theme' + + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] diff --git a/src/data.md b/data.rst similarity index 75% rename from src/data.md rename to data.rst index 8352378..5157acb 100644 --- a/src/data.md +++ b/data.rst @@ -1,15 +1,16 @@ -# Data Sources +5. Data Sources +############### The Urban Analyst platform aims to be applicable to as much of the world as possible. To achieve this, data sources are chosen which are ideally have global coverage, and which are not specific to any one city. The global sources used are: -- [Open Street Map](https://openstreetmap.org) for all data on traversable +- `Open Street Map `_ for all data on traversable ways, natural spaces, parking infrastructure, and locations of schools. -- Population density data from the [European Union *Global Human Settlement - Layer*](https://ghsl.jrc.ec.europa.eu/index.php). -- Elevation data from [NASA Earth Observation - Data](https://www.earthdata.nasa.gov/), used to include effects of incline +- Population density data from the `European Union *Global Human Settlement + Layer* `_. +- Elevation data from `NASA Earth Observation + Data `_, used to include effects of incline on both pedestrian and bicycle travel times. The following additional data are then required for each city: @@ -24,7 +25,7 @@ The last of these data requirements is the most restrictive, as most cities of the world do not have or provide public transport data in GTFS format. There are nevertheless thousands of cities which do provide GTFS feeds, as can be seen for example in the GTFS feed aggregation platform -[transit.land](https://transit.land). +`transit.land `_. For USA cities, data for the additional two variables of housing value and rental price per room are obtained from US Government census data. diff --git a/src/example.md b/example.rst similarity index 87% rename from src/example.md rename to example.rst index 848837a..9d2f699 100644 --- a/src/example.md +++ b/example.rst @@ -1,7 +1,8 @@ -# Example +3. Example +########## -This chapter demonstrates most of the capabilities of the [Urban Analyst -platform](https://urbananalyst.city) through exploring comparisons between the +This chapter demonstrates most of the capabilities of the `Urban Analyst +platform `_ through exploring comparisons between the cities of Paris, France, and Berlin, Germany. It is important to remember throughout that lower values in all UA statistics are always better. Values are also weighted by local population densities. This is important because, for @@ -21,8 +22,8 @@ any given city. This comparison starts by stepping through each variable to describe kinds of information able to be extracted, before examining pairwise relationships -between these variables, and concluding with a general summary. The [Urban -Analyst platform](https://urbananalyst.city) currently measures 11 variables, +between these variables, and concluding with a general summary. The `Urban +Analyst platform `_ currently measures 11 variables, along with strengths of relationship between all paired combinations of these. This amounts to 11 * (11 - 1) / 2 = 55 pairwise combinations. Strengths of relationship are standardised, so are comparable throughout between all pairs @@ -30,23 +31,49 @@ of variables, and between different cities. Two additional variables are included for cities from the USA, enabling even more pairwise comparisons for these cities. -## Individual Variables. +Individual Variables +******************** The following table summarises the values of the individual variables for each city (each measured on its own distinct scale). -| Variable | Berlin | Paris | -|:----:|:---------|:---------| -| Times (abs; min) | 40.9 | 39.5 | -| Times (rel) | 1.09 | 1.03 | -| Num. Transfers | 0.9 | 1.5 | -| Intervals (min) | 6.9 | 4.9 | -| Transport | 33.2 | 25.5 | -| Pop. Dens. | 3 | 3 | -| School Dist (m) | 338 | 186 | -| Bike Index | 0.81 | 0.76 | -| Nature Index | 0.88 | 0.93 | -| Parking | 1.32 | 1.55 | +.. list-table:: UA Variables + :widths: 50 25 25 + :header-rows: 1 + + * - Variable + - Berlin + - Paris + * - Times (abs; min) + - 40.9 + - 39.5 + * - Times (rel) + - 1.09 + - 1.03 + * - Num. Transfers + - 0.9 + - 1.5 + * - Intervals (min) + - 6.9 + - 4.9 + * - Transport + - 33.2 + - 25.5 + * - Pop. Dens. + - 3 + - 3 + * - School Dist (m) + - 338 + - 186 + * - Bike Index + - 0.81 + - 0.76 + * - Nature Index + - 0.88 + - 0.93 + * - Parking + - 1.32 + - 1.55 Social disadvantage is also quantified for all cities. However, each city @@ -54,7 +81,8 @@ calculates this in different ways, and values are not comparable between cities. Values are nevertheless standardised for the pairwise comparisons, and strengths of relationship described there remain valid. -### Transport +Transport +========= The "Transport Absolute" variable measures the absolute time (in minutes) required to travel a distance of 10km from each point in a city, using any @@ -103,7 +131,8 @@ times by intervals between services. Low values of this statistic reflect fast and frequent transport. This statistic also indicates considerably superior service in Paris compared with Berlin. -### Other Variables +Other Variables +=============== - "School Distance": Paris has notably shorter distances from each point in the city to the nearest school than does Berlin. @@ -131,7 +160,8 @@ service in Paris compared with Berlin. to park private automobiles compared with the other UA cities, with Berlin notably less than Paris. -## Relationships between variables +Relationships between variables +******************************* This section considers relationships between each individual variable and all other variables. All strengths of relationship shown in the "Stats" page are @@ -146,29 +176,90 @@ not interpreted in the following sub-sections. The following table summarises the values of the strongest pairwise relationships for each city: -| Variable1 | Variable2 | Berlin | Paris | -|:------:|:----:|:---------|:---------| -| Times (abs) | Bike | 1.0 | 2.0 | -| Times (abs) | Natural | -1.0 | -0.5 | -| Times (abs) | Parking | 0 | -0.15 | -| Times (abs) | Pop. Dens. | -0.15 | -0.11 | -| Times (abs) | School dist | 0.12 | 0.06 | -| Times (abs) | Transfers | -0.31 | -0.48 | -| Times (rel) | Bike | 0 | 0.16 | -| | | | -| Transport | Natural | -0.22 | 2.46 | -| Transport | Parking | 1.7 | 1.9 | -| | | | -| School dist | Bike | 0 | 0.4 | -| School dist | Natural | -0.12 | -0.06 | -| | | | -| Social | Bike | 0.52 | -0.38 | -| Social | Natural | -0.1 | 2.0 | -| Social | Parking | 0.04 | -2.18 | -| Social | School dist | -0.05 | -0.25 | - - -### Transport Variables +.. list-table:: Pairwise Relationships between Variables + :widths: 30 30 20 20 + :header-rows: 1 + + * - Variable 1 + - Variable 2 + - Berlin + - Paris + * - Times (abs) + - Bike + - 1.0 + - 2.0 + * - Times (abs) + - Natural + - -1.0 + - -0.5 + * - Times (abs) + - Parking + - 0 + - -0.15 + * - Times (abs) + - Pop. Dens. + - -0.15 + - -0.11 + * - Times (abs) + - School dist. + - 0.12 + - 0.06 + * - Times (abs) + - Transfers + - -0.31 + - -0.48 + * - Times (rel) + - Bike + - 0 + - 0.16 + * - + - + - + - + * - Transport + - Natural + - -0.22 + - 2.46 + * - Transport + - Parking + - 1.7 + - 1.9 + * - + - + - + - + * - School Dist. + - Bike + - 0 + - 0.4 + * - School Dist. + - Natural + - -0.12 + - -0.06 + * - + - + - + - + * - Social + - Bike + - 0.52 + - -0.38 + * - Social + - Natural + - -0.1 + - 2.0 + * - Social + - Parking + - 0.04 + - -2.18 + * - Social + - School Dist. + - -0.05 + - -0.25 + + +Transport Variables +=================== This sub-section only considers transport times, both in absolute and relative sense. The other transport variables, of intervals and numbers of transfers, @@ -212,7 +303,8 @@ transport also tend to have more automobile parking spaces, reflecting planning decisions that associate use of public transport with the driving of private automobiles. No such relationship appears to exist in Berlin. -### Non-Transport Variables +Non-Transport Variables +======================= Shorter school distances are positively associated with the bicycle index in Paris, indicating a positive association between good bicycle infrastructure @@ -252,9 +344,11 @@ spaces, or conversely that socially disadvantaged parts of the city offer relatively few automobile parking spaces. The relationship in Berlin is, in contrast, slightly positive. -## Conclusions +Conclusions +*********** -### Lessons for Berlin +Lessons for Berlin +================== Paris's transport system is considerably faster and more frequent. Nevertheless, it also involves greater numbers of transfers, suggesting that @@ -293,7 +387,8 @@ spaces is only weakly related to social advantage. This provides robust evidence for Berlin to appreciate its natural spaces, and to ensure that they remain accessible for everybody. -### Lessons for Paris +Lessons for Paris +================= Paris's transport system is notably better than Berlin's in almost all ways except for the number of transfers necessary to travel equivalent distances. diff --git a/index.rst b/index.rst new file mode 100644 index 0000000..ab9943b --- /dev/null +++ b/index.rst @@ -0,0 +1,23 @@ +.. ropensci-review-tools documentation master file, created by + sphinx-quickstart on Wed Aug 25 10:43:40 2021. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Urban Analyst +############# + +This is the documentation of `the Urban Analyst platform +`_. + + +.. toctree:: + :maxdepth: 1 + :caption: Contents + + intro.rst + overview.rst + example.rst + variables.rst + data.rst + software.rst + diff --git a/src/intro.md b/intro.rst similarity index 50% rename from src/intro.md rename to intro.rst index 92abd29..f1857b6 100644 --- a/src/intro.md +++ b/intro.rst @@ -1,15 +1,16 @@ -# Introduction +1. Introduction +############### -This is the documentation for [Urban Analyst (UA)](https://urbananalyst.city). +This is the documentation for `Urban Analyst (UA) `_. Urban Analyst analyses the structure and function of cities across the world. -Each city can be viewed as an [interactive map](https://urbananalyst.city/maps) +Each city can be viewed as an `interactive map `_ displaying several different properties or variables. These include socio-demographic conditions and the structure and function of transport systems. The platform also analyses relationships between individual variables, such as between socio-demographic conditions and frequency of transport services, or between distances to nearest schools and access to natural spaces. -UA also provides [statistical comparisons](https://urbananalyst.city/compare) +UA also provides `statistical comparisons `_ between all cities, enabling comparisons across all UA cities of single variables, as well as relationships between any pair of variables, such as transport and socio-demographic disadvantage. @@ -23,21 +24,23 @@ like Paris. Values for every area in Berlin are then displayed as the proportional increase in bicycle infrastructure which would be necessary for the whole city to have infrastructure equivalent to Paris. -# How does it work? +How does it work? +***************** -Urban Analyst present a variety of [variables](./variables.md) for each city -analysed, as well as relationships between these variables. Values for each -variable are derived at every street intersection in each city. These values -are then aggregated into the polygons shown in the ["Map" -page](https://urbananalyst.city/maps) and -["Transform"](https://urbananalyst.city/transform) pages, and across entire -cities for the values shown in the -["Compare"](https://urbananalyst.city/compare) page. Aggregations are always -weighted by local population densities, so that all UA values represent values -*per person* as experienced in each city. Details are provided in the [*Data -Sources*](./data.md) and [*Software and Algorithms*](./software.md) chapters. +Urban Analyst present a variety of :ref:`variables<4. UA Variables>` for each +city analysed, as well as relationships between these variables. Values for +each variable are derived at every street intersection in each city. These +values are then aggregated into the polygons shown in the `"Map" page +`_ and `"Transform" +`_ pages, and across entire cities for the +values shown in the `"Compare" `_ page. +Aggregations are always weighted by local population densities, so that all UA +values represent values *per person* as experienced in each city. Details are +provided in the :ref:`*Data Sources* <5. Data Sources>` and :ref:`*Software and +Algorithms* <6. Software and Algorithms>` chapters. -# How many calculations are involved? +How many calculations are involved? +*********************************** The values presented in Urban Analyst are derived from estimates of travel times from every point in each city to every other point using any combination @@ -45,12 +48,38 @@ of possible modes of transport. The following table summarises numbers of street intersections, public transport ("PT") stops, and calculations for a selection of Urban Analyst cities. - city | intersections
(thousands) | PT stops | PT calcs
(millions) | routing calcs
(billions) --------- | ------------- | -------- | -------- | ----------- -Berlin | 360 | 9,302 | 173 | 150 -Hamburg | 192 | 4,585 | 42 | 56 -London | 506 | 20,072 | 806 | 160 -Paris | 313 | 29,393 | 1,728 | 124 +.. list-table:: Numbers of calculations + :header-rows: 1 + + * - | city + - | intersections + | (thousands) + - | PT stops + - | PT calcs + | (millions) + - | routing calcs + | (millions) + * - Berlin + - 360 + - 9,302 + - 173 + - 150 + * - Hamburg + - 192 + - 4,585 + - 42 + - 56 + * - London + - 506 + - 20,072 + - 806 + - 160 + * - Paris + - 313 + - 29,393 + - 1,728 + - 124 + One way to appreciate the scale of these calculations is through comparison with commercial alternatives. One service, *traveltime.com*, charges a flat @@ -67,22 +96,24 @@ powerful, and provide a depth of insight into how people move through cities not available in any other way. -# Can I access the full data? +Can I access the full data? +*************************** -Not directly, but feel free to open a [GitHub -issue](https://github.com/mpadge/UrbanAnalyst/issues) to start a discussion +Not directly, but feel free to open a `GitHub +issue `_ to start a discussion about requesting full data sources. -# Structure +Structure +********* This documentation includes the following five chapters: 1. This introduction -2. ["Overview"](./overview.md): A brief overview of the main components of Urban Analyst. -3. ["Example"](./example.md): A walk-through example comparison between Berlin, Germany and Paris, France, illustrating the kinds of comparisons enabled by the Urban Analyst platform. -4. ["UA Variables"](./variables.md): Providing descriptions of all variables included in the Urban Analyst platform. -5. ["Data Sources"](./data.md): Providing descriptions of all data sources used to derive these variables. -6. ["Software and Algorithms"](./software.md): Providing descriptions of, and links to, all software used to generate the UA variables. +2. :ref:`Overview<2. Overview>`: A brief overview of the main components of Urban Analyst. +3. :ref:`Example<3. Example>`: A walk-through example comparison between Berlin, Germany and Paris, France, illustrating the kinds of comparisons enabled by the Urban Analyst platform. +4. :ref:`UA Variables<4. UA Variables>`: Providing descriptions of all variables included in the Urban Analyst platform. +5. :ref:`Data Sources<5. Data Sources>`: Providing descriptions of all data sources used to derive these variables. +6. :ref:`Software and Algorithms<6. Software and Algorithms>`: Providing descriptions of, and links to, all software used to generate the UA variables. Contributions to, or questions regarding, this documentation, are welcome at -[this GitHub repository](https://githu.com/UrbanAnalyst/docs). +`this GitHub repository `_. diff --git a/make.bat b/make.bat new file mode 100644 index 0000000..8084272 --- /dev/null +++ b/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/src/overview.md b/overview.rst similarity index 75% rename from src/overview.md rename to overview.rst index 014a6ae..7f2fbf6 100644 --- a/src/overview.md +++ b/overview.rst @@ -1,20 +1,21 @@ -# Overview +2. Overview +########### -This chapter provides an overview of the four main pages of the [Urban Analyst -platform](https://urbananalyst.city): +This chapter provides an overview of the four main pages of the `Urban Analyst +platform `_: -- The [summarise page](https://urbananalyst.city/summarise) provides summary +- The `summarise page `_ provides summary overviews for each city of key statistical properties and relationships with other cities; -- The [compare page](https://urbananalyst.city/compare) compares aggregate +- The `compare page `_ compares aggregate statistics for all cities; -- The [map page](https://urbananalyst.city/maps) shows interactive maps for +- The `map page `_ shows interactive maps for each city; -- The [transform page](https://urbananalyst.city/transform) shows the effect of +- The `transform page `_ shows the effect of transforming any chosen city to become more like other cities. -The best place to start is the [Summarise -page](https://urbananalyst.city/summarise). The summary for any chosen city +The best place to start is the `Summarise +page `_. The summary for any chosen city will indicate which properties of the other pages are most important. Each of the latter three pages also includes a pop-up "guided tour" explaining the key features. These tours will automatically start the first time a page is opened, @@ -23,35 +24,37 @@ pages. ---- -## Summarise +Summarise +********* -The [Summarise page](https://urbananalyst.city/summarise) provides an overview +The `Summarise page `_ provides an overview of the general statistical properties of any chosen UA city. Statistics for each chosen city are compared with those for all other cities, and textual summaries generated for all statistics which are significantly different. Summaries are provided not just for individual statistics, but for the strengths of relationship between all pairs of statistics. -The values described in this initial part of the [Summarise -page](https://urbananalyst.city/summarise) indicate which statistics might be -particularly worth examining in both the -[Compare](https://urbananalyst.city/compare) and the [Map -](https://urbananalyst.city/map) pages. +The values described in this initial part of the `Summarise +page `_ indicate which statistics might be +particularly worth examining in both the `Compare +`_ and the +`Map `_ pages. -The [Summarise page](https://urbananalyst.city/summarise) also includes a +The `Summarise page `_ also includes a section describing the best "Target city" for each chosen city. As explained there, the best target city is the city which is best in all the ways that the chosen city is worse than average. This target city, and corresponding variables described there, indicate which cities and variables might be -particularly worth examining in the [Transform -page](https://urbananalyst.city/transform). +particularly worth examining in the `Transform +page `_. ---- -## Compare +Compare +******* -The [Compare page](https://urbananalyst.city/compare) enables comparisons +The `Compare page `_ enables comparisons between all UA cities, both in terms of single variables and relationships between any selected pair of variables. A pull-down panel enables each variable or "layer" to be selected. The page then displays a graphical representation of @@ -60,9 +63,10 @@ generally better than higher values. The control panel includes an "Explain Layer" button which opens a text panel explaining details of the chosen variable. -### Single and Paired Variables +Single and Paired Variables +*************************** -The control panel of the [compare page](https://urbananalyst.city/compare) +The control panel of the `compare page `_ includes an option to select "paired" variables. The resultant graphs then display the strength of relationship between any chosen *pair* of variables. For example, choosing social index and the nature index will display the @@ -79,15 +83,16 @@ conditions." ---- -## Map +Map +*** -The [Map page](https://urbananalyst.city/map) shows interactive maps for each +The `Map page `_ shows interactive maps for each city, with values for all UA variables displayed in small polygons. These polygons are defined by city-specific assessments of spatial disadvantage. Berlin, for example, regularly measures a compound index of social disadvantage aggregated into XX polygons. The map for Berlin uses these polygons provided by the city to aggregate all measured variables. The variables are described in a -[subsequent chapter](./variables.md). +:ref:`subsequent chapter<4. UA Variables>`. Details of the polygons for each city can be seen by selecting the "Social" layer in the Map page and then clicking on the "Explain Layer" button. @@ -100,22 +105,23 @@ button which opens a text panel explaining details of the chosen variable. ---- -## Transform +Transform +********* -The [Transform page](https://urbananalyst.city/transform) enables the +The `Transform page `_ enables the properties of any chosen city to be transformed to reflect equivalent properties of some chosen "target" city. This page is best explained by an -example. Looking at the [Compare page](https://urbananalyst.city/compare) for +example. Looking at the `Compare page `_ for the "bike index" shows that Berlin has relatively poor bicycle infrastructure, while Paris is a very good city for cyclists. The -[Transform page](https://urbananalyst.city/transform) can be used to visualise +`Transform page `_ can be used to visualise how Berlin could best transform its current bicycle infrastructure to have an overall distribution across the whole city equivalent to Paris. Conversely, Paris has poorer access to natural spaces than Berlin, and the page could also be used to examine how Paris could best transform its access to natural spaces so that it functioned more like Berlin. -Urban Analyst values displayed in the [Map page](https://urbananalyst.city/map) +Urban Analyst values displayed in the `Map page `_ are aggregated from generally hundreds of thousands of individual calculations at every street junction in each city. For the chosen variable, subsets of these individual data points are sampled from each city, and the statistical @@ -125,16 +131,17 @@ target city. These values are then aggregated into the polygons defined for the city, to produce a visual representation of the least-cost transformation that would be necessary for the city to have the same distribution as that of the target city. The transformation algorithm is described in detail in the final -[*Software and Algorithms* chapter](./software.md). +:ref:`*Software and Algorithms* chapter<6. Software and Algorithms>`. -### Extra Layers +Extra Layers +============ -The [Transform page](https://urbananalyst.city/transform) includes an +The `Transform page `_ includes an additional button labelled *Extra Layers*. The transformations described above described transforming single layers or variables. The *Extra Layers* panel enables transformations not just of single chosen variables, but also of their -relationships with other variables. Examining the [Compare -page](https://urbananalyst.city/compare), for example, shows that not only does +relationships with other variables. Examining the `Compare +page `_, for example, shows that not only does Paris provide poorer access to natural spaces than Berlin, but also that Berlin has a better relationship between access to natural spaces and social disadvantage. (This can be seen by clicking on the "*Paired*" layer option and @@ -149,9 +156,10 @@ thus change for each choice of target city and focal layer. It may be necessary to click on the "Reset" button in the *Extra Layers* panel to update this default selection after changing any of these options. -### Output Layer +Output Layer +============ -Finally, the [Transform page](https://urbananalyst.city/transform) also has an +Finally, the `Transform page `_ also has an *Output Layer* option at the bottom of the control panel. This enables results of the transformation algorithm to be displayed in one of four ways: diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..a36b74e --- /dev/null +++ b/requirements.txt @@ -0,0 +1,2 @@ +myst-parser +sphinx_rtd_theme diff --git a/software.rst b/software.rst new file mode 100644 index 0000000..a27d267 --- /dev/null +++ b/software.rst @@ -0,0 +1,27 @@ +6. Software and Algorithms +########################## + +## Software + +The primary software used to generate the results presented on `Urban Analyst `_ are: + +- `osmdata `_ for accessing and processing + data from Open Street Map. + +- `dodgr `_ for general network routing queries. + +- `gtfsrouter `_ for public transport routine queries. + +- `m4ra `_ for multi-modal routing queries + +- `uaengine `_ for additional + algorithms combining aspects of these other routing algorithms for tasks + specific to Urban Analyst. + +All of this software was primarily developed by the same team responsible for +Urban Analyst itself. + +Algorithms +********** + +(... coming soon) diff --git a/src/SUMMARY.md b/src/SUMMARY.md deleted file mode 100644 index de54746..0000000 --- a/src/SUMMARY.md +++ /dev/null @@ -1,8 +0,0 @@ -# Summary - -- [Introduction](./intro.md) -- [Overview](./overview.md) -- [Example](./example.md) -- [UA Variables](./variables.md) -- [Data Sources](./data.md) -- [Software and Algorithms](./software.md) diff --git a/src/software.md b/src/software.md deleted file mode 100644 index e3e82ce..0000000 --- a/src/software.md +++ /dev/null @@ -1,25 +0,0 @@ -# Software and Algorithms - -## Software - -The primary software used to generate the results presented on [Urban Analyst](https://urbananalyst.city) are: - -- [`osmdata`](https://docs.ropensci.org/osmdata) for accessing and processing - data from Open Street Map. - -- [`dodgr`](https://UrbanAnalyst.github.io/dodgr) for general network routing queries. - -- [`gtfsrouter`](https://UrbanAnalyst.github.io/gtfsrouter) for public transport routine queries. - -- [`m4ra`](https://UrbanAnalyst.github.io/m4ra) for multi-modal routing queries - -- [`uaengine`](https://github.com/UrbanAnalyst/uaengine) for additional - algorithms combining aspects of these other routing algorithms for tasks - specific to Urban Analyst. - -All of this software was primarily developed by the same team responsible for -Urban Analyst itself. - -## Algorithms - -(... coming soon) diff --git a/src/variables.md b/variables.rst similarity index 91% rename from src/variables.md rename to variables.rst index 8ba40e5..bfa5e11 100644 --- a/src/variables.md +++ b/variables.rst @@ -1,4 +1,5 @@ -# Variables +4. UA Variables +############### All UA variables are measured such that lower or negative values are good, whereas higher values are bad. (Exceptions are neutral variables such as @@ -20,10 +21,11 @@ values within the statistics page are aggregated across entire cities. Unless explicitly described otherwise, values of all variables are weighted by population density. This means that, for example, distances to nearest schools represent average distances that each person must travel to get to school. Full -descriptions of the calculation of all variables are given in the [*Software -and Algorithms* chapter](./software.md). +descriptions of the calculation of all variables are given in the :ref:`*Software +and Algorithms* chapter<6. Software and Algorithms>`. -## Socio-demographic variables +Socio-demographic variables +*************************** The extent and structure of each city is defined by its "socio-demographic variable," or "social variable" for short. These are taken from open-source @@ -42,7 +44,8 @@ disadvantage provided by each city, and defaults to rates of unemployment only where no more comprehensive of integrative measures are openly provided by cities. -## Travel Variables +Travel Variables +**************** Urban Analyst provides highly detailed statistics on transport systems. Many of these are derived from estimates of times required to travel fixed distances of @@ -73,7 +76,8 @@ The remainder of this section describes the five travel variables: - Intervals between consecutive services - Compound travel statistic -### Absolute and Relative Travel Times +Absolute and Relative Travel Times +================================== Urban Analyst enables comparisons of travel times between two primary modes of transport: @@ -82,8 +86,8 @@ transport: benchmark for measures of travel time using other modes. UA generates realistic estimates of private automobile travel times through scaling to empirically observed data on actual vehicular travel times. (Calibration - procedures are implemented and documented in [this GitHub - repository](https://github.com/UrbanAnalyst/ttcalib).) Importantly, UA + procedures are implemented and documented in `this GitHub + repository `_.) Importantly, UA includes an additional, unique aspect of automobile travel times not quantified in any other equivalent system, through an algorithm to accurately estimate the likely time required to park a private vehicle, and then to walk @@ -115,7 +119,8 @@ following two primary travel time statistics: transport with private automobile, while values greater than one indicate that private automobile transport is faster. -### Intervals and Numbers of Transfers +Intervals and Numbers of Transfers +================================== In addition to travel times, UA also includes the following two additional statistics quantifying other aspects of public transport systems. Both are @@ -140,7 +145,8 @@ times for the next equivalent journey out to that distance. slower than absolute fastest journeys (generally by up to 5 minutes) if they involve fewer transfers. -### The Compound Travel Statistic +The Compound Travel Statistic +============================= All three of the statistics described above - travel times, intervals, and numbers of transfers - are measured such that lower values are more desirable. @@ -156,13 +162,15 @@ directly discern reasons for high values of this compound travel statistic. Urban Analyst nevertheless provides direct insight into all individual values, as well as all pairwise combinations of values, permitting indirect insight. -## Population density +Population density +****************** -Population density values are taken directly from the [European Union *Global -Human Settlement Layer*](https://ghsl.jrc.ec.europa.eu/index.php) data, +Population density values are taken directly from the `European Union *Global +Human Settlement Layer* `_ data, aggregated into polygons for maps, or across entire cities for statistics. -## Distance to nearest schools +Distance to nearest schools +*************************** Distances to nearest schools are measured in kilometres, as shortest walking distances from each point to the nearest school. These are network distances, @@ -170,7 +178,8 @@ and not simple straight line distances. A single value is ascribed to each point within a city, and all points aggregated after weighting by local population densities. -## Bicycle infrastructure +Bicycle infrastructure +********************** The bicycle infrastructure index is derived from a measure of the proportion of all possible journeys from each point out to a fixed distance of five @@ -190,15 +199,16 @@ dedicated bicycle ways. These "half-weight" ways include residential or "living" streets, unpaved tracks, and bicycle lanes directly alongside automobile lanes. A third category of ways are weighted at one-quarter, including footpaths and general pedestrian areas which permit bicycle travel. -The precise weighting scheme can be viewed in [this source code -file](https://github.com/UrbanAnalyst/uaengine/blob/main/R/bicycle-infrastructure.R). +The precise weighting scheme can be viewed in `this source code file +`_. The weighted sums of all distances along these types of ways traversed out to five kilometres from any given point are then divided by the sum of all distances travelled regardless of way type to give a ratio between zero and one. This bicycle infrastructure index is then one minus this value. -## Natural space accessibility +Natural space accessibility +*************************** Natural space accessibility is measured in a similar way to the bicycle infrastructure variable, except it quantifies proportions of walking distances @@ -220,7 +230,8 @@ zero would represent an entire city of natural space, with no built structures at all, while a value of one would represent a complete absence of natural spaces. -## Parking index +Parking index +************* The parking index is the ratio of numbers of nearby parking spaces to total volumes of nearby buildings. The parking statistic is calculated for each point @@ -235,7 +246,8 @@ All publicly accessible parking spaces are counted, including on-street parking, open parking lots, and multi-level parking garages. Building volumes are aggregated regardless of type or purpose. -## Housing value and rent +Housing value and rent +********************** For USA cities only, additional statistics are provided for average housing value per room, and average rental per room, both in US dollars.