From c83aedc5a1bab27941660c76e56b5a53ed487da5 Mon Sep 17 00:00:00 2001 From: mpadge Date: Wed, 11 Sep 2024 17:58:50 +0200 Subject: [PATCH 01/20] initial commit of rst docs for #5 --- docs/Makefile | 20 +++ docs/conf.py | 75 +++++++++ docs/data.rst | 31 ++++ docs/example.rst | 344 ++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 23 +++ docs/intro.rst | 119 +++++++++++++++ docs/make.bat | 35 +++++ docs/overview.rst | 164 ++++++++++++++++++++ docs/requirements.txt | 2 + docs/software.rst | 26 ++++ docs/variables.rst | 242 +++++++++++++++++++++++++++++ 11 files changed, 1081 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/data.rst create mode 100644 docs/example.rst create mode 100644 docs/index.rst create mode 100644 docs/intro.rst create mode 100644 docs/make.bat create mode 100644 docs/overview.rst create mode 100644 docs/requirements.txt create mode 100644 docs/software.rst create mode 100644 docs/variables.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/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/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..d9c868a --- /dev/null +++ b/docs/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'] + + +# -- 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/docs/data.rst b/docs/data.rst new file mode 100644 index 0000000..bcc8a3a --- /dev/null +++ b/docs/data.rst @@ -0,0 +1,31 @@ +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 + 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 + on both pedestrian and bicycle travel times. + +The following additional data are then required for each city: + +- Data on some measure of socio-demographic inequality or disadvantage, such as + rates of unemployment, quantified within a series of polygonal shapes which + are also used to define each city. +- Data on public transport timetables in *General Transit Feed Specification* + (GTFS) format, or in other formats able to be converted to GTFS format. + +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). + +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/docs/example.rst b/docs/example.rst new file mode 100644 index 0000000..e0eadd8 --- /dev/null +++ b/docs/example.rst @@ -0,0 +1,344 @@ +3. Example +########## + +This chapter demonstrates most of the capabilities of the [Urban Analyst +platform](https://urbananalyst.city) 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 +example, public transport systems should be constructed to offer the fastest +services to the areas where most people live. Not implementing this weighting +would, in contrast, leave measures in some form of times per unit area, so that +for example travel times from unpopulated parts of a city would be weighted +equally to times from densely populated parts. Weighting travel times, and all +other UA variables, by population density converts them to values as +experienced on average by each person in a city. + +The comparisons in this chapter between Paris and Berlin are mostly drawn from +the "Stats" page, which provides overviews of entire cities, and comparisons +with all other UA cities. The "Maps" page can then be used to examine the +actual spatial distributions of particular variables or relationships within +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, +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 +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. + +The following table summarises the values of the individual variables for each +city (each measured on its own distinct scale). + +.. 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 +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 + +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 +combination of travel modes except private automobile, including walking, +bicycling, and any available public transport options. Travelling 10km in +Paris takes under 40 minutes on average, while equivalent journeys in +Berlin require almost 1.5 minutes more. + +The "Transport Relative" values divide the absolute travel times described above +by times for equivalent journeys with private automobile. Ratios of one imply +automobile times equal to multi-modal times; ratios of less than one imply that +multi-modal transport is faster than private automobile. Paris and Berlin both +have comparably low values for this ratio, implying relatively fast multi-modal +transport, with Paris notably faster than Berlin. This is likely influenced by +Paris's recent introduction of a uniform maximum speed limits of 30km/hour +through the city, whereas Berlin features a number of "autobahns" with much +higher speed limits. + +Note that travel times with private automobiles include estimates of times +required to park a vehicle and ultimately walk to any desired destination. +Vehicular times calculated here are thus notably longer than with most +commercial routing engines, which give vehicular travel times only, and ignore +the critical need to park a vehicle and walk to a destination. + +All individual variables also enable comparison in terms of "Variation", rather +than "Average" values. Comparing these reveals that Berlin generally has +markedly lower variation than Paris. A comparison of these statistics on the +"Maps" page reveals that this is largely because Paris is simply much larger +than Berlin, and the ranges of both absolute and relative transport times are +correspondingly greater. The fact that relative transport in Paris is still +better on average than in Berlin is thus even more impressive considering this +stark difference in scale. + +Travelling in Paris requires notably greater numbers of transfers to travel +equivalent distances than Berlin. The values in the "Number of Transfers" layer +are for journeys of 10km total distance (including walking or cycling distances +at either end). Travelling in Paris requires > 50% more transfers than journeys +in Berlin. + +The fourth transport variable, "Interval", measures the time to wait (in +minutes) until the next equivalent service. Intervals in Paris are slightly +under 5 minutes, whereas values in Berlin are just under 7 minutes. + +Finally, the "Compound Transport" variable simply multiplies absolute travel +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 + +- "School Distance": Paris has notably shorter distances from each point in the + city to the nearest school than does Berlin. +- "Bicycle Index": Paris has very notably better bicycle infrastructure than + Berlin. This index is simply one minus the average portion of all bicycle + journeys out to 5km from each point which may be taken on dedicated bicycle + infrastructure. Around one quarter of all bicycle journeys in Paris may be + taken along dedicated bicycle ways, compared to less than one fifth in + Berlin. Moreover, comparing the maps for this variable reveal that the + bicycle infrastructure in Berlin generally improves with distance away from + the city centre, whereas Paris has the best bicycle infrastructure + concentrated towards the centre of the city. +- "Nature Index": Access to natural spaces in the two cities is effectively the + opposite of the bicycle index. Paris provides relatively little + access to natural spaces for anybody not close to one of the two huge parks + in the city, whereas Berlin provides an abundance of generally smaller + natural spaces dispersed throughout the city. Note that natural space access + includes walks alongside water bodies. Both cities include dominant rivers, + yet Berlin also provides greater pedestrian access to the banks of its rivers + and canals. Comparison of this layer on the maps reveals the comparably + greater access in Berlin to walking paths alongside canals and rivers, + whereas most of the Seine in Paris is effectively inaccessible to + pedestrians. +- "Parking": Finally, both Paris and Berlin offer relatively little opportunity + to park private automobiles compared with the other UA cities, with Berlin + notably less than Paris. + +## 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 +assessed in standardised ways, so they may be directly compared between cities. +Moreover, the scales shown in the "Stats" page may also be directly compared. +Values of one or greater indicate very strong relationships, whereas values +less than 0.1 or so indicate weak relationships, and values less than around +0.01 should generally be interpret to indicate no relationship. Pairs of +variables with very weak or negligible strengths of relationship are generally +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 + +This sub-section only considers transport times, both in absolute and relative +sense. The other transport variables, of intervals and numbers of transfers, +generally follow similar patterns and are not explicitly considered here. +Relative transport times are only very weakly related to most other variables. +In contrast, absolute transport times are strongly related to most other +variables. + +Relative transport times are negligibly associated with population densities, +while absolute times are particularly strongly and negatively correlated. These +negative relationships indicate that faster transport is associated with higher +population densities, more so in Berlin than Paris. + +Slightly weaker relationships are manifest between absolute travel times and +distances to nearest schools. Relationships in both Berlin and Paris are +positive, indicating that fast public transport is positively associated with +shorter distances to schools, with the relationship about twice as strong in +Berlin as in Paris. + +Travel times are very strongly, and positively, correlated with bicycle +infrastructure, indicating faster travel times in regions with better bicycle +infrastructure. This relationship is much stronger in Paris than in Berlin, for +reasons easy to discern by looking at the maps of Berlin for these two +variables. Bicycle infrastructure there is much better in the periphery of the +city, whereas transport times exhibit more of a systematic discrepancy between +the east (fast) and west (slow) portions of the city. In Paris, in contrast, +faster transport times and better bicycle infrastructure are both concentrated +more towards the centre of the city. + +Relationships between transport times and the index of accessibility to natural +spaces are also very strong, and negative. This means that faster transport +times are associated with lower accessibility to natural spaces, as might be +generally expected of most high-density cities. The relationship is stronger in +Berlin than Paris, indicating that faster transport times are most strongly +associated with poorer access to natural spaces there than in Paris. + +Finally, absolute transport times are slightly negatively associated with +numbers of automobile parking spaces in Paris, whereas there is no relationship +in Berlin. This negative relationship indicates that regions with faster public +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 + +Shorter school distances are positively associated with the bicycle index in +Paris, indicating a positive association between good bicycle infrastructure +and short distances to schools. Berlin manifests no such relationship, likely +for reasons described above, that bicycle infrastructure in Berlin is generally +more peripheral than in Paris. + +Although much weaker, relationships between schools distances and the index of +accessibility to natural spaces are negative, indicating that locations closer +to schools are further from nature, and more so in Berlin than in Paris. + +Finally, the social variables are more strongly related to all other +non-transport variables in Paris than in Berlin, except for with the index of +bicycle infrastructure. This variable is more strongly, and positively, +correlated with the social indicator in Berlin than in Paris, where the +relationship is negative. The positive relationship in Berlin indicates that +the provision of bicycle infrastructure is positively associated with social +advantage, an effect again readily seen in examining the map of Berlin. In +contrast, Paris is more effective in providing bicycle infrastructure in areas +of relative social disadvantage. + +Paris also seems to be more effective in educational provision in areas of +social disadvantage, with the strong negative correlation indicating that +socially disadvantaged Parisians generally have to travel shorter distances to +schools. Although this relationship is also negative in Berlin, it is much +weaker. + +In contrast, Paris's very strong and positive relationship between social +advantage and access to natural spaces indicates the relatively far greater +difficulty experienced by less socially advantaged Parisians in accessing +natural spaces compared with equivalent inhabitants of Berlin. + +Finally, Paris manifests a very strong and negative association between social +advantage and numbers of automobile parking spaces, indicating that low social +disadvantage is strongly associated with high numbers of automobile parking +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 + +### Lessons for Berlin + +Paris's transport system is considerably faster and more frequent. +Nevertheless, it also involves greater numbers of transfers, suggesting that +any attempt to improve the system in Berlin should take care to avoid +inadvertently increasing numbers of transfers. + +Berlin's average relative speed is also notably higher than Paris's, and at +1.09 likely too high to effectively discourage large numbers of people from +opting to travel via private automobile. Examination of the map of relative +travel times clearly reveals the effect of the connected ring out autobahns +encircling the city. While reducing speeds on these carriageways may not be +feasible, a uniform 30km/hour limit as introduced in Paris may nevertheless +significantly reduce this ratio, and further incentivise many more people to +opt for public transport rather than private automobile. + +Although Paris is a far larger city, its average population density is +nevertheless very similar to Berlin's. It is then even more striking that Paris +offers considerably shorter average distances to schools than Berlin. School +distances in Berlin are also only weakly correlated with social conditions, +whereas average distances to schools in Paris are shorter in less socially +advantaged areas. Both of these factors indicate a need in Berlin for more +provision of local schooling in general, and particularly in socially +disadvantaged regions, if it is to match the educational opportunities provided +in Paris. + +Paris's bicycle infrastructure is considerably better than Berlin's, and +perhaps even more importantly, becomes better towards the inner city regions. +In contrast, Berlin really only offers good bicycle infrastructure in the +relatively peripheral, and more affluent, outer regions. Berlin really needs to +proactively focus on improving bicycle infrastructure in the inner city +regions. + +Berlin is fortunately greatly enhanced by an abundance of natural space, +including access to the city's rivers and canals, and access to these natural +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 + +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. +This difference is especially notable given that Paris is much larger than +Berlin. Improvements to Paris's public transport system should focus on +decreasing numbers of transfers. + +Paris's average relative speed is very close to the "magical" value of one, at +which point private automobiles are no faster than multi-modal transport +including walking and cycling. + +Paris has done a great job of providing bicycle infrastructure in the inner +city regions, and notably of proactively enhancing or creating bicycle +infrastructure in regions of social disadvantage. + +Contrasts with Berlin nevertheless emphasise a couple of aspects which Paris +could focus on improving. The most notable of these is the index of +accessibility to natural spaces, and the relationship of this to other +variables. Paris simply has far less natural space than Berlin, and much poorer +general accessibility. Moreover, access to natural spaces is positively +associated with social advantage, so that it is relatively difficult for +socially disadvantaged Parisians to access natural spaces. diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..ab9943b --- /dev/null +++ b/docs/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/docs/intro.rst b/docs/intro.rst new file mode 100644 index 0000000..c758c97 --- /dev/null +++ b/docs/intro.rst @@ -0,0 +1,119 @@ +1. Introduction +############### + +This is the documentation for [Urban Analyst (UA)](https://urbananalyst.city). +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) +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) +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. + +Finally, UA enables cities to "learn" from one another, by visualising how the +properties of any chosen city can best be transformed to become more like the +properties of any other chosen city. Paris, for example, has better bicycle +infrastructure than Berlin, and the UA transformation algorithm can calculate +how Berlin can most easily transform its bicycle infrastructure to become more +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? +***************** + +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. + +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 +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. + +.. 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 +subscription fee of €540 per month for a maximum of 60 requests per minute. +That rate would permit 31.5 million queries per year. The city of Hamburg, for +example, would then take almost 2,000 years to calculate, and would cost +€12 million. Google also offers a commercial routing service, limited to a +maximum of 500,000 queries per month, for a total price of US$2,000. At that +rate, the analyses for Hamburg would cost US$224 million. + +The results presented in Urban Analyst are simply not possible using commercial +tools, or indeed any other open source tools. These analyses truly are uniquely +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? +*************************** + +Not directly, but feel free to open a [GitHub +issue](https://github.com/mpadge/UrbanAnalyst/issues) to start a discussion +about requesting full data sources. + +Structure +********* + +This documentation includes the following five chapters: + +1. This introduction +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. 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 `_. diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..8084272 --- /dev/null +++ b/docs/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/docs/overview.rst b/docs/overview.rst new file mode 100644 index 0000000..07ea2d3 --- /dev/null +++ b/docs/overview.rst @@ -0,0 +1,164 @@ +2. Overview +########### + +This chapter provides an overview of the four main pages of the [Urban Analyst +platform](https://urbananalyst.city): + +- The [summarise page](https://urbananalyst.city/summarise) provides summary + overviews for each city of key statistical properties and relationships with + other cities; +- The [compare page](https://urbananalyst.city/compare) compares aggregate + statistics for all cities; +- The [map page](https://urbananalyst.city/maps) shows interactive maps for + each city; +- The [transform page](https://urbananalyst.city/transform) 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 +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, +or can be manually opened by clicking on the "Help" button on any of the main +pages. + +---- + +## Summarise + +The [Summarise page](https://urbananalyst.city/summarise) 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 [Summarise page](https://urbananalyst.city/summarise) 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). + + +---- + +## Compare + +The [Compare page](https://urbananalyst.city/compare) 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 +values of the chosen layer for all cities. As in all UA pages, lower values are +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 + +The control panel of the [compare page](https://urbananalyst.city/compare) +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 +strength of relationship between access to natural spaces and social +disadvantage. Both of these variables are measured such that low values are +better than high values. A positive relationship between the two would then +mean that lower social disadvantage is coupled with better access to natural +spaces, while high social disadvantage is coupled with worse access to natural +spaces. Conversely, a negative relationship would indicate that higher social +disadvantage was coupled with better access to natural resources. Or, in the +words brought up by clicking the "Explain Layer" button, "Low values indicate +that good access to natural spaces is coupled with disadvantageous social +conditions." + +---- + +## Map + +The [Map page](https://urbananalyst.city/map) 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). + +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. + +As in all UA measurements, lower values of all variables are generally better +than higher values. Colour scales on all maps thus generally display lower +values in brighter, yellow colours, while higher values are displayed in +darker, blue or violet colours. The control panel includes an "Explain Layer" +button which opens a text panel explaining details of the chosen variable. + +---- + +## Transform + +The [Transform page](https://urbananalyst.city/transform) 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 +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 +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) +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 +distribution for the chosen city is then transformed by changing each point by +the smallest amount possible so that they reflect the distribution in the +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). + +### Extra Layers + +The [Transform page](https://urbananalyst.city/transform) 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 +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 +selecting those two layers.) The *Extra Layers* panel can be used in this case +to examine not just how Paris might best transform its access to nature to look +more like Berlin, but also how it might also improve its relationship between +access to nature and social disadvantage. + +By default, values of *Extra Layers* are automatically selected as those which +have better relationships in the chosen target city. These default values will +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 + +Finally, the [Transform page](https://urbananalyst.city/transform) 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: + +1. *Original* to show original values, prior to transformation; +2. *Transformed* to show the actual transformed values; +3. *Absolute* to show the absolute value by which each are in the city would + have to be transformed to match the distribution in the target city; and +4. *Relative*, which displays the absolute transformation values relative to + the original, untransformed values. diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..a36b74e --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +myst-parser +sphinx_rtd_theme diff --git a/docs/software.rst b/docs/software.rst new file mode 100644 index 0000000..6483232 --- /dev/null +++ b/docs/software.rst @@ -0,0 +1,26 @@ +6. 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/docs/variables.rst b/docs/variables.rst new file mode 100644 index 0000000..9ccbed7 --- /dev/null +++ b/docs/variables.rst @@ -0,0 +1,242 @@ +4. 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 +population density which are nevertheless straightforward to interpret.) For +example, unemployment or transport times are both better when values are lower. +Indices of bicycle infrastructure and access to natural spaces are also +transformed so that lower values indicate better or more of either. In these +cases, the transformations are simply one minus the respective proportions of +journeys out to a fixed distance travelled along bicycle infrastructure, or +through or alongside natural spaces. Values of 0 then reflect 100% of all +journeys spent on bicycle infrastructure or in natural spaces, while values of +1 would represent complete absence of either bicycle infrastructure or natural +spaces. + +Variables are measured for every way, path, or street intersection within each +city. Values for the maps are aggregated within polygons defined by the +*Socio-demographic variables* described in the following sub-section, while +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). + +## 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 +datasets provided by the cities as a series of geographic areas, defined as +polygonal shapes, and some corresponding measure of socio-demographic +disadvantage. The cities themselves decide the resolution and extent of these +polygonal data. These polygons then define the extent and shape of cities +analysed in Urban Analyst, and the individual polygons into which the map data +are aggregated. + +Values of these socio-demographic variables are the only aspect that differs +between different cities. One of the simplest versions is unemployment rate, +generally measured either as a percentage (0-100), or a proportion (0-1). The +UA platform selects the most representative measure of general social +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 + +Urban Analyst provides highly detailed statistics on transport systems. Many of +these are derived from estimates of times required to travel fixed distances of +10km. This value is chosen to capture the general efficiency of public +transport systems. Shorter distances do not sufficiently capture the influence +of transport modes such as express or long-distance train services, while +longer distances unfairly penalise smaller cities in which most journeys are +only of shorter distances. + +Values at this distance of 10km are obtained by following these three steps, +taking the example statistic of travel times: + +1. Calculate total travel times from all street intersections to all other + street intersections within a city. +2. Calculate a straight line of "best fit" (a "least squares regression" line) + which describes how travel times vary with distance. +3. Use that line to obtain the "average" value of travel time at the distance + of 10km. + +Values shown in the maps are aggregated within each polygon of a chosen city, +while values shown in the statistics page are aggregated over entire cities. + +The remainder of this section describes the five travel variables: + +- Absolute travel times +- Relative travel times +- Numbers of transfers +- Intervals between consecutive services +- Compound travel statistic + +### Absolute and Relative Travel Times + +Urban Analyst enables comparisons of travel times between two primary modes of +transport: + +- *Private Automobile.* Travel times with private automobile are used as a + 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 + 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 + to a desired destination. These parking times are crucial, as direct travel + times to many inner-city destinations do not provide realistic estimates of + actual journey times to locations where it may be impossible to actually park + a private automobile. + +- *Multi-Modal Transport.* UA's "multi-modal travel times" represent fastest + possible times taken for journeys from every single point in a city to travel + 10km using any combination of transport modes excluding private automobile. + The primary modes considered are walking, bicycling, and all available modes + of public transport within each city. Where it is faster to cycle 10km than + to take public transport (such as from locations with very poor public + transport connections, or on the top of long hills where downhill cycling may + actually be faster), these times will represent the single mode of cycling + only, but multi-modal times will generally reflect fastest times formed by + combining multiple modes of transport. + +Travel times measured these two ways are then combined to generate the +following two primary travel time statistics: + +- *Absolute travel times* as the multi-modal travel times; that is, using any + mode except private automobile. + +- *Relative travel times* as the ratios of absolute travel times compared with + equivalent travel times with private automobile. Relative travel times of + less than one indicate that multi-modal transport is faster than equivalent + transport with private automobile, while values greater than one indicate + that private automobile transport is faster. + +### 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 +measured for every point of origin with a city, with final values again derived +by following the steps described above to obtain average values of each for all +trips of 10km distance. Numbers of transfers are thus the average number +required for all journeys of 10km, while intervals are the required waiting +times for the next equivalent journey out to that distance. + +- *Intervals to Next Service* are measured in minutes. For each point of origin + in a city, this statistic measures the waiting time necessary before + departing to each destination within a city on the service after the one + corresponding to the fastest journey. This delayed service may not be fast as + the original, or it may even be faster in some cases, as the UA algorithms + also prioritise connections with the fewest possible transfers. It can happen + that subsequent services are actually faster, yet involve additional + transfers not required in the originally identified "fastest" service. + +- *Numbers of Transfers* measure the number of transfers necessary for a + *minimal-transfer* journey out to a distance of 10km. These + *minimal-transfer* journeys are selected to allow for journeys slightly + slower than absolute fastest journeys (generally by up to 5 minutes) if they + involve fewer transfers. + +### 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. +Travel times are then directly multiplied by (a logarithmically-transformed +version of) intervals between services to generate a "*compound travel +statistic*". Low values of this statistic only arise in locations which have +fast travel times and short intervals between services. Low values may +accordingly always be interpreted as indicating overall good transport +services. In contrast, high values may arise through various combinations of +variables, from extremely high values of one single variable, to less extreme +combinations of the two variables. It is thus generally not possible to +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 values are taken directly from the [European Union *Global +Human Settlement Layer*](https://ghsl.jrc.ec.europa.eu/index.php) data, +aggregated into polygons for maps, or across entire cities for statistics. + +## 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, +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 + +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 +kilometres that travel along dedicated bicycle infrastructure. To conform with +all other UA variables, the index is one minus this proportion, so that low +values reflect high proportions of bicycle infrastructure. Values of zero would +then reflect all journeys taken along dedicated bicycle paths, while values of +one would mean a complete absence of dedicated bicycle infrastructure. + +Travel is calculated using a bicycle-specific algorithm that only extends along +ways unsuitable for bicycle travel where no alternatives exist. The weighting +scheme used adds total distances for all portions of travel along designated +cycleways that are separated from vehicular traffic. Portions of trips +extending along other types of ways are added with "half weightings" so, for +example, one kilometre along these types is equivalent to two kilometres on +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 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 is measured in a similar way to the bicycle +infrastructure variable, except it quantifies proportions of walking distances +out to maximal distances of two kilometres that traverse natural spaces. This +provides a more realistic measure of natural space than simple aggregations of +areas, because it measures the ability of people to directly walk from every +point in a city through or alongside nearby natural spaces. + +Moreover, aggregate metrics do not generally capture the ability of people to +actually access natural spaces. A park may, for example, have restricted or +even private access. This would count as a natural space in a simply aggregate +metric, yet not in UA because access restrictions are taken into account in the +routing algorithms. + +The algorithm also measures lengths of ways walked adjacent to water - +so-called "blue space", providing a comprehensive metric of the actual ability +to access natural spaces from every point in a city. A natural space index of +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 + +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 +by adding all nearby parking spaces with a weighting scheme that decreases +exponentially with distance, so that nearby parking spaces count more than +parking spaces that are farther away. Building volumes are also aggregated +using an identical weighting scheme. The parking index at each point is then +the ratio of the sum of distance-weighted numbers of parking spaces to the sum +of distance-weighted total building volumes. + +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 + +For USA cities only, additional statistics are provided for average housing +value per room, and average rental per room, both in US dollars. From 04ff5a95bce13650ffa96fd5d990f5f879b164f5 Mon Sep 17 00:00:00 2001 From: mpadge Date: Wed, 11 Sep 2024 18:06:18 +0200 Subject: [PATCH 02/20] fix hyperlinks in intro.rst for #5 --- docs/intro.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/intro.rst b/docs/intro.rst index c758c97..fb5ea83 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -1,16 +1,16 @@ 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. @@ -27,17 +27,17 @@ the whole city to have infrastructure equivalent to Paris. How does it work? ***************** -Urban Analyst present a variety of [variables](./variables.md) for each city +Urban Analyst present a variety of :ref:`variables<4. 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](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. +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? *********************************** @@ -99,8 +99,8 @@ not available in any other way. 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 From ad6e1348c57b9ac18c4aed2556f1934c1b7460ec Mon Sep 17 00:00:00 2001 From: mpadge Date: Wed, 11 Sep 2024 18:12:51 +0200 Subject: [PATCH 03/20] update all hlinks in overview to rst for #5 --- docs/overview.rst | 60 +++++++++++++++++++++++------------------------ 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/docs/overview.rst b/docs/overview.rst index 07ea2d3..0fd7578 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -1,21 +1,21 @@ 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, @@ -24,35 +24,35 @@ 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 +The values described in this initial part of the `Summarise +page `_ indicate which statistics might be particularly worth examining in both the -[Compare](https://urbananalyst.city/compare) and the [Map -](https://urbananalyst.city/map) pages. +`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 -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 @@ -63,7 +63,7 @@ variable. ### 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 @@ -82,13 +82,13 @@ conditions." ## 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. 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. @@ -103,20 +103,20 @@ button which opens a text panel explaining details of the chosen variable. ## 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 @@ -126,16 +126,16 @@ 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 -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 @@ -152,7 +152,7 @@ default selection after changing any of these options. ### 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: From 3c468ea513a49b5b8742bdf4389fab6b69729c8d Mon Sep 17 00:00:00 2001 From: mpadge Date: Wed, 11 Sep 2024 18:13:09 +0200 Subject: [PATCH 04/20] rst headers in overview for #5 --- docs/overview.rst | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/docs/overview.rst b/docs/overview.rst index 0fd7578..21b7798 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -25,6 +25,7 @@ pages. ---- Summarise +********* The `Summarise page `_ provides an overview of the general statistical properties of any chosen UA city. Statistics for @@ -50,7 +51,8 @@ page `_. ---- -## Compare +Compare +******* The `Compare page `_ enables comparisons between all UA cities, both in terms of single variables and relationships @@ -61,7 +63,8 @@ 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 `_ includes an option to select "paired" variables. The resultant graphs then @@ -80,7 +83,8 @@ conditions." ---- -## Map +Map +*** The `Map page `_ shows interactive maps for each city, with values for all UA variables displayed in small polygons. These @@ -101,7 +105,8 @@ button which opens a text panel explaining details of the chosen variable. ---- -## Transform +Transform +********* The `Transform page `_ enables the properties of any chosen city to be transformed to reflect equivalent @@ -128,7 +133,8 @@ 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 :ref:`*Software and Algorithms* chapter<6. Software and Algorithms>`. -### Extra Layers +Extra Layers +============ The `Transform page `_ includes an additional button labelled *Extra Layers*. The transformations described above @@ -150,7 +156,8 @@ 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 `_ also has an *Output Layer* option at the bottom of the control panel. This enables results From d1633ef75f589f9ee55bca78113e0fb1cc38254a Mon Sep 17 00:00:00 2001 From: mpadge Date: Wed, 11 Sep 2024 18:15:28 +0200 Subject: [PATCH 05/20] rst headers in example.rst for #5 --- docs/example.rst | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/docs/example.rst b/docs/example.rst index e0eadd8..61d3aae 100644 --- a/docs/example.rst +++ b/docs/example.rst @@ -31,7 +31,8 @@ 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). @@ -80,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 @@ -129,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. @@ -157,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 @@ -194,7 +198,8 @@ relationships for each city: | Social | School dist | -0.05 | -0.25 | -### Transport Variables +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, @@ -238,7 +243,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 @@ -278,9 +284,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 @@ -319,7 +327,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. From 163a8e57f326bbbb2d50d69dc6f88a3c2c3445ea Mon Sep 17 00:00:00 2001 From: mpadge Date: Wed, 11 Sep 2024 18:22:29 +0200 Subject: [PATCH 06/20] update table in example to rst for #5 --- docs/example.rst | 100 +++++++++++++++++++++++++++++++++++++---------- 1 file changed, 80 insertions(+), 20 deletions(-) diff --git a/docs/example.rst b/docs/example.rst index 61d3aae..d3bda6f 100644 --- a/docs/example.rst +++ b/docs/example.rst @@ -176,26 +176,86 @@ 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 | +.. 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 From 215c89bce54ec3a523cfa3aac40a733bf9414a1c Mon Sep 17 00:00:00 2001 From: mpadge Date: Wed, 11 Sep 2024 18:24:54 +0200 Subject: [PATCH 07/20] rst headers for variables for #5 --- docs/variables.rst | 33 ++++++++++++++++++++++----------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/docs/variables.rst b/docs/variables.rst index 9ccbed7..df7d295 100644 --- a/docs/variables.rst +++ b/docs/variables.rst @@ -24,7 +24,8 @@ 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). -## 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 @@ -43,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 @@ -74,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: @@ -116,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 @@ -141,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. @@ -157,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, 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, @@ -171,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 @@ -199,7 +207,8 @@ 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 @@ -221,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 @@ -236,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. From 27c80f667d72e60e6ce73cafbf16627dfcacf0f8 Mon Sep 17 00:00:00 2001 From: mpadge Date: Wed, 11 Sep 2024 18:29:09 +0200 Subject: [PATCH 08/20] rst all hrefs in variables.rst for #5 --- docs/variables.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/variables.rst b/docs/variables.rst index df7d295..9abca5f 100644 --- a/docs/variables.rst +++ b/docs/variables.rst @@ -21,8 +21,8 @@ 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 *************************** @@ -86,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 @@ -165,8 +165,8 @@ as well as all pairwise combinations of values, permitting indirect insight. 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 @@ -199,8 +199,8 @@ 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 From bc0147da9b5bd15a1a87e99c25a78ded9c930fc6 Mon Sep 17 00:00:00 2001 From: mpadge Date: Wed, 11 Sep 2024 18:30:01 +0200 Subject: [PATCH 09/20] rst all hrefs in data.rst for #5 --- docs/data.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/data.rst b/docs/data.rst index bcc8a3a..5157acb 100644 --- a/docs/data.rst +++ b/docs/data.rst @@ -5,12 +5,12 @@ 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: @@ -25,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. From 4498e5f376f528e46d659ab00e2e016459d64901 Mon Sep 17 00:00:00 2001 From: mpadge Date: Wed, 11 Sep 2024 18:34:31 +0200 Subject: [PATCH 10/20] rst all hrefs in software for #5 --- docs/software.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/software.rst b/docs/software.rst index 6483232..a27d267 100644 --- a/docs/software.rst +++ b/docs/software.rst @@ -3,24 +3,25 @@ ## Software -The primary software used to generate the results presented on [Urban Analyst](https://urbananalyst.city) are: +The primary software used to generate the results presented on `Urban Analyst `_ are: -- [`osmdata`](https://docs.ropensci.org/osmdata) for accessing and processing +- `osmdata `_ for accessing and processing data from Open Street Map. -- [`dodgr`](https://UrbanAnalyst.github.io/dodgr) for general network routing queries. +- `dodgr `_ for general network routing queries. -- [`gtfsrouter`](https://UrbanAnalyst.github.io/gtfsrouter) for public transport routine queries. +- `gtfsrouter `_ for public transport routine queries. -- [`m4ra`](https://UrbanAnalyst.github.io/m4ra) for multi-modal routing queries +- `m4ra `_ for multi-modal routing queries -- [`uaengine`](https://github.com/UrbanAnalyst/uaengine) for additional +- `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 +Algorithms +********** (... coming soon) From 9ed70da304f728132c5cd0aa5e3b27df53f70c2d Mon Sep 17 00:00:00 2001 From: mpadge Date: Wed, 11 Sep 2024 18:38:49 +0200 Subject: [PATCH 11/20] fix one link for #5 --- docs/overview.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/overview.rst b/docs/overview.rst index 21b7798..ebb11dd 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -36,9 +36,9 @@ strengths of relationship between all pairs of statistics. 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. +particularly worth examining in both the `Compare +`_ and the +`Map `_ pages. The `Summarise page `_ also includes a section describing the best "Target city" for each chosen city. As explained From 7d38df41f5c18731a4a9707478cc5eecf9e50b96 Mon Sep 17 00:00:00 2001 From: mpadge Date: Wed, 11 Sep 2024 18:40:04 +0200 Subject: [PATCH 12/20] update rst hrefs in example for #5 --- docs/example.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/example.rst b/docs/example.rst index d3bda6f..9d2f699 100644 --- a/docs/example.rst +++ b/docs/example.rst @@ -1,8 +1,8 @@ 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 @@ -22,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 From 0830589b1a298df49a1085212c089b68db2cfc95 Mon Sep 17 00:00:00 2001 From: mpadge Date: Thu, 12 Sep 2024 12:21:28 +0200 Subject: [PATCH 13/20] rename variables chapter --- docs/variables.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/variables.rst b/docs/variables.rst index 9abca5f..1e11433 100644 --- a/docs/variables.rst +++ b/docs/variables.rst @@ -1,4 +1,4 @@ -4. Variables +4. UA Variables ############ All UA variables are measured such that lower or negative values are good, From f1271c90e07164c6b0dc1295489e9a76339d4921 Mon Sep 17 00:00:00 2001 From: mpadge Date: Thu, 12 Sep 2024 12:24:31 +0200 Subject: [PATCH 14/20] rm former mdbook files for #5 --- book.toml | 6 - src/SUMMARY.md | 8 -- src/data.md | 30 ----- src/example.md | 318 ----------------------------------------------- src/intro.md | 88 ------------- src/overview.md | 163 ------------------------ src/software.md | 25 ---- src/variables.md | 241 ----------------------------------- 8 files changed, 879 deletions(-) delete mode 100644 book.toml delete mode 100644 src/SUMMARY.md delete mode 100644 src/data.md delete mode 100644 src/example.md delete mode 100644 src/intro.md delete mode 100644 src/overview.md delete mode 100644 src/software.md delete mode 100644 src/variables.md 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/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/data.md b/src/data.md deleted file mode 100644 index 8352378..0000000 --- a/src/data.md +++ /dev/null @@ -1,30 +0,0 @@ -# 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 - 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 - on both pedestrian and bicycle travel times. - -The following additional data are then required for each city: - -- Data on some measure of socio-demographic inequality or disadvantage, such as - rates of unemployment, quantified within a series of polygonal shapes which - are also used to define each city. -- Data on public transport timetables in *General Transit Feed Specification* - (GTFS) format, or in other formats able to be converted to GTFS format. - -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). - -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/src/example.md deleted file mode 100644 index 848837a..0000000 --- a/src/example.md +++ /dev/null @@ -1,318 +0,0 @@ -# Example - -This chapter demonstrates most of the capabilities of the [Urban Analyst -platform](https://urbananalyst.city) 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 -example, public transport systems should be constructed to offer the fastest -services to the areas where most people live. Not implementing this weighting -would, in contrast, leave measures in some form of times per unit area, so that -for example travel times from unpopulated parts of a city would be weighted -equally to times from densely populated parts. Weighting travel times, and all -other UA variables, by population density converts them to values as -experienced on average by each person in a city. - -The comparisons in this chapter between Paris and Berlin are mostly drawn from -the "Stats" page, which provides overviews of entire cities, and comparisons -with all other UA cities. The "Maps" page can then be used to examine the -actual spatial distributions of particular variables or relationships within -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, -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 -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. - -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 | - - -Social disadvantage is also quantified for all cities. However, each city -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 - -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 -combination of travel modes except private automobile, including walking, -bicycling, and any available public transport options. Travelling 10km in -Paris takes under 40 minutes on average, while equivalent journeys in -Berlin require almost 1.5 minutes more. - -The "Transport Relative" values divide the absolute travel times described above -by times for equivalent journeys with private automobile. Ratios of one imply -automobile times equal to multi-modal times; ratios of less than one imply that -multi-modal transport is faster than private automobile. Paris and Berlin both -have comparably low values for this ratio, implying relatively fast multi-modal -transport, with Paris notably faster than Berlin. This is likely influenced by -Paris's recent introduction of a uniform maximum speed limits of 30km/hour -through the city, whereas Berlin features a number of "autobahns" with much -higher speed limits. - -Note that travel times with private automobiles include estimates of times -required to park a vehicle and ultimately walk to any desired destination. -Vehicular times calculated here are thus notably longer than with most -commercial routing engines, which give vehicular travel times only, and ignore -the critical need to park a vehicle and walk to a destination. - -All individual variables also enable comparison in terms of "Variation", rather -than "Average" values. Comparing these reveals that Berlin generally has -markedly lower variation than Paris. A comparison of these statistics on the -"Maps" page reveals that this is largely because Paris is simply much larger -than Berlin, and the ranges of both absolute and relative transport times are -correspondingly greater. The fact that relative transport in Paris is still -better on average than in Berlin is thus even more impressive considering this -stark difference in scale. - -Travelling in Paris requires notably greater numbers of transfers to travel -equivalent distances than Berlin. The values in the "Number of Transfers" layer -are for journeys of 10km total distance (including walking or cycling distances -at either end). Travelling in Paris requires > 50% more transfers than journeys -in Berlin. - -The fourth transport variable, "Interval", measures the time to wait (in -minutes) until the next equivalent service. Intervals in Paris are slightly -under 5 minutes, whereas values in Berlin are just under 7 minutes. - -Finally, the "Compound Transport" variable simply multiplies absolute travel -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 - -- "School Distance": Paris has notably shorter distances from each point in the - city to the nearest school than does Berlin. -- "Bicycle Index": Paris has very notably better bicycle infrastructure than - Berlin. This index is simply one minus the average portion of all bicycle - journeys out to 5km from each point which may be taken on dedicated bicycle - infrastructure. Around one quarter of all bicycle journeys in Paris may be - taken along dedicated bicycle ways, compared to less than one fifth in - Berlin. Moreover, comparing the maps for this variable reveal that the - bicycle infrastructure in Berlin generally improves with distance away from - the city centre, whereas Paris has the best bicycle infrastructure - concentrated towards the centre of the city. -- "Nature Index": Access to natural spaces in the two cities is effectively the - opposite of the bicycle index. Paris provides relatively little - access to natural spaces for anybody not close to one of the two huge parks - in the city, whereas Berlin provides an abundance of generally smaller - natural spaces dispersed throughout the city. Note that natural space access - includes walks alongside water bodies. Both cities include dominant rivers, - yet Berlin also provides greater pedestrian access to the banks of its rivers - and canals. Comparison of this layer on the maps reveals the comparably - greater access in Berlin to walking paths alongside canals and rivers, - whereas most of the Seine in Paris is effectively inaccessible to - pedestrians. -- "Parking": Finally, both Paris and Berlin offer relatively little opportunity - to park private automobiles compared with the other UA cities, with Berlin - notably less than Paris. - -## 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 -assessed in standardised ways, so they may be directly compared between cities. -Moreover, the scales shown in the "Stats" page may also be directly compared. -Values of one or greater indicate very strong relationships, whereas values -less than 0.1 or so indicate weak relationships, and values less than around -0.01 should generally be interpret to indicate no relationship. Pairs of -variables with very weak or negligible strengths of relationship are generally -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 - -This sub-section only considers transport times, both in absolute and relative -sense. The other transport variables, of intervals and numbers of transfers, -generally follow similar patterns and are not explicitly considered here. -Relative transport times are only very weakly related to most other variables. -In contrast, absolute transport times are strongly related to most other -variables. - -Relative transport times are negligibly associated with population densities, -while absolute times are particularly strongly and negatively correlated. These -negative relationships indicate that faster transport is associated with higher -population densities, more so in Berlin than Paris. - -Slightly weaker relationships are manifest between absolute travel times and -distances to nearest schools. Relationships in both Berlin and Paris are -positive, indicating that fast public transport is positively associated with -shorter distances to schools, with the relationship about twice as strong in -Berlin as in Paris. - -Travel times are very strongly, and positively, correlated with bicycle -infrastructure, indicating faster travel times in regions with better bicycle -infrastructure. This relationship is much stronger in Paris than in Berlin, for -reasons easy to discern by looking at the maps of Berlin for these two -variables. Bicycle infrastructure there is much better in the periphery of the -city, whereas transport times exhibit more of a systematic discrepancy between -the east (fast) and west (slow) portions of the city. In Paris, in contrast, -faster transport times and better bicycle infrastructure are both concentrated -more towards the centre of the city. - -Relationships between transport times and the index of accessibility to natural -spaces are also very strong, and negative. This means that faster transport -times are associated with lower accessibility to natural spaces, as might be -generally expected of most high-density cities. The relationship is stronger in -Berlin than Paris, indicating that faster transport times are most strongly -associated with poorer access to natural spaces there than in Paris. - -Finally, absolute transport times are slightly negatively associated with -numbers of automobile parking spaces in Paris, whereas there is no relationship -in Berlin. This negative relationship indicates that regions with faster public -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 - -Shorter school distances are positively associated with the bicycle index in -Paris, indicating a positive association between good bicycle infrastructure -and short distances to schools. Berlin manifests no such relationship, likely -for reasons described above, that bicycle infrastructure in Berlin is generally -more peripheral than in Paris. - -Although much weaker, relationships between schools distances and the index of -accessibility to natural spaces are negative, indicating that locations closer -to schools are further from nature, and more so in Berlin than in Paris. - -Finally, the social variables are more strongly related to all other -non-transport variables in Paris than in Berlin, except for with the index of -bicycle infrastructure. This variable is more strongly, and positively, -correlated with the social indicator in Berlin than in Paris, where the -relationship is negative. The positive relationship in Berlin indicates that -the provision of bicycle infrastructure is positively associated with social -advantage, an effect again readily seen in examining the map of Berlin. In -contrast, Paris is more effective in providing bicycle infrastructure in areas -of relative social disadvantage. - -Paris also seems to be more effective in educational provision in areas of -social disadvantage, with the strong negative correlation indicating that -socially disadvantaged Parisians generally have to travel shorter distances to -schools. Although this relationship is also negative in Berlin, it is much -weaker. - -In contrast, Paris's very strong and positive relationship between social -advantage and access to natural spaces indicates the relatively far greater -difficulty experienced by less socially advantaged Parisians in accessing -natural spaces compared with equivalent inhabitants of Berlin. - -Finally, Paris manifests a very strong and negative association between social -advantage and numbers of automobile parking spaces, indicating that low social -disadvantage is strongly associated with high numbers of automobile parking -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 - -### Lessons for Berlin - -Paris's transport system is considerably faster and more frequent. -Nevertheless, it also involves greater numbers of transfers, suggesting that -any attempt to improve the system in Berlin should take care to avoid -inadvertently increasing numbers of transfers. - -Berlin's average relative speed is also notably higher than Paris's, and at -1.09 likely too high to effectively discourage large numbers of people from -opting to travel via private automobile. Examination of the map of relative -travel times clearly reveals the effect of the connected ring out autobahns -encircling the city. While reducing speeds on these carriageways may not be -feasible, a uniform 30km/hour limit as introduced in Paris may nevertheless -significantly reduce this ratio, and further incentivise many more people to -opt for public transport rather than private automobile. - -Although Paris is a far larger city, its average population density is -nevertheless very similar to Berlin's. It is then even more striking that Paris -offers considerably shorter average distances to schools than Berlin. School -distances in Berlin are also only weakly correlated with social conditions, -whereas average distances to schools in Paris are shorter in less socially -advantaged areas. Both of these factors indicate a need in Berlin for more -provision of local schooling in general, and particularly in socially -disadvantaged regions, if it is to match the educational opportunities provided -in Paris. - -Paris's bicycle infrastructure is considerably better than Berlin's, and -perhaps even more importantly, becomes better towards the inner city regions. -In contrast, Berlin really only offers good bicycle infrastructure in the -relatively peripheral, and more affluent, outer regions. Berlin really needs to -proactively focus on improving bicycle infrastructure in the inner city -regions. - -Berlin is fortunately greatly enhanced by an abundance of natural space, -including access to the city's rivers and canals, and access to these natural -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 - -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. -This difference is especially notable given that Paris is much larger than -Berlin. Improvements to Paris's public transport system should focus on -decreasing numbers of transfers. - -Paris's average relative speed is very close to the "magical" value of one, at -which point private automobiles are no faster than multi-modal transport -including walking and cycling. - -Paris has done a great job of providing bicycle infrastructure in the inner -city regions, and notably of proactively enhancing or creating bicycle -infrastructure in regions of social disadvantage. - -Contrasts with Berlin nevertheless emphasise a couple of aspects which Paris -could focus on improving. The most notable of these is the index of -accessibility to natural spaces, and the relationship of this to other -variables. Paris simply has far less natural space than Berlin, and much poorer -general accessibility. Moreover, access to natural spaces is positively -associated with social advantage, so that it is relatively difficult for -socially disadvantaged Parisians to access natural spaces. diff --git a/src/intro.md b/src/intro.md deleted file mode 100644 index 92abd29..0000000 --- a/src/intro.md +++ /dev/null @@ -1,88 +0,0 @@ -# Introduction - -This is the documentation for [Urban Analyst (UA)](https://urbananalyst.city). -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) -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) -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. - -Finally, UA enables cities to "learn" from one another, by visualising how the -properties of any chosen city can best be transformed to become more like the -properties of any other chosen city. Paris, for example, has better bicycle -infrastructure than Berlin, and the UA transformation algorithm can calculate -how Berlin can most easily transform its bicycle infrastructure to become more -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? - -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. - -# 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 -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 - -One way to appreciate the scale of these calculations is through comparison -with commercial alternatives. One service, *traveltime.com*, charges a flat -subscription fee of €540 per month for a maximum of 60 requests per minute. -That rate would permit 31.5 million queries per year. The city of Hamburg, for -example, would then take almost 2,000 years to calculate, and would cost -€12 million. Google also offers a commercial routing service, limited to a -maximum of 500,000 queries per month, for a total price of US$2,000. At that -rate, the analyses for Hamburg would cost US$224 million. - -The results presented in Urban Analyst are simply not possible using commercial -tools, or indeed any other open source tools. These analyses truly are uniquely -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? - -Not directly, but feel free to open a [GitHub -issue](https://github.com/mpadge/UrbanAnalyst/issues) to start a discussion -about requesting full data sources. - -# 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. - -Contributions to, or questions regarding, this documentation, are welcome at -[this GitHub repository](https://githu.com/UrbanAnalyst/docs). diff --git a/src/overview.md b/src/overview.md deleted file mode 100644 index 014a6ae..0000000 --- a/src/overview.md +++ /dev/null @@ -1,163 +0,0 @@ -# Overview - -This chapter provides an overview of the four main pages of the [Urban Analyst -platform](https://urbananalyst.city): - -- The [summarise page](https://urbananalyst.city/summarise) provides summary - overviews for each city of key statistical properties and relationships with - other cities; -- The [compare page](https://urbananalyst.city/compare) compares aggregate - statistics for all cities; -- The [map page](https://urbananalyst.city/maps) shows interactive maps for - each city; -- The [transform page](https://urbananalyst.city/transform) 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 -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, -or can be manually opened by clicking on the "Help" button on any of the main -pages. - ----- - -## Summarise - -The [Summarise page](https://urbananalyst.city/summarise) 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 [Summarise page](https://urbananalyst.city/summarise) 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). - - ----- - -## Compare - -The [Compare page](https://urbananalyst.city/compare) 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 -values of the chosen layer for all cities. As in all UA pages, lower values are -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 - -The control panel of the [compare page](https://urbananalyst.city/compare) -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 -strength of relationship between access to natural spaces and social -disadvantage. Both of these variables are measured such that low values are -better than high values. A positive relationship between the two would then -mean that lower social disadvantage is coupled with better access to natural -spaces, while high social disadvantage is coupled with worse access to natural -spaces. Conversely, a negative relationship would indicate that higher social -disadvantage was coupled with better access to natural resources. Or, in the -words brought up by clicking the "Explain Layer" button, "Low values indicate -that good access to natural spaces is coupled with disadvantageous social -conditions." - ----- - -## Map - -The [Map page](https://urbananalyst.city/map) 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). - -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. - -As in all UA measurements, lower values of all variables are generally better -than higher values. Colour scales on all maps thus generally display lower -values in brighter, yellow colours, while higher values are displayed in -darker, blue or violet colours. The control panel includes an "Explain Layer" -button which opens a text panel explaining details of the chosen variable. - ----- - -## Transform - -The [Transform page](https://urbananalyst.city/transform) 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 -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 -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) -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 -distribution for the chosen city is then transformed by changing each point by -the smallest amount possible so that they reflect the distribution in the -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). - -### Extra Layers - -The [Transform page](https://urbananalyst.city/transform) 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 -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 -selecting those two layers.) The *Extra Layers* panel can be used in this case -to examine not just how Paris might best transform its access to nature to look -more like Berlin, but also how it might also improve its relationship between -access to nature and social disadvantage. - -By default, values of *Extra Layers* are automatically selected as those which -have better relationships in the chosen target city. These default values will -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 - -Finally, the [Transform page](https://urbananalyst.city/transform) 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: - -1. *Original* to show original values, prior to transformation; -2. *Transformed* to show the actual transformed values; -3. *Absolute* to show the absolute value by which each are in the city would - have to be transformed to match the distribution in the target city; and -4. *Relative*, which displays the absolute transformation values relative to - the original, untransformed values. 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/src/variables.md deleted file mode 100644 index 8ba40e5..0000000 --- a/src/variables.md +++ /dev/null @@ -1,241 +0,0 @@ -# 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 -population density which are nevertheless straightforward to interpret.) For -example, unemployment or transport times are both better when values are lower. -Indices of bicycle infrastructure and access to natural spaces are also -transformed so that lower values indicate better or more of either. In these -cases, the transformations are simply one minus the respective proportions of -journeys out to a fixed distance travelled along bicycle infrastructure, or -through or alongside natural spaces. Values of 0 then reflect 100% of all -journeys spent on bicycle infrastructure or in natural spaces, while values of -1 would represent complete absence of either bicycle infrastructure or natural -spaces. - -Variables are measured for every way, path, or street intersection within each -city. Values for the maps are aggregated within polygons defined by the -*Socio-demographic variables* described in the following sub-section, while -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). - -## 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 -datasets provided by the cities as a series of geographic areas, defined as -polygonal shapes, and some corresponding measure of socio-demographic -disadvantage. The cities themselves decide the resolution and extent of these -polygonal data. These polygons then define the extent and shape of cities -analysed in Urban Analyst, and the individual polygons into which the map data -are aggregated. - -Values of these socio-demographic variables are the only aspect that differs -between different cities. One of the simplest versions is unemployment rate, -generally measured either as a percentage (0-100), or a proportion (0-1). The -UA platform selects the most representative measure of general social -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 - -Urban Analyst provides highly detailed statistics on transport systems. Many of -these are derived from estimates of times required to travel fixed distances of -10km. This value is chosen to capture the general efficiency of public -transport systems. Shorter distances do not sufficiently capture the influence -of transport modes such as express or long-distance train services, while -longer distances unfairly penalise smaller cities in which most journeys are -only of shorter distances. - -Values at this distance of 10km are obtained by following these three steps, -taking the example statistic of travel times: - -1. Calculate total travel times from all street intersections to all other - street intersections within a city. -2. Calculate a straight line of "best fit" (a "least squares regression" line) - which describes how travel times vary with distance. -3. Use that line to obtain the "average" value of travel time at the distance - of 10km. - -Values shown in the maps are aggregated within each polygon of a chosen city, -while values shown in the statistics page are aggregated over entire cities. - -The remainder of this section describes the five travel variables: - -- Absolute travel times -- Relative travel times -- Numbers of transfers -- Intervals between consecutive services -- Compound travel statistic - -### Absolute and Relative Travel Times - -Urban Analyst enables comparisons of travel times between two primary modes of -transport: - -- *Private Automobile.* Travel times with private automobile are used as a - 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 - 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 - to a desired destination. These parking times are crucial, as direct travel - times to many inner-city destinations do not provide realistic estimates of - actual journey times to locations where it may be impossible to actually park - a private automobile. - -- *Multi-Modal Transport.* UA's "multi-modal travel times" represent fastest - possible times taken for journeys from every single point in a city to travel - 10km using any combination of transport modes excluding private automobile. - The primary modes considered are walking, bicycling, and all available modes - of public transport within each city. Where it is faster to cycle 10km than - to take public transport (such as from locations with very poor public - transport connections, or on the top of long hills where downhill cycling may - actually be faster), these times will represent the single mode of cycling - only, but multi-modal times will generally reflect fastest times formed by - combining multiple modes of transport. - -Travel times measured these two ways are then combined to generate the -following two primary travel time statistics: - -- *Absolute travel times* as the multi-modal travel times; that is, using any - mode except private automobile. - -- *Relative travel times* as the ratios of absolute travel times compared with - equivalent travel times with private automobile. Relative travel times of - less than one indicate that multi-modal transport is faster than equivalent - transport with private automobile, while values greater than one indicate - that private automobile transport is faster. - -### 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 -measured for every point of origin with a city, with final values again derived -by following the steps described above to obtain average values of each for all -trips of 10km distance. Numbers of transfers are thus the average number -required for all journeys of 10km, while intervals are the required waiting -times for the next equivalent journey out to that distance. - -- *Intervals to Next Service* are measured in minutes. For each point of origin - in a city, this statistic measures the waiting time necessary before - departing to each destination within a city on the service after the one - corresponding to the fastest journey. This delayed service may not be fast as - the original, or it may even be faster in some cases, as the UA algorithms - also prioritise connections with the fewest possible transfers. It can happen - that subsequent services are actually faster, yet involve additional - transfers not required in the originally identified "fastest" service. - -- *Numbers of Transfers* measure the number of transfers necessary for a - *minimal-transfer* journey out to a distance of 10km. These - *minimal-transfer* journeys are selected to allow for journeys slightly - slower than absolute fastest journeys (generally by up to 5 minutes) if they - involve fewer transfers. - -### 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. -Travel times are then directly multiplied by (a logarithmically-transformed -version of) intervals between services to generate a "*compound travel -statistic*". Low values of this statistic only arise in locations which have -fast travel times and short intervals between services. Low values may -accordingly always be interpreted as indicating overall good transport -services. In contrast, high values may arise through various combinations of -variables, from extremely high values of one single variable, to less extreme -combinations of the two variables. It is thus generally not possible to -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 values are taken directly from the [European Union *Global -Human Settlement Layer*](https://ghsl.jrc.ec.europa.eu/index.php) data, -aggregated into polygons for maps, or across entire cities for statistics. - -## 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, -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 - -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 -kilometres that travel along dedicated bicycle infrastructure. To conform with -all other UA variables, the index is one minus this proportion, so that low -values reflect high proportions of bicycle infrastructure. Values of zero would -then reflect all journeys taken along dedicated bicycle paths, while values of -one would mean a complete absence of dedicated bicycle infrastructure. - -Travel is calculated using a bicycle-specific algorithm that only extends along -ways unsuitable for bicycle travel where no alternatives exist. The weighting -scheme used adds total distances for all portions of travel along designated -cycleways that are separated from vehicular traffic. Portions of trips -extending along other types of ways are added with "half weightings" so, for -example, one kilometre along these types is equivalent to two kilometres on -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 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 is measured in a similar way to the bicycle -infrastructure variable, except it quantifies proportions of walking distances -out to maximal distances of two kilometres that traverse natural spaces. This -provides a more realistic measure of natural space than simple aggregations of -areas, because it measures the ability of people to directly walk from every -point in a city through or alongside nearby natural spaces. - -Moreover, aggregate metrics do not generally capture the ability of people to -actually access natural spaces. A park may, for example, have restricted or -even private access. This would count as a natural space in a simply aggregate -metric, yet not in UA because access restrictions are taken into account in the -routing algorithms. - -The algorithm also measures lengths of ways walked adjacent to water - -so-called "blue space", providing a comprehensive metric of the actual ability -to access natural spaces from every point in a city. A natural space index of -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 - -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 -by adding all nearby parking spaces with a weighting scheme that decreases -exponentially with distance, so that nearby parking spaces count more than -parking spaces that are farther away. Building volumes are also aggregated -using an identical weighting scheme. The parking index at each point is then -the ratio of the sum of distance-weighted numbers of parking spaces to the sum -of distance-weighted total building volumes. - -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 - -For USA cities only, additional statistics are provided for average housing -value per room, and average rental per room, both in US dollars. From 4e83c2b3bf59fb8e4a6a7d59fb9fb463527bf090 Mon Sep 17 00:00:00 2001 From: mpadge Date: Thu, 12 Sep 2024 12:25:47 +0200 Subject: [PATCH 15/20] mv all rst docs to root for #5 --- docs/Makefile => Makefile | 0 docs/conf.py => conf.py | 0 docs/data.rst => data.rst | 0 docs/example.rst => example.rst | 0 docs/index.rst => index.rst | 0 docs/intro.rst => intro.rst | 0 docs/make.bat => make.bat | 0 docs/overview.rst => overview.rst | 0 docs/requirements.txt => requirements.txt | 0 docs/software.rst => software.rst | 0 docs/variables.rst => variables.rst | 0 11 files changed, 0 insertions(+), 0 deletions(-) rename docs/Makefile => Makefile (100%) rename docs/conf.py => conf.py (100%) rename docs/data.rst => data.rst (100%) rename docs/example.rst => example.rst (100%) rename docs/index.rst => index.rst (100%) rename docs/intro.rst => intro.rst (100%) rename docs/make.bat => make.bat (100%) rename docs/overview.rst => overview.rst (100%) rename docs/requirements.txt => requirements.txt (100%) rename docs/software.rst => software.rst (100%) rename docs/variables.rst => variables.rst (100%) diff --git a/docs/Makefile b/Makefile similarity index 100% rename from docs/Makefile rename to Makefile diff --git a/docs/conf.py b/conf.py similarity index 100% rename from docs/conf.py rename to conf.py diff --git a/docs/data.rst b/data.rst similarity index 100% rename from docs/data.rst rename to data.rst diff --git a/docs/example.rst b/example.rst similarity index 100% rename from docs/example.rst rename to example.rst diff --git a/docs/index.rst b/index.rst similarity index 100% rename from docs/index.rst rename to index.rst diff --git a/docs/intro.rst b/intro.rst similarity index 100% rename from docs/intro.rst rename to intro.rst diff --git a/docs/make.bat b/make.bat similarity index 100% rename from docs/make.bat rename to make.bat diff --git a/docs/overview.rst b/overview.rst similarity index 100% rename from docs/overview.rst rename to overview.rst diff --git a/docs/requirements.txt b/requirements.txt similarity index 100% rename from docs/requirements.txt rename to requirements.txt diff --git a/docs/software.rst b/software.rst similarity index 100% rename from docs/software.rst rename to software.rst diff --git a/docs/variables.rst b/variables.rst similarity index 100% rename from docs/variables.rst rename to variables.rst From 01fefb0a43cec127186b545d149ce9177f0309fe Mon Sep 17 00:00:00 2001 From: mpadge Date: Thu, 12 Sep 2024 12:28:01 +0200 Subject: [PATCH 16/20] fix cross-links to variables chapter --- intro.rst | 10 +++++----- overview.rst | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/intro.rst b/intro.rst index fb5ea83..f1857b6 100644 --- a/intro.rst +++ b/intro.rst @@ -27,10 +27,10 @@ the whole city to have infrastructure equivalent to Paris. How does it work? ***************** -Urban Analyst present a variety of :ref:`variables<4. 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 +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. @@ -111,7 +111,7 @@ This documentation includes the following five chapters: 1. This introduction 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. Variables>`: Providing descriptions of all variables included in 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. diff --git a/overview.rst b/overview.rst index ebb11dd..7f2fbf6 100644 --- a/overview.rst +++ b/overview.rst @@ -92,7 +92,7 @@ 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 -:ref:`subsequent chapter<4. Variables>`. +: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. From ba5e9e4e4c63b59ba4b718c8b6f979f088e6bae9 Mon Sep 17 00:00:00 2001 From: mpadge Date: Thu, 12 Sep 2024 12:28:10 +0200 Subject: [PATCH 17/20] fix title underline --- variables.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/variables.rst b/variables.rst index 1e11433..bfa5e11 100644 --- a/variables.rst +++ b/variables.rst @@ -1,5 +1,5 @@ 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 From e5d06f48a00fdb792a350e4168b979178f072a84 Mon Sep 17 00:00:00 2001 From: mpadge Date: Thu, 12 Sep 2024 12:32:44 +0200 Subject: [PATCH 18/20] exlude README in conf.py --- conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/conf.py b/conf.py index d9c868a..1082ef8 100644 --- a/conf.py +++ b/conf.py @@ -57,7 +57,7 @@ # 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'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README.md', 'aaa*'] # -- Options for HTML output ------------------------------------------------- From 33700c5259c08e2c733a3fd6272561281b3ab42b Mon Sep 17 00:00:00 2001 From: mpadge Date: Thu, 12 Sep 2024 12:36:47 +0200 Subject: [PATCH 19/20] update workflow to make and deploy sphinx instead of mdbook for #5 --- .github/workflows/deploy.yaml | 55 ++++++++++++++++++++--------------- 1 file changed, 31 insertions(+), 24 deletions(-) diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml index 4566d0f..9552e3a 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_reqest: + 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 From f6cf9b9735e3e09c87a5fb43e4aa345c22c91c03 Mon Sep 17 00:00:00 2001 From: mpadge Date: Thu, 12 Sep 2024 12:38:12 +0200 Subject: [PATCH 20/20] fix typo: 'request' --- .github/workflows/deploy.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml index 9552e3a..a849870 100644 --- a/.github/workflows/deploy.yaml +++ b/.github/workflows/deploy.yaml @@ -4,7 +4,7 @@ on: push: branches: - main - pull_reqest: + pull_request: branches: - main