RoadCongestion (r5 4.6.1-SNAPSHOT API)

java.lang.Object
- com.conveyal.r5.analyst.scenario.Modification
- - com.conveyal.r5.analyst.scenario.RoadCongestion

All Implemented Interfaces:

Serializable
```
public class RoadCongestion
extends Modification
```
To simulate traffic congestion, apply a slow-down (or speed-up) factor to roads, according to attributes of polygon features. This replaces the array of edge speeds in a scenario copy of the street layer's edge store. Driving is not available as an egress mode, and the updated speed fields don't affect walking or biking, so this modification should not cause distance tables to be rebuilt, though of course routing with the car mode will cause a car linkage to be built. There are several ways to implement the assignment of a slowdown factor to each edge. These approaches will be more or less efficient, depending on the parameters and polygons chosen. We must iterate over either the edges or the polygons, finding which objects in the other category they intersect. Doing this efficiently requires a spatial index on the second category of objects, to avoid nested iteration and possible N^2 complexity. We can reasonably assume that there will always be many less polygons than street edges. But the total quantity of intersection and length calculations will be roughly equal no matter which is the outer loop: the number of times an edge's bounding box overlaps the bounding box of a polygon. So assuming the intersection math is the slow part of the process, the nesting order is not so significant. We already have an efficiently iterable spatial index of all the edges in the street layer, so we could iterate over all polygons, and set the speed on all edges falling inside them. But some edges intersect multiple polygons. We need to see all these polygons at once to decide which polygon wins. Unless we want to store a lot of auxiliary state (e.g. a map from each updated edge to its current polygon object or a priority value per updated edge), we must iterate over the edges instead of the polygons to have all relevant polygons in hand at once. Additional challenges: Which polygon should we select when there are multiple candidates? Even if all polygons are non-overlapping, a road may touch more than one polygon, or may be partially inside one or more polygons and partially outside all polygons. But in normal usage, it's possible for polygons to overlap partially or completely. A smaller polygon may be entirely inside a larger polygon. This will be the case when a center city polygon is drawn on top of a suburban polygon. We cannot use a simple rule that the polygon with the worst congestion should win, because it's entirely possible that small zones of lower congestion will exist or will be modeled within larger zones of lesser congestion. Therefore we give polygons explicit priorities, which must be positive to beat the default. In ties where the edge falls within two or more polygons with the same priority, the one with the longest overlap wins. At first, assigning speeds to all the edges in the Netherlands from 10 polygons took 25 seconds. Changing to calculate intersection lengths only to break ties, assignment takes 13 seconds. With 151000 polygons, setting speeds on all edges in the Netherlands takes 1 minute and 40 seconds. It is reduced to 57 seconds if we only compute edge fragment lengths in cases where it can have an effect of the scaling factor. Created by abyrd on 2019-03-11

See Also:

Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`double`	`defaultScaling` The default value by which to scale when no polygon is found.
`String`	`nameAttribute` The name of the attribute (text) within the polygon layer that contains the polygon names.
`String`	`polygonLayer` The identifier of the polygon layer containing the speed data.
`String`	`priorityAttribute` The name of the attribute (numeric) within the polygon layer that contains the polygon priority.
`String`	`scalingAttribute` The name of the attribute (floating-point) within the polygon layer that contains the speed scaling factor.

Fields inherited from class com.conveyal.r5.analyst.scenario.Modification
activeInVariants, comment, errors, warnings

Constructor Summary

Constructors
Constructor and Description

RoadCongestion()

Constructors
Constructor and Description
`RoadCongestion()`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`affectsStreetLayer()` See Scenario::affectsStreetLayer
`boolean`	`affectsTransitLayer()` See Scenario::affectsTransitLayer
`boolean`	`apply(TransportNetwork network)` Apply this single modification to a TransportNetwork.
`int`	`getSortOrder()` This determines the sequence in which modifications will be applied.
`boolean`	`resolve(TransportNetwork network)` Implementations of this function on concrete Modification classes should do three things: 1.

Methods inherited from class com.conveyal.r5.analyst.scenario.Modification
checkIds, findOrCreateStops

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - polygonLayer
```
public String polygonLayer
```
    The identifier of the polygon layer containing the speed data.
  - scalingAttribute
```
public String scalingAttribute
```
    The name of the attribute (floating-point) within the polygon layer that contains the speed scaling factor.
  - priorityAttribute
```
public String priorityAttribute
```
    The name of the attribute (numeric) within the polygon layer that contains the polygon priority.
  - nameAttribute
```
public String nameAttribute
```
    The name of the attribute (text) within the polygon layer that contains the polygon names. This is only used for logging.
  - defaultScaling
```
public double defaultScaling
```
    The default value by which to scale when no polygon is found.
- Constructor Detail
  - RoadCongestion
```
public RoadCongestion()
```
- Method Detail
  - resolve
```
public boolean resolve(TransportNetwork network)
```
    Description copied from class: Modification
    
    Implementations of this function on concrete Modification classes should do three things: 1. Infer the canonical internal representation of any parameters e.g. convert frequencies to periods in seconds. 2. Resolve any GTFS IDs contained in this Modification to integer IDs in the given TransportNetwork. 3. Sanity check the resulting values to allow early failure, avoiding missing identifiers, infinite loops etc. A particular Modification instance should only be used by one thread on a single TransportNetwork, so it is fine to store the canonical parameter representations and resolved IDs in instance fields of Modification subclasses. We return a boolean rather than throwing an exception to provide cleaner program flow. This also allows accumulation of error messages, rather than reporting only the first error encountered. Messages describing the errors encountered should be added to the list of Strings in the Modification field "errors". The resolve step could conceivably be folded into the actual application of the modification to the network, but by resolving all the modifications up front before applying any, we are able to accumulate multiple errors and return them to the user all at once, simplifying debugging.
    
    Overrides:
    
    resolve in class Modification
    
    Returns:
    
    true if an out of range, missing, or otherwise problematic parameter is encountered.
  - apply
```
public boolean apply(TransportNetwork network)
```
    Description copied from class: Modification
    
    Apply this single modification to a TransportNetwork. The TransportNetwork should be pre-cloned by the caller, but may still contain references to collections or other deep objects from the original TransportNetwork. The Modification is responsible for ensuring that no damage is done to the original TransportNetwork by making copies of referenced objects as necessary. TODO arguably this and resolve() don't need to return booleans - all implementations just check whether the errors list is empty, so we could just supply a method that does that. TODO remove the network field, and use the network against which this Modification was resolved.
    
    Specified by:
    
    apply in class Modification
    
    Returns:
    
    true if any errors happened while applying the modification.
  - getSortOrder
```
public int getSortOrder()
```
    Description copied from class: Modification
    
    This determines the sequence in which modifications will be applied. It is used in a standard compare function, so lower numbered modifications will be applied before higher ones. Typical values are 10 through 100.
    
    Specified by:
    
    getSortOrder in class Modification
  - affectsStreetLayer
```
public boolean affectsStreetLayer()
```
    Description copied from class: Modification
    
    See Scenario::affectsStreetLayer
    
    Overrides:
    
    affectsStreetLayer in class Modification
    
    Returns:
    
    true if this modification will result in changes to the StreetLayer of the TransportNetwork.
  - affectsTransitLayer
```
public boolean affectsTransitLayer()
```
    Description copied from class: Modification
    
    See Scenario::affectsTransitLayer
    
    Overrides:
    
    affectsTransitLayer in class Modification
    
    Returns:
    
    true if this modification will result in changes to the TransitLayer of the TransportNetwork.

Class RoadCongestion

Field Summary

Fields inherited from class com.conveyal.r5.analyst.scenario.Modification

Constructor Summary

Method Summary

Methods inherited from class com.conveyal.r5.analyst.scenario.Modification

Methods inherited from class java.lang.Object

Field Detail

polygonLayer

scalingAttribute

priorityAttribute

nameAttribute

defaultScaling

Constructor Detail

RoadCongestion

Method Detail

resolve

apply

getSortOrder

affectsStreetLayer

affectsTransitLayer