Temporal

Handling Temporal Data in TerraME

Pedro R. Andrade, Rodrigo Avancini

This tutorial still does not work. Its content is currently being implemented.

Summary

• Introduction
• Temporal Layers
• Filling cells
• Splitted Layers
• Visualising output
• Documentation

Introduction

This tutorial describes how TerraME handles temporal geospatial data. There are two ways to represent temporal data in TerraME:

1. The different times are stored as separate layers, whose names follow the same prefix, followed by underscore and then the time. It is important to repeat that the time here is related to the name of the layers. If the data sources are different but the layer names follow the same pattern, they will be considered as different times for the same data.
2. Using only one layer. In this case, different times are described as attributes with the same prefix, followed by underscore and then the given time.

It is possible to convert these representations using Layer:split() and Layer:merge().

This tutorial uses the following files:

• indigenous_2000.shp, indigenous_2005.shp, indigenous_2010.shp: indigenous lands in Brazilian Amazonia in three different years.
• roads_2000.shp, roads_2010.shp: roads in Brazilian Amazonia in two years.
• limit.shp: a polygon with the legal Amazonia limit.

Temporal Layers

import("gis")

proj = Project{
    file = "amazonia.tview",
    clean = true,
    indigenous = "indigenous*.shp",
    roads = "roads*.shp",
    limit = "limit.shp"
}

Note that layers indigenous and roads will not exist. What really exist are the layers indigenous_2005, indigenous_2010, indigenous_2010, roads_2000, and roads_2010. This is the way one refers to a temporal layer in TerraME: always use the name without the temporal representation.

TerraME automatically recognizes the available times when working with files. If the layer comes from a database or a web service, it is necessary to explicitly define the selected times. In this case, it is necessary to define the Layer explicitly, as shown in the code below. The other available times will be ignored in this case. For example, the code below creates only two layers for indigenous lands, with years 2000 and 2010.

Layer{
    project = proj,
    file = "indigenous*.shp"
    times = {2000, 2010}
}

Filling cells

In order to fill cells from temporal data, first it is necessary to create a cellular space. Note that the geometry of the cellular space is static. Only the attributes might change over time.

amazonia = Layer{
    project = proj,
    name = "cells",
    clean = true,
    file = "amazonia.shp",
    input = "limit",
    resolution = 50000
}

When filling data, use the layer name prefix, and TerraME will create attributes for all the available times. For example, the code below creates the attributes "dist_2000" and "dist_2010" and then "il_2000", "il_2005", and "il_2010". These five attributes will be stored in file amazonia.shp.

amazonia:fill{
    operation = "distance",
    layer = "roads*",
    attribute = "dist"
}

amazonia:fill{
    operation = "area",
    layer = "indigenous*",
    attribute = "il" -- indigenous lands
}

Splitted Layers

There is a second temporal representation in TerraME. It stores the different times in different layers, splitting the data. It is useful for large data in order to save memory, loading each time separated from the others. In this case, TerraME creates new layers whenever necessary during Layer:fill() calls. The code below uses split to create layers amazonia_2000 and amazonia_2010, each one stored in a different shapefile with the same name of the layer. Each shapefile will have one attribute dist. The attribute name does not have a temporal suffix as the time is already defined in the layer's name.

amazonia:fill{
    operation = "distance",
    layer = "roads*",
    attribute = "dist",
    split = true
}

A new call to Layer:fill() using split adds attributes to files that already exist and create new ones whenever necessary. For example, the code below creates layer amazonia_2005 in addition to the two other temporal layers, as there are three years of data for indigenous lands and only two years for roads.

amazonia:fill{
    operation = "area",
    layer = "indigenous*",
    attribute = "il", -- indigenous lands
    split = true
}

Using splitted representation, it is recommended to create non-temporal attributes after filling the temporal ones. Each file created with a new time is a copy of the file without temporal suffix. This way, if non-temporal attributes are created before the temporal ones, the temporal files will contain copies of the non-temporal attributes.

Visualising output

To visualize the attributes created by Layer:fill(), it is necessary to create a CellularSpace. When this CellularSpace is created, it executes as follows:

1. When all the data is stored in amazonia.shp, it loads data and creates the attributes il from il_2000 and dist from dist_200.
2. When the data is splitted, it loads from amazonia.shp and also from amazonia_2000.shp, the first temporal data. It one attribute belongs to both files, the attribute of the non-temporal layer will be overwritten by the first temporal layer.

cs = CellularSpace{
    project = proj,
    layer = "amazonia*" -- TODO: aqui e o problema, se for a representacao 1 nao tem o *
}

Now it is necessary to create some Map objects to visualize the attributes. For example, the code below creates two Maps, one for distance to roads and the other for indigenous lands. Be careful to include all the data to be visualized by a Map in the static data or in the first time.

map1 = Map{
    target = cs,
    select = "il",
    slices = 6,
    color = "Greens"
}

map2 = Map{
    target = cs,
    select = "dist",
    slices = 6,
    color = "Blues"
}

In order to tell TerraME to update the CellularSpace with the new temporal data, it is necessary to create an Event using the CellularSpace as action. One additional Event needs to be created for each Map. All the Events have to belong to a Timer.

timer = Timer{
    Event{start = 2000, action = cs},
    Event{start = 2000, action = map1},
    Event{start = 2000, action = map2},
}

Finally, just run the Timer until the final available time.

timer:run(2010) -- final time

Documentation

TerraME can use fill scripts to automatically document cellular layers. To accomplish that, it is necessary to create a TerraME package to store data as well as scripts to create projects and cellular spaces, in the same way of packages without temporal data.