API References#

This page contains the API References for the existing functions in MapMatcher.

Trip#

class mapmatcher.trip.Trip(gps_trace: GeoDataFrame, parameters: Parameters, network: Network)#

Bases: object

Builds the path a vehicle did.

>>> from mapmatcher.trip import Trip

>>> trip = Trip(gps_trace, parameters, network)
>>> trip.map_match()

>>> trip.result.plot()

__init__(gps_trace: GeoDataFrame, parameters: Parameters, network: Network)#

Arguments:

gps_trace (gpd.GeoDataFrame): GeoDataFrame containing the vehicle GPS traces.

parameters (Parameters): Map-Matching parameters.

network (mapmatcher.network.Network): MapMatcher Network object.

map_match(ignore_errors=False)#

Performs map-matching.

Arguments:: ignore_errors (bool):

property success#: Indicates the success of the map-matching procedure. If it succeeded, it returns 1, otherwise returns 0.

property path_shape: LineString#: Returns the shapely.LineString that represents the map-matched path.

property result#: Returns a GeoDataFrame containing the network links selected in map-matching.

property coverage: float#: Returns the distance (in metres) between the bounds of the geometries that represent the path.

property has_error: bool#: Indicates the presence of errors during the map-matching process. Returns True if there are any errors, otherwise, it returns False.

compute_stops()#: Compute stops.

property match_quality#: Assesses the map-matching quality. Returns the percentage of GPS pings close to the map-matched trip.

property distance_ratio#

property match_quality_raw#

Network#

class mapmatcher.network.Network(graph: Graph, links: GeoDataFrame, parameters: Parameters)#

Bases: object

Creates the properties for the outputs.

>>> from mapmatcher.network import Network

>>> network = Network(graph, links, parameters)

__init__(graph: Graph, links: GeoDataFrame, parameters: Parameters)#

Arguments:

graph (aequilibrae.graph.Graph): AequilibraE graph

links (gpd.GeoDataFrame): GeoDataFrame containing the network links

parameters (Parameters): Map-Matching parameters.

property has_speed: bool#: Returns True if there is a speed field, otherwise it returns False.

set_speed_field(speed_field: str)#: Sets the speed field, if it exists.

discount_graph(links: ndarray)#: Updates the costs for each link in the graph.

reset_graph()#: Resets the current graph.

Mapmatcher#

class mapmatcher.map_matcher.MapMatcher#

Bases: object

Performs map-matching.

>>> from mapmatcher import MapMatcher

>>> matcher = MapMatcher.from_aequilibrae(project, "c")
>>> matcher.load_gps_traces(nauru_gps)
>>> matcher.map_match()

__init__()#

static from_aequilibrae(proj: Project, mode: str)#

Loads the network and creates the graph from an existing AequilibraE project.

Arguments:

proj (aequilibrae.project.Project): path to existing project.

mode (str): mode to create the graph

set_output_folder(output_folder: str)#

Name of the output folder.

Arguments:: output_folder (str): path to folder

load_network(graph: Graph, links: GeoDataFrame)#

Loads the project network.

Arguments:

graph (aequilibrae.graph.Graph): AequilibraE graph

links (gpd.GeoDataFrame): GeoDataFrame with the network links

load_gps_traces(gps_traces: GeoDataFrame | PathLike, crs: int | None = None)#

Loads the GPS traces to the map-matcher.

Coordinate system for GPS pings must ALWAYS be 4326 when loading from CSV. Required fields are: [“trace_id”, “latitude”, “longitude”, “timestamp”]

Arguments:

gps_trace (gpd.GeoDataFrame): GeoDataFrame containing the vehicle GPS traces.

crs (:obj: int, optional): coordinate system

map_match(ignore_errors=False, parallel_threads: int = 0)#

Executes map-matching.

Arguments:

ignore_errors (bool): Attempts to perform map-matching even when the data does not meet all data quality criteria

parallel_threads (int, optional): Number of CPU threads to use. Defaults to all

Returns:

object (np.ndarray): NumPy array

set_logging_folder(folder)#

Parameters#

class mapmatcher.parameters.geoprocessing(projected_crs: int = 3857)#

Bases: object

projected_crs: int = 3857#

__init__(projected_crs: int = 3857) → None#

class mapmatcher.parameters.data_quality(max_speed: float = 36.1, max_speed_time: float = 120, minimum_pings: int = 15, minimum_coverage: float = 500, maximum_jittery: float = 1)#

Bases: object

max_speed: float = 36.1#

max_speed_time: float = 120#

minimum_pings: int = 15#

minimum_coverage: float = 500#

maximum_jittery: float = 1#

__init__(max_speed: float = 36.1, max_speed_time: float = 120, minimum_pings: int = 15, minimum_coverage: float = 500, maximum_jittery: float = 1) → None#

class mapmatcher.parameters.map_matching(cost_discount: float = 0.1, buffer_size: float = 20, minimum_match_quality: float = 0.99, maximum_waypoints: int = 20, keep_ping_classification: bool = True, heading_tolerance: float = 22.5)#

Bases: object

cost_discount: float = 0.1#

buffer_size: float = 20#

minimum_match_quality: float = 0.99#

maximum_waypoints: int = 20#

keep_ping_classification: bool = True#

heading_tolerance: float = 22.5#

__init__(cost_discount: float = 0.1, buffer_size: float = 20, minimum_match_quality: float = 0.99, maximum_waypoints: int = 20, keep_ping_classification: bool = True, heading_tolerance: float = 22.5) → None#

class mapmatcher.parameters.DeliveryStop(stopped_speed: float = 2.22, min_time_stopped: float = 300, max_time_stopped: float = 14400, max_stop_coverage: float = 800)#

Bases: object

stopped_speed: float = 2.22#

min_time_stopped: float = 300#

max_time_stopped: float = 14400#

max_stop_coverage: float = 800#

__init__(stopped_speed: float = 2.22, min_time_stopped: float = 300, max_time_stopped: float = 14400, max_stop_coverage: float = 800) → None#

class mapmatcher.parameters.Parameters#

Bases: object

geoprocessing = geoprocessing(projected_crs=3857)#

data_quality = data_quality(max_speed=36.1, max_speed_time=120, minimum_pings=15, minimum_coverage=500, maximum_jittery=1)#

stop_finding = DeliveryStop(stopped_speed=2.22, min_time_stopped=300, max_time_stopped=14400, max_stop_coverage=800)#

map_matching = map_matching(cost_discount=0.1, buffer_size=20, minimum_match_quality=0.99, maximum_waypoints=20, keep_ping_classification=True, heading_tolerance=22.5)#

__init__() → None#