Flows distribution#

class libadalina_analytics.flows_distribution.GraphCost(name: str, cost_per_unit: float, weight: float)[source]#
cost_per_unit: float#

The cost per unit of the cost attribute.

name: str#

The name of the cost attribute in the graph edges.

weight: float#

The weight of the cost attribute in the overall cost calculation. The sum of all weights must be equal to 1.0.

libadalina_analytics.flows_distribution.flows_distribution_algorithm(graph: Graph, shapes_df: DataFrame | GeoDataFrame | DataFrame, flows_df: DataFrame | GeoDataFrame | DataFrame, graph_costs: list[GraphCost], shapes_id_column: str = 'id', flows_origin_id_column: str = 'origin_id', flows_destination_id_column: str = 'destination_id', flows_demand_column: str = 'demand', sources: list | None = None, destinations: list | None = None) → DataFrame | GeoDataFrame[source]#

Distribute flow demands between origin and destination areas on a graph while minimizing total transportation costs.

Parameters:

  • graph (nx.Graph) – The networkx graph on which to distribute the flows. The graph edges must contain the cost attributes specified in graph_costs.

  • shapes_df (pandas.DataFrame or geopandas.GeoDataFrame or pyspark.DataFrame) – A DataFrame containing the shapes of the areas with their geometries and identifiers.

  • flows_df (pandas.DataFrame or geopandas.GeoDataFrame or pyspark.DataFrame) – A DataFrame containing the flows to distribute, with origin and destination identifiers and demand values.

  • graph_costs (list[GraphCost]) – A list of GraphCost objects defining the cost attributes to consider in the graph edges, their cost per unit, and their weights in the overall cost calculation. The sum of all weights must be equal to 1.0.

  • shapes_id_column (str) – The name of the column in shapes_df containing the area identifiers. Default is ‘id’.

  • flows_origin_id_column (str) – The name of the column in flows_df containing the origin area identifiers. Default is ‘origin_id’.

  • flows_destination_id_column (str) – The name of the column in flows_df containing the destination area identifiers. Default is ‘destination_id’.

  • flows_demand_column (str) – The name of the column in flows_df containing the demand values to distribute. Default is ‘demand’.

  • sources (list | None) – An optional list of origin area identifiers to filter the flows. If provided, only flows with origins in this list will be considered. Default is None. Identifiers must be of the same type as the ones in flows_origin_id_column.

  • destinations (list | None) – An optional list of destination area identifiers to filter the flows. If provided, only flows with destinations in this list will be considered. Default is None. Identifiers must be of the same type as the ones in flows_destination_id_column.

Returns:

The DataFrame flows_df enriched with columns for the computed path, its geometry, the total path cost, and the individual costs for each pair or origin and destination areas. If the input flows_df is a pandas DataFrame or a geopandas GeoDataFrame, the output will be a geopandas GeoDataFrame, otherwise a pyspark DataFrame.

Return type:

pandas.DataFrame or geopandas.GeoDataFrame or pyspark.DataFrame