Maps

The type of map used to display data can be changed based on what works best for you application. Each map class must conform to the map interface defined in mappymatch.maps.map_interface.MapInterface.

Available Maps

For readability, the full path is listed below and not used in other parts of the documentation.

mappymatch.maps.nx.nx_map.NxMap

NxMap

class NxMap(graph: networkx.classes.multidigraph.MultiDiGraph)[source]

A road map that uses a networkx graph to represent its roads.

g: The networkx graph that represents the road map

crs: The coordinate reference system of the map

property distance_weight: str

Get the distance weight

Returns: The distance weight

classmethod from_dict(d: Dict[str, Any]) → mappymatch.maps.nx.nx_map.NxMap[source]: Build a NxMap instance from a dictionary

classmethod from_file(file: Union[str, pathlib.Path]) → mappymatch.maps.nx.nx_map.NxMap[source]

Build a NxMap instance from a file

Parameters: file – The graph pickle file to load the graph from
Returns: A NxMap instance

classmethod from_geofence(geofence: mappymatch.constructs.geofence.Geofence, xy: bool = True, network_type: mappymatch.maps.nx.readers.osm_readers.NetworkType = NetworkType.DRIVE) → mappymatch.maps.nx.nx_map.NxMap[source]

Read an OSM network graph into a NxMap

Parameters

geofence – the geofence to clip the graph to
xy – whether to use xy coordinates or lat/lon
network_type – the network type to use for the graph

Returns

a NxMap

nearest_road(coord: mappymatch.constructs.coordinate.Coordinate, buffer: float = 10.0) → mappymatch.constructs.road.Road[source]

A helper function to get the nearest road.

Parameters

coord – The coordinate to find the nearest road to
buffer – The buffer to search around the coordinate

Returns

The nearest road to the coordinate

road_by_id(road_id: mappymatch.constructs.road.RoadId) → Optional[mappymatch.constructs.road.Road][source]

Get a road by its id

Parameters: road_id – The id of the road to get
Returns: The road with the given id, or None if it does not exist

property roads: List[mappymatch.constructs.road.Road]

Get a list of all the roads in the map

Returns: A list of all the roads in the map

set_road_attributes(attributes: Dict[mappymatch.constructs.road.RoadId, Dict[str, Any]])[source]

Set the attributes of the roads in the map

Parameters: attributes – A dictionary mapping road ids to dictionaries of attributes
Returns: None

shortest_path(origin: mappymatch.constructs.coordinate.Coordinate, destination: mappymatch.constructs.coordinate.Coordinate, weight: Optional[Union[str, Callable]] = None) → List[mappymatch.constructs.road.Road][source]

Computes the shortest path between an origin and a destination

Parameters

origin – The origin coordinate
destination – The destination coordinate
weight – The weight to use for the path, either a string or a function

Returns

A list of roads that form the shortest path

property time_weight: str

Get the time weight

Returns: The time weight

to_dict() → Dict[str, Any][source]: Convert the map to a dictionary

to_file(outfile: Union[str, pathlib.Path])[source]

Save the graph to a pickle file

Parameters: outfile – The file to save the graph to

Utility Functions

Map interface

Each Matcher class must conform to the matcher interface defined below.

class MapInterface[source]

Abstract base class for a Matcher

abstract property distance_weight: str

Get the distance weight

Returns: The distance weight

abstract nearest_road(coord: mappymatch.constructs.coordinate.Coordinate) → mappymatch.constructs.road.Road[source]

Return the nearest road to a coordinate

Parameters: coord – The coordinate to find the nearest road to
Returns: The nearest road to the coordinate

abstract road_by_id(road_id: mappymatch.constructs.road.RoadId) → Optional[mappymatch.constructs.road.Road][source]

Get a road by its id

Parameters: road_id – The id of the road to get
Returns: The road with the given id or None if it does not exist

abstract property roads: List[mappymatch.constructs.road.Road]

Get a list of all the roads in the map

Returns: A list of all the roads in the map

abstract shortest_path(origin: mappymatch.constructs.coordinate.Coordinate, destination: mappymatch.constructs.coordinate.Coordinate, weight: Optional[Union[str, Callable]] = None) → List[mappymatch.constructs.road.Road][source]

Computes the shortest path on the road network

Parameters

origin – The origin coordinate
destination – The destination coordinate
weight – The weight to use for the path

Returns

A list of roads that form the shortest path

abstract property time_weight: str

Get the time weight

Returns: The time weight