assignment.functions: Support functions for developing highway assignment...
In travelr: Functions for Travel Demand Modeling

Description Usage Arguments Details Value Author(s) See Also

These functions are used to construct functions and perform operations in support of highway assignment. Generally, they are only of interest to developers implementing new assignment algorithms.

build.convergence.test(control,test=c("min.relative.gap","max.iter","max.elapsed"))
build.equil.stats.function(objective.function,flow=0)
build.lambda.function(aset)
build.lambda.search(lambda.func,opt.tol=.Machine$double.eps^0.25)

weighted.update(weight,base,new)
weighted.update.diff(weight,base,new.diff)
weighted.update.intercept(weight,base,new)

`control`	Assignment algorithm control parameters (a named list)
`test`	Which control parameters indicate convergence criteria (parameter name must start with `.min` or `.max` indicating how to test; the remainder of the name must match a value computed in the equilibrium statistics function; see details)
`objective.function`	The objective function to be minimized during the equilibrium assignment process
`flow`	The sum of all the demand matrices in the assignment set (used to compute average excess cost)
`lambda.func`	The function for which a zero is found to compute the optimum step size in a search direction
`opt.tol`	Convergence tolerance for the root of lambda.func
`aset`	An `assignment.set` with a `cost.function`
`tol`	Convergence tolerance for cost function integration using adaptive quadrature
`weight`	Weight of new values in computing weighted average of base and new
`base`	Base values to be updated
`new.diff`	Difference between base and new values (weight applied only to difference)
`new`	New values to use for updating (weight applied to new values, 1-weight applied to base)

These functions will generally only be of interest to the developers of new highway assignment algorithms.

parse.control extracts a parameter from the control list typically provided to the highway.assign function. Certain parameters have global defaults, which may be overridden by a local default if the default parameter is supplied. The global defaults are as follows:

min.relative.gap	numeric	`1e-4`	Target for relative gap statistic
max.iter	numeric	`100`	Maximum iteration, except 4 for method=“MSA”)
max.elapsed	numeric	`3600`	seconds since the algorithm started
opt.tol	numeric	`.Machine$double.eps^0.5`	tolerance for internal line searches)
verbose	numeric	`1`	Debugging level (higher numbers may generate more output; 0 for silent)
log	logical	`FALSE`	If true, save a `data.frame` with the equilibrium statistics from each iteration

Any parameter for which no default is provided will return NULL when requested.

Arbitrary additional parameters may be defined. The control parameter is just a named list of values, and the function simply looks up the name and returns the corresponding element. It differs from simple list indexing in that it can provide a default value.

Certain of these functions build other functions, tying certain fixed parameters into the function's environment in order to reduce the burden of redundant interpretation and computation during highway assignment.

Perhaps the most obscure are the following:

build.equil.stats.function builds a function that computes performance statistics for an iteration of the equilibrium assignment algorithm. The built function is defined as follows:

1	function(iter, cost, vol, diff, best.lower.bound=as.numeric(NA), extras=list())

iter: The current iteration, numeric
cost: The current cost structure (usually a data.frame; see cost.functions)
vol: The current volume structure (usually a data.frame; see load.paths)
diff: A data.frame containing the difference between the most recent AON volume and the current equilibrium volume
best.lower.bound: The best.lower.bound as of the previous iteration, or as.numeric(NA) if the first iteration
extras: a named list of additional (scalar) values to be placed in the output list

The standard equilibrium statistics function returns a list of computed statistics that can be compared against target values to assess the convergence of an assignment algorithm. The output includes:

iter: Current iteration, supplied as an input parameter
elapsed: Time, in seconds, elapsed since the function was defined
objective: Value of the objective function at the start of this iteration
gap: Value of the “gap” statistic
relative.gap: Value of the “relative gap” statistic
lower.bound: Value of the “lower bound” statistic
best.lower.bound: The greatest of either the best.lower.bound parameter or the newly computed lower.bound
avg.excess.cost: Value of the Average Excess Cost (normalized gap) statistic
extras: Any values passed in through the extras parameter

The build.convergence.test function returns a function that will compare the computed equilibrim statistics to target values supplied either through the control parameter for the highway.assign function, or as a default value through parse.control, or as a global default value.

The general mechanism for constructing a test is to provide names in the test vector that match the names of values in the control list. Those names should begin either with “min.” or “max.” indicating how the equilibrium statistic will be compared. The name without the prefix should correspond to the name of a statistic in the result list from the equilibrium statistics function (including, possibly, a name in the extras list.

The highway.assign source code provides examples of how to apply these functions.

parse.control returns a value for the named highway assignment control parameter

build.convergence.test returns a function that does a convergence test

build.equil.stats.function returns a function that builds a list of assignment statistics for reporting and convergence testing

build.lambda.function returns a function with a zero at a point of interest

build.lambda.search returns a function that finds the zero of a lambda function given upper and lower limits

weighted.update returns a value the same shape as its first argument that is the weighted average of its arguments

weighted.update.diff returns a value the same shape as its first argument that is the first argument plus weight times its second argument

weighted.update.intercept returns an intercept list (with two elements, od and volumes) that is the weighted average of the two intercept lists passed to it

Jeremy Raw

highway.assign, cost.functions

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