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]¶

quetzal.engine.engine.graph_links(links)[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;

quetzal.engine.engine.loaded_links_and_nodes(links, nodes, volumes=None, path_finder_stack=None, volume_column='volume', path_column='path', pivot_column=None, boardings=False, alightings=False, transfers=False, link_checkpoints=set(), node_checkpoints=set(), checkpoints_how='all')[source]¶

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, boarding_cost=300, footpaths=None)[source]¶

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, impedance_matrix=None, power=2, coordinates_unit='degree', intrazonal=False)[source]¶

Use this function to build an Origin -> Destination demand matrix.

an impedance matrix can be provided, if not:
- The euclidean distance matrix will be calculated automatically.
- The friction 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
impedance_matrix – Default None. The impedance matrix used to compute the distribution. If not provided, an impedance 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’]

quetzal.engine.engine.path_and_duration_from_links_and_ntlegs(links, ntlegs, pole_set, footpaths=None, boarding_cost=300)[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);
Returns:	Origin->Destination stack matrix with path and duration;