Geografic-Information-System/python/grass/temporal/spatio_temporal_relationships.py

"""
Class to build the spatio-temporal topology between map lists

Usage:

.. code-block:: python

    import grass.temporal as tgis

    tgis.print_temporal_relations(maps)


(C) 2012-2013 by the GRASS Development Team
This program is free software under the GNU General Public
License (>=v2). Read the file COPYING that comes with GRASS
for details.

:authors: Soeren Gebbert
"""
from __future__ import print_function
from datetime import datetime
from .core import init_dbif
from .abstract_dataset import AbstractDatasetComparisonKeyStartTime
from .datetime_math import time_delta_to_relative_time_seconds
import grass.lib.vector as vector
import grass.lib.rtree as rtree
import grass.lib.gis as gis

###############################################################################


class SpatioTemporalTopologyBuilder(object):
    """This class is designed to build the spatio-temporal topology
    of spatio-temporally related abstract dataset objects.

    The abstract dataset objects must be provided as a single list, or in
    two lists.

     Example:

     .. code-block:: python

         # We have a space time raster dataset and build a map list
         # from all registered maps ordered by start time
         maps = strds.get_registered_maps_as_objects()

         # Now lets build the temporal topology of the maps in the list

         tb = SpatioTemporalTopologyBuilder()

         tb.build(maps)

         dbif, connection_state_changed = init_dbif(None)

         for map in tb:
             map.select(dbif)
             map.print_info()

         # Same can be done with the existing map list
         # But be aware that this is might not be temporally ordered
         for map in maps:
             map.select(dbf)
             map.print_info()

         # Using the next and previous methods, we can iterate over the
         # topological related maps in this way

         first = tb.get_first()

         while first:
             first.print_topology_info()
             first = first.next()

         # Dictionary like accessed
         map = tb["name@mapset"]

         >>> # Example with two lists of maps
         >>> import grass.temporal as tgis
         >>> import datetime
         >>> # Create two list of maps with equal time stamps
         >>> mapsA = []
         >>> mapsB = []
         >>> for i in range(4):
         ...     idA = "a%i@B"%(i)
         ...     mapA = tgis.RasterDataset(idA)
         ...     idB = "b%i@B"%(i)
         ...     mapB = tgis.RasterDataset(idB)
         ...     check = mapA.set_relative_time(i, i + 1, "months")
         ...     check = mapB.set_relative_time(i, i + 1, "months")
         ...     mapsA.append(mapA)
         ...     mapsB.append(mapB)
         >>> # Build the topology between the two map lists
         >>> tb = SpatioTemporalTopologyBuilder()
         >>> tb.build(mapsA, mapsB, None)
         >>> # Check relations of mapsA
         >>> for map in mapsA:
         ...     if map.get_equal():
         ...         relations = map.get_equal()
         ...         print("Map %s has equal relation to map %s"%(map.get_name(),
         ...               relations[0].get_name()))
         Map a0 has equal relation to map b0
         Map a1 has equal relation to map b1
         Map a2 has equal relation to map b2
         Map a3 has equal relation to map b3
         >>> # Check relations of mapsB
         >>> for map in mapsB:
         ...     if map.get_equal():
         ...         relations = map.get_equal()
         ...         print("Map %s has equal relation to map %s"%(map.get_name(),
         ...               relations[0].get_name()))
         Map b0 has equal relation to map a0
         Map b1 has equal relation to map a1
         Map b2 has equal relation to map a2
         Map b3 has equal relation to map a3


         >>> mapsA = []
         >>> mapsB = []
         >>> for i in range(4):
         ...     idA = "a%i@B"%(i)
         ...     mapA = tgis.RasterDataset(idA)
         ...     idB = "b%i@B"%(i)
         ...     mapB = tgis.RasterDataset(idB)
         ...     check = mapA.set_relative_time(i, i + 1, "months")
         ...     check = mapB.set_relative_time(i + 1, i + 2, "months")
         ...     mapsA.append(mapA)
         ...     mapsB.append(mapB)
         >>> # Build the topology between the two map lists
         >>> tb = SpatioTemporalTopologyBuilder()
         >>> tb.build(mapsA, mapsB, None)
         >>> # Check relations of mapsA
         >>> for map in mapsA:
         ...     print(map.get_temporal_extent_as_tuple())
         ...     m = map.get_temporal_relations()
         ...     for key in m.keys():
         ...         if key not in ["NEXT", "PREV"]:
         ...             print((key, m[key][0].get_temporal_extent_as_tuple()))
         (0, 1)
         ('PRECEDES', (1, 2))
         (1, 2)
         ('PRECEDES', (2, 3))
         ('EQUAL', (1, 2))
         (2, 3)
         ('FOLLOWS', (1, 2))
         ('PRECEDES', (3, 4))
         ('EQUAL', (2, 3))
         (3, 4)
         ('FOLLOWS', (2, 3))
         ('EQUAL', (3, 4))
         ('PRECEDES', (4, 5))

         >>> mapsA = []
         >>> mapsB = []
         >>> for i in range(4):
         ...     idA = "a%i@B"%(i)
         ...     mapA = tgis.RasterDataset(idA)
         ...     idB = "b%i@B"%(i)
         ...     mapB = tgis.RasterDataset(idB)
         ...     start = datetime.datetime(2000 + i, 1, 1)
         ...     end = datetime.datetime(2000 + i + 1, 1, 1)
         ...     check = mapA.set_absolute_time(start, end)
         ...     start = datetime.datetime(2000 + i + 1, 1, 1)
         ...     end = datetime.datetime(2000 + i + 2, 1, 1)
         ...     check = mapB.set_absolute_time(start, end)
         ...     mapsA.append(mapA)
         ...     mapsB.append(mapB)
         >>> # Build the topology between the two map lists
         >>> tb = SpatioTemporalTopologyBuilder()
         >>> tb.build(mapsA, mapsB, None)
         >>> # Check relations of mapsA
         >>> for map in mapsA:
         ...     print(map.get_temporal_extent_as_tuple())
         ...     m = map.get_temporal_relations()
         ...     for key in m.keys():
         ...         if key not in ["NEXT", "PREV"]:
         ...             print((key, m[key][0].get_temporal_extent_as_tuple()))
         (datetime.datetime(2000, 1, 1, 0, 0), datetime.datetime(2001, 1, 1, 0, 0))
         ('PRECEDES', (datetime.datetime(2001, 1, 1, 0, 0), datetime.datetime(2002, 1, 1, 0, 0)))
         (datetime.datetime(2001, 1, 1, 0, 0), datetime.datetime(2002, 1, 1, 0, 0))
         ('PRECEDES', (datetime.datetime(2002, 1, 1, 0, 0), datetime.datetime(2003, 1, 1, 0, 0)))
         ('EQUAL', (datetime.datetime(2001, 1, 1, 0, 0), datetime.datetime(2002, 1, 1, 0, 0)))
         (datetime.datetime(2002, 1, 1, 0, 0), datetime.datetime(2003, 1, 1, 0, 0))
         ('FOLLOWS', (datetime.datetime(2001, 1, 1, 0, 0), datetime.datetime(2002, 1, 1, 0, 0)))
         ('PRECEDES', (datetime.datetime(2003, 1, 1, 0, 0), datetime.datetime(2004, 1, 1, 0, 0)))
         ('EQUAL', (datetime.datetime(2002, 1, 1, 0, 0), datetime.datetime(2003, 1, 1, 0, 0)))
         (datetime.datetime(2003, 1, 1, 0, 0), datetime.datetime(2004, 1, 1, 0, 0))
         ('FOLLOWS', (datetime.datetime(2002, 1, 1, 0, 0), datetime.datetime(2003, 1, 1, 0, 0)))
         ('EQUAL', (datetime.datetime(2003, 1, 1, 0, 0), datetime.datetime(2004, 1, 1, 0, 0)))
         ('PRECEDES', (datetime.datetime(2004, 1, 1, 0, 0), datetime.datetime(2005, 1, 1, 0, 0)))

         >>> mapsA = []
         >>> mapsB = []
         >>> for i in range(4):
         ...     idA = "a%i@B"%(i)
         ...     mapA = tgis.RasterDataset(idA)
         ...     idB = "b%i@B"%(i)
         ...     mapB = tgis.RasterDataset(idB)
         ...     start = datetime.datetime(2000 + i, 1, 1)
         ...     end = datetime.datetime(2000 + i + 1, 1, 1)
         ...     check = mapA.set_absolute_time(start, end)
         ...     start = datetime.datetime(2000 + i, 1, 1)
         ...     end = datetime.datetime(2000 + i + 3, 1, 1)
         ...     check = mapB.set_absolute_time(start, end)
         ...     mapsA.append(mapA)
         ...     mapsB.append(mapB)
         >>> # Build the topology between the two map lists
         >>> tb = SpatioTemporalTopologyBuilder()
         >>> tb.build(mapsA, mapsB, None)
         >>> # Check relations of mapsA
         >>> for map in mapsA:
         ...     print(map.get_temporal_extent_as_tuple())
         ...     m = map.get_temporal_relations()
         ...     for key in m.keys():
         ...         if key not in ["NEXT", "PREV"]:
         ...             print((key, m[key][0].get_temporal_extent_as_tuple()))
         (datetime.datetime(2000, 1, 1, 0, 0), datetime.datetime(2001, 1, 1, 0, 0))
         ('DURING', (datetime.datetime(2000, 1, 1, 0, 0), datetime.datetime(2003, 1, 1, 0, 0)))
         ('STARTS', (datetime.datetime(2000, 1, 1, 0, 0), datetime.datetime(2003, 1, 1, 0, 0)))
         ('PRECEDES', (datetime.datetime(2001, 1, 1, 0, 0), datetime.datetime(2004, 1, 1, 0, 0)))
         (datetime.datetime(2001, 1, 1, 0, 0), datetime.datetime(2002, 1, 1, 0, 0))
         ('DURING', (datetime.datetime(2000, 1, 1, 0, 0), datetime.datetime(2003, 1, 1, 0, 0)))
         ('STARTS', (datetime.datetime(2001, 1, 1, 0, 0), datetime.datetime(2004, 1, 1, 0, 0)))
         ('PRECEDES', (datetime.datetime(2002, 1, 1, 0, 0), datetime.datetime(2005, 1, 1, 0, 0)))
         (datetime.datetime(2002, 1, 1, 0, 0), datetime.datetime(2003, 1, 1, 0, 0))
         ('PRECEDES', (datetime.datetime(2003, 1, 1, 0, 0), datetime.datetime(2006, 1, 1, 0, 0)))
         ('FINISHES', (datetime.datetime(2000, 1, 1, 0, 0), datetime.datetime(2003, 1, 1, 0, 0)))
         ('DURING', (datetime.datetime(2000, 1, 1, 0, 0), datetime.datetime(2003, 1, 1, 0, 0)))
         ('STARTS', (datetime.datetime(2002, 1, 1, 0, 0), datetime.datetime(2005, 1, 1, 0, 0)))
         (datetime.datetime(2003, 1, 1, 0, 0), datetime.datetime(2004, 1, 1, 0, 0))
         ('FOLLOWS', (datetime.datetime(2000, 1, 1, 0, 0), datetime.datetime(2003, 1, 1, 0, 0)))
         ('DURING', (datetime.datetime(2001, 1, 1, 0, 0), datetime.datetime(2004, 1, 1, 0, 0)))
         ('FINISHES', (datetime.datetime(2001, 1, 1, 0, 0), datetime.datetime(2004, 1, 1, 0, 0)))
         ('STARTS', (datetime.datetime(2003, 1, 1, 0, 0), datetime.datetime(2006, 1, 1, 0, 0)))

         >>> mapsA = []
         >>> mapsB = []
         >>> for i in range(4):
         ...     idA = "a%i@B"%(i)
         ...     mapA = tgis.RasterDataset(idA)
         ...     idB = "b%i@B"%(i)
         ...     mapB = tgis.RasterDataset(idB)
         ...     start = datetime.datetime(2000 + i, 1, 1)
         ...     end = datetime.datetime(2000 + i + 2, 1, 1)
         ...     check = mapA.set_absolute_time(start, end)
         ...     start = datetime.datetime(2000 + i, 1, 1)
         ...     end = datetime.datetime(2000 + i + 3, 1, 1)
         ...     check = mapB.set_absolute_time(start, end)
         ...     mapsA.append(mapA)
         ...     mapsB.append(mapB)
         >>> # Build the topology between the two map lists
         >>> tb = SpatioTemporalTopologyBuilder()
         >>> tb.build(mapsA, mapsB, None)
         >>> # Check relations of mapsA
         >>> for map in mapsA:
         ...     print(map.get_temporal_extent_as_tuple())
         ...     m = map.get_temporal_relations()
         ...     for key in m.keys():
         ...         if key not in ["NEXT", "PREV"]:
         ...             print((key, m[key][0].get_temporal_extent_as_tuple()))
         (datetime.datetime(2000, 1, 1, 0, 0), datetime.datetime(2002, 1, 1, 0, 0))
         ('OVERLAPS', (datetime.datetime(2001, 1, 1, 0, 0), datetime.datetime(2004, 1, 1, 0, 0)))
         ('DURING', (datetime.datetime(2000, 1, 1, 0, 0), datetime.datetime(2003, 1, 1, 0, 0)))
         ('STARTS', (datetime.datetime(2000, 1, 1, 0, 0), datetime.datetime(2003, 1, 1, 0, 0)))
         ('PRECEDES', (datetime.datetime(2002, 1, 1, 0, 0), datetime.datetime(2005, 1, 1, 0, 0)))
         (datetime.datetime(2001, 1, 1, 0, 0), datetime.datetime(2003, 1, 1, 0, 0))
         ('OVERLAPS', (datetime.datetime(2002, 1, 1, 0, 0), datetime.datetime(2005, 1, 1, 0, 0)))
         ('PRECEDES', (datetime.datetime(2003, 1, 1, 0, 0), datetime.datetime(2006, 1, 1, 0, 0)))
         ('FINISHES', (datetime.datetime(2000, 1, 1, 0, 0), datetime.datetime(2003, 1, 1, 0, 0)))
         ('DURING', (datetime.datetime(2000, 1, 1, 0, 0), datetime.datetime(2003, 1, 1, 0, 0)))
         ('STARTS', (datetime.datetime(2001, 1, 1, 0, 0), datetime.datetime(2004, 1, 1, 0, 0)))
         (datetime.datetime(2002, 1, 1, 0, 0), datetime.datetime(2004, 1, 1, 0, 0))
         ('OVERLAPS', (datetime.datetime(2003, 1, 1, 0, 0), datetime.datetime(2006, 1, 1, 0, 0)))
         ('OVERLAPPED', (datetime.datetime(2000, 1, 1, 0, 0), datetime.datetime(2003, 1, 1, 0, 0)))
         ('FINISHES', (datetime.datetime(2001, 1, 1, 0, 0), datetime.datetime(2004, 1, 1, 0, 0)))
         ('DURING', (datetime.datetime(2001, 1, 1, 0, 0), datetime.datetime(2004, 1, 1, 0, 0)))
         ('STARTS', (datetime.datetime(2002, 1, 1, 0, 0), datetime.datetime(2005, 1, 1, 0, 0)))
         (datetime.datetime(2003, 1, 1, 0, 0), datetime.datetime(2005, 1, 1, 0, 0))
         ('OVERLAPPED', (datetime.datetime(2001, 1, 1, 0, 0), datetime.datetime(2004, 1, 1, 0, 0)))
         ('DURING', (datetime.datetime(2002, 1, 1, 0, 0), datetime.datetime(2005, 1, 1, 0, 0)))
         ('FINISHES', (datetime.datetime(2002, 1, 1, 0, 0), datetime.datetime(2005, 1, 1, 0, 0)))
         ('STARTS', (datetime.datetime(2003, 1, 1, 0, 0), datetime.datetime(2006, 1, 1, 0, 0)))
         ('FOLLOWS', (datetime.datetime(2000, 1, 1, 0, 0), datetime.datetime(2003, 1, 1, 0, 0)))

         >>> mapsA = []
         >>> mapsB = []
         >>> for i in range(4):
         ...     idA = "a%i@B"%(i)
         ...     mapA = tgis.RasterDataset(idA)
         ...     idB = "b%i@B"%(i)
         ...     mapB = tgis.RasterDataset(idB)
         ...     start = datetime.datetime(2000, 1, 1, 0, 0, i)
         ...     end = datetime.datetime(2000, 1, 1, 0, 0, i + 2)
         ...     check = mapA.set_absolute_time(start, end)
         ...     start = datetime.datetime(2000, 1, 1, 0, 0, i + 1)
         ...     end = datetime.datetime(2000, 1, 1, 0, 0, i + 3)
         ...     check = mapB.set_absolute_time(start, end)
         ...     mapsA.append(mapA)
         ...     mapsB.append(mapB)
         >>> # Build the topology between the two map lists
         >>> tb = SpatioTemporalTopologyBuilder()
         >>> tb.build(mapsA, mapsB, None)
         >>> # Check relations of mapsA
         >>> for map in mapsA:
         ...     print(map.get_temporal_extent_as_tuple())
         ...     m = map.get_temporal_relations()
         ...     for key in m.keys():
         ...         if key not in ["NEXT", "PREV"]:
         ...             print((key, m[key][0].get_temporal_extent_as_tuple()))
         (datetime.datetime(2000, 1, 1, 0, 0), datetime.datetime(2000, 1, 1, 0, 0, 2))
         ('OVERLAPS', (datetime.datetime(2000, 1, 1, 0, 0, 1), datetime.datetime(2000, 1, 1, 0, 0, 3)))
         ('PRECEDES', (datetime.datetime(2000, 1, 1, 0, 0, 2), datetime.datetime(2000, 1, 1, 0, 0, 4)))
         (datetime.datetime(2000, 1, 1, 0, 0, 1), datetime.datetime(2000, 1, 1, 0, 0, 3))
         ('OVERLAPS', (datetime.datetime(2000, 1, 1, 0, 0, 2), datetime.datetime(2000, 1, 1, 0, 0, 4)))
         ('PRECEDES', (datetime.datetime(2000, 1, 1, 0, 0, 3), datetime.datetime(2000, 1, 1, 0, 0, 5)))
         ('EQUAL', (datetime.datetime(2000, 1, 1, 0, 0, 1), datetime.datetime(2000, 1, 1, 0, 0, 3)))
         (datetime.datetime(2000, 1, 1, 0, 0, 2), datetime.datetime(2000, 1, 1, 0, 0, 4))
         ('OVERLAPS', (datetime.datetime(2000, 1, 1, 0, 0, 3), datetime.datetime(2000, 1, 1, 0, 0, 5)))
         ('OVERLAPPED', (datetime.datetime(2000, 1, 1, 0, 0, 1), datetime.datetime(2000, 1, 1, 0, 0, 3)))
         ('PRECEDES', (datetime.datetime(2000, 1, 1, 0, 0, 4), datetime.datetime(2000, 1, 1, 0, 0, 6)))
         ('EQUAL', (datetime.datetime(2000, 1, 1, 0, 0, 2), datetime.datetime(2000, 1, 1, 0, 0, 4)))
         (datetime.datetime(2000, 1, 1, 0, 0, 3), datetime.datetime(2000, 1, 1, 0, 0, 5))
         ('OVERLAPS', (datetime.datetime(2000, 1, 1, 0, 0, 4), datetime.datetime(2000, 1, 1, 0, 0, 6)))
         ('FOLLOWS', (datetime.datetime(2000, 1, 1, 0, 0, 1), datetime.datetime(2000, 1, 1, 0, 0, 3)))
         ('OVERLAPPED', (datetime.datetime(2000, 1, 1, 0, 0, 2), datetime.datetime(2000, 1, 1, 0, 0, 4)))
         ('EQUAL', (datetime.datetime(2000, 1, 1, 0, 0, 3), datetime.datetime(2000, 1, 1, 0, 0, 5)))

         >>> mapsA = []
         >>> for i in range(4):
         ...     idA = "a%i@B"%(i)
         ...     mapA = tgis.RasterDataset(idA)
         ...     start = datetime.datetime(2000, 1, 1, 0, 0, i)
         ...     end = datetime.datetime(2000, 1, 1, 0, 0, i + 2)
         ...     check = mapA.set_absolute_time(start, end)
         ...     mapsA.append(mapA)
         >>> tb = SpatioTemporalTopologyBuilder()
         >>> tb.build(mapsA)
         >>> # Check relations of mapsA
         >>> for map in mapsA:
         ...     print(map.get_temporal_extent_as_tuple())
         ...     m = map.get_temporal_relations()
         ...     for key in m.keys():
         ...         if key not in ["NEXT", "PREV"]:
         ...             print((key, m[key][0].get_temporal_extent_as_tuple()))
         (datetime.datetime(2000, 1, 1, 0, 0), datetime.datetime(2000, 1, 1, 0, 0, 2))
         ('OVERLAPS', (datetime.datetime(2000, 1, 1, 0, 0, 1), datetime.datetime(2000, 1, 1, 0, 0, 3)))
         ('PRECEDES', (datetime.datetime(2000, 1, 1, 0, 0, 2), datetime.datetime(2000, 1, 1, 0, 0, 4)))
         (datetime.datetime(2000, 1, 1, 0, 0, 1), datetime.datetime(2000, 1, 1, 0, 0, 3))
         ('OVERLAPS', (datetime.datetime(2000, 1, 1, 0, 0, 2), datetime.datetime(2000, 1, 1, 0, 0, 4)))
         ('OVERLAPPED', (datetime.datetime(2000, 1, 1, 0, 0), datetime.datetime(2000, 1, 1, 0, 0, 2)))
         ('PRECEDES', (datetime.datetime(2000, 1, 1, 0, 0, 3), datetime.datetime(2000, 1, 1, 0, 0, 5)))
         (datetime.datetime(2000, 1, 1, 0, 0, 2), datetime.datetime(2000, 1, 1, 0, 0, 4))
         ('OVERLAPS', (datetime.datetime(2000, 1, 1, 0, 0, 3), datetime.datetime(2000, 1, 1, 0, 0, 5)))
         ('FOLLOWS', (datetime.datetime(2000, 1, 1, 0, 0), datetime.datetime(2000, 1, 1, 0, 0, 2)))
         ('OVERLAPPED', (datetime.datetime(2000, 1, 1, 0, 0, 1), datetime.datetime(2000, 1, 1, 0, 0, 3)))
         (datetime.datetime(2000, 1, 1, 0, 0, 3), datetime.datetime(2000, 1, 1, 0, 0, 5))
         ('FOLLOWS', (datetime.datetime(2000, 1, 1, 0, 0, 1), datetime.datetime(2000, 1, 1, 0, 0, 3)))
         ('OVERLAPPED', (datetime.datetime(2000, 1, 1, 0, 0, 2), datetime.datetime(2000, 1, 1, 0, 0, 4)))

    """

    def __init__(self):
        self._reset()
        # 0001-01-01 00:00:00
        self._timeref = datetime(1, 1, 1)

    def _reset(self):
        self._store = {}
        self._first = None
        self._iteratable = False

    def _set_first(self, first):
        self._first = first
        self._insert(first)

    def _detect_first(self):
        if len(self) > 0:
            prev_ = list(self._store.values())[0]
            while prev_ is not None:
                self._first = prev_
                prev_ = prev_.prev()

    def _insert(self, t):
        self._store[t.get_id()] = t

    def get_first(self):
        """Return the first map with the earliest start time

        :return: The map with the earliest start time
        """
        return self._first

    def _build_internal_iteratable(self, maps, spatial):
        """Build an iteratable temporal topology structure for all maps in
        the list and store the maps internally

        Basically the "next" and "prev" relations will be set in the
        temporal topology structure of each map
        The maps will be added to the object, so they can be
        accessed using the iterator of this class

        :param maps: A sorted (by start_time)list of abstract_dataset
                     objects with initiated temporal extent
        """
        self._build_iteratable(maps, spatial)

        for _map in maps:
            self._insert(_map)

        # Detect the first map
        self._detect_first()

    def _build_iteratable(self, maps, spatial):
        """Build an iteratable temporal topology structure for
        all maps in the list

        Basically the "next" and "prev" relations will be set in
        the temporal topology structure of each map.

        :param maps: A sorted (by start_time)list of abstract_dataset
                     objects with initiated temporal extent
        """
        #        for i in xrange(len(maps)):
        #            offset = i + 1
        #            for j in xrange(offset, len(maps)):
        #                # Get the temporal relationship
        #                relation = maps[j].temporal_relation(maps[i])
        #
        #                # Build the next reference
        #                if relation != "equal" and relation != "started":
        #                    maps[i].set_next(maps[j])
        #                    break

        # First we need to order the map list chronologically
        sorted_maps = sorted(maps, key=AbstractDatasetComparisonKeyStartTime)

        for i in range(len(sorted_maps) - 1):
            sorted_maps[i].set_next(sorted_maps[i + 1])

        for map_ in sorted_maps:
            next_ = map_.next()
            if next_:
                next_.set_prev(map_)
            map_.set_temporal_topology_build_true()
            if spatial is not None:
                map_.set_spatial_topology_build_true()

    def _map_to_rect(self, tree, map_, spatial=None):
        """Use the spatio-temporal extent of a map to create and
        return a RTree rectangle

        :param spatial: This indicates if the spatial topology is created
                        as well: spatial can be None (no spatial topology),
                        "2D" using west, east, south, north or "3D" using
                        west, east, south, north, bottom, top
        """
        rect = rtree.RTreeAllocRect(tree)

        start, end = map_.get_temporal_extent_as_tuple()

        if not end:
            end = start

        if map_.is_time_absolute():
            start = time_delta_to_relative_time_seconds(start - self._timeref)
            end = time_delta_to_relative_time_seconds(end - self._timeref)

        if spatial is None:
            rtree.RTreeSetRect1D(rect, tree, float(start), float(end))
        elif spatial == "2D":
            north, south, east, west, top, bottom = map_.get_spatial_extent_as_tuple()
            rtree.RTreeSetRect3D(
                rect, tree, west, east, south, north, float(start), float(end)
            )
        elif spatial == "3D":
            north, south, east, west, top, bottom = map_.get_spatial_extent_as_tuple()
            rtree.RTreeSetRect4D(
                rect,
                tree,
                west,
                east,
                south,
                north,
                bottom,
                top,
                float(start),
                float(end),
            )

        return rect

    def _build_rtree(self, maps, spatial=None):
        """Build and return the 1-4 dimensional R*-Tree

        :param spatial: This indicates if the spatial topology is created
                        as well: spatial can be None (no spatial topology),
                        "2D" using west, east, south, north or "3D" using
                        west, east, south, north, bottom, top
        """
        dim = 1
        if spatial == "2D":
            dim = 3
        if spatial == "3D":
            dim = 4

        tree = rtree.RTreeCreateTree(-1, 0, dim)

        for i in range(len(maps)):

            rect = self._map_to_rect(tree, maps[i], spatial)
            rtree.RTreeInsertRect(rect, i + 1, tree)

        return tree

    def build(self, mapsA, mapsB=None, spatial=None):
        """Build the spatio-temporal topology structure between
        one or two unordered lists of abstract dataset objects

        This method builds the temporal or spatio-temporal topology from
        mapsA to mapsB and vice verse. The spatio-temporal topology
        structure of each map will be reset and rebuild for mapsA and
        mapsB.

        After building the temporal or spatio-temporal topology the modified
        map objects of mapsA can be accessed
        in the same way as a dictionary using there id.
        The implemented iterator assures
        the chronological iteration over the mapsA.

        :param mapsA: A list of abstract_dataset
                      objects with initiated spatio-temporal extent
        :param mapsB: An optional list of abstract_dataset
                      objects with initiated spatio-temporal extent
        :param spatial: This indicates if the spatial topology is created
                        as well: spatial can be None (no spatial topology),
                        "2D" using west, east, south, north or "3D" using
                        west, east, south, north, bottom, top
        """

        identical = False
        if mapsA == mapsB:
            identical = True

        if mapsB is None:
            mapsB = mapsA
            identical = True

        for map_ in mapsA:
            map_.reset_topology()

        if not identical:
            for map_ in mapsB:
                map_.reset_topology()

        tree = self._build_rtree(mapsA, spatial)

        list_ = gis.G_new_ilist()

        for j in range(len(mapsB)):

            rect = self._map_to_rect(tree, mapsB[j], spatial)
            vector.RTreeSearch2(tree, rect, list_)
            rtree.RTreeFreeRect(rect)

            for k in range(list_.contents.n_values):
                i = list_.contents.value[k] - 1

                # Get the temporal relationship
                relation = mapsB[j].temporal_relation(mapsA[i])

                A = mapsA[i]
                B = mapsB[j]
                set_temoral_relationship(A, B, relation)

                if spatial is not None:
                    relation = mapsB[j].spatial_relation(mapsA[i])
                    set_spatial_relationship(A, B, relation)

        self._build_internal_iteratable(mapsA, spatial)
        if not identical and mapsB is not None:
            self._build_iteratable(mapsB, spatial)

        gis.G_free_ilist(list_)

        rtree.RTreeDestroyTree(tree)

    def __iter__(self):
        start_ = self._first
        while start_ is not None:
            yield start_
            start_ = start_.next()

    def __getitem__(self, index):
        return self._store[index.get_id()]

    def __len__(self):
        return len(self._store)

    def __contains__(self, _map):
        return _map in self._store.values()


###############################################################################


def set_temoral_relationship(A, B, relation):
    if relation == "equal" or relation == "equals":
        if A != B:
            if not B.get_equal() or (B.get_equal() and A not in B.get_equal()):
                B.append_equal(A)
            if not A.get_equal() or (A.get_equal() and B not in A.get_equal()):
                A.append_equal(B)
    elif relation == "follows":
        if not B.get_follows() or (B.get_follows() and A not in B.get_follows()):
            B.append_follows(A)
        if not A.get_precedes() or (A.get_precedes() and B not in A.get_precedes()):
            A.append_precedes(B)
    elif relation == "precedes":
        if not B.get_precedes() or (B.get_precedes() and A not in B.get_precedes()):
            B.append_precedes(A)
        if not A.get_follows() or (A.get_follows() and B not in A.get_follows()):
            A.append_follows(B)
    elif relation == "during" or relation == "starts" or relation == "finishes":
        if not B.get_during() or (B.get_during() and A not in B.get_during()):
            B.append_during(A)
        if not A.get_contains() or (A.get_contains() and B not in A.get_contains()):
            A.append_contains(B)
        if relation == "starts":
            if not B.get_starts() or (B.get_starts() and A not in B.get_starts()):
                B.append_starts(A)
            if not A.get_started() or (A.get_started() and B not in A.get_started()):
                A.append_started(B)
        if relation == "finishes":
            if not B.get_finishes() or (B.get_finishes() and A not in B.get_finishes()):
                B.append_finishes(A)
            if not A.get_finished() or (A.get_finished() and B not in A.get_finished()):
                A.append_finished(B)
    elif relation == "contains" or relation == "started" or relation == "finished":
        if not B.get_contains() or (B.get_contains() and A not in B.get_contains()):
            B.append_contains(A)
        if not A.get_during() or (A.get_during() and B not in A.get_during()):
            A.append_during(B)
        if relation == "started":
            if not B.get_started() or (B.get_started() and A not in B.get_started()):
                B.append_started(A)
            if not A.get_starts() or (A.get_starts() and B not in A.get_starts()):
                A.append_starts(B)
        if relation == "finished":
            if not B.get_finished() or (B.get_finished() and A not in B.get_finished()):
                B.append_finished(A)
            if not A.get_finishes() or (A.get_finishes() and B not in A.get_finishes()):
                A.append_finishes(B)
    elif relation == "overlaps":
        if not B.get_overlaps() or (B.get_overlaps() and A not in B.get_overlaps()):
            B.append_overlaps(A)
        if not A.get_overlapped() or (
            A.get_overlapped() and B not in A.get_overlapped()
        ):
            A.append_overlapped(B)
    elif relation == "overlapped":
        if not B.get_overlapped() or (
            B.get_overlapped() and A not in B.get_overlapped()
        ):
            B.append_overlapped(A)
        if not A.get_overlaps() or (A.get_overlaps() and B not in A.get_overlaps()):
            A.append_overlaps(B)


###############################################################################


def set_spatial_relationship(A, B, relation):

    if relation == "equivalent":
        if A != B:
            if not B.get_equivalent() or (
                B.get_equivalent() and A not in B.get_equivalent()
            ):
                B.append_equivalent(A)
            if not A.get_equivalent() or (
                A.get_equivalent() and B not in A.get_equivalent()
            ):
                A.append_equivalent(B)
    elif relation == "overlap":
        if not B.get_overlap() or (B.get_overlap() and A not in B.get_overlap()):
            B.append_overlap(A)
        if not A.get_overlap() or (A.get_overlap() and B not in A.get_overlap()):
            A.append_overlap(B)
    elif relation == "meet":
        if not B.get_meet() or (B.get_meet() and A not in B.get_meet()):
            B.append_meet(A)
        if not A.get_meet() or (A.get_meet() and B not in A.get_meet()):
            A.append_meet(B)
    elif relation == "contain":
        if not B.get_contain() or (B.get_contain() and A not in B.get_contain()):
            B.append_contain(A)
        if not A.get_in() or (A.get_in() and B not in A.get_in()):
            A.append_in(B)
    elif relation == "in":
        if not B.get_in() or (B.get_in() and A not in B.get_in()):
            B.append_in(A)
        if not A.get_contain() or (A.get_contain() and B not in A.get_contain()):
            A.append_contain(B)
    elif relation == "cover":
        if not B.get_cover() or (B.get_cover() and A not in B.get_cover()):
            B.append_cover(A)
        if not A.get_covered() or (A.get_covered() and B not in A.get_covered()):
            A.append_covered(B)
    elif relation == "covered":
        if not B.get_covered() or (B.get_covered() and A not in B.get_covered()):
            B.append_covered(A)
        if not A.get_cover() or (A.get_cover() and B not in A.get_cover()):
            A.append_cover(B)


###############################################################################


def print_temporal_topology_relationships(maps1, maps2=None, dbif=None):
    """Print the temporal relationships of the
    map lists maps1 and maps2 to stdout.

     :param maps1: A list of abstract_dataset
                   objects with initiated temporal extent
     :param maps2: An optional list of abstract_dataset
                   objects with initiated temporal extent
     :param dbif: The database interface to be used
    """

    tb = SpatioTemporalTopologyBuilder()

    tb.build(maps1, maps2)

    dbif, connection_state_changed = init_dbif(dbif)

    for _map in tb:
        _map.select(dbif)
        _map.print_info()

    if connection_state_changed:
        dbif.close()

    return


###############################################################################


def print_spatio_temporal_topology_relationships(
    maps1, maps2=None, spatial="2D", dbif=None
):
    """Print the temporal relationships of the
    map lists maps1 and maps2 to stdout.

     :param maps1: A list of abstract_dataset
                   objects with initiated temporal extent
     :param maps2: An optional list of abstract_dataset
                   objects with initiated temporal extent
     :param spatial: The dimension of the spatial extent to be used: "2D"
                     using west, east, south, north or "3D" using west,
                     east, south, north, bottom, top
     :param dbif: The database interface to be used
    """

    tb = SpatioTemporalTopologyBuilder()

    tb.build(maps1, maps2, spatial)

    dbif, connection_state_changed = init_dbif(dbif)

    for _map in tb:
        _map.select(dbif)
        _map.print_info()

    if connection_state_changed:
        dbif.close()

    return


###############################################################################


def count_temporal_topology_relationships(maps1, maps2=None, dbif=None):
    """Count the temporal relations of a single list of maps or between two
    lists of maps


     :param maps1: A list of abstract_dataset
                   objects with initiated temporal extent
     :param maps2: A list of abstract_dataset
                   objects with initiated temporal extent
     :param dbif: The database interface to be used
     :return: A dictionary with counted temporal relationships
    """

    tb = SpatioTemporalTopologyBuilder()
    tb.build(maps1, maps2)

    dbif, connection_state_changed = init_dbif(dbif)

    relations = None

    for _map in tb:
        if relations is not None:
            r = _map.get_number_of_relations()
            for k in r.keys():
                relations[k] += r[k]
        else:
            relations = _map.get_number_of_relations()

    if connection_state_changed:
        dbif.close()

    return relations


###############################################################################


def create_temporal_relation_sql_where_statement(
    start,
    end,
    use_start=True,
    use_during=False,
    use_overlap=False,
    use_contain=False,
    use_equal=False,
    use_follows=False,
    use_precedes=False,
):
    """Create a SQL WHERE statement for temporal relation selection of maps in
    space time datasets

     :param start: The start time
     :param end: The end time
     :param use_start: Select maps of which the start time is located in
                       the selection granule ::

                           map    :        s
                           granule:  s-----------------e

                           map    :        s--------------------e
                           granule:  s-----------------e

                           map    :        s--------e
                           granule:  s-----------------e


     :param use_during: Select maps which are temporal during the selection
                        granule  ::

                            map    :     s-----------e
                            granule:  s-----------------e

     :param use_overlap: Select maps which temporal overlap the selection
                         granule ::

                             map    :     s-----------e
                             granule:        s-----------------e

                             map    :     s-----------e
                             granule:  s----------e

     :param use_contain: Select maps which temporally contain the selection
                         granule ::

                             map    :  s-----------------e
                             granule:     s-----------e

     :param use_equal: Select maps which temporally equal to the selection
                       granule ::

                           map    :  s-----------e
                           granule:  s-----------e

     :param use_follows: Select maps which temporally follow the selection
                         granule ::

                             map    :              s-----------e
                             granule:  s-----------e

     :param use_precedes: Select maps which temporally precedes the
                          selection granule ::

                              map    :  s-----------e
                              granule:              s-----------e

     Usage:

     .. code-block:: python

         >>> # Relative time
         >>> start = 1
         >>> end = 2
         >>> create_temporal_relation_sql_where_statement(start, end,
         ... use_start=False)
         >>> create_temporal_relation_sql_where_statement(start, end)
         '((start_time >= 1 and start_time < 2) )'
         >>> create_temporal_relation_sql_where_statement(start, end,
         ... use_start=True)
         '((start_time >= 1 and start_time < 2) )'
         >>> create_temporal_relation_sql_where_statement(start, end,
         ... use_start=False, use_during=True)
         '(((start_time > 1 and end_time < 2) OR (start_time >= 1 and end_time < 2) OR (start_time > 1 and end_time <= 2)))'
         >>> create_temporal_relation_sql_where_statement(start, end,
         ... use_start=False, use_overlap=True)
         '(((start_time < 1 and end_time > 1 and end_time < 2) OR (start_time < 2 and start_time > 1 and end_time > 2)))'
         >>> create_temporal_relation_sql_where_statement(start, end,
         ... use_start=False, use_contain=True)
         '(((start_time < 1 and end_time > 2) OR (start_time <= 1 and end_time > 2) OR (start_time < 1 and end_time >= 2)))'
         >>> create_temporal_relation_sql_where_statement(start, end,
         ... use_start=False, use_equal=True)
         '((start_time = 1 and end_time = 2))'
         >>> create_temporal_relation_sql_where_statement(start, end,
         ... use_start=False, use_follows=True)
         '((start_time = 2))'
         >>> create_temporal_relation_sql_where_statement(start, end,
         ... use_start=False, use_precedes=True)
         '((end_time = 1))'
         >>> create_temporal_relation_sql_where_statement(start, end,
         ... use_start=True, use_during=True, use_overlap=True, use_contain=True,
         ... use_equal=True, use_follows=True, use_precedes=True)
         '((start_time >= 1 and start_time < 2)  OR ((start_time > 1 and end_time < 2) OR (start_time >= 1 and end_time < 2) OR (start_time > 1 and end_time <= 2)) OR ((start_time < 1 and end_time > 1 and end_time < 2) OR (start_time < 2 and start_time > 1 and end_time > 2)) OR ((start_time < 1 and end_time > 2) OR (start_time <= 1 and end_time > 2) OR (start_time < 1 and end_time >= 2)) OR (start_time = 1 and end_time = 2) OR (start_time = 2) OR (end_time = 1))'

         >>> # Absolute time
         >>> start = datetime(2001, 1, 1, 12, 30)
         >>> end = datetime(2001, 3, 31, 14, 30)
         >>> create_temporal_relation_sql_where_statement(start, end,
         ... use_start=False)
         >>> create_temporal_relation_sql_where_statement(start, end)
         "((start_time >= '2001-01-01 12:30:00' and start_time < '2001-03-31 14:30:00') )"
         >>> create_temporal_relation_sql_where_statement(start, end,
         ... use_start=True)
         "((start_time >= '2001-01-01 12:30:00' and start_time < '2001-03-31 14:30:00') )"
         >>> create_temporal_relation_sql_where_statement(start, end,
         ... use_start=False, use_during=True)
         "(((start_time > '2001-01-01 12:30:00' and end_time < '2001-03-31 14:30:00') OR (start_time >= '2001-01-01 12:30:00' and end_time < '2001-03-31 14:30:00') OR (start_time > '2001-01-01 12:30:00' and end_time <= '2001-03-31 14:30:00')))"
         >>> create_temporal_relation_sql_where_statement(start, end,
         ... use_start=False, use_overlap=True)
         "(((start_time < '2001-01-01 12:30:00' and end_time > '2001-01-01 12:30:00' and end_time < '2001-03-31 14:30:00') OR (start_time < '2001-03-31 14:30:00' and start_time > '2001-01-01 12:30:00' and end_time > '2001-03-31 14:30:00')))"
         >>> create_temporal_relation_sql_where_statement(start, end,
         ... use_start=False, use_contain=True)
         "(((start_time < '2001-01-01 12:30:00' and end_time > '2001-03-31 14:30:00') OR (start_time <= '2001-01-01 12:30:00' and end_time > '2001-03-31 14:30:00') OR (start_time < '2001-01-01 12:30:00' and end_time >= '2001-03-31 14:30:00')))"
         >>> create_temporal_relation_sql_where_statement(start, end,
         ... use_start=False, use_equal=True)
         "((start_time = '2001-01-01 12:30:00' and end_time = '2001-03-31 14:30:00'))"
         >>> create_temporal_relation_sql_where_statement(start, end,
         ... use_start=False, use_follows=True)
         "((start_time = '2001-03-31 14:30:00'))"
         >>> create_temporal_relation_sql_where_statement(start, end,
         ... use_start=False, use_precedes=True)
         "((end_time = '2001-01-01 12:30:00'))"
         >>> create_temporal_relation_sql_where_statement(start, end,
         ... use_start=True, use_during=True, use_overlap=True, use_contain=True,
         ... use_equal=True, use_follows=True, use_precedes=True)
         "((start_time >= '2001-01-01 12:30:00' and start_time < '2001-03-31 14:30:00')  OR ((start_time > '2001-01-01 12:30:00' and end_time < '2001-03-31 14:30:00') OR (start_time >= '2001-01-01 12:30:00' and end_time < '2001-03-31 14:30:00') OR (start_time > '2001-01-01 12:30:00' and end_time <= '2001-03-31 14:30:00')) OR ((start_time < '2001-01-01 12:30:00' and end_time > '2001-01-01 12:30:00' and end_time < '2001-03-31 14:30:00') OR (start_time < '2001-03-31 14:30:00' and start_time > '2001-01-01 12:30:00' and end_time > '2001-03-31 14:30:00')) OR ((start_time < '2001-01-01 12:30:00' and end_time > '2001-03-31 14:30:00') OR (start_time <= '2001-01-01 12:30:00' and end_time > '2001-03-31 14:30:00') OR (start_time < '2001-01-01 12:30:00' and end_time >= '2001-03-31 14:30:00')) OR (start_time = '2001-01-01 12:30:00' and end_time = '2001-03-31 14:30:00') OR (start_time = '2001-03-31 14:30:00') OR (end_time = '2001-01-01 12:30:00'))"

    """

    where = "("

    if use_start:
        if isinstance(start, datetime):
            where += "(start_time >= '%s' and start_time < '%s') " % (start, end)
        else:
            where += "(start_time >= %i and start_time < %i) " % (start, end)

    if use_during:
        if use_start:
            where += " OR "

        if isinstance(start, datetime):
            where += "((start_time > '%s' and end_time < '%s') OR " % (start, end)
            where += "(start_time >= '%s' and end_time < '%s') OR " % (start, end)
            where += "(start_time > '%s' and end_time <= '%s'))" % (start, end)
        else:
            where += "((start_time > %i and end_time < %i) OR " % (start, end)
            where += "(start_time >= %i and end_time < %i) OR " % (start, end)
            where += "(start_time > %i and end_time <= %i))" % (start, end)

    if use_overlap:
        if use_start or use_during:
            where += " OR "

        if isinstance(start, datetime):
            where += (
                "((start_time < '%s' and end_time > '%s' and end_time <"
                " '%s') OR " % (start, start, end)
            )
            where += (
                "(start_time < '%s' and start_time > '%s' and end_time "
                "> '%s'))" % (end, start, end)
            )
        else:
            where += "((start_time < %i and end_time > %i and end_time < %i)" " OR " % (
                start,
                start,
                end,
            )
            where += "(start_time < %i and start_time > %i and end_time > " "%i))" % (
                end,
                start,
                end,
            )

    if use_contain:
        if use_start or use_during or use_overlap:
            where += " OR "

        if isinstance(start, datetime):
            where += "((start_time < '%s' and end_time > '%s') OR " % (start, end)
            where += "(start_time <= '%s' and end_time > '%s') OR " % (start, end)
            where += "(start_time < '%s' and end_time >= '%s'))" % (start, end)
        else:
            where += "((start_time < %i and end_time > %i) OR " % (start, end)
            where += "(start_time <= %i and end_time > %i) OR " % (start, end)
            where += "(start_time < %i and end_time >= %i))" % (start, end)

    if use_equal:
        if use_start or use_during or use_overlap or use_contain:
            where += " OR "

        if isinstance(start, datetime):
            where += "(start_time = '%s' and end_time = '%s')" % (start, end)
        else:
            where += "(start_time = %i and end_time = %i)" % (start, end)

    if use_follows:
        if use_start or use_during or use_overlap or use_contain or use_equal:
            where += " OR "

        if isinstance(start, datetime):
            where += "(start_time = '%s')" % (end)
        else:
            where += "(start_time = %i)" % (end)

    if use_precedes:
        if (
            use_start
            or use_during
            or use_overlap
            or use_contain
            or use_equal
            or use_follows
        ):
            where += " OR "

        if isinstance(start, datetime):
            where += "(end_time = '%s')" % (start)
        else:
            where += "(end_time = %i)" % (start)

    where += ")"

    # Catch empty where statement
    if where == "()":
        where = None

    return where


###############################################################################

if __name__ == "__main__":
    import doctest

    doctest.testmod()