Distribution

`ultimodel.DistributeTraffic.TargetValues(country_layer, cn_col='cntr_code')`

Determine shares of international and national transport for a country and calculate corresponding total trips and vehicle kilometers travelled (VKT)

Parameters:	`country_layer` (`pd.DataFrame \| gpd.GeoDataFrame`) – countries with target values for raod transport volumes `cn_col` (`str`, default: `'cntr_code'` ) – name of column with country code in country layer, default 'cntr_code'

`targets_personal_transport(cn, target_col='car_pkm', unit=1000000.0)`

Calculate VKT for the segments short and long distance (national) and international personal transport for a country

Parameters:	`cn` (`str`) – country code `target_col` (`str`, default: `'car_pkm'` ) – name of column in self.country_layer with the total transport volume in person kilometers travelled, default 'car_pkm' `unit` (`float`, default: `1000000.0` ) – scaling factor for total transport volume, default 1.e+6

Returns:	`dict` – vkt per segment

`targets_freight_transport(cn, target_col='freight_tkm', segments=None, shares_tkm=None, loads_t=None, seg_split=None, unit=1000000.0)`

Calculate VKT and trips for the segments short and long distance (national) and international freight transport for a country

!! Long-distance and international freight transport only cover 1 segment (heavy weight transport) !! Short-distance freight transport can cover multiple segments, inlcuding the long-distance segment (heavy weight transport) !! The distribution of tkm among segments is given with the shares_tkm parameter, short-distance tkm are then further spread among these segments

Parameters:

seg_split (str, default: None ) –

freight transport segment where there is traffic in all categories (short, long, international)
cn (str) –

country code
target_col (str, default: 'freight_tkm' ) –

name of column in self.country_layer with the total transport volume in tkm
segments (list, default: None ) –

names of freight transport segments; default None refers to ['lcv', 'mft', 'hft']
shares_tkm (dict, default: None ) –

shares of different freight transport segments of total tkm; default None refers to shares {'lcv': 0.08, 'mft': 0.09, 'hft': 0.83}
loads_t (dict, default: None ) –

average load in t per freight transport segment; default None refers to load {'lcv': 0.5, 'mft': 3, 'hft': 10}
unit (float, default: 1000000.0 ) –

scaling factor for total transport volume, default 1.e+6

Returns:	`dict` – vkt and trips per segment

`ultimodel.DistributeTraffic.GravityModel(cost_matrix, taz, taz_cn='cntr_code')`

Create OD trip matrices for personal and freight transport using a gravity model

Parameters:	`matrix` (`np.array`) – np.array with shape [len(taz),len(taz),2], cost matrix with travel times [:,:,0] and distances [:,:,1] `taz` (`gpd.GeoDataFrame \| pd.DataFrame`) – gpd.GeoDataFrame or pd.DataFrame with TAZ `taz_cn` (`str`, default: `'cntr_code'` ) – name of column with country code in TAZ

`get_country_model(cn)`

Get TAZ and cost matrix for country

Parameters:	`cn` (`str`) – country code

Returns:	`pd.DataFrame \| gpd.GeoDataFrame, np.array` – TAZ for country, cost matrix for country

`matrix_international()`

Adjust cost matrix for international assignment (no inner country trips) by setting costs for inner country relations to 9.e+12

Returns:	`np.array` – international cost matrix with travel times and distances

`trip_distribution_pt(target, cn=None, taz_pop='population', alpha=0.5, gamma=-2.75, unit_dis=1000, unit_tt=60, mob_rate=36.0, occ_rate=1.3)`

Distribute personal transport using a gravity model and an input for total VKT Gravity model parameters are given as defaults and were estimated using the German NHTS MiD 2017

Parameters:

target (float) –

total VKT
cn (str, default: None ) –

country code; default None means all countries in self.taz are included
taz_pop (str, default: 'population' ) –

name of column with population in taz, default 'population'
alpha (float, default: 0.5 ) –

alpha parameter in gravity model, default 0.5
gamma (float, default: -2.75 ) –

gamma parameter in gravity model, default -2.75
unit_dis (float, default: 1000 ) –

factor to transform unit in distance matrix to km, default 1000 (suggesting distance is in m)
unit_tt (float, default: 60 ) –

factor to transform unit in travel time matrix to min, default 60 (suggesting distance is in s)
mob_rate (float, default: 36.0 ) –

mobility rate of inhabitants, default 36
occ_rate (float, default: 1.3 ) –

average vehicle occupancy

Returns:	`np.array` – np.array with OD trip matrix

`trip_distribution_ft(target_trips, target_vkt=None, cn=None, beta=0.00421, unit_tt=60, unit_dis=1000, trips_key='')`

Distribute freight transport using a gravity model and an input for total trips and VKT Gravity model parameters are given as defaults and were estimated using microscopic truck data for Germany

Parameters:

target_trips (float | dict) –

float or dict, total trips or if cn is None dict with total trips per country and segment in the form of {cn: {segment: target_trips}}
target_vkt (float, default: None ) –

optional: total VKT used for comparing VKT from OD matrix and goal, default None
cn (None | str, default: None ) –

country code; default None means all countries in self.taz are included
beta (float, default: 0.00421 ) –

gamma parameter in gravity model, default 0.00421
unit_dis (float, default: 1000 ) –

factor to transform unit in distance matrix to km, default 1000 (suggesting distance is in m)
unit_tt (float, default: 60 ) –

factor to transform unit in travel time matrix to min, default 60 (suggesting distance is in s)
trips_key (str, default: '' ) –

key for segment if cn is None target_trips is dict

Returns:	`np.array` – np.array with OD trip matrix

`ultimodel.DistributeTraffic.IntraZonal(taz, net, from_node='from_node', to_node='to_node', link_id='ultimo_id')`

Distribute intrazonal trips on road network

Parameters:

taz (gpd.GeoDataFrame | pd.DataFrame) –

gpd.GeoDataFrame or pd.DataFrame with TAZ
net (gpd.GeoDataFrame | pd.DataFrame) –

gpd.GeoDataFrame or pd.DataFrame with road network
from_node (str, default: 'from_node' ) –

column name for from node in net, default 'from_node'
to_node (str, default: 'to_node' ) –

column name for to node in net, default 'to_node'
link_id (str, default: 'ultimo_id' ) –

column name for unique id of the elements in net, default 'ultimo_id'

`road_type_weighted_single(target, weights=None, veh_types=None, taz_id='nuts_id', index='population', sub_len='length_sub', net_type='type', occ_rate=1.0)`

Distribute total VKT per TAZ and assign loads to roads within this TAZ, weighted by road type

Parameters:

target (dict) –

target values for total VKT per vehicle type in the form of {veh_type: target_vkt}
weights (None | pd.DataFrame, default: None ) –

weights of different road types; default None leads to pd.DataFrame({net_type: [0, 1, 2, 3], 'weight': [0.75, 1.5, 3.5, 3.5]})
veh_types (list, default: None ) –

names of vehicle types to be considered; default None leads to ['car']
taz_id (str, default: 'nuts_id' ) –

name of column with taz id in self.taz and self.net, defaults to 'nuts_id'
index (str, default: 'population' ) –

name of column with attraction index to be used for trip generation in self.taz, defaults to 'population'
sub_len (str, default: 'length_sub' ) –

name of column with length of subordinate network in self.taz, defaults to 'length'
net_type (str, default: 'type' ) –

name of column with road type in self.net, defaults to 'type'
occ_rate (float, default: 1.0 ) –

average vehicle occupancy (applied for personal transport, i.e. if veh_type == 'car')

Returns:	`gpd.GeoDataFrame \| pd.DataFrame` – gpd.GeoDataFrame or pd.DataFrame for network with traffic loads, taz with subordinate network VKT

`road_type_weighted_multiple(target, matrix_dis, veh_types=None, weights=None, taz_id='nuts_id', taz_mx_id='id', index='index_nat', sub_len='length_sub', net_type='type', distance=55, cell_size=500, fac_cell=1.5, occ_rate=1.0)`

Distribute total VKT per TAZ and assign loads to roads within this TAZ and surrounding TAZ, weighted by road type

Parameters:

target (dict) –

target values for total VKT per vehicle type in the form of {veh_type: target_vkt}
matrix_dis (np.array) –

distance matrix between TAZ (in km)
veh_types (list, default: None ) –

names of vehicle types to be considered; default None leads to ['lcv', 'mft', 'hft']
weights (pd.DataFrame, default: None ) –

weights of different road types; default None leads to pd.DataFrame({net_type: [0, 1, 2, 3], 'weight': [0, 5, 1.5, 0.5]})
taz_id (str, default: 'nuts_id' ) –

name of column with taz id in self.taz and self.net, defaults to 'nuts_id'
taz_mx_id (str, default: 'id' ) –

name of column with taz id relating to position in matrix_dis in self.taz, defaults to 'id'
index (str, default: 'index_nat' ) –

name of column with attraction index to be used for trip generation in self.taz, defaults to 'index_nat'
sub_len (str, default: 'length_sub' ) –

name of column with length of subordinate network in self.taz, defaults to 'length'
net_type (str, default: 'type' ) –

name of column with road type in self.net, defaults to 'type'
distance (float, default: 55 ) –

max distance between TAZ to be included in km, defaults to 55km
cell_size (float, default: 500 ) –

max cell size of TAZ to force inclusion of surrounding TAZ, defaults to 500km²
fac_cell (float, default: 1.5 ) –

factor to apply to main TAZ during distribution, defaults to 1.5
occ_rate (float, default: 1.0 ) –

average vehicle occupancy (applied for personal transport, i.e. if veh_type == 'car')

Returns:	`gpd.GeoDataFrame \| pd.DataFrame` – gpd.GeoDataFrame or pd.DataFrame for network with traffic loads, taz with subordinate network VKT

`ultimodel.DistributeTraffic.pt_shares_int(a, b)`

Determine shares of international transport for personal transport for a country based on area and share of land border

Parameters:	`a` (`float`) – area of country `b` (`float`) – share of land border of country

Returns:	`dict` – dict with international transport shares

`ultimodel.DistributeTraffic.get_trip_matrix(mx_grav, taz, goal_col, taz_id='id')`

Get trip matrix based on total trips per taz and gravity model matrix

Parameters:	`mx_grav` (`np.array`) – matrix from gravity model `taz` (`gpd.GeoDataFrame \| pd.DataFrame`) – gpd.GeoDataFrame or pd.DataFrame with TAZ; needs id column to identify coordinate in mx_grav `goal_col` (`str`) – name of column in taz with total trips per taz

Returns:	`np.array` – matrix with trips between taz

`ultimodel.DistributeTraffic.assignment_single(net_g, net, o, d, weight, trips, from_='from_node', to_='to_node')`

Performs a shortest path network assignment between two nodes on a MultiDiGraph based on a specified weight and returns a GeoDataFrame with the resulting network load

Parameters:

net_g (MultiDiGraph) –

MultiDiGraph with network
net (gpd.GeoDataFrame) –

gpd.GeoDataFrame with network
o (int) –

ID of origin node
d (int) –

ID of destination node
weight (str) –

name of weight attribute; is an attribute of links in net and net_g, e.g. travel time or length
trips (float) –

number of vehicle trips to distribute between o and d
from_ (str, default: 'from_node' ) –

name of from node attribute in net, defaults to 'from_node'
to_ (str, default: 'to_node' ) –

name of to node attribute in net, defaults to 'to_node'

Returns:	`gpd.GeoDataFrame` – GeoDataFrame of net with trips on the links, on the path between o and d

`ultimodel.DistributeTraffic.assignment_multiple(net_g, net, o, d, k, weight, trips, from_='from_node', to_='to_node', id_='link_id')`

Performs a shortest path assignment for the k shortest paths between two nodes on a MultiDiGraph based on a specified weight and returns a GeoDataFrame with the resulting network load Paths are weighted based on the total weight per path

Parameters:

net_g (MultiDiGraph) –

MultiDiGraph with network
net (gpd.GeoDataFrame) –

gpd.GeoDataFrame with network
o (int) –

ID of origin node
d (int) –

ID of destination node
k (int) –

int, number of paths to find
weight (str) –

name of weight attribute; is an attribute of links in net and net_g, e.g. travel time or length
trips (float) –

number of vehicle trips to distribute between o and d
from_ (str, default: 'from_node' ) –

name of from node attribute in net, defaults to 'from_node'
to_ (str, default: 'to_node' ) –

name of to node attribute in net, defaults to 'to_node'
id_ (str, default: 'link_id' ) –

name of id attribute in net, defaults to 'link_id'

Returns:	`gpd.GeoDataFrame` – GeoDataFrame of net with trips on the links, on the path between o and d

`ultimodel.DistributeTraffic.create_network_graph(net_, nodes_, node_id='node_id', node_geo='geometry', net_from='from_node', net_to='to_node', net_id='link_id')`

Transform a GeoDataFrame of a network and the corresponding nodes to a MultiDiGraph Needs columns for node id in nodes, from node, to node and link id in network

Parameters:

net_ (gpd.GeoDataFrame) –

GeoDataFrame with network
nodes_ (gpd.GeoDataFrame) –

GeoDataFrame with nodes
node_id (str, default: 'node_id' ) –

name of id column in nodes_, defaults to 'node_id'
node_geo (str, default: 'geometry' ) –

name of geometry column in nodes_, defaults to 'geometry'
net_from (str, default: 'from_node' ) –

name of from node column in net_, defaults to 'from_node'
net_to (str, default: 'to_node' ) –

name of to node column in net_, defaults to 'to_node'
net_id (str, default: 'link_id' ) –

name of id column in net_, defaults to 'link_id'

Returns:	`MultiDiGraph` – MultiDiGraph of net_