Package org.opentrafficsim.core.egtf

Class EGTF

java.lang.Object

org.opentrafficsim.core.egtf.EGTF

Direct Known Subclasses:

TypedEGTF

public class EGTF
extends Object

Extended Generalized Treiber-Helbing Filter (van Lint and Hoogendoorn, 2009). This is an extension of the Adaptive Smoothing Method (Treiber and Helbing, 2002). A fast filter for equidistant grids (Schreiter et al., 2010) is available. This fast implementation also supports multiple data sources.

To allow flexible usage the EGTF works with DataSource, DataStream and Quantity.

A DataSource, such as "loop detectors", "floating-car data" or "camera" is mostly an identifier, but can be requested to provide several data streams.

A DataStream is one DataSource supplying one Quantity. For instance "loop detectors" supplying "flow". In a DataStream, supplied by the DataSource, standard deviation of measurements in congestion and free flow are defined. These determine the reliability of the Quantity data from the given DataSource, and thus ultimately the weight of the data in the estimation of the quantity.

A Quantity, such as "flow" or "density" defines what is measured and what is requested as output. The output can be in typed format using a Converter. Default quantities are available under SPEED_SI, FLOW_SI and DENSITY_SI, all under Quantity.

Data can be added using several methods for point data, vector data (multiple independent location-time combinations) and grid data (data in a grid pattern). Data is added for a particular DataStream.

For simple use-cases where a single data source is used, data can be added directly with a Quantity, in which case a default DataSource, and default DataStream for each Quantity is internally used. All data should either be added using Quantity's, or it should all be added using DataSource's. Otherwise relative data reliability is undefined.

Output can be requested from the EGTF using a Kernel, a spatiotemporal pattern determining measurement weights. The Kernel defines an optional maximum spatial and temporal range for measurements to consider, and uses a Shape to determine the weight for a given distance and time from the estimated point. By default this is an exponential function. A Gaussian kernel is also available, while any other shape could be also be implemented.

Parameters from the EGTF are found in the following places:

• EGTF: cCong, cFree, deltaV and vc, defining the overall traffic flow properties.
• Kernel: tMax and xMax, defining the maximum range to consider.
• KernelShape: sigma and tau, determining the decay of weights for further measurements in space and time.
• DataStream: thetaCong and thetaFree, defining the reliability by the standard deviation of measured data in free flow and congestion from a particular data stream.

References:

• van Lint, J. W. C. and Hoogendoorn, S. P. (2009). A robust and efficient method for fusing heterogeneous data from traffic sensors on freeways. Computer Aided Civil and Infrastructure Engineering, accepted for publication.
• Schreiter, T., van Lint, J. W. C., Treiber, M. and Hoogendoorn, S. P. (2010). Two fast implementations of the Adaptive Smoothing Method used in highway traffic state estimation. 13th International IEEE Conference on Intelligent Transportation Systems, 19-22 Sept. 2010, Funchal, Portugal.
• Treiber, M. and Helbing, D. (2002). Reconstructing the spatio-temporal traffic dynamics from stationary detector data. Cooper@tive Tr@nsport@tion Dyn@mics, 1:3.1–3.24.

Copyright (c) 2013-2022 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
BSD-style license. See OpenTrafficSim License.

Version:

$Revision$, $LastChangedDate$, by $Author$, initial version 3 okt. 2018

Author:

Wouter Schakel

Constructor Summary

Constructors

Constructor	Description
EGTF()	Constructor using cCong = -18km/h, cFree = 80km/h, deltaV = 10km/h and vc = 80km/h.
EGTF(double cCong, double cFree, double deltaV, double vc)	Constructor defining global settings.
EGTF(double cCong, double cFree, double deltaV, double vc, double sigma, double tau, double xMax, double tMax)	Convenience constructor that also sets a specified kernel.

Method Summary

Modifier and Type	Method	Description
void	addGridDataSI(DataStream<?> dataStream, double[] location, double[] time, double[][] values)	Adds grid data.
void	addGridDataSI(Quantity<?,?> quantity, double[] location, double[] time, double[][] values)	Adds grid data.
void	addListener(EgtfListener listener)	Add listener.
void	addPointDataSI(DataStream<?> dataStream, double location, double time, double value)	Adds point data.
void	addPointDataSI(Quantity<?,?> quantity, double location, double time, double value)	Adds point data.
void	addVectorDataSI(DataStream<?> dataStream, double[] location, double[] time, double[] values)	Adds vector data.
void	addVectorDataSI(Quantity<?,?> quantity, double[] location, double[] time, double[] values)	Adds vector data.
void	clearDataBefore(double time)	Removes all data from before the given time.
Filter	filterFastSI(double xMin, double xStep, double xMax, double tMin, double tStep, double tMax, Quantity<?,?>... quantities)	Returns filtered data that is processed using fast fourier transformation.
EgtfParallelListener	filterParallelFastSI(double xMin, double xStep, double xMax, double tMin, double tStep, double tMax, Quantity<?,?>... quantities)	Executes fast filtering in parallel.
EgtfParallelListener	filterParallelSI(double[] location, double[] time, Quantity<?,?>... quantities)	Executes filtering in parallel.
Filter	filterSI(double[] location, double[] time, Quantity<?,?>... quantities)	Returns filtered data.
DataSource	getDataSource(String name)	Return a data source, which is created if necessary.
(package private) double	getWaveSpeedCongestion()	Returns the wave speed in congestion.
(package private) double	getWaveSpeedFreeFlow()	Returns the wave speed in free flow.
void	interrupt()	Interrupt the calculation.
void	removeListener(EgtfListener listener)	Remove listener.
void	setGaussKernelSI(double sigma, double tau)	Sets a Gaussian kernel with infinite range.
void	setGaussKernelSI(double sigma, double tau, double xMax, double tMax)	Sets a Gaussian kernel with limited range.
void	setKernel()	Sets a default exponential kernel with infinite range, sigma = 300m, and tau = 30s.
void	setKernelSI(double sigma, double tau)	Sets an exponential kernel with infinite range.
void	setKernelSI(double sigma, double tau, double xMax, double tMax)	Sets an exponential kernel with limited range.
void	setKernelSI(double xMax, double tMax, KernelShape shape)	Sets a kernel with limited range and provided shape.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

EGTF

public EGTF()

Constructor using cCong = -18km/h, cFree = 80km/h, deltaV = 10km/h and vc = 80km/h. A default kernel is set.

EGTF

public EGTF(double cCong,
            double cFree,
            double deltaV,
            double vc)

Constructor defining global settings. A default kernel is set.

Parameters:

cCong - double; shock wave speed in congestion [km/h]

cFree - double; shock wave speed in free flow [km/h]

deltaV - double; speed range between congestion and free flow [km/h]

vc - double; flip-over speed below which we have congestion [km/h]

EGTF

public EGTF(double cCong,
            double cFree,
            double deltaV,
            double vc,
            double sigma,
            double tau,
            double xMax,
            double tMax)

Convenience constructor that also sets a specified kernel.

Parameters:

cCong - double; shock wave speed in congestion [km/h]

cFree - double; shock wave speed in free flow [km/h]

deltaV - double; speed range between congestion and free flow [km/h]

vc - double; flip-over speed below which we have congestion [km/h]

sigma - double; spatial kernel size in [m]

tau - double; temporal kernel size in [s]

xMax - double; maximum spatial range in [m]

tMax - double; maximum temporal range in [s]

Method Detail

getDataSource

public DataSource getDataSource(String name)

Return a data source, which is created if necessary.

Parameters:

name - String; unique name for the data source

Returns:

DataSource; data source

Throws:

IllegalStateException - when data has been added without a data source

clearDataBefore

public void clearDataBefore(double time)

Removes all data from before the given time. This is useful in live usages of this class, where older data is no longer required.

Parameters:

time - double; time before which all data can be removed

addPointDataSI

public void addPointDataSI(Quantity<?,?> quantity,
                           double location,
                           double time,
                           double value)

Adds point data.

Parameters:

quantity - Quantity<?, ?>; quantity of the data

location - double; location in [m]

time - double; time in [s]

value - double; data value

Throws:

IllegalStateException - if data was added with a data stream previously

addPointDataSI

public void addPointDataSI(DataStream<?> dataStream,
                           double location,
                           double time,
                           double value)

Adds point data.

Parameters:

dataStream - DataStream<?>; data stream of the data

location - double; location in [m]

time - double; time in [s]

value - double; data value

Throws:

IllegalStateException - if data was added with a quantity previously

addVectorDataSI

public void addVectorDataSI(Quantity<?,?> quantity,
                            double[] location,
                            double[] time,
                            double[] values)

Adds vector data.

Parameters:

quantity - Quantity<?, ?>; quantity of the data

location - double[]; locations in [m]

time - double[]; times in [s]

values - double[]; data values in SI unit

Throws:

IllegalStateException - if data was added with a data stream previously

addVectorDataSI

public void addVectorDataSI(DataStream<?> dataStream,
                            double[] location,
                            double[] time,
                            double[] values)

Adds vector data.

Parameters:

dataStream - DataStream<?>; data stream of the data

location - double[]; locations in [m]

time - double[]; times in [s]

values - double[]; data values in SI unit

Throws:

IllegalStateException - if data was added with a quantity previously

addGridDataSI

public void addGridDataSI(Quantity<?,?> quantity,
                          double[] location,
                          double[] time,
                          double[][] values)

Adds grid data.

Parameters:

quantity - Quantity<?, ?>; quantity of the data

location - double[]; locations in [m]

time - double[]; times in [s]

values - double[][]; data values in SI unit

Throws:

IllegalStateException - if data was added with a data stream previously

addGridDataSI

public void addGridDataSI(DataStream<?> dataStream,
                          double[] location,
                          double[] time,
                          double[][] values)

Adds grid data.

Parameters:

dataStream - DataStream<?>; data stream of the data

location - double[]; locations in [m]

time - double[]; times in [s]

values - double[][]; data values in SI unit

Throws:

IllegalStateException - if data was added with a quantity previously

setKernel

public void setKernel()

Sets a default exponential kernel with infinite range, sigma = 300m, and tau = 30s.

setKernelSI

public void setKernelSI(double sigma,
                        double tau)

Sets an exponential kernel with infinite range.

Parameters:

sigma - double; spatial kernel size

tau - double; temporal kernel size

setKernelSI

public void setKernelSI(double sigma,
                        double tau,
                        double xMax,
                        double tMax)

Sets an exponential kernel with limited range.

Parameters:

sigma - double; spatial kernel size in [m]

tau - double; temporal kernel size in [s]

xMax - double; maximum spatial range in [m]

tMax - double; maximum temporal range in [s]

setGaussKernelSI

public void setGaussKernelSI(double sigma,
                             double tau)

Sets a Gaussian kernel with infinite range.

Parameters:

sigma - double; spatial kernel size

tau - double; temporal kernel size

setGaussKernelSI

public void setGaussKernelSI(double sigma,
                             double tau,
                             double xMax,
                             double tMax)

Sets a Gaussian kernel with limited range.

Parameters:

sigma - double; spatial kernel size in [m]

tau - double; temporal kernel size in [s]

xMax - double; maximum spatial range in [m]

tMax - double; maximum temporal range in [s]

setKernelSI

public void setKernelSI(double xMax,
                        double tMax,
                        KernelShape shape)

Sets a kernel with limited range and provided shape. The shape allows using non-exponential kernels.

Parameters:

xMax - double; maximum spatial range

tMax - double; maximum temporal range

shape - KernelShape; shape of the kernel

getWaveSpeedCongestion

final double getWaveSpeedCongestion()

Returns the wave speed in congestion.

Returns:

double; wave speed in congestion

getWaveSpeedFreeFlow

final double getWaveSpeedFreeFlow()

Returns the wave speed in free flow.

Returns:

double; wave speed in free flow

filterParallelSI

public EgtfParallelListener filterParallelSI(double[] location,
                                             double[] time,
                                             Quantity<?,?>... quantities)

Executes filtering in parallel. The returned listener can be used to report progress and wait until the filtering is done. Finally, the filtering results can then be obtained from the listener.

Parameters:

location - double[]; location of output grid in [m]

time - double[]; time of output grid in [s]

quantities - Quantity<?, ?>...; quantities to calculate filtered data of

Returns:

EgtfParallelListener; listener to notify keep track of the progress

filterParallelFastSI

public EgtfParallelListener filterParallelFastSI(double xMin,
                                                 double xStep,
                                                 double xMax,
                                                 double tMin,
                                                 double tStep,
                                                 double tMax,
                                                 Quantity<?,?>... quantities)

Executes fast filtering in parallel. The returned listener can be used to report progress and wait until the filtering is done. Finally, the filtering results can then be obtained from the listener.

Parameters:

xMin - double; minimum location value of output grid [m]

xStep - double; location step of output grid [m]

xMax - double; maximum location value of output grid [m]

tMin - double; minimum time value of output grid [s]

tStep - double; time step of output grid [s]

tMax - double; maximum time value of output grid [s]

quantities - Quantity<?, ?>...; quantities to calculate filtered data of

Returns:

EgtfParallelListener; listener to notify keep track of the progress

filterSI

public Filter filterSI(double[] location,
                       double[] time,
                       Quantity<?,?>... quantities)

Returns filtered data. This is the standard EGTF implementation.

Parameters:

location - double[]; location of output grid in [m]

time - double[]; time of output grid in [s]

quantities - Quantity<?, ?>...; quantities to calculate filtered data of

Returns:

Filter; filtered data, null when interrupted

filterFastSI

public Filter filterFastSI(double xMin,
                           double xStep,
                           double xMax,
                           double tMin,
                           double tStep,
                           double tMax,
                           Quantity<?,?>... quantities)

Returns filtered data that is processed using fast fourier transformation. This is much faster than the standard filter, at the cost that all input data is discretized to the output grid. The gain in computation speed is however such that finer output grids can be used to alleviate this. For discretization the output grid needs to be equidistant. It is recommended to set a Kernel with maximum bounds before using this method.

More than being a fast implementation of the Adaptive Smoothing Method, this implementation includes all data source like the Extended Generalized Treiber-Helbing Filter.

Parameters:

xMin - double; minimum location value of output grid [m]

xStep - double; location step of output grid [m]

xMax - double; maximum location value of output grid [m]

tMin - double; minimum time value of output grid [s]

tStep - double; time step of output grid [s]

tMax - double; maximum time value of output grid [s]

quantities - Quantity<?, ?>...; quantities to calculate filtered data of

Returns:

Filter; filtered data, null when interrupted

interrupt

public final void interrupt()

Interrupt the calculation.

addListener

public final void addListener(EgtfListener listener)

Add listener.

Parameters:

listener - EgtfListener; listener

removeListener

public final void removeListener(EgtfListener listener)

Remove listener.

Parameters:

listener - EgtfListener; listener

toString

public String toString()

Overrides:

toString in class Object