jodeln.network package

jodeln.network.geh module

jodeln.network.geh.geh(m, c)

Calculates the GEH between two hourly traffic volumes.

See: https://en.wikipedia.org/wiki/GEH_statistic

Parameters

• m (float) – Modeled traffic volume.

• c (float) – Counted traffic volume.

Returns

GEH statistic.

Return type

float

jodeln.network.net module

Contains the Network class and related classes.

class jodeln.network.net.LinkParameters(name: str, cost: float, target_volume: float, shape_points: List[Tuple[float, float]])

Bases: object

Parameters needed for constructing a NetLinkData object.

class jodeln.network.net.NetLinkData(cost: float, name: str, target_volume: float, link_index: int, assigned_volume: float, geh: float, seed_volume: float, shape_points: List[Tuple[float, float]])

Bases: object

Data on Network links.

cost

Friction on the link that is used when determining shortest routes.

Type

float

name

Human-readable name for the link. Does not have to be unique.

Type

str

target_volume

Desired volume on this link.

Type

float

link_index

Unique identifier for this link.

Type

int

assigned_volume

Volume on the link as assigned from the estimated OD matrix.

Type

float

geh

GEH statistic comparing the target_volume and assigned_volume.

Type

float

seed_volume

Volume on the link as assigned from the seed OD matrix.

Type

float

class jodeln.network.net.NetNode(key, parameters: NodeParameters)

Bases: object

A point (junction) in the network graph.

Two connected nodes form an link. A sequence of three nodes forms a Turn (see TurnData).

key

Unique identifier for the node.

Type

int

name

Name, or label, for the node.

Type

str

x

x-coordinate of node. Defaults to zero.

Type

float

y

y-coordinate of node. Defaults to zero.

Type

float

is_origin

Indicates if traffic can start their trip from this node (source node)

Type

bool

is_destination

Indicates if traffic can end their trip at this node (sink node)

Type

bool

neighbors

Adjacency list of connected downstream node IDs and associated data

Type

Dict[int, NetLinkData]

up_neighbors

Upstream node IDs connected to this node.

Type

list

add_neighbor(neighbor, link_data) → None

Connects two nodes to form an link.

links are stored as an adjacency list.

Parameters

• neighbor (int) – Unique identifier of neighboring (connecting) node.

• link_data (NetLinkData) – See NetLinkData class.

get_connections()

Return list of node keys connected to self node.

class jodeln.network.net.NetODpair(origin: int, destination: int, seed_total_volume: float, est_total_volume: float, routes: List[NetRoute])

Bases: object

Origin-Destination data in the Network.

origin

node ID of the OD origin.

Type

int

destination

node ID of the OD destination.

Type

int

seed_total_volume

Volume for this OD pair within the seed OD matrix.

Type

float

est_total_volume

Volume for this OD pair within the estimated OD matrix.

Type

float

routes

List of all possible routes from origin to destination to include in the OD optimization. One OD can contain multiple routes.

Type

List[route]

class jodeln.network.net.NetRoute(nodes: List[int], name: str, seed_volume: float, target_ratio: float, target_rel_diff: float, assigned_volume: float, assigned_ratio: float, opt_var_index: int)

Bases: object

Contains sequence of nodes from origin to destination.

nodes

Ordered sequence of node IDs along the route, from origin to destination.

Type

List[int]

name

Human-readable name for the route. Does not have to be unique amongst all routes.

Type

str

seed_volume

Volume on the route assigned from the seed OD matrix.

Type

float

target_ratio

If one OD pair has multiple routes, this is the desired proportion of the total OD volume that should occur on this route.

Type

float

target_rel_diff

If one OD pair has multiple routes, this is a helper variable for the OD optimization that indicates how different this route is relative to all other routes within the OD. For example, 2 routes, one has a target_ratio of 0.8, the other 0.20. The target relative differences are 0.60 and -0.60, respectively.

Type

float

assigned_volume

Volume assigned to this route based on the estimated OD matrix.

Type

float

assigned_ratio

If one OD pair has multiple routes, this is the actual proportion of the total estimated OD volume. assigned_ratio is compared to the target_ratio in the OD optimization.

Type

float

opt_var_index

Helper variable for the OD optimization algorithm. The OD optimization takes a list of variables. opt_var_index is the position of this route within the list of optimization variables.

Type

int

class jodeln.network.net.Network

Bases: object

Contains the network nodes and links, turns, and assigned origin-destination information.

Nodes and links are stored in an ‘adjaceny list’ graph data structure. For example: self.nodes = {node id, node data} where node data contains the connected nodes that form the network links.

nodes

nodes within the Network graph.

Type

Dict[int, NetNode]

turns

Turns within the Network graph.

Type

Dict[int, TurnData]

n_links

number of links in the network.

Type

int

od

OD data for the network.

Type

List[NetODpair]

total_geh

Grand total of summing all the GEH values of the links and turns. See the calc_network_geh method.

Type

int

add_link(i_name, j_name, parameters: LinkParameters) → None

Connects two nodes to form an link in the network graph.

Parameters

• i_name (str) – Origin node name

• j_name (str) – Destination node name

• parameters (LinkParameters) – Data belonging to the link. Name, cost, etc.

add_node(parameters: NodeParameters) → None

Add a node to the network graph.

Parameters

parameters (NodeParameters) – Data about the node. Name, x,y coordinates, etc.

calc_network_geh() → None

Sum up the total geh of all the links & turns in the network.

get_node_by_name(node_name)

Helper function to return a node by name.

init_routes() → None

Initialize routes by determining shortest route from all origins to all destinations.

init_seed_volumes(od_mat) → None

Assign route, link, and turn seed volumes based on an od matrix.

Parameters

od_mat (Dict) – OD matrix, imported from csv. See od_read.py.

init_turns() → None

Initialize all turns within the network.

link(i, j)

Convenience function to access link properties.

links_() → Generator[Tuple[int, int, NetLinkData], None, None]

Generator function to iterate through all the links.

Function name has a trailing underscore for consistency with self.turns_()

set_link_and_turn_volume_from_route() → None

Calculate the volume on all links and turns based on the OD route volumes.

set_route_names() → None

Assign unique route names within each OD.

Unique names are assigned by finding a unique link on the route. For example, if there are two routes from A to B with nodes: A-X-Y-B and A-X-C-Y-B, the two routes could be named “X-Y” and “X-C” because those links are unique to their respective routes.

turns_() → Generator[Tuple[Tuple[int, int, int], TurnData], None, None]

Generator function to itertae through all the turns.

Function name has a trailing underscore to avoid conflict with self.turns variable name. Function is implemented to create consistent looking code when iterating through all the turns or iterating through all the links. e.x.:

“for k, v in net.turns_()” or “for k, v in net.links_()”

class jodeln.network.net.NodeParameters(name: str, x: float, y: float, is_origin: bool, is_destination: bool)

Bases: object

Parameters needed for constructing a NetNode object.

class jodeln.network.net.TurnData(key: int, name: str, seed_volume: float, target_volume: float, assigned_volume: float, geh: float)

Bases: object

Data on Network turns.

A turn is a sequence of three consecutive nodes: A-B-C. In this case “B” is the intersection, A is upstream, and C is downstream.

key

Unique ID for the turn.

Type

int

name

Human-readable name for the turn. Typically based on the A-B-C node names.

Type

str

seed_volume

Volume on the turn as assigned from the seed OD matrix.

Type

float

target_volume

Desired volume on this turn.

Type

float

assigned_volume

Volume on the turn as assigned from the estimated OD matrix.

Type

float

geh

GEH statistic comparing the target_volume and assigned_volume.

Type

float

jodeln.network.net_read module

Create Network objects from various user inputs.

Users may have varying available inputs when using this program. For example:

• node and link only.

• node, link, and turn.

• node, link, and OD

• etc

jodeln.network.net_read.add_links_from_csv(net: Network, link_csv: str) → None

Adds links to the network from the given csv file.

Requires that the network already has nodes in it.

Columns in link csv (columns must be in this order):

1. from_node

2. to_node

3. cost

4. name

5. target_volume

The csv file format does not allow defining intermediate shape points between the link start point and end point. Use shapefile format if intermediate points are desired.

Parameters

• net (Network) – Network object where links will be added.

• link_csv (str) – File path to link file.

jodeln.network.net_read.add_links_from_shp(net: Network, link_shp: str) → None

Adds links to the network from the given shapefile paths.

Requires that the network already has nodes in it.

Parameters

• net (Network) – Network object where links will be added.

• link_shp (str) – File path to link shapefile.

jodeln.network.net_read.add_nodes_from_csv(net: Network, node_csv: str) → None

Adds nodes to the network from the given csv file.

Columns in node csv (columns must be in this order):

1. node name

2. x-coordinate

3. y-coordinate

4. is_origin (0 = False, 1 = True)

5. is_destination (0 = False, 1 = True)

Parameters

• net (Network) – Network object where nodes will be added.

• node_csv (str) – File path to node file.

jodeln.network.net_read.add_nodes_from_shp(net: Network, node_shp: str) → None

Adds nodes to the network from the given shapefile path.

Parameters

• net (Network) – Network object where nodes will be added.

• node_shp (str) – File path to node shapefile.

jodeln.network.net_read.create_network(node_file: str, link_file: str) → Network

Create a new network from user-supplied files.

The network turns and potential OD routes are also initialized so that the new network object returned is functional.

Parameters

• node_file (str) – File path to node file.

• link_file (str) – File path to link file.

Returns

New network containing nodes and links. Turns and routes are initialized from the nodes and links.

Return type

Network

jodeln.network.net_read.import_routes(route_csv, net: Network) → None

Replace routes from O to D with user-defined routes.

All routes between O and D must be contained in the csv. For example, if there is one existing route between O and D, and the user wants to add a new second route, both the existing and new route must be contained in the csv.

Columns in the route csv (columns must be in this order):

1. origin: node name

2. destination: node name

3. target_ratio: how much volume should be on the route

   (e.x. 0.20 means 20% of the total OD volume should be on this route)

4. sequence: comma separated values of the node names from O to D

Parameters

• route_csv (str) – File path to user-defined OD route file.

• net (Network) – OD routes are imported into this network.

jodeln.network.net_read.import_turns(turn_csv, net: Network) → None

Import turn target volumes from csv.

Turns are any portion of a route traversing 3 nodes, ex: A-B-C

Columns in node csv (columns must be in this order):

1. A node name

2. B node name

3. C node name

4. turn name

5. target volume

Parameters

• turn_csv (str) – File path to user gernerated turn csv file.

• net (Network) – Turns are imported into this network.

jodeln.network.net_write module

Export network features to csv files.

jodeln.network.net_write.export_node_sequences(net: Network, output_folder=None) → None

Export the links and turns on every OD route to csv.

Parameters

• net (Network) – Network containing the node sequences to export.

• output_folder (str) – Folder to export the node file, by default None indicates the current working directory as returned by os.getcwd().

jodeln.network.net_write.export_route_list(net: Network, output_folder=None) → None

Export the nodes along each route. One row per route.

Sample csv output. First two rows of the sample output are the same origin-destination, but have different routes. – 100,101,103,105 100,110,112,105 105,107,108,109 –

Parameters

• net (Network) – Network containing the routes to export.

• output_folder (str, optional) – Folder to export route file, by default None indicates the current working directory as returned by os.getcwd().

jodeln.network.net_write.export_turns(net: Network, output_folder=None) → None

Exports network turns to a csv file.

Parameters

• net (Network) – Network cotaining turns to export.

• output_folder (str, optional) – Folder to export turn file, by default None indicates the current working directory as returned by os.getcwd().