FlowDataFrame

FlowDataFrame is fastmob's sparse origin-destination wrapper. It represents an aggregate flow table independently of the trajectory hierarchy, while a Trips collection with global endpoint locations can create one directly.

Required data

The table needs origin, destination, and flow-value columns. A tessellation or location geometry table is optional and enables geometry lookup and legacy mapping helpers. Column names can be supplied explicitly when constructing the wrapper.

from fastmob import FlowDataFrame

flows = FlowDataFrame({
    "origin": ["A", "A"],
    "destination": ["B", "C"],
    "flow": [12, 4],
})

between_a_and_b = flows.get_flow("A", "B")
matrix = flows.to_matrix()

For trajectory-derived flows, start from Trips and call to_flow_dataframe() after assigning global location IDs.

API

`fastmob.core.flow_dataframe.FlowDataFrame`

Bases: BaseDataFrame

Narwhals-backed wrapper for origin-destination flow data.

Stores a flow table with columns origin, destination, and flow, optionally coupled with a spatial tessellation (geopandas.GeoDataFrame).

Parameters:

Name	Type	Description	Default
`df`	`DataFrame - like`	Source data. Accepted types: `pandas.DataFrame`, `polars.DataFrame`, any Narwhals-compatible eager frame, `list`, `numpy.ndarray`, or `dict`.	`None`
`origin`	`str`	Column name for origin tile IDs. Default `'origin'`.	`ORIGIN`
`destination`	`str`	Column name for destination tile IDs. Default `'destination'`.	`DESTINATION`
`flow`	`str`	Column name for flow values. Default `'flow'`.	`FLOW`
`tile_id`	`str`	Column name for tile IDs in the tessellation. Default `'tile_id'`.	`TILE_ID`
`tessellation`	`GeoDataFrame`	Spatial tessellation associated with the flow data.	`None`
`parameters`	`dict`	Arbitrary metadata dictionary. Default `{}`.	`None`

Examples:

>>> import pandas as pd
>>> import fastmob
>>> flows = pd.DataFrame({
...     "origin": ["A", "A", "B"],
...     "destination": ["A", "B", "A"],
...     "flow": [100, 50, 30],
... })
>>> fdf = fastmob.FlowDataFrame(flows)
>>> fdf.get_flow("A", "B")
50

`common_part_of_commuters(other)`

Compare sparse OD flows with another FlowDataFrame using Rust CPC.

Parameters:

Name	Type	Description	Default
`other`	`FlowDataFrame`	Reference sparse OD flows with the same location identity scheme.	required

Returns:

Type	Description
`float`	Common part of commuters score.

Examples:

>>> score = flows.common_part_of_commuters(reference_flows)

`common_part_of_links(other)`

Return the common part of links score against another flow table.

Parameters:

Name	Type	Description	Default
`other`	`FlowDataFrame`	Reference sparse OD flows.	required

Returns:

Type	Description
`float`	Common part of links score.

Examples:

>>> score = flows.common_part_of_links(reference_flows)

`get_flow(origin_id, destination_id)`

Return the flow between two tile IDs (0 if no such pair exists).

Parameters:

Name	Type	Description	Default
`origin_id`	`str`	Origin tile identifier.	required
`destination_id`	`str`	Destination tile identifier.	required

Returns:

Type	Description
`int or float`	Flow value, or 0 if the pair is not present.

Examples:

>>> import pandas as pd
>>> import fastmob
>>> flows = pd.DataFrame({
...     "origin": ["A", "A", "B"],
...     "destination": ["A", "B", "A"],
...     "flow": [100, 50, 30],
... })
>>> fdf = fastmob.FlowDataFrame(flows)
>>> fdf.get_flow("A", "B")
50
>>> fdf.get_flow("B", "C")
0

`get_geometry(tile_id)`

Return the geometry of a tessellation tile.

Parameters:

Name	Type	Description	Default
`tile_id`	`str`	Identifier of the tile to look up.	required

Returns:

Type	Description
`shapely geometry`	The geometry associated with tile_id in the tessellation.

Raises:

Type	Description
`ValueError`	If no tessellation is attached or the tile ID is not found.

Examples:

>>> import fastmob
>>> fdf = fastmob.data.load_dataset("flow_foursquare_nyc")
>>> geom = fdf.get_geometry("36005")

`settings_from(other)`

Copy metadata attributes from another FlowDataFrame.

Parameters:

Name	Type	Description	Default
`other`	`FlowDataFrame`	Source FlowDataFrame to copy attributes from.	required

Examples:

>>> import pandas as pd
>>> import fastmob
>>> flows = pd.DataFrame({"origin": ["A"], "destination": ["B"], "flow": [10]})
>>> fdf1 = fastmob.FlowDataFrame(flows.copy())
>>> fdf2 = fastmob.FlowDataFrame(flows.copy(), parameters={"year": 2020})
>>> fdf1.settings_from(fdf2)
>>> fdf1.parameters
{'year': 2020}

`to_matrix()`

Convert the flow table to a numpy matrix.

The rows and columns are ordered by the tile IDs in the tessellation (if present) or by the sorted union of all origin and destination IDs.

Returns:

Type	Description
`ndarray`	Square flow matrix of shape `(n_tiles, n_tiles)`.

Examples:

>>> import pandas as pd
>>> import fastmob
>>> flows = pd.DataFrame({
...     "origin": ["A", "A", "B"],
...     "destination": ["A", "B", "A"],
...     "flow": [100, 50, 30],
... })
>>> fdf = fastmob.FlowDataFrame(flows)
>>> fdf.to_matrix()
array([[100.,  50.],
       [ 30.,   0.]])