Data Models#

tfm defines a few key objects:

Network stores nodes and edges
OD stores origin-destination flows
ODFlows stores flows allocated to paths over a network (for each OD pair, the flow might use one or more paths to route over the network)
NetworkFlows stores flows allocated to the network in aggregate (for each node or edge in a Network, multiple OD pairs might be allocated to it)

Network edges#

Create a Network from a DataFrame with edge_from, edge_to, and edge_id columns. Optional columns such as cost and capacity are used later to allocate flows.

>>> import pandas as pd
>>> from transport_flow_model.model import Network, NetworkFlows, OD, ODFlows
>>> network = Network(
...     pd.DataFrame(
...         {
...             "edge_from": ["A", "B", "C"],
...             "edge_to": ["B", "C", "D"],
...             "edge_id": ["AB", "BC", "CD"],
...             "cost": [1, 1, 1],
...         }
...     )
... )
>>> network.to_dataframe()[["edge_from", "edge_to", "edge_id"]].to_dict("records")
[{'edge_from': 'A', 'edge_to': 'B', 'edge_id': 'AB'}, {'edge_from': 'B', 'edge_to': 'C', 'edge_id': 'BC'}, {'edge_from': 'C', 'edge_to': 'D', 'edge_id': 'CD'}]

OD demand#

An OD object represents demand for flows between origin and destination nodes.

>>> od = OD(
...     pd.DataFrame(
...         {
...             "origin_id": ["A"],
...             "destination_id": ["C"],
...             "flow": [10],
...         }
...     )
... )
>>> od.to_dataframe().to_dict("records")
[{'origin_id': 'A', 'destination_id': 'C', 'flow': 10}]

Allocated flows#

An ODFlows object stores the paths used for each allocated OD flow. The edge_path values are lists of edge IDs.

>>> od_flows = ODFlows(
...     pd.DataFrame(
...         {
...             "origin_id": ["A", "B"],
...             "destination_id": ["B", "C"],
...             "flow": [10, 5],
...             "edge_path": [["AB"], ["BA", "AC"]],
...         }
...     )
... )
>>> od_flows.to_dataframe()["edge_path"].tolist()
[['AB'], ['BA', 'AC']]

Edge totals#

NetworkFlows.from_network_and_od_flows aggregates path flows onto network edges. Unused edges are have zero flow.

>>> network_flows = NetworkFlows.from_network_and_od_flows(network, od_flows)
>>> network_flows.to_dataframe().set_index("edge_id")["flow"].to_dict()
{'AB': 10, 'BC': 0, 'CD': 0}

CSV input#

CSV inputs can use project-specific column names. from_csv normalizes them to the model schema using a column_map dictionary.

>>> import tempfile
>>> with tempfile.TemporaryDirectory() as tmpdir:
...     csv_path = f"{tmpdir}/network.csv"
...     pd.DataFrame(
...         {
...             "from_id": ["A"],
...             "to_id": ["B"],
...             "id": ["E1"],
...             "flow_capacity": [100],
...             "gcost_usd_per_ton": [10.5],
...         }
...     ).to_csv(csv_path, index=False)
...     loaded = Network.from_csv(
...         csv_path,
...         {
...             "from_id": "edge_from",
...             "to_id": "edge_to",
...             "id": "edge_id",
...             "flow_capacity": "capacity",
...             "gcost_usd_per_ton": "cost",
...         },
...     )
...     loaded.to_dataframe().to_dict("records")
[{'edge_from': 'A', 'edge_to': 'B', 'edge_id': 'E1', 'capacity': 100, 'cost': 10.5}]

Table of Contents