Preparation#

Virtual Environment#

A virtual environment is highly recommended for all projects using mtldp. It can help you isolate your project environment from one to another. With a virtual environment, you can avoid most dependency issues and reproducible problems.

You can use Anaconda or Miniconda, or you can use python standard library venv.

Anaconda/Miniconda will be used in the following tutorial.

Create a virtual environment:

$ conda create -n mtldp python=3.8 -y
$ conda activate mtldp
(mtldp) $

Install system-level dependencies#

$ sudo apt install default-libmysqlclient-dev

Install#

Clone the repository:

$ git clone git@github.com:michigan-traffic-lab/mtldp-meta-utils.git

For user that only use this library, you can install the library directly:

(mtldp) $ cd mtldp-meta-utils && pip install .

For the developer of this library, install the library in develop/edit mode:

(mtldp) $ cd mtldp-meta-utils && pip install -e .
Tips:

In develop/edit mode, the packages (mtldp.meta and mtldp.utils) will be installed as a symbolic link. That means any changes you make to the source code will be reflected in the installed library. This is useful when you are developing the library itself.

A command line interfaces (CLI) are provided in mtldp.utils. Two commands are available: - create_config_file: create config file for any application based on mtldp - create_region: create the region that the application will work on.

You can use --help to validate the installation and see the usage of the command:

(mtldp) $ create_config_file --help

  Usage: create_config_file [OPTIONS]

 ╭─ Options ────────────────────────────────────────────────────────────────────╮
 │ *  --region         -n      TEXT                     Enter a unique region   │
 │                                                      ID can help you         │
 │                                                      distinguish with other  │
 │                                                      region                  │
 │                                                      [default: None]         │
 │                                                      [required]              │
 │ *  --city           -c      TEXT                     Give the city ID that   │
 │                                                      this region belongs to  │
 │                                                      [default: None]         │
 │                                                      [required]              │
 │    --mode           -m      [application|preprocess  Give purpose of         │
 │                             ing]                     creating this region    │
 │                                                      [default:               │
 │                                                      RegionMode.application] │
 │    --start-date     -s      TEXT                     Specify the start date  │
 │                                                      of the date range, only │
 │                                                      take effect in          │
 │                                                      application mode        │
 │    --end-date       -e      TEXT                     Specify the end date of │
 │                                                      the date range, only    │
 │                                                      take effect in          │
 │                                                      application mode        │
 │    --junction-ids   -j      TEXT                     Comma seperated         │
 │                                                      junction IDs related to │
 │                                                      the region, only take   │
 │                                                      effect in application   │
 │                                                      mode                    │
 │    --timezone       -t      TEXT                     Give the city ID that   │
 │                                                      this region belongs to  │
 │                                                      [default:               │
 │                                                      America/Detroit]        │
 │    --processed-dir  -p      TEXT                     Raw dir                 │
 │                                                      [default:               │
 │                                                      processed_data]         │
 │    --raw-dir        -r      TEXT                     Raw dir for non         │
 │                                                      processed data, only    │
 │                                                      take effect in          │
 │                                                      preprocessing mode      │
 │                                                      [default: raw_data]     │
 │    --help                                            Show this message and   │
 │                                                      exit.                   │
 ╰──────────────────────────────────────────────────────────────────────────────╯

Install mtldp.preproc (optional)#

mtldp.preproc is a plugin that contains some useful functions for preprocessing raw data including OSM map, CSV SPaT, and GPS trajectory data.

You will need this plugin only if you are working with raw data rather than processed data.

You may need extra permission to install this plugin. Please contact the MTL director: shengyin@umich.edu

Clone the repository:

$ git clone git@github.com:michigan-traffic-lab/mtldp-preproc.git

Install the library in develop/edit mode:

(mtldp) $ cd mtldp-preproc && pip install -e .

This plugin provides a command line interface (CLI) for preprocessing raw data. Five commands are available:

  • build_traffic_network: build traffic network from OSM map data

  • parse_spat: parse SPaT data from CSV files

  • split_trajs: split trajectories CSV files based on date

  • match_trajs_to_map: running fast map-matching algorithm to match trajectories to traffic network

  • calc_trajs_index: calculate the movement-level traffic index of trajectories

You can use --help to validate the installation and see the usage of the command:

(mtldp) $ parse_spat --help

  Usage: parse_spat [OPTIONS]

 ╭─ Options ────────────────────────────────────────────────────────────────────╮
 │ *  --config        -c      TEXT  Config file that includes parameters of the │
 │                                  region.                                     │
 │                                  [default: None]                             │
 │                                  [required]                                  │
 │    --junction-ids  -j      TEXT  Comma seperated junction ids, default for   │
 │                                  all junction in the region                  │
 │                                  [default: all]                              │
 │    --help                        Show this message and exit.                 │
 ╰──────────────────────────────────────────────────────────────────────────────╯