.. _getting_started:

.. currentmodule:: tasi

Getting started
#################

Hi there and welcome to the getting started guide of ``TASI`` 👋😀 This page
shall help to get started right away with instructions on how to install
``TASI`` and a description of the main ``TASI`` concepts. You may visit the
following links one after another. Note that the sections may contain links to
external pages. It is recommended to visit those links before continuing. If you
have any questions regarding ``TASI``, feel free raise an issue. Happy reading
😁

Installation
--------------
An always up-2-date version of ``TASI`` is available via the `Pypi
<https://pypi.org/project/tasi/>`_ registry. So, to get started with ``TASI``,
it is just a  matter of installing tasi with

.. code-block:: bash

    pip install tasi


The previous command will install the base version of ``TASI``. Extensions can
be installed via the following *extras*. 

.. list-table:: Available extras
    :widths: auto
    :header-rows: 1

    * - Extra 
      - Description
    * - all
      - Full version of ``TASI`` with all extensions
    * - geo
      - Models for representing data using GeoObjects
    * - visualization
      - Add visualization capabilities
    * - wms 
      - Add additional visualization capabilities of layers from WMS/WFS
    * - io 
      - Add the input/output interface based on `pydantic` and `SQLAlchemy`



Basic concepts
---------------
Similar to `pandas`_ and `geopandas`_ in ``TASI``, we represent traffic data
using a tabular-styled format. To achive this, ``TASI`` extends `pandas`_  and
`geopandas`_ to provide functionality for traffic data analysis. The top-level
model is the :py:class:`Dataset` as illustrated in :numref:`tasi_dataset`. Every
row in a :py:class:`Dataset` contains information for a specific point in time
as attributes. That is, an attribute can be any relevant traffic information,
e.g., the position of a traffic participant or the rain intensity.


.. _tasi_dataset:
.. figure:: ../_static/dataset.png
    :width: 100%
    :align: center
    :alt: TASI dataset model
    :figclass: align-center
    :name: tasi-dataset

    The top level model for traffic data representation is the
    :py:class:`Dataset`.

Most of the time, we will work with information about the traffic participants
that are represented in the :py:class:`Dataset`. To make live a little bit
easier, ``TASI`` uses a hierarchical view on trajectory data based on the
:py:class:`Dataset` as illustrated in :numref:`tasi_trajectory_data`. Since a
:py:class:`Dataset` typically contains information about multiple traffic
participants, each having a trajectory, the :py:class:`Dataset` is a container
for multiple :py:class:`Trajectory`. This is denoted with the different `id`
values and color encoded rows. Furthermore, since a single row is a
representation of a traffic participant's state in a specific point in time, the
:py:class:`Pose`

representation of a traffic participant's state for a specific point in time is
with the  class.

.. _tasi_trajectory_data:
.. figure:: ../_static/pose_trajectory.png
    :width: 100%
    :align: center
    :alt: TASI trajectory and pose model
    :figclass: align-center

    Hierarchical view on trajectory data.


Since ``TASI`` uses `Pandas`_ under the hood, head over to the official `pandas
User Guide <https://pandas.pydata.org/docs/user_guide/index.html>`_. Afterwards,
you may head over to the :ref:`User Guide <user_guide>` for some use-case
related examples using ``TASI``. If you want to contribute to ``TASI``, visit
:ref:`Development Documentation <contribute>` for further instructions.

.. _pandas: https://pandas.pydata.org
.. _geopandas: https://geopandas.org/en/stable/