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

"""
The abstract_dataset module provides the AbstractDataset class
that is the base class for all map layer and Space Time Datasets.

(C) 2011-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 abc import ABCMeta, abstractmethod
from .core import (
    get_tgis_message_interface,
    init_dbif,
    get_current_mapset,
)
from .temporal_topology_dataset_connector import TemporalTopologyDatasetConnector
from .spatial_topology_dataset_connector import SpatialTopologyDatasetConnector

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


class AbstractDataset(
    SpatialTopologyDatasetConnector, TemporalTopologyDatasetConnector
):
    """This is the base class for all datasets
    (raster, vector, raster3d, strds, stvds, str3ds)"""

    __metaclass__ = ABCMeta

    def __init__(self):
        SpatialTopologyDatasetConnector.__init__(self)
        TemporalTopologyDatasetConnector.__init__(self)
        self.msgr = get_tgis_message_interface()

    def reset_topology(self):
        """Reset any information about temporal topology"""

        self.reset_spatial_topology()
        self.reset_temporal_topology()

    def get_number_of_relations(self):
        """Return a dictionary in which the keys are the relation names and the
        value are the number of relations.

        The following relations are available:

        Spatial relations:

            - equivalent
            - overlap
            - in
            - contain
            - meet
            - cover
            - covered

        Temporal relations:

            - equal
            - follows
            - precedes
            - overlaps
            - overlapped
            - during (including starts, finishes)
            - contains (including started, finished)
            - starts
            - started
            - finishes
            - finished

        To access topological information the spatial, temporal or booth
        topologies must be build first using the SpatioTemporalTopologyBuilder.

        :return: The dictionary with relations as keys and number as values or
                 None in case the topology  wasn't build
        """
        if self.is_temporal_topology_build() and not self.is_spatial_topology_build():
            return self.get_number_of_temporal_relations()
        elif self.is_spatial_topology_build() and not self.is_temporal_topology_build():
            self.get_number_of_spatial_relations()
        else:
            return (
                self.get_number_of_temporal_relations()
                + self.get_number_of_spatial_relations()
            )

        return None

    def set_topology_build_true(self):
        """Use this method when the spatio-temporal topology was build"""
        self.set_spatial_topology_build_true()
        self.set_temporal_topology_build_true()

    def set_topology_build_false(self):
        """Use this method when the spatio-temporal topology was not build"""
        self.set_spatial_topology_build_false()
        self.set_temporal_topology_build_false()

    def is_topology_build(self):
        """Check if the spatial and temporal topology was build

        :return: A dictionary with "spatial" and "temporal" as keys that
                 have boolen values
        """
        d = {}
        d["spatial"] = self.is_spatial_topology_build()
        d["temporal"] = self.is_temporal_topology_build()

        return d

    def print_topology_info(self):
        if self.is_temporal_topology_build():
            self.print_temporal_topology_info()
        if self.is_spatial_topology_build():
            self.print_spatial_topology_info()

    def print_topology_shell_info(self):
        if self.is_temporal_topology_build():
            self.print_temporal_topology_shell_info()
        if self.is_spatial_topology_build():
            self.print_spatial_topology_shell_info()

    @abstractmethod
    def reset(self, ident):
        """Reset the internal structure and set the identifier

         This method creates the dataset specific internal objects
         that store the base information, the spatial and temporal extent
         and the metadata. It must be implemented in the dataset
         specific subclasses. This is the code for the
         vector dataset:

         .. code-block:: python

             self.base = VectorBase(ident=ident)
             self.absolute_time = VectorAbsoluteTime(ident=ident)
             self.relative_time = VectorRelativeTime(ident=ident)
             self.spatial_extent = VectorSpatialExtent(ident=ident)
             self.metadata = VectorMetadata(ident=ident)

        :param ident: The identifier of the dataset that  "name@mapset" or
                      in case of vector maps "name:layer@mapset"
        """

    @abstractmethod
    def is_stds(self):
        """Return True if this class is a space time dataset

        :return: True if this class is a space time dataset, False otherwise
        """

    @abstractmethod
    def get_type(self):
        """Return the type of this class as string

        The type can be "vector", "raster", "raster3d", "stvds", "strds" or "str3ds"

        :return: "vector", "raster", "raster3d", "stvds", "strds" or "str3ds"
        """

    @abstractmethod
    def get_new_instance(self, ident):
        """Return a new instance with the type of this class

        :param ident: The identifier of the new dataset instance
        :return: A new instance with the type of this object
        """

    @abstractmethod
    def spatial_overlapping(self, dataset):
        """Return True if the spatial extents overlap

        :param dataset: The abstract dataset to check spatial overlapping
        :return: True if self and the provided dataset spatial overlap
        """

    @abstractmethod
    def spatial_intersection(self, dataset):
        """Return the spatial intersection as spatial_extent
        object or None in case no intersection was found.

        :param dataset: The abstract dataset to intersect with
        :return: The intersection spatial extent
        """

    @abstractmethod
    def spatial_union(self, dataset):
        """Return the spatial union as spatial_extent
        object or None in case the extents does not overlap or meet.

        :param dataset: The abstract dataset to create a union with
        :return: The union spatial extent
        """

    @abstractmethod
    def spatial_disjoint_union(self, dataset):
        """Return the spatial union as spatial_extent object.

        :param dataset: The abstract dataset to create a union with
        :return: The union spatial extent
        """

    @abstractmethod
    def spatial_relation(self, dataset):
        """Return the spatial relationship between self and dataset

        :param dataset: The abstract dataset to compute the spatial
                        relation with self
        :return: The spatial relationship as string
        """

    @abstractmethod
    def print_info(self):
        """Print information about this class in human readable style"""

    @abstractmethod
    def print_shell_info(self):
        """Print information about this class in shell style"""

    @abstractmethod
    def print_self(self):
        """Print the content of the internal structure to stdout"""

    def set_id(self, ident):
        """Set the identifier of the dataset"""
        self.base.set_id(ident)
        self.temporal_extent.set_id(ident)
        self.spatial_extent.set_id(ident)
        self.metadata.set_id(ident)
        if self.is_stds() is False:
            self.stds_register.set_id(ident)

    def get_id(self):
        """Return the unique identifier of the dataset
        :return: The id of the dataset "name(:layer)@mapset" as string
        """
        return self.base.get_id()

    def get_name(self):
        """Return the name
        :return: The name of the dataset as string
        """
        return self.base.get_name()

    def get_mapset(self):
        """Return the mapset
        :return: The mapset in which the dataset was created as string
        """
        return self.base.get_mapset()

    def get_temporal_extent_as_tuple(self):
        """Returns a tuple of the valid start and end time

        Start and end time can be either of type datetime or of type
        integer, depending on the temporal type.

        :return: A tuple of (start_time, end_time)
        """
        start = self.temporal_extent.get_start_time()
        end = self.temporal_extent.get_end_time()
        return (start, end)

    def get_absolute_time(self):
        """Returns the start time, the end
        time of the map as tuple

        The start time is of type datetime.

        The end time is of type datetime in case of interval time,
        or None on case of a time instance.

        :return: A tuple of (start_time, end_time)
        """

        start = self.absolute_time.get_start_time()
        end = self.absolute_time.get_end_time()

        return (start, end)

    def get_relative_time(self):
        """Returns the start time, the end
        time and the temporal unit of the dataset as tuple

        The start time is of type integer.

        The end time is of type integer in case of interval time,
        or None on case of a time instance.

        :return: A tuple of (start_time, end_time, unit)
        """

        start = self.relative_time.get_start_time()
        end = self.relative_time.get_end_time()
        unit = self.relative_time.get_unit()

        return (start, end, unit)

    def get_relative_time_unit(self):
        """Returns the relative time unit
        :return: The relative time unit as string, None if not present
        """
        return self.relative_time.get_unit()

    def check_relative_time_unit(self, unit):
        """Check if unit is of type  year(s), month(s), day(s), hour(s),
        minute(s) or second(s)

        :param unit: The unit string
        :return: True if success, False otherwise
        """
        # Check unit
        units = [
            "year",
            "years",
            "month",
            "months",
            "day",
            "days",
            "hour",
            "hours",
            "minute",
            "minutes",
            "second",
            "seconds",
        ]
        if unit not in units:
            return False
        return True

    def get_temporal_type(self):
        """Return the temporal type of this dataset

        The temporal type can be absolute or relative

        :return: The temporal type of the dataset as string
        """
        return self.base.get_ttype()

    def get_spatial_extent_as_tuple(self):
        """Return the spatial extent as tuple

        Top and bottom are set to 0 in case of a two dimensional spatial
        extent.

        :return: A the spatial extent as tuple (north, south, east, west,
                 top, bottom)
        """
        return self.spatial_extent.get_spatial_extent_as_tuple()

    def get_spatial_extent(self):
        """Return the spatial extent"""
        return self.spatial_extent

    def select(self, dbif=None, mapset=None):
        """Select temporal dataset entry from database and fill
        the internal structure

        The content of every dataset is stored in the temporal database.
        This method must be used to fill this object with the content
        from the temporal database.

        :param dbif: The database interface to be used
        :param mapset: The dbif connection to be used
        """

        dbif, connection_state_changed = init_dbif(dbif)

        # default mapset is mapset of this instance
        if mapset is None:
            mapset = self.get_mapset()

        self.base.select(dbif, mapset=mapset)
        self.temporal_extent.select(dbif, mapset=mapset)
        self.spatial_extent.select(dbif, mapset=mapset)
        self.metadata.select(dbif, mapset=mapset)
        if self.is_stds() is False:
            self.stds_register.select(dbif, mapset=mapset)

        if connection_state_changed:
            dbif.close()

    def is_in_db(self, dbif=None, mapset=None):
        """Check if the dataset is registered in the database

        :param dbif: The database interface to be used
        :param mapset: The dbif connection to be used
        :return: True if the dataset is registered in the database
        """
        return self.base.is_in_db(dbif, mapset)

    @abstractmethod
    def delete(self):
        """Delete dataset from database if it exists"""

    def insert(self, dbif=None, execute=True):
        """Insert dataset into database

        :param dbif: The database interface to be used
        :param execute: If True the SQL statements will be executed.
                        If False the prepared SQL statements are returned
                        and must be executed by the caller.
        :return: The SQL insert statement in case execute=False, or an
                 empty string otherwise
        """

        # it must be possible to insert a map from a different
        # mapset in the temporal database of the current mapset
        # the temporal database must be in the current mapset

        dbif, connection_state_changed = init_dbif(dbif)

        self.msgr.debug(2, "AbstractDataset.insert...")

        # only modify database in current mapset
        mapset = get_current_mapset()

        # Build the INSERT SQL statement
        statement = self.base.get_insert_statement_mogrified(dbif)
        statement += self.temporal_extent.get_insert_statement_mogrified(dbif)
        statement += self.spatial_extent.get_insert_statement_mogrified(dbif)
        statement += self.metadata.get_insert_statement_mogrified(dbif)
        if self.is_stds() is False:
            statement += self.stds_register.get_insert_statement_mogrified(dbif)

        self.msgr.debug(2, "insert with %s" % statement)
        if execute:
            # database to be modified must be in the current mapset
            dbif.execute_transaction(statement, mapset=mapset)
            if connection_state_changed:
                dbif.close()
            return ""

        if connection_state_changed:
            dbif.close()
        return statement

    def update(self, dbif=None, execute=True, ident=None):
        """Update the dataset entry in the database from the internal structure
        excluding None variables

        :param dbif: The database interface to be used
        :param execute: If True the SQL statements will be executed.
                        If False the prepared SQL statements are returned
                        and must be executed by the caller.
        :param ident: The identifier to be updated, useful for renaming
        :return: The SQL update statement in case execute=False, or an
                 empty string otherwise
        """

        dbif, connection_state_changed = init_dbif(dbif)

        # Build the UPDATE SQL statement
        statement = self.base.get_update_statement_mogrified(dbif, ident)
        statement += self.temporal_extent.get_update_statement_mogrified(dbif, ident)
        statement += self.spatial_extent.get_update_statement_mogrified(dbif, ident)
        statement += self.metadata.get_update_statement_mogrified(dbif, ident)

        if self.is_stds() is False:
            statement += self.stds_register.get_update_statement_mogrified(dbif, ident)

        if execute:
            dbif.execute_transaction(statement)
            if connection_state_changed:
                dbif.close()
            return ""

        if connection_state_changed:
            dbif.close()
        return statement

    def update_all(self, dbif=None, execute=True, ident=None):
        """Update the dataset entry in the database from the internal structure
        and include None variables.

        :param dbif: The database interface to be used
        :param execute: If True the SQL statements will be executed.
                        If False the prepared SQL statements are returned
                        and must be executed by the caller.
        :param ident: The identifier to be updated, useful for renaming
        :return: The SQL update statement in case execute=False, or an
                 empty string otherwise
        """

        dbif, connection_state_changed = init_dbif(dbif)

        # Build the UPDATE SQL statement
        statement = self.base.get_update_all_statement_mogrified(dbif, ident)
        statement += self.temporal_extent.get_update_all_statement_mogrified(
            dbif, ident
        )
        statement += self.spatial_extent.get_update_all_statement_mogrified(dbif, ident)
        statement += self.metadata.get_update_all_statement_mogrified(dbif, ident)

        if self.is_stds() is False:
            statement += self.stds_register.get_update_all_statement_mogrified(
                dbif, ident
            )

        if execute:
            dbif.execute_transaction(statement)
            if connection_state_changed:
                dbif.close()
            return ""

        if connection_state_changed:
            dbif.close()
        return statement

    def is_time_absolute(self):
        """Return True in case the temporal type is absolute

        :return: True if temporal type is absolute, False otherwise
        """
        if "temporal_type" in self.base.D:
            return self.base.get_ttype() == "absolute"
        else:
            return None

    def is_time_relative(self):
        """Return True in case the temporal type is relative

        :return: True if temporal type is relative, False otherwise
        """
        if "temporal_type" in self.base.D:
            return self.base.get_ttype() == "relative"
        else:
            return None

    def get_temporal_extent(self):
        """Return the temporal extent of the correct internal type"""
        if self.is_time_absolute():
            return self.absolute_time
        if self.is_time_relative():
            return self.relative_time
        return None

    temporal_extent = property(fget=get_temporal_extent)

    def temporal_relation(self, dataset):
        """Return the temporal relation of self and the provided dataset

        :return: The temporal relation as string
        """
        return self.temporal_extent.temporal_relation(dataset.temporal_extent)

    def temporal_intersection(self, dataset):
        """Intersect self with the provided dataset and
        return a new temporal extent with the new start and end time

        :param dataset: The abstract dataset to temporal intersect with
        :return: The new temporal extent with start and end time,
                 or None in case of no intersection
        """
        return self.temporal_extent.intersect(dataset.temporal_extent)

    def temporal_union(self, dataset):
        """Creates a union with the provided dataset and
        return a new temporal extent with the new start and end time.

        :param dataset: The abstract dataset to create temporal union with
        :return: The new temporal extent with start and end time,
                 or None in case of no intersection
        """
        return self.temporal_extent.union(dataset.temporal_extent)

    def temporal_disjoint_union(self, dataset):
        """Creates a union with the provided dataset and
        return a new temporal extent with the new start and end time.

        :param dataset: The abstract dataset to create temporal union with
        :return: The new temporal extent with start and end time
        """
        return self.temporal_extent.disjoint_union(dataset.temporal_extent)


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


class AbstractDatasetComparisonKeyStartTime(object):
    """This comparison key can be used to sort lists of abstract datasets
    by start time

     Example:

     .. code-block:: python

         # Return all maps in a space time raster dataset as map objects
         map_list = strds.get_registered_maps_as_objects()

         # Sort the maps in the list by start time
         sorted_map_list = sorted(map_list, key=AbstractDatasetComparisonKeyStartTime)
    """

    def __init__(self, obj, *args):
        self.obj = obj

    def __lt__(self, other):
        startA, endA = self.obj.get_temporal_extent_as_tuple()
        startB, endB = other.obj.get_temporal_extent_as_tuple()
        return startA < startB

    def __gt__(self, other):
        startA, endA = self.obj.get_temporal_extent_as_tuple()
        startB, endB = other.obj.get_temporal_extent_as_tuple()
        return startA > startB

    def __eq__(self, other):
        startA, endA = self.obj.get_temporal_extent_as_tuple()
        startB, endB = other.obj.get_temporal_extent_as_tuple()
        return startA == startB

    def __le__(self, other):
        startA, endA = self.obj.get_temporal_extent_as_tuple()
        startB, endB = other.obj.get_temporal_extent_as_tuple()
        return startA <= startB

    def __ge__(self, other):
        startA, endA = self.obj.get_temporal_extent_as_tuple()
        startB, endB = other.obj.get_temporal_extent_as_tuple()
        return startA >= startB

    def __ne__(self, other):
        startA, endA = self.obj.get_temporal_extent_as_tuple()
        startB, endB = other.obj.get_temporal_extent_as_tuple()
        return startA != startB


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


class AbstractDatasetComparisonKeyEndTime(object):
    """This comparison key can be used to sort lists of abstract datasets
    by end time

     Example:

     .. code-block:: python

         # Return all maps in a space time raster dataset as map objects
         map_list = strds.get_registered_maps_as_objects()

         # Sort the maps in the list by end time
         sorted_map_list = sorted(map_list, key=AbstractDatasetComparisonKeyEndTime)
    """

    def __init__(self, obj, *args):
        self.obj = obj

    def __lt__(self, other):
        startA, endA = self.obj.get_temporal_extent_as_tuple()
        startB, endB = other.obj.get_temporal_extent_as_tuple()
        return endA < endB

    def __gt__(self, other):
        startA, endA = self.obj.get_temporal_extent_as_tuple()
        startB, endB = other.obj.get_temporal_extent_as_tuple()
        return endA > endB

    def __eq__(self, other):
        startA, endA = self.obj.get_temporal_extent_as_tuple()
        startB, endB = other.obj.get_temporal_extent_as_tuple()
        return endA == endB

    def __le__(self, other):
        startA, endA = self.obj.get_temporal_extent_as_tuple()
        startB, endB = other.obj.get_temporal_extent_as_tuple()
        return endA <= endB

    def __ge__(self, other):
        startA, endA = self.obj.get_temporal_extent_as_tuple()
        startB, endB = other.obj.get_temporal_extent_as_tuple()
        return endA >= endB

    def __ne__(self, other):
        startA, endA = self.obj.get_temporal_extent_as_tuple()
        startB, endB = other.obj.get_temporal_extent_as_tuple()
        return endA != endB


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

if __name__ == "__main__":
    import doctest

    doctest.testmod()