highway.net: Highway network management functions
In travelr: Functions for Travel Demand Modeling

Description Usage Arguments Details Value Under Development Author(s) See Also Examples

Functions for constructing a highway network suitable for use in shortest path analysis and highway assignment functions.

as.highway.net(links, numNodes, numZones,
    Penalty = NULL, nodes = NULL, nodeMap = NULL,
    firstThruNode = NULL, Link.fields = NULL, Penalty.fields = NULL)
## S3 method for class 'highway.net'
summary(object,...)
## S3 method for class 'highway.net'
print(x,...)

`links`	A `data.frame` of links in the network; see details
`numNodes`	The number of nodes in the network. The nodes must account for all 'From' and 'To' nodes in the network links
`numZones`	The number of zones (origins and destinations) in the network. The zones must have sequential numbers from `1` to `numZones`
`Penalty`	An optional `data.frame` describing network turn (junction) penalties; see details
`nodes`	An optional node specification, typically a `data.frame`, that can contain useful information such as geographical coordinates
`nodeMap`	Optional element for mapping node numbers; constructed by `map.highway.nodes`; used to consistently renumber nodes in the `links`, `nodes` and `Penalty` `data.frame`
`firstThruNode`	Lowest node number through which paths can be built. Usually either `1` or (the default) `numZones+1`
`Link.fields`	A named character vector describing which columns contain required fields in the links `data.frame`; see details
`Penalty.fields`	A named character vector describing which columns contain required fields in the Penalty `data.frame`
`object`	The `highway.net` object to be summarized
`x`	The `highway.net` object to be printed
`...`	Additional arguments passed to generic methods

The highway network provides a standard format for storing network information. The highway.net object is simply a list that contains data and interpretive guidance that is used later when the network is converted to other formats (particularly to a network.set for use in highway assignment). It provides a mechanism for mapping link and penalty fields to the values necessary for use in highway assignment. The field mapping is used when building a fast internal structure for highway assignment.

The most important elements for highway routing are the links, which must include at a minimum fields From and To indicating node numbers that are connected by the link. At present, the highway network is represented as a directional network with explicit coding. That is, if a two-way connection is present between two nodes, then two links should be coded into the network. Many GIS systems, however, make it much easier to code a network link as a single feature with two sets of attributes (one for each direction). In that case, either the R function reshape, or a simple combination of subsetting and rbind may prove useful to pre-format the network into the necessary format.

The number of rows in the links table defines the number of links in the network

If the network does not already contain suitably formatted fields, the optional Link.fields character vector may be used to identify alternate field names. If Link.fields is provided, the element names must include From and To, and the values should be the actual field names include the Links table.

Also important are the numNodes and numZones parameters, which indicate how many node numbers are present in the network (a value that is required in order to construct a shortest path tree), and numZones indicating the number of terminal nodes in the network, which defines how many paths will be built. These term “Zones” is short for Traffic Analysis Zone or Transportation Analysis Zone, which are also often referred to by acronym as TAZ. In the world of travel demand models, paths through the network are typically only required to span the zones, and the travelr path builder algorithm will stop once it has built paths from each origin zone to every destination zone (so some non-terminal nodes on the network may not have paths built for them from every origin).

Another common convention in transportation networks is to forbid building paths through terminal nodes (zones). The firstThruNode parameter controls that behavior. Any node numbered below firstThruNode is treated as a terminal node and no paths will be built through such nodes. In general application, firstThruNode will be set to 1 if paths are allowed to be built through zones, and otherwise to (numZones + 1) in case the zones are true terminal nodes.

To facilitate the creation of compact data structures, travelr generally requires highway networks to use a compact sequence of nodes. The first numZones nodes (defining an integer sequence 1:numZones) establish the size of demand matrices (which must have numZones rows (origins) and columns (destinations)). Nodes in the integer sequence from numZones + 1 to numNodes are intermediate nodes through which paths may be built. Since many existing travel model networks have discontinuous node numbering sequences (for example, if certain node sequences are associated with particular jurisdictions or facility types), the nodeMap element can contain a map.highway.nodes object to facilitate renumbering the nodes into a suitable sequence.

The Penalty table, if it is provided, is a table of junction movements to which penalty or prohibition values can be attached. A penalty is a positive numeric value, whereas a prohibition is any negative value. Penalty values may be updated during assignment only for the movements identified in this table. Each table row is assigned a unique identifier in field .PenaltyID, and the vector of penalty or prohibition factors is stored in ascending order by .PenaltyID.

The Penalty table itself has three required fields identifying the nodes through which the penalized movements pass, conventionally called From, Thru and To, but these can be mapped to other field names by using the Penalty.fields character vector. If Penalty.fields is provided, the element names must include From, Thru and To, and the values should be the actual field names include the Penalty table. Penalties that include nodes that are not actually in the network itself, or not in a subset, are allowed and are simply ignored.

The nodes element is not used directly, but provides a documented place to store node values that might be useful for junction modeling, or for coordinates that could be used to present the network spatially.

Returns a regularized highway network structure as a list with class highway.net. The elements of this list include the following (some of which optionally may not be present, as noted):

The highway.net was designed to facilitate conversion to the igraph package in order to perform graph analysis of the network (something the author finds useful), and subsequent developments will allow travelr highway networks to interoperate with the spatial classes in sp to facilitate use of open source GIS tools and analysis. Doing either conversion by hand, if one has a table of node coordinates, is straightforward.

Jeremy Raw

sample.networks,tntp to get networks to work with

map.highway.nodes for a tool to renumber network nodes

assignment.set,highway.assign to use a highway network

## Not run: 
links <- read.table("My_Network.net",header=TRUE)
link.names <- c(From="A",To="B")
numZones <- 10
firstThruNode <- 11
allNodes <- unique(c(links[link.names$A],links[link.names$B]))
numNodes <- length(allNodes)
if ( numNodes != max(allNodes) )
    stop("You should use map.highway.nodes to renumber the nodes")
my.network <-
    as.nighway.net(links,numNodes,numZones,
        firstThruNode=firstThruNode, Link.fields=link.names)


## End(Not run)