assignment.set: Assignment Sets: Managing multi-class highway assignment
In travelr: Functions for Travel Demand Modeling

Description Usage Arguments Details Value Author(s) See Also

Keep network variants and demand sets for use in multi-class highway assignment.

new.assignment.set(network,classes,cost.volume.type=c("vector","matrix"),cost.function=NULL,objective.function=NULL,obj.tol=1e-4,...)
hwy.update.demand(aset,name,demand)
hwy.update.penalties(aset,penalties)
hwy.update.class(aset,name,aclass)
## S3 method for class 'highway.assignment.set'
add.assignment.class(classes,aclass)

`network`	The base highway network on which this assignment set will be loaded.
`classes`	A list of assignment classes, or for the generic `hwy.update.class`, either a list of assignment classes or an assignment set
`cost.function`	A function generating costs from volumes for the assignment set (optional if each assignment class has its own); see details
`cost.volume.type`	Indicates how the loaded volume should be passed to the cost function
`objective.function`	An objective function for equilibrium assignment; see details
`obj.tol`	Required precision for objective.function (to support, for example, adaptive quadrature for integrating a cost.function)
`aset`	An assignment set
`name`	A name (character string) for the assignment class.
`demand`	A demand matrix for the named assignment class
`penalties`	A numeric vector of revised penalty values
`aclass`	An assignment class, usually created by `make.assignment.class`
`...`	Additional parameters to be passed to the `cost.function`

The assignment.set structure is the essential parameter for any of the highway.assign algorithms.

The assignment set is constructed from a highway.net, and a list of assignment.class elements (the classes parameter). The network establishes the set of possible links, the set of possible locations for turn penalties and prohibitions, and the initial turn penalty values. The classes establish an initial demand, a subset of links across which that class can be assigned, and a subset of penalties that are to be applied for the class.

The cost.function parameter provides a cost function (see cost.functions, and build.BPR.cost.function for further information). If no cost.function is supplied, each link is given a unit cost, so the shortest path in that case is always the one with the fewest links. That is only rarely useful.

A cost function providing a fixed link parameter can be provided, for example, by defining a simple function that simply returns a link attribute:

1	cost.function <- with(network$Links,function(...) Distance

where Distance is a column in the table of link attributes from which the network was constructed (and which might, in this example, correspond to the link length, and thus yield paths representing the shortest distance between each origin and destination).

The objective.function parameter provides an objective function for equilibrium assignment. See objective.functions for details. A default function will be built (using the cost.function and the cost.integrator) if an objective.function is not supplied. If possible, writing an explicit objective function will greatly improve the speed of the assignment algorithms.

The parameter cost.volume.type controls how volumes are passed to the cost and objective functions: “vector” produces a vector with the total volume on each link, while “matrix” passes the entire cost matrix (actually, a data.frame with one numeric column per assignment class, and one row per network link). The cost.function should be written accordingly.

The obj.tol parameter controls the convergence tolerance passed to the cost.integrator function when building a default objective function. It may safely be ignored.

The resulting assignment set (which has a class of highway.assignment.set) has these elements:

network: The base highway network for all the assignment classes
penalties: The vector of initial turn penalties and turn prohibitions from the base network
cost.function: A constructed cost function that calls the user's cost function after converting the volumes to the cost.volume.type
classes: The assignment classes for this set
ff.vol: Free-flow volume: a set of zeroes with one column per assignment class, and one row per network link; see free.flow
ff.cost: The set of routing costs that result from applying cost.function to ff.vol
objective.function: The supplied or constructed equilibrium objective function

hwy.update.class can replace (or add) an entire assignment class to an assignment set. The assignment class should have been built by make.assignment.class

hwy.update.demand returns the assignment set after the named class has had its demand matrix updated to the demand parameter value.

hwy.update.penalties returns the assignment set with updated penalty values; this function is useful for dynamically updating penalty values during an assignment algorithm.

add.assignment.class, when applied to a assignment.set will add an additional assignment class to the set of assignment classes already defined. It the named class already exists, its values will be updated.

The various hwy.update functions can be replaced with suitable recursive list indexing to find and then add or replace the target value, and the user may wish to do that if speed is of utmost concern. Otherwise, these functions provide an additional level of error-checking that may be useful when first developing a model or algorithm.

new.assignment.set returns an assignment.set structure describing demand and network characteristics for each class of user in highway assignment.

hwy.update.class, hwy.update.demand and hwy.update.penalties return the updated assignment set

add.assignment.class returns the updated assignment set

Jeremy Raw

highway.assign

cost.functions for a discussion of cost functions, and build.BPR.cost.function for a helper function.

objective.functions for a discussion of objective functions, build.general.objective.function, and build.BPR.objective.function

travelr documentation built on May 2, 2019, 5:17 p.m.