Demand/Importing O/D Matrices
Importing O/D Matrices from VISUM=
OD2TRIPS computes trips tables from O/D (origin/destination) matrices. OD2TRIPS assumes the matrix / the matrices to be coded as amounts of vehicles that drive from one district to another within a certain time period. Because the generated trips must start and end at edges, OD2TRIPS requires a mapping of districts to edges. During conversion of VISUM networks with NETCONVERT districts stored in the VISUM input file are parsed and stored within the generated SUMO network file. If you do not use VISUM as input, you must build a districts file by your own. The format is given in "Describing the Districts", one of the next subchapters. You have to pass the file containing the district definitions to OD2TRIPS using the --net-file <FILE> (--net <FILE> or -n <FILE> for short) option.
Because OD2TRIPS was used only to import data stored in VISUM/VISION/VISSIM formats, it assumes O/D to be stored in one of the formats used by these applications. Not all VISUM/VISION/VISSIM formats are supported, by now only two, namely the "V"- and the "O"-format. If you do not own matrices stored in these formats, you still have three possibilities: a) convert them into one of the supported formats, b) write your own reader for OD2TRIPS, or c) convert them into flow definitions and then give them to DUAROUTER (see Chapter "Using Flow Definitions"). Both supported formats are described in "Describing the Matrix Cells", one of the next subchapters. You may either give a list of matrices to OD2TRIPS using the --od-files <FILE>[,<FILE>]* (--od <FILE>[,<FILE>]* or -d <FILE>[,<FILE>]* for short) option followed by the list of files separated using a ','.
OD2TRIPS reads all matrices and generates trip definitions as described in "Using Trip Definitions". The generated trip definitions are numbered starting at zero. You can also add a prefix to the generated trip definition names using (--prefix <STRING>. As usual, they are written to the output file named using the --output-file <FILE> option (--output <FILE> or -o <FILE> for short). You can specify a vehicle type to be added to the trip definitions using --vtype followed by the type name. Please remark that vehicles will have no type unless not given in the O/D-matrices or defined using this option. If a type is spuulied, but you do not want to include it within the output, set the --no-vtype option. The command line option overrides type names given in the O/D-matrices. The type itself will not be generated. Vehicles will be generated for the time period between --begin <INT> (-b <INT>) and --end <INT> (-e <INT>), having 0 and 86400 as default values, respectively. The meaning is the simulation step in seconds, as usual.
Because each O/D-matrix cell describes the amount of vehicles to be emitted within a certain time period, OD2TRIPS has to compute the vehicle's explicite departure times. Normally, this is done by using a random time within the time interval a O/D-matrix cell describes. It still is possible to emit a cell's vehicles with an uniform time between their emissions. Use the option --spread.uniform to enable this.
You can scale the amounts stored in the O/D-matrices using the --scale <FLOAT> option which assumes a float as parameter. All read flows will be multiplied with this value, the default is 1. When importing O/D-matrices that cover a whole day, you maybe want to apply a curve which resembles the spread of the trip begins found in reality. Please read the subchapter "Splitting large matrices" on this.
Describing the Districts
A file containing a mapping from districts to edges looks as following:
<districts> <district id="<DISTRICT_ID>"> <dsource id="<EDGE_ID>" weight="<PROBABILITY_TO_USE>"/> ... further source edges ... <dsink id="<EDGE_ID>" weight="<PROBABILITY_TO_USE>"/> ... further destination edges ... </district> ... further districts ... </districts>
This means that a district is described by its id, being a simple name, and lists of source and destination edges. A district should have at least one source and one destination edge, each described by its id and use probability called weight herein. These edges are used to emit and remove vehicles into/from the network respectively. The probability sums of each the source and the destination lists are normalized after loading.
Describing the Matrix Cells
To understand how an O/D-matrix is stored, we should remind the meanings of the values stored herein. Each matrix describes a certain time period. The indices within the matrix are names of the origin/destination districts (normally they are equivalent, both lists are the same). The values stored within the matrix are amounts of vehicles driving from the according origin district to the according destination district within the described time period.
The formats used by ptv are described in the VISUM-documentation more detailed. All start with a line where the type of the O/D-matrix is given, appended to a '$'. The first following character tells in which format the table is stored. Then, further characters follow which describe which values are supplied additionally within the matrix. For further information we ask you to consult the documentation supported by ptv. Herein, only the supported variants are described.
The V-format stores the O/D matrix by giving the number of districts first and then naming them. After this, for each of the named districts, a list of vehicle amounts that leave this district is given, sorted by the destination district names as given in the district name list. An example may look like this:
$VMR * vehicle type 4 * From-Time To-Time 7.00 8.00 * Factor 1.00 * * some * additional * comments * District number 3 * names: 1 2 3 * * District 1 Sum = 6 1 2 3 * District 2 Sum = 15 4 5 6 * District 2 Sum = 24 7 8 9
The 'M' in the type name indicates that a vehicle type is used, the "R" that the values shall be rounded randomly. The second information is not processed by OD2TRIPS what means that you can parse both V-, VR-, VMR, and VM-matrices. Please remark that both the names list and the lists containing the amounts are written in a way that no more than 10 fields are stored in the same line. Each of the entries they contain seem to be left-aligned to a boundary of 11 characters (possibly 10 for the name and one space character). Both constraints are not mandatory for the importer used in OD2TRIPS.
The O-format instead simply lists each origin and each destination together with the amount in one line (please remark that we currently ignore the string after the ';' that occures after the type identifier "$OR" in the first line):
$OR;D2 * From-Time To-Time 7.00 8.00 * Factor 1.00 * some * additional * comments 1 1 1.00 1 2 2.00 1 3 3.00 2 1 4.00 2 2 5.00 2 3 6.00 3 1 7.00 3 2 8.00 3 3 9.00
Splitting large matrices
Since version 0.9.5 OD2TRIPS allows splitting matrices which define a long time period into smaller parts which contain definite percentages of the whole. There are two ways of defining the amounts the matrix shall be split into. The first possibility is to use the option --timeline directly. In this case, it should be followed by a list of times and probabilities, separated by ','. Each time and probability field is made up of two values, an integer time being the simulation time in seconds and a floating point number describing the probability. These two values are separated using a ':'. At least two values must be supplied making the definition of a timeline in this case being decribeable by the following BNF-formula:
In this case, the matrix will be split into (fields-1) parts and each part will have the amount described by the integral within the field.
The second case is rather common in transportation science. It allows to split the matrix into 24 subparts - this means the number of fields is fixed to 24 - allowing to spread an O/D-matrix over a day describing it by hours. To use this, give additionally the option --timeline.day-in-hours to OD2TRIPS. It the assumes the values from the --timeline - option being a list of 24 floats, divided by ',', each describing the probability of emitting a vehicle within the according hour.
In both cases, the probabilities are automatically normed.