# GRASS GIS Temporal Framework

## Introduction

The GRASS GIS Temporal Framework implements the temporal GIS functionality of GRASS GIS and provides an API to implement spatio-temporal processing modules. The framework introduces space time datasets that represent time series of raster, 3D raster or vector maps. This framework provides the following functionalities:

- Assign time stamp to maps and register maps in the temporal database

- Modification of time stamps

- Creation, renaming and deletion of space time datasets

- Registration and un-registration of maps in space time datasets

- Query of maps that are registered in space time datasets using SQL where statements

- Analysis of the spatio-temporal topology of space time datasets

- Sampling of space time datasets

- Computation of temporal and spatial relationships between registered maps

- Higher level functions that are shared between modules

Most of the functions described above are member functions of dedicated map layer and space time dataset classes.

## Temporal API

The temporal framework API consists of several dedicated modules. Each module contains one or several classes as well as function definition. The API can be roughly divided in a low level and high level part. However, several functions from the low level module are used in module implementation as well.

### Low level API

The low level API implements the core functionality of the temporal framework. Core functionality is for example the database interface, the temporal database creation and initialization, the SQL object serialization, all classes that represent table entries, datetime mathematics and many more.

#### `core`

> The core functionality of the temporal framework:

> - Initialization function `init()`

> - Definition of global variables

> - Several global functions to access TGIS specific variables

> - Interfaces to the TGIS C-library and PyGRASS messenger objects

> - Database interface connection class `SQLDatabaseInterfaceConnection` to sqlite3 and postgresql database backends

> - Functions to create the temporal database

#### `base`

> Implements of basic dataset information and SQL conversion of such information:

> - Definition of the SQL serialize class `DictSQLSerializer` that converts the content of temporal classes into SQL SELECT, INSERT or UPDATE statements

> - Definition of `SQLDatabaseInterface` that is the base class for all temporal datatype subclasses

> - Contains classes for all datasets 1 that contain basic information (id, name, mapset, creator, …)

#### `spatial_extent`

> Implements of 2d and 3d spatial extents of all datasets:

> - Implements class `SpatialExtent` that is the base class for all dataset specific spatial extent classes It provides spatial topological logic and operations for 2D and 3D extents

> - Implements spatial extent classes for all datasets 1

#### `temporal_extent`

> Implements of the temporal extent of all datasets for relative and absolute time:

> - Implements class `TemporalExtent` that is the base class for all dataset specific temporal extent classes It provides temporal topological logic and operations

> - Implements temporal extent classes for relative time and absolute time for all datasets 1

#### `metadata`

> Implements the metadata base classes and datatype specific derivatives fpr all datasets 1.

#### `spatial_topology_dataset_connector`

> Implements the interface to link datasets by spatial topological relations

#### `temporal_topology_dataset_connector`

> Implements the interface to link datasets by temporal topological relations

#### `c_libraries_interface`

> The RPC C-library interface for exit safe and fast access to raster, vector and 3D raster information.

#### `temporal_granularity`

> The computation of the temporal granularity for a list of `AbstractDataset` objects for absolute and relative is implemented here.

#### `datetime_math`

> This module contains function to parse, convert and process datetime objects in the temporal framework.

Spatio-temporal algebra classes for space time raster and vector datasets are defined in:

- `temporal_algebra`

- `temporal_operator`

- `temporal_raster_base_algebra`

- `temporal_raster_algebra`

- `temporal_raster3d_algebra`

- `temporal_vector_algebra`

### High level API

The high level API utilizes the low level API. Its classes and functions are usually used to implement temporal processing algorithms and temporal GRASS modules.

#### `abstract_dataset`

> - Implements the base class for all datasets 1 `AbstractDataset`.

> - Implements the the select, insert and update functionality as well as convenient functions to access the base, extent and metadata information

#### `abstract_map_dataset`

> - Implements the base class `AbstractMapDataset` for all map layer specific classes

> - Provides the interface to all map layer specific information in the temporal database

#### `abstract_space_time_dataset`

> - Implements the base class `AbstractSpaceTimeDataset` for all Space Time Datasets classes

> - Contains the creation and deletion functionality, the map registration and un-registration, access methods to map layer objects and so on

> - Provides the interface to all Space Time Dataset specific information in the temporal database

#### `space_time_datasets`

> This module contains all classes that represent specific datasets 1. A module developer uses these map layer and Space Time Dataset object representations to perform spatio-temporal tasks.

#### `spatio_temporal_relationships`

> The logic to compute spatio-temporal topology for a single list or two lists of `AbstractDataset` objects is implemented in this module. The class `SpatioTemporalTopologyBuilder` provides a convenient interface for topology computation.

#### `gui_support`

> Helper functions to support the listing of space time datasets in the automatically generated GUI.

### Shared Module functionality

Functionality that is shared between different temporal GRASS modules, such as map listing, space time dataset creation, map registration and un-registration, aggregation, extraction, map calculation, statistics as well as import and export of space time datasets.

#### `aggregation`

> Aggregation of Space Time Raster Datasets based on topological relations. Used in t.rast.aggregate and t.rast.aggregate.ds

#### `extract`

> Extraction of subsets from Space Time Datasets including map algebra and vector selection statements. Used in t.rast.extract, t.rast3d.extract and t.vect.extract.

#### `factory`

> Factory functions to create datasets of all types 1.

#### `open_stds`

> Convenient functions to open existing Space Time Datasets or to create new ones. Used in almost all temporal modules.

#### `list_stds`

> Convenient functions to list datasets of all types 1 registered in the temporal database.

#### `mapcalc`

> Simple temporal algebra for Space Time Raster and 3d Raster datasets. Used in t.rast.mapcalc and t.rast3d.mapcalc

#### `register`

> Convenient functions to register a single or multiple map layer in the temporal database and SpaceTime Datasets. Used in several modules, most important t.register.

#### `sampling`

> Sampling functions used in several modules.

#### `stds_export`

> Functions to export of Space Time Datasets, used in t.rast.export, t.rast3d.export and t.vect.export.

#### `stds_import`

> Functions to import Space Time Datasets, used in t.rast.import, t.rast3d.import and t.vect.import.

#### `univar_statistics`

> Simple statistical analysis functions for Space Time Datasets, used in t.rast.univar, t.rast3d.univar and t.vect.univar.

1(1,2,3,4,5,6,7,8)

  : Raster Map Layer, 3d Raster Map Layer, Vector Map Layer, Space time Raster Datasets (STRDS), Space Time 3d Raster Datasets (STR3DS) and Space Time Vector Datasets (STVDS)

Here the full list of all temporal modules:

- temporal package
  - Submodules
  - temporal.abstract_dataset module
  - temporal.abstract_map_dataset module
  - temporal.abstract_space_time_dataset module
  - temporal.aggregation module
  - temporal.base module
  - temporal.c_libraries_interface module
  - temporal.core module
  - temporal.datetime_math module
  - temporal.extract module
  - temporal.factory module
  - temporal.gui_support module
  - temporal.list_stds module
  - temporal.mapcalc module
  - temporal.metadata module
  - temporal.open_stds module
  - temporal.register module
  - temporal.sampling module
  - temporal.space_time_datasets module
  - temporal.spatial_extent module
  - temporal.spatial_topology_dataset_connector module
  - temporal.spatio_temporal_relationships module
  - temporal.stds_export module
  - temporal.stds_import module
  - temporal.temporal_algebra module
  - temporal.temporal_extent module
  - temporal.temporal_granularity module
  - temporal.temporal_operator module
  - temporal.temporal_raster3d_algebra module
  - temporal.temporal_raster_algebra module
  - temporal.temporal_raster_base_algebra module
  - temporal.temporal_topology_dataset_connector module
  - temporal.temporal_vector_algebra module
  - temporal.unit_tests module
  - temporal.univar_statistics module
  - Module contents

## Examples

### Howto start example

This simple example shows how to open a space time raster dataset to access its registered maps.

    # Lets import the temporal framework and
    # the script framework
    import grass.temporal as tgis
    import grass.script as gs

    # Make sure the temporal database exists
    # and set the temporal GIS environment
    tgis.init()

    # We create the temporal database interface for fast processing
    dbif = tgis.SQLDatabaseInterfaceConnection()
    dbif.connect()

    # The id of a space time raster dataset is build from its name and its mapset
    id = "test@PERMANENT"

    # We create a space time raster dataset object
    strds = tgis.SpaceTimeRasterDataset(id)

    # Check if the space time raster dataset is in the temporal database
    if strds.is_in_db(dbif=dbif) == False:
        dbif.close()
        gs.fatal(_("Space time %s dataset <%s> not found") % (
            strds.get_new_map_instance(None).get_type(), id))

    # Fill the object with the content from the temporal database
    strds.select(dbif=dbif)

    # Print information about the space time raster dataset to stdout
    strds.print_info()

    # Get all maps that are registered in the strds and print
    # information about the maps to stdout
    maps = strds.get_registered_maps_as_objects(dbif=dbif)

    # We iterate over the temporal sorted map list
    for map in maps:
        # We fill the map object with the content
        # from the temporal database. We use the existing
        # database connection, otherwise a new connection
        # will be established for each map object
        # which slows the processing down
        map.select(dbif=dbif)
        map.print_info()

    # Close the database connection
    dbif.close()

### Creation of a space time dataset

This example shows howto create a space time dataset. The code is generic and works for different space time datasets (raster, 3D raster and vector):

    # Lets import the temporal framework and
    # the script framework
    import grass.temporal as tgis
    import grass.script as gs

    # The id of the new space time dataset
    id="test@PERMANENT"
    # The title of the new space time dataset
    title="This is a test dataset"
    # The description of the space time dataset
    description="The description"
    # The type of the space time dataset (strds, str3ds or stvds)
    type="strds"
    # The temporal type of the space time dataset (absolute or relative)
    temporal_type="absolute"

    # Make sure the temporal database exists
    # and set the temporal GIS environment
    tgis.init()

    # We use the dataset factory to create an new space time dataset instance of a specific type
    stds = tgis.dataset_factory(type, id)

    # We need a dtabase connection to insert the content of the space time dataset
    dbif = tgis.SQLDatabaseInterfaceConnection()
    dbif.connect()

    # First we check if the dataset is already in the database
    if stds.is_in_db(dbif=dbif) and overwrite == False:
        dbif.close()
        gs.fatal(_("Space time %s dataset <%s> is already in the database. "
                   "Use the overwrite flag.") %
                 (stds.get_new_map_instance(None).get_type(), name))

    # We delete the exiting dataset and create a new one in case we are allowed to overwrite it
    if stds.is_in_db(dbif=dbif) and overwrite == True:
        gs.warning(_("Overwrite space time %s dataset <%s> "
                     "and unregister all maps.") %
                   (stds.get_new_map_instance(None).get_type(), name))
        stds.delete(dbif=dbif)
        stds = stds.get_new_instance(id)

    # We set the initial values. This function also created the command history.
    stds.set_initial_values(temporal_type=temporaltype, semantic_type="mean",
                            title=title, description=description)

    # Now we can insert the new space time dataset in the database
    stds.insert(dbif=dbif)

    # Close the database connection
    dbif.close()

### Temporal shifting

    import grass.script as gs
    import grass.temporal as tgis

    id="test@PERMANENT"
    type="strds"

    # Make sure the temporal database exists
    tgis.init()

    dbif = tgis.SQLDatabaseInterfaceConnection()
    dbif.connect()

    stds = tgis.dataset_factory(type, id)

    if stds.is_in_db(dbif) == False:
        dbif.close()
        gs.fatal(_("Space time dataset <%s> not found in temporal database") % (id))

    stds.select(dbif=dbif)

    stds.snap(dbif=dbif)

    stds.update_command_string(dbif=dbif)
    dbif.close()

## References

- Gebbert, S., Pebesma, E., 2014. TGRASS: A temporal GIS for field based environmental modeling. Environmental Modelling & Software. 2(1):201-219. doi:10.1016/j.envsoft.2013.11.001

- TGRASS related articles in the GRASS GIS Wiki

- Supplementary material of the publication The GRASS GIS Temporal Framework to be published in International Journal of Geographical Information Science in 2017, Download `The GRASS GIS Temporal Framework: Object oriented code design with examples`

Authors

  Soeren Gebbert

TODO

  add more documentation

Help Index | Topics Index | Keywords Index | Full Index

© 2003-2024 GRASS Development Team, GRASS GIS 8.2.2dev Reference Manual