.. _spat_module:

SPaT data
##############################################

.. sectionauthor:: Zhen Yang <zhenyang@umich.edu>

Overview
**************************************

**The Signal Phasing and Timing (SPaT) module is used to load and process the SPaT data. The SPaT data is very important
for the trajectory data at signalized intersections. By matching the SPaT data with the trajectory data, the traffic
state and the vehicle behaviours can be analyzed. The SPaT information of each movement at each signalized intersection
is stored in a Pandas data framework, and can be visualized and queried depending on the research needs.**

Structure
************************************************

The MTLDP structures SPaT data in a three-level framework:

.. image:: ../_static/overview/spat_data_structure.png
    :width: 100%
    :align: center
    :alt: SPaT data structure

In this UML diagram, each block in the figure represents a class, and the links show the aggregation relationship. The
``SPaTCollection`` class includes a dictionary of ``NodeSPaT`` objects. A major class function in the ``SPaTCollection`` class is
``add_node_spat()``, which append the dictionary with a given ``NodeSPaT`` object.
It also includes the function of ``load_spat_csv()``, which
loads predefined standard csv files. The format of the standard csv file is introduced in the next section. The function
of ``output_spat_csv()`` is the inverse function of ``load_spat_csv()``, which output the SPaT data from the ``SPaTCollection`` to a
standard csv file. The ``NodeSPaT`` class includes a dictionary of ``MovementSPaT`` objects. It also includes the function of
``add_movement_signal_state()``, which append the dictionary with a given ``MovementSPaT`` object.

The ``MovementSPaT`` class includes the Pandas dataframe that stores the SPaT data of each movement in a tabular fashion.
This is also the fundamental class that includes several key functions. Given a specific timestamp, ``get_signal_state()``
can output the corresponding signal state. Given a **sorted** list of timestamp, ``get_signal_states()`` can output the
corresponding list of signal state. In the traffic state estimation or traffic signal optimization, it is also important
to know the corresponding start of the green time for a given timestamp, so ``get_green_start()`` function is designed
accordingly.


Standard csv file format for SPaT data
************************************************
The figure below shows the standard csv file format for SPaT data. Raw SPaT data needs to be first converted into this
format, since the SPaT data in this format can be fast retrieved by Pandas dataframe in the SPaT data structure of this
project. The standard csv file includes the entries of ``node_id``, ``movement_id``, ``start_time``, ``end_time``, ``duration``, and
``signal_state``. ``start_time`` and ``end_time`` represents the start time and the end time of the phase associated
with the movement of ``movement_id`` at the node of ``node_id``. ``duration`` is equal to ``end_time`` - ``start_time``.
``signal_state`` should be a string, chosen from "Red", "Yellow" or "Green".

The SPaT data should be aggregated by node_id and movement_id, so the csv table can be easily partitioned
to sub tables. For the SPaT data of each movement, they should be sorted by the start_time. Examples of generating such
standard csv file format can be found in ``mtldp.adapters.aacvte_spat``.

.. image:: ../_static/overview/spat_standard_csv.png
    :width: 100%
    :align: center
    :alt: Standard csv file format for SPaT data