Main modules

MTLDP is split into three Python packages that share the mtldp namespace, plus the tools around them. The packages are installed separately (see Preparation) but live in the same virtual environment.

Package	Repository	Role
mtldp.meta	mtldp-meta-utils	Data structures: traffic network, trajectory, SPaT.
mtldp.utils	mtldp-meta-utils	Everything that works on processed data: regions and paths, file I/O, time and geometry helpers, filters, aggregation, plots, database export, command line tools.
mtldp.preproc	mtldp-preproc	Raw data processing: OSM parsing and network building, map matching, trajectory indices.
mtldp-review	mtldp-review	Web tool to review and annotate the intermediate artifacts of a region (network, overrides).
mtldp-doc	mtldp-doc	This documentation and the example notebooks.

mtldp.meta

Three sub-packages, imported directly:

from mtldp.meta.TrafficNetwork import Network, SignalizedNetwork, Node, Link, Segment, Movement
from mtldp.meta.Trajectory import Trajectory, TrajectoryDict, Trip
from mtldp.meta.SPaT import HistoryRegionSPaT

• TrafficNetwork — Network and its elements (OsmWay, Node and its typed subclasses, Segment, Link, Movement, Arterial), SignalizedNetwork, NetworkLinkPath, BoundingBox and Geometry.

• Trajectory — Trajectory (points of one vehicle on one movement), TrajectoryDict and Trip, plus the canonical attribute name lists.

• SPaT — the history classes HistoryRegionSPaT and HistoryControllerSPaT and the period classes they resolve into.

The classes are plain containers with light helpers; they are documented in Data structures: mtldp.meta.

mtldp.utils

A namespace package of sub-modules:

Sub-module	Content
config	Region, ProdRegion, AppRegion, RawPathManager, ProcessedPathManager and the sub-region resolution rule (Regions and sub-regions).
scripts	The command line tools mtldp, create_config_file, create_region, create_sub_regions, copy_regions, extract_osm_map, delete_processed_trajs, draw_region_bbox (Command line tools of mtldp-meta-utils).
data_io	Pickle and GeoJSON export of networks, raw and processed trajectory readers, SPaT loaders, ProcessedDataLoader, OSMDownloader.
time	Conversions between timestamps, dates, clock times and time of day; date ranges.
geo_utils	Haversine distances, headings, local metric coordinates, movement-index convention.
filter	OSM bounding-box cutting with complete ways; trajectory selection.
aggregation	Movement, junction, link, region and arterial aggregation of the indices.
algs	Shortest paths on the link graph, time-of-day plan segmentation.
converter	Network layers and trajectories to DataFrame and back.
interpolation, performance	Point resampling; corridor travel time.
visualizer	Time-space diagrams, metric plots, tables, region map.
database	MySQL tables and upload.
common	Typer decorator, logging, chunking.

Each sub-module is described in Utilities: mtldp.utils.

mtldp.preproc

• build_network — OSM parsing and the construction of nodes, segments, links, movements, arterials and the signalized network; overrides; export for the map matcher; merging of split signal nodes.

• map_match — FmmModule around the Fast Map Matching library, input and output conversion, attachment of the map attributes to the matched points.

• process_trajs — cutting matched points into per-movement trajectories, distance to the stop bar, stops, delays and the other indices; quality-control metrics.

• scripts — the command line tools merge_osm, build_traffic_network, parse_spat, split_points, match_points_to_map, process_trajs, eva_trajs_qc (Command line tools of mtldp-preproc).

The internals are described in Pre-processing: mtldp.preproc and the end-to-end data flow in The raw data pipeline.

mtldp-review

A FastAPI back end (a thin layer over the mtldp packages) with a Vue front end that opens a region from its configuration file, displays the network layers exported as GeoJSON on a map and lets the reviewer inspect junctions, movements and arterials and record corrections. It is started with mtldp-review -c configs/<region>.json and reads the same files as AppRegion.