Merge branch 'main' of https://github.com/UrbanAnalyst/docs

src/SUMMARY.md

@@ -3,6 +3,6 @@
 - [Introduction](./intro.md)
 - [Overview](./overview.md)
 - [Example](./example.md)
-- [UTA Variables](./variables.md)
+- [UA Variables](./variables.md)
 - [Data Sources](./data.md)
 - [Software and Algorithms](./software.md)

src/data.md

@@ -25,3 +25,6 @@ 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.

src/example.md

@@ -3,19 +3,19 @@
 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 UTA statistics are always better. Values
+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 UTA variables, by population density converts them to values as
+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 UTA cities. The "Maps" page can then be used to examine the
+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.
 
@@ -26,7 +26,9 @@ 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.
+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.
 
@@ -46,6 +48,7 @@ city (each measured on its own distinct scale).
 | 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
@@ -125,7 +128,7 @@ service in Paris compared with Berlin.
   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 UTA cities, with Berlin
+  to park private automobiles compared with the other UA cities, with Berlin
   notably less than Paris.
 
 ## Relationships between variables

src/intro.md

@@ -1,19 +1,18 @@
 # Introduction
 
 This is the documentation for [Urban Analyst (UA)](https://urbananalyst.city).
-Urban Analyst provides open source analyses of the structure and function of
-cities across the world. Each city can be viewed as an [interactive
-map](https://urbananalyst.city/maps) displaying a range of 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.
+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 relationships between any pair of variables, such
-as transport and socio-demographic disadvantage, to be compared across all UA
-cities.
+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
@@ -26,17 +25,17 @@ the whole city to have infrastructure equivalent to Paris.
 
 # How does it work?
 
-Urban Analyst present a variety of [statistics](./variables.md) for each city
-analysed, as well as relationships between these statistics. Values for each
-statistic are derived at every street intersection in each city. These values
+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 across entire cities for the values
-shown in the ["Compare"](https://urbananalyst.city/compare) and
-["Transform"](https://urbananalyst.city/transform) pages. 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.
+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?
 
@@ -81,9 +80,9 @@ 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. ["UTA Variables"](./variables.md): Providing descriptions of all variables included in 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 UTA 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).

src/overview.md

@@ -1,24 +1,25 @@
 # Overview
 
-This chapter provides an overview of the three main pages of the [Urban Analyst
+This chapter provides an overview of the four main pages of the [Urban Analyst
 platform](https://urbananalyst.city):
 
-- [Summarise](https://urbananalyst.city/summarise) providing summary overviews
-  for each city of key statistical properties and relationships with other
-  cities;
-- [Compare](https://urbananalyst.city/compare) comparing aggregate statistics
-  for all cities;
-- [Map](https://urbananalyst.city/maps) showing interactive maps for each
-  city;
-- [Transform](https://urbananalyst.city/transform) for transforming any chosen
-  city to become more like other cities.
-
-The [Summarise page](https://urbananalyst.city/summarise) is the best place to
-start. 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.
+- 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.
 
 ----
 
@@ -50,13 +51,14 @@ page](https://urbananalyst.city/transform).
 
 ## Compare
 
-The [Compare page](https://urbananalyst.city/compare) is the first and main
-page of Urban Analyst, enabling the properties of all UA cities to be compared.
-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.
+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
 
@@ -87,6 +89,9 @@ 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
@@ -139,10 +144,10 @@ 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 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.
+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
 

src/variables.md

@@ -7,7 +7,7 @@ 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 fixed distance travelled along bicycle infrastructure, or
+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
@@ -234,3 +234,8 @@ 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.