add separate Travel Time Analysis docs page

moved info out of v1-v2 comparison and accessibility pages

docs/Accessibility.md

@@ -2,24 +2,17 @@
 
 ## Preamble
 
-In this document and in OTP, the term "accessibility" is used with what has become its most common 
+In this document and in OTP, the term "accessibility" is used with its most common 
 meaning: design of products, devices, services, vehicles, or environments to ensure they are usable by 
-people with disabilities. It has other meanings in other contexts (see below).
+people with disabilities. If you have reached this page looking for cumulative opportunities 
+accessibility indicators (access to opportunities metrics) please see the [Analysis](Analysis.md) page.
+
 While accessibility is a complex subject, at this point GTFS and Netex mostly represent it very
 simply as a yes/no possibility of wheelchair use. While OTP developers hope to broaden the
 scope and nuance of accessibility support in OTP, the lack of detailed data from data producers
-currently limits implementation and discussion in this document to this binary 
+currently limits implementation and discussion in this document to this binary
 "wheelchair accessible" definition.
 
-The term "accessibility" has a completely separate, unrelated definition in the fields of
-spatial analysis, urban transportation planning, and associated social sciences, where it refers to
-quantitative indicators of how well-connected a particular location is to people or opportunities.
-OpenTripPlanner has been widely used in research settings for the calculation of such accessibility
-indicators. If this is what you're looking for, see the documentation sections [on isochrones](sandbox/TravelTime.md) and [analysis](Version-Comparison.md/#analysis).
-Although this meaning of the term dates back many decades, it is less well known and has become a
-source of confusion, so the academic and planning communities are gradually shifting to the 
-expression "access to opportunities", often shortened to "access".
-
 ## Unknown data
 
 Many agencies have the same problem: data on wheelchair-accessibility is, if it exists at all,

docs/Analysis.md

@@ -0,0 +1,21 @@
+# Travel Time Analysis
+
+## Background
+
+Since the beginning of the project, many OTP contributors and users have been primarily interested in research, spatial analysis, and urban planning use cases. They have prototyped many ideas within or on top of the OTP codebase, including one-to-many searches producing travel time grids, isochrones, and access-to-opportunities indicators (see Terminology Note below). This has historically been a major area of application for OpenTripPlanner and has helped popularize cumulative opportunities metrics in urban planning. For example, the University of Minnesota Accessibility Observatory used OpenTripPlanner for [Access Across America](https://www.cts.umn.edu/programs/ao/aaa). 
+
+Although we consider these use cases quite important, most work of this kind has long since shifted to separate projects focused on urban planning and analytics. As of version 2, OTP has chosen to focus entirely on passenger information rather than analytics.
+
+## Travel Time Analysis in OTP1
+
+Much of the analysis code present in the v1.x legacy branch of OTP is essentially an unmaintained and unsupported early prototype for later projects, specifically [R5](https://github.com/conveyal/r5/) and the [Conveyal Analysis](https://conveyal.com/learn) system built upon it. OTP1 seems to have gained popularity for analysis uses due to the existence of documentation and an active user community, but has significant technical shortcomings. One of these is simply speed: OTP1 can be orders of magnitude slower (and more memory-intensive) than the approaches used in R5. The other is the requirement to search at a single specific time. Travel times and especially wait times on scheduled transit vary greatly depending on when you depart. Accounting for variation over a time window requires repeated independent searches at each possible departure time, which is very inefficient. R5 is highly optimized to capture variations in travel time across time windows and account for uncertainty in waiting times on frequency-based routes.
+
+## Travel Time Analysis in OTP2
+
+OTP2's new transit router is quite similar to R5 (indeed it was directly influenced by R5) and would not face the same technical problems. Nonetheless, we have decided not to port the OTP1 analysis features over to OTP2 since it would broaden the scope of OTP2 away from passenger information and draw the finite amount of available attention and resources away from existing open source analytics tools. If you would like to apply the routing innovations present in OTP2 in analytics situations, we recommend taking a look at projects like R5 or the R and Python language wrappers for it created by the community.
+
+Some analytics features may still be available as optional "sandbox" features in OTP2 (such as [Travel Time](sandbox/TravelTime.md)), but these do not work in the same way as the features you may have used or read about in OTP1. They are unmaintained and unsupported, and may be removed in the near future.
+
+## Terminology Note
+
+In OpenTripPlanner, we usually use the term "accessibility" with its most common meaning: design of products, devices, services, vehicles, or environments to ensure they are usable by people with disabilities. The term "accessibility" has a completely separate, unrelated definition in the fields of spatial analysis, urban transportation planning, and associated social sciences, where it refers to quantitative indicators of how well-connected a particular location is to people or opportunities. OTP has been widely used in research and planning settings for the calculation of such indicators. Although this meaning of the term dates back many decades, it is less well known and has become a source of confusion, so the academic and planning communities are gradually shifting to the expression "access to opportunities", often shortened to "access".

docs/Version-Comparison.md

@@ -81,31 +81,14 @@ other projects where they are more actively developed.
 
 ### Analysis
 
-Many OpenTripPlanner contributors have been primarily interested in transportation and urban
-planning use cases. We consider these use cases quite important. This has been a major area of
-application for OpenTripPlanner and has helped popularize cumulative opportunities accessibility
-metrics. For example, the University of Minnesota Accessibility Observatory used OpenTripPlanner
-for [Access Across America](http://access.umn.edu/research/america/). Nonetheless, the analysis code
-in OTP1 is essentially an unmaintained and unsupported early prototype for later projects,
-specifically Conveyal's R5 (and the Conveyal Analysis system built upon it). OTP1 seems to have
-gained popularity for analysis uses due to the existence of documentation and an active user
-community, but has significant technical shortcomings. One of these is simply speed: OTP1 can be
-orders of magnitude slower (and more memory-intensive) than the approaches exemplified in R5. The
-other is the requirement to search at a single specific time. Travel times and especially wait times
-on scheduled transit vary greatly depending on when you depart. Accounting for variation over a time
-window requires repeated independent searches at each possible departure time, which is very
-inefficient. R5 is highly optimized to capture variations in travel time across time windows and
-account for uncertainty in waiting times on frequency-based routes.
-
-Due to its similarity to the R5 approach, OTP2's transit router would not have these same problems.
-Nonetheless, we have decided not to port the OTP1 analysis features over to OTP2 since it would
-broaden the focus away from passenger information and draw finite attention away from existing
-projects like R5 and Conveyal Analysis.
-
-Accordingly, we have made an effort to clean up and augment OTP1 analysis documentation for
-researchers who will continue to need it. It should remain possible for people to continue using
-OTP1 if they prefer. If you would instead like to apply the innovations present in OTP2, we
-recommend looking into R5 or Conveyal Analysis.
+From the beginning of the project, many OTP contributors and users have used OTP in research,
+analysis, and planning applications. They have prototyped many ideas within the OTP codebase, 
+including one-to-many searches producing travel time grids, isochrones, and access-to-opportunities
+metrics. While some of these features may still be available as optional "sandbox" features in OTP2, they are unsupported and may be removed in the near future.
+
+Most work of this kind moved over separate projects focused on urban planning and analytics. As of 
+version 2, OTP has chosen to focus entirely on passenger information rather than analytics
+applications. See the [Analysis](Analysis.md) page for more details.
 
 ### Routers API and Hot Reloading
 

docs/sandbox/TravelTime.md

@@ -11,7 +11,11 @@
 ## Documentation
 
 The API produces a snapshot of travel time form a single place to places around it. The results can
-be fetched either as a set of isochrones or a raster map.
+be fetched either as a set of isochrones or a raster map. Please note that as a sandbox feature this
+functionality is UNSUPPORTED and neither maintained nor well-understood by most current OTP 
+developers, and may not be accurate or reliable. Travel time analytics work that began within OTP
+has moved years ago to other projects, where it actively continues. See the 
+[Analysis](../Analysis.md) page for further details.
 
 ### Configuration
 

mkdocs.yml

@@ -84,6 +84,7 @@ nav:
     - "Stop Area Relations": 'StopAreas.md'
     - "Street Graph Pruning": 'IslandPruning.md'
     - Accessibility: 'Accessibility.md'
+    - "Travel Time Analysis": 'Analysis.md'
     - "Logging": "Logging.md"
 - Development:
     - "Developers' Guide": 'Developers-Guide.md'