quetzal.engine.engine module

quetzal.engine.engine.aggregate_shares(shared, zones)[source]

Aggregates modal shares by zone. Weights the share by the demand; :param shared: straight output from the modal split; :param zones: zoning GeoDataFrame :return: aggregated_shares, the zoning augmented with the modal shares as columns;

quetzal.engine.engine.attraction_share_pt(shared, destination)[source]
quetzal.engine.engine.emission_share_pt(shared, origin)[source]

Decorates a link dataframe so it can be used as a basis for building a graph; It is meant to be used on a LineDraft export link DataFrame; :param links: LineDraft link DataFrame; :return: Basically the same as links but with different names and trivial columns;

The assignment function. The last step of modelling the demand.

  • the shortest path are known in the public transport graph;

  • the demand by mode is known;

  • we want to assign the demand to the edges and nodes of the shortest path for every OD

example:

links, nodes = engine.loaded_links_and_nodes(
links, nodes, shared, path_finder_stack, 'volume_pt')
Parameters

  • links – links DataFrame to be loaded

  • nodes – nodes DataFrame to be loaded

  • volumes – demand stack matrix by mode

  • path_finder_stack – paths stack matrix (pathfinder output)

  • od_stack – path / demand merged stack matrix

  • volume_column – name of the column from ‘volumes’ to use in order to load the links and nodes

  • pivot_column – name of the column from od_stack to multiply with volumes. Default None

Returns

(links, nodes) a tuple containing the loaded DataFrames

quetzal.engine.engine.modal_split_from_volumes_and_los(volumes, los, time_scale=0.0002777777777777778, alpha_car=2, beta_car=0)[source]

This is a modal split wrapper essentially based on duration and modal penalties. Based on all modes demand and levels of services, it returns the volume by mode.

Example

los = pd.merge(

car_skims, path_finder_stack, on=[‘origin’, ‘destination’], suffixes=[‘_car’, ‘_pt’]

) shared = engine.modal_split_from_volumes_and_los(

volumes, los, time_scale=1/1800 alpha_cal=2, beta_car=600

)

Parameters

  • volumes – all mode, origin->destination demand matrix;

  • los – levels of service. An od stack matrix with: ‘duration_pt’, ‘duration_car’

  • time_scale – time scale of the logistic regression that compares ‘duration_pt’ to alpha_car * ‘duration_car’ + beta_car

  • alpha_car – multiplicative penalty on ‘duration_car’ for the calculation of ‘utility_car’

  • beta_car – additive penalty on ‘duration_car’ for the calculation of ‘utility_car’

Returns

quetzal.engine.engine.multimodal_graph(links, ntlegs, pole_set, footpaths=None, boarding_cost=300, ntlegs_penalty=1000000000.0)[source]
This is a graph builder and a pathfinder wrapper

  • Builds a public transport frequency graph from links;

  • Adds access and eggress to the graph (accegg) using the ntlegs;

  • Search for shortest paths in the time graph;

  • Returns an Origin->Destination stack matrix with path and duration;

example:

links = engine.graph_links(links) # links is a LineDraft export
path_finder_stack = engine.path_and_duration_from_links_and_ntlegs(
    links,
    ntlegs
)
Parameters

  • links – link DataFrame, built with graph_links;

  • ntlegs – ntlegs DataFrame built;

  • boarding_cost – an artificial cost to add the boarding edges of the frequency graph (seconds);

  • ntlegs_penalty – (default 1e9) high time penalty in seconds to ensure ntlegs are used only once for access and once for eggress;

Returns

Origin->Destination stack matrix with path and duration;

quetzal.engine.engine.ntlegs_from_centroids_and_nodes(centroids, nodes, short_leg_speed=3, long_leg_speed=15, threshold=500, n_neighbors=5, coordinates_unit='degree')[source]

From a given zoning an a given set of nodes, links the nearest nodes to each centroid of the zoning.

example:

centroids = zones.copy()
centroids['geometry'] = centroids['geometry'].apply(lambda g: g.centroid)
ntlegs = engine.ntlegs_from_centroids_and_nodes(
    centroids,
    nodes,
    ntleg_speed=3,
    n_neighbors=6
)
Parameters

  • centroids – a point GeoDataFrame indexed by a numeric index;

  • nodes – a point GeoDataFrame indexed by a numeric index;

  • ntleg_speed – speed, as a crow flies, along the ntlegs km/h;

  • n_neighbors – number of ntleg of each centroid;

  • coordinates_unit – degree or meter

Returns

ntlegs, a line GeoDataFrame containing the ids of the the centroid and the node, the distance and the proximity rank;

:rtype : line GeoDataFrame

quetzal.engine.engine.od_volume_from_zones(zones, deterrence_matrix=None, power=2, coordinates_unit='degree', intrazonal=False)[source]
Use this function to build an Origin -> Destination demand matrix.
  • a deterrence matrix can be provided, if not:

    • The euclidean distance matrix will be calculated automatically.

    • The deterrence matrix will be calculated from the distance matrix

      (elevated to a given power)

  • A doubly constrained distribution will be performed in the end,

    it is based on zones[‘emission’] and zones[‘attraction’]

examples:

volumes = engine.od_volume_from_zones(zones, power=2)
volumes = engine.od_volume_from_zones(zones, friction_matrix)
Parameters

  • zones – zoning GeoDataFrame, indexed by the zones numeric contains a geometry column named ‘geometry’, productions and attractions

  • deterrence_matrix – Default None. The deterrence matrix used to compute the distribution. If not provided, a deterrence matrix will automatically be computed from the euclidean distance elevated to a given power.

  • power – the friction curve used in the gravity model is equal to the euclidean distance to the power of this exponent

  • intrazonal – (bool) if True, computes intrazonal volumes using a zone characteristic distance. Default False.

Returns

volumes, a DataFrame with the following columns [‘origin’, ‘destination’, ‘volume’]

This is a graph builder and a pathfinder wrapper

  • Builds a public transport frequency graph from links;

  • Adds access and eggress to the graph (accegg) using the ntlegs;

  • Search for shortest paths in the time graph;

  • Returns an Origin->Destination stack matrix with path and duration;

example:

links = engine.graph_links(links) # links is a LineDraft export
path_finder_stack = engine.path_and_duration_from_links_and_ntlegs(
    links,
    ntlegs
)
Parameters

  • links – link DataFrame, built with graph_links;

  • ntlegs – ntlegs DataFrame built;

  • boarding_cost – an artificial cost to add the boarding edges of the frequency graph (seconds);

  • ntlegs_penalty – (default 1e9) high time penalty in seconds to ensure ntlegs are used only once for access and once for eggress;

Returns

Origin->Destination stack matrix with path and duration;