mapmatcher4gmns 0.1.8

A high-performance map matching tool for GMNS networks

MapMatcher4GMNS

A high-performance map matching tool for GPS trajectories on GMNS (General Modeling Network Specification) networks.

Features

• High-Performance Map Matching: Efficient Hidden Markov Model (HMM) based map matching algorithm
• GMNS Network Support: Native support for GMNS network format (node.csv, link.csv)
• Multi-Core Processing: Built-in parallel processing support for large-scale GPS data
• Flexible Configuration: Comprehensive parameters for fine-tuning matching quality
• Route Generation: Automatic generation of complete routes between matched points

Installation

From PyPI

pip install mapmatcher4gmns

Quick Start

import mapmatcher4gmns as m4g

def main():
    # Load network from GMNS format
    net = m4g.LoadNetFromCSV(
        folder='path/to/network',
        node_file='node.csv',
        link_file='link.csv'
    )

    # Create matcher
    matcher = m4g.MapMatcher(
        network=net,
        time_field='timestamp',
        time_format='%Y-%m-%dT%H:%M:%S.%fZ',
        out_dir='output',
        result_file='matched_result.csv',
        route_file='matched_route.csv',
    )

    # Perform map matching (pass CSV path)
    matcher.match('gps_data.csv')

    # Note: match(...) accepts CSV path string input.

if __name__ == '__main__':
    main()

Input Data Requirements

Network Files (GMNS Format)

node.csv (required fields):

• node_id: Unique node identifier
• x_coord: Longitude (if coordinate_type='lonlat') or X coordinate
• y_coord: Latitude (if coordinate_type='lonlat') or Y coordinate

link.csv (required fields):

• link_id: Unique link identifier
• from_node_id: Starting node ID
• to_node_id: Ending node ID
• lanes: Number of lanes
• geometry: LineString geometry in WKT format

GPS Data

Required fields:

• journey_id (or custom agent_field): Unique identifier for each GPS trajectory
• longitude: GPS longitude
• latitude: GPS latitude

Optional but recommended:

• time (or custom time_field): Timestamp for temporal ordering
• speed: Speed
• heading: Heading direction in degrees

Configuration Parameters

Core Matching Parameters

• search_radius (default: 15.0): Search radius in meters for candidate links
• noise_sigma (default: 8.0): GPS noise standard deviation in meters
• trans_weight (default: 12.0): Weight for transition probability
• max_candidates (default: 10): Maximum number of candidate links per GPS point

Movement Consistency

• turn_sigma (default: 45.0): Turn angle standard deviation in degrees
• heading_sigma (default: 30.0): Heading difference standard deviation
• use_heading (default: True): Whether to use heading information

Filtering

• filter_dwell (default: True): Filter out stationary points
• dwell_dist (default: 5.0): Distance threshold for dwell detection in meters
• dwell_count (default: 2): Minimum consecutive points to be considered dwelling
• max_gap_seconds (default: 45.0): Maximum time gap allowed between consecutive points

Performance

• core_num: Number of CPU cores to use (default: 1). If set above os.cpu_count(), it is capped to available CPU cores.
• max_agents (default: None): Maximum number of trajectories to process (useful for testing/debugging). If set, only the first N trajectories will be matched

Output

The tool generates two main output files:

1. Matched Results (matched_result.csv)

Contains the matched GPS points with:

• journey_id: Trajectory identifier
• seq: Sequence number
• time: Timestamp
• link_id: Matched link ID
• from_node_id, to_node_id: Link endpoints
• longitude, latitude: Original GPS coordinates
• speed_mph: Speed (if provided)
• match_heading: Heading of matched link
• route_dis: Culmulative route distance

2. Route File (matched_route.csv)

Contains the complete route for each journey:

• journey_id: Trajectory identifier
• link_ids: Comma-separated list of link IDs forming the complete route

3. Run Summary (summary.txt)

Contains run-level summary statistics:

• Input/kept/dropped/matched journeys
• Input/matched data points and match rate
• Total elapsed time

Advanced Usage

Note: When using multiprocessing features, wrap your code in if __name__ == '__main__': to avoid issues, especially on Windows.

Multi-Core Processing

matcher = m4g.MapMatcher(
    network=net,
    core_num=2,  # Use 2 CPU cores
    # ... other parameters
)

Large CSV (Memory-Safe Streaming)

For very large GPS files (for example, 100M+ rows), avoid loading all rows into memory at once. Pass CSV path directly to match(...).

In streaming mode, the matcher internally hashes journey_id into temporary partitions first, then processes partition files. This keeps the same journey_id in one partition without requiring a global CSV sort.

matcher = m4g.MapMatcher(
    network=net,
    time_field='local_time',
    time_format='%Y-%m-%dT%H:%M:%S%z',
    out_dir='output',
    result_file='matched_result.csv',
    route_file='matched_route.csv',
    core_num=1,
)

matcher.match('data.csv')

Custom Field Names

matcher = m4g.MapMatcher(
    network=net,
    agent_field='vehicle_id',  # Custom trajectory ID field
    lng_field='lon',           # Custom longitude field
    lat_field='lat',            # Custom latitude field
    time_field='timestamp',     # Custom time field
    # ... other parameters
)

Extra Fields

Keep additional fields from input GPS data in the output:

matcher = m4g.MapMatcher(
    network=net,
    extra_fields=['vehicle_type', 'driver_id', 'trip_purpose'],
    # ... other parameters
)

Requirements

• Python >= 3.8
• numpy >= 1.20.0
• pandas >= 1.3.0
• shapely >= 2.0.0
• geopandas >= 0.10.0
• networkx >= 2.6.0
• tqdm >= 4.60.0

Citation

If you use this tool in your research, please cite this tool.

[Add your citation here]

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

This package was inspired by and references the excellent work of the TrackIt (GoTrackIt) project. We are grateful for their contributions to the open-source map matching community and their innovative approach to HMM-based map matching algorithms.

References

• TrackIt/GoTrackIt: A comprehensive map matching Python package based on Hidden Markov Model (HMM)
  • GitHub: https://github.com/zdsjjtTLG/TrackIt
  • Documentation: https://gotrackit.readthedocs.io/
  • Developed by: TangKai and contributors at Hangzhou Zecheng Data Technology Co., Ltd.

This tool is designed to work with the General Modeling Network Specification (GMNS) format, supporting transportation network analysis and GPS trajectory processing.

Support

For questions, issues, or feature requests, please contact us.