Installation

Requirements

python-mobilitydb has several dependencies beyond an installation of Python 3.x:

psycopg2 [http://initd.org/psycopg/docs/] or asyncpg [https://magicstack.github.io/asyncpg/] to connect to PostgreSQL,

postgis [https://github.com/tilery/python-postgis] to connect to PostGIS,

Spans [https://spans.readthedocs.io/] for an implementation of PostgreSQL’s range types,

python-dateutil [http://labix.org/python-dateutil] for extensions to the standard datetime module,

parsec [https://pythonhosted.org/parsec/] for parsing.

Python Package Index

python-mobilitydb may be installed from PyPI.

$ pip install python-mobilitydb

Source

The package sources are available at https://github.com/ULB-CoDE-WIT/python-mobilitydb. Building and installing python-mobilitydb from source can be done with setuptools [https://setuptools.readthedocs.io/en/latest/]:

$ python setup.py install

Tests

Tests require pytest [https://docs.pytest.org/en/latest/] and pytest-asyncio [https://github.com/pytest-dev/pytest-asyncio].

$ pytest

The PostgreSQL database server must be started before launching the tests.

Documentation

Building the documentation from source requires Sphinx [http://www.sphinx-doc.org/]. By default, the documentation will be rendered in HTML:

$ python setup.py build_sphinx

For other documentation output formats, see the options in the docs subdirectory:

$ cd docs
$ make

Basic usage

python-mobilitydb is a Python converter to and from the temporal types provided by MobilityDB [https://docs.mobilitydb.com/nightly/], that is tbool, tint, tfloat, ttext, tgeompoint, and tgeogpoint.

TBool, TInt, and TText

Classes TBool, TInt, and TText represent, respectively, temporal Booleans, temporal integers, and temporal strings. These classes have in common that their base type is discrete. As a consequence of this, the interpolation for the instances of sequence or sequence set duration is stepwise. We illustrate next how to create new instances of the TInt class, the creation of instances of the TBool and TText classes is similar.

New TInt instances can be created by using one of its subclasses TIntInst, TIntI, TIntSeq, or TIntS.

New TIntInst instances can be created either with a single string argument as in MobilityDB or with two arguments: the value and the timestamp.

>>> from dateutil.parser import parse
>>> from mobilitydb import TIntInst
>>> TIntInst("1@2020-01-01 00:00:00+01")
>>> TIntInst("1", "2020-01-01 00:00:00+01")
>>> TIntInst(1, parse("2020-01-01 00:00:00+01"))

New TIntI instances can be created either with a single string argument as in MobilityDB or with a tuple or list of the composing instants.

>>> from mobilitydb import TIntI
>>> TIntI("{1@2020-01-01, 2@2020-01-02}")
>>> TIntI(["1@2020-01-01", "2@2020-01-02"])
>>> TIntI("1@2020-01-01", "2@2020-01-02")
>>> TIntI(TIntInst(1, "2020-01-01"), TIntInst(2, "2020-01-02"))

New TIntSeq instances can be created either with a single string argument as in MobilityDB or with several arguments: the list of composing instants, the left inclusion flag, and the right inclusion flag, where only the first argument is mandatory.

>>> from mobilitydb import TIntSeq
>>> TIntSeq("[1@2020-01-01, 2@2020-01-02]")
>>> TIntSeq(["1@2020-01-01", "2@2020-01-02"], lower_inc= True, upper_inc=True)
>>> TIntSeq([TIntInst(1, "2020-01-01"), TIntInst(2, "2020-01-02")], lower_inc= True, upper_inc=True)

Finally, new TIntS instances can be created either with a single string argument as in MobilityDB or with a single argument: the list of composing sequences.

>>> from mobilitydb import TIntS
>>> TIntS("{[1@2020-01-01, 2@2020-01-02], [2@2020-01-03, 1@2020-01-04]}")
>>> TIntS(["[1@2020-01-01, 2@2020-01-02]", "[2@2020-01-03, 1@2020-01-04]"])
>>> TIntS([TIntSeq("[1@2020-01-01, 2@2020-01-02]"), TIntSeq("[2@2020-01-03, 1@2020-01-04]")])

TFloat

Class TFloat represents temporal floats. Since the base type of TFloat is continuous, the interpolation for instances of the sequence or sequence set duration may be either linear or stepwise, the former being the default.

New TFloat instances can be created by using one of its subclasses TFloatInst, TFloatI, TFloatSeq, or TFloatS.

New TFloatInst instances can be created either with a single string argument as in MobilityDB or with two arguments: the value and the timestamp.

>>> from dateutil.parser import parse
>>> from mobilitydb import TFloatInst
>>> TFloatInst("1.0@2020-01-01 00:00:00+01")
>>> TFloatInst("1.0", "2020-01-01 00:00:00+01")
>>> TFloatInst(1.0, parse("2020-01-01 00:00:00+01"))

New TFloatI instances can be created either with a single string argument as in MobilityDB or with a tuple or list of the composing instants.

>>> from mobilitydb import TFloatI
>>> TFloatI("{1.0@2020-01-01, 2.0@2020-01-02}")
>>> TFloatI(["1.0@2020-01-01", "2.0@2020-01-02"])
>>> TFloatI("1.0@2020-01-01", "2.0@2020-01-02")
>>> TFloatI(TFloatInst("1.0@2020-01-01"), TFloatInst("2.0@2020-01-02"))

New TFloatSeq instances can be created either with a single string argument as in MobilityDB or with several arguments: the list of composing instants, the left inclusion flag, the right inclusion flag, and the interpolation, where only the first argument is mandatory.

>>> from mobilitydb import TFloatSeq
>>> TFloatSeq("[1.0@2020-01-01, 2.0@2020-01-02]")
>>> TFloatSeq("Interp=Stepwise;[1.0@2020-01-01, 2.0@2020-01-02]")
>>> TFloatSeq(["1.0@2020-01-01", "2.0@2020-01-02"], lower_inc= True, upper_inc=True, interp='Stepwise')

Finally, new TFloatS instances can be created either with a single string argument as in MobilityDB or with two arguments: the list of composing sequences and the interpolation, where only the first argument is mandatory.

>>> from mobilitydb import TFloatS
>>> TFloatS("{[1.0@2020-01-01, 2.0@2020-01-02], [2.0@2020-01-03, 1.0@2020-01-04]}")
>>> TFloatS(["[1.0@2020-01-01, 2.0@2020-01-02]", "[2.0@2020-01-03, 1.0@2020-01-04]"], interp='Stepwise')

TGeomPoint and TGeogPoint

Class TGeomPoint represents temporal geometric points with Cartesian (planar) coordinates while TGeogPoint represents geographic points with geodetic (spherical) coordinates. Since the base type of these classes is continuous, the interpolation for the instances of sequence or sequence set duration may be either linear or stepwise, the former being the default. We illustrate next how to create instances of the TGeomPoint class, the creation of instances of the TGeogPoint class is similar.

New TGeomPoint instances can be created by using one of its subclasses TGeomPointInst, TGeomPointI, TGeomPointSeq, or TGeomPointS.

New TGeomPointInst instances can be created either with a single string argument as in MobilityDB or with several arguments: the value, the timestamp, and the SRID, the latter being optional. In both cases, the value of the point can be specified using a Well-Known Text (WKT) [https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry] or Well-Known Binary (WKB) [https://en.wikipedia.org/wiki/Well-known_text#Well-known_binary] representation as well as its format variations [https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry#Format_variations] Extended Well-Known Text (EWKT) and Extended Well-Known Binary (EWKB).

>>> from dateutil.parser import parse
>>> from postgis import Point
>>> from mobilitydb import TGeomPointInst
>>> TGeomPointInst("POINT(1 1)@2020-01-01 00:00:00+01")
>>> TGeomPointInst("SRID=4326;POINT(1 1)@2020-01-01 00:00:00+01")
>>> TGeomPointInst("01010000000000000000004AC00000000000000000@2020-01-01")
>>> TGeomPointInst("POINT(1 1)", "2020-01-01 00:00:00+01", srid=4326)
>>> TGeomPointInst(Point(1, 1), parse("2020-01-01 00:00:00+01"), srid=4326)

New TGeomPointI instances can be created either with a single string argument as in MobilityDB or with two arguments: the list of composing instants and the SRID, the latter being optional.

>>> from mobilitydb import TGeomPointI
>>> TGeomPointI("{POINT(1 1)@2020-01-01, POINT(2 2)@2020-01-02}")
>>> TGeomPointI(["POINT(1 1)@2020-01-01", "POINT(2 2)@2020-01-02"], srid=4326)
>>> TGeomPointI([TGeomPointInst("POINT(1 1)@2020-01-01"), TGeomPointInst("POINT(2 2)@2020-01-02")], srid=4326)

New TGeomPointSeq instances can be created either with a single string argument as in MobilityDB or with several arguments: the list of composing instants, the left inclusion flag, the right inclusion flag, the interpolation, and the SRID, where only the first argument is mandatory.

>>> from mobilitydb import TGeomPointSeq
>>> TGeomPointSeq("[POINT(1 1)@2020-01-01, POINT(2 2)@2020-01-02]")
>>> TGeomPointSeq("SRID=4326;[POINT(1 1)@2020-01-01, POINT(2 2)@2020-01-02]")
>>> TGeomPointSeq("SRID=4326,Interp=Stepwise;[POINT(1 1)@2020-01-01, POINT(2 2)@2020-01-02]")
>>> TGeomPointSeq(["POINT(1 1)@2020-01-01", "POINT(2 2)@2020-01-02"], lower_inc= True, upper_inc=True, interp='Stepwise', srid=4326)
>>> TGeomPointSeq([TGeomPointInst("POINT(1 1)@2020-01-01"), TGeomPointInst("POINT(2 2)@2020-01-02")], lower_inc= True, upper_inc=True, interp='Stepwise', srid=4326)

Finally, new TGeomPointS instances can be created either with a single string argument as in MobilityDB or with several arguments: the list of composing sequences, the interpolation, and the SRID, where only the first argument is mandatory.

>>> from mobilitydb import TGeomPointS
>>> TGeomPointS("{[POINT(1 1)@2020-01-01, POINT(2 2)@2020-01-02], [POINT(2 2)@2020-01-03, POINT(1 1)@2020-01-04]}")
>>> TGeomPointS("SRID=4326;{[POINT(1 1)@2020-01-01, POINT(2 2)@2020-01-02], [POINT(2 2)@2020-01-03, POINT(1 1)@2020-01-04]}")
>>> TGeomPointS(["[POINT(1 1)@2020-01-01, POINT(2 2)@2020-01-02]", "[POINT(2 2)@2020-01-03, POINT(1 1)@2020-01-04]"], interp='Stepwise', srid=4326)
>>> TGeomPointS([TGeomPointSeq("[POINT(1 1)@2020-01-01, POINT(2 2)@2020-01-02]"), TGeomPointSeq("[POINT(2 2)@2020-01-03, POINT(1 1)@2020-01-04]")], interp='Stepwise', srid=4326)

API Reference

Time Types

Temporal Types

Box Types

Main Types

Index