GRASS logo

Note: A new GRASS GIS stable version has been released: GRASS GIS 7.4, available here.
Updated manual page: here

NAME

t.rast.mapcalc - Performs spatio-temporal mapcalc expressions on temporally sampled maps of space time raster datasets.

KEYWORDS

temporal, algebra, raster, time

SYNOPSIS

t.rast.mapcalc
t.rast.mapcalc --help
t.rast.mapcalc [-ns] inputs=name[,name,...] expression=string [method=name[,name,...]] output=name basename=basename [nprocs=integer] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-n
Register Null maps
-s
Check spatial overlap
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog

Parameters:

inputs=name[,name,...] [required]
Name of the input space time raster datasets
expression=string [required]
Spatio-temporal mapcalc expression
method=name[,name,...]
The method to be used for sampling the input dataset
Options: start, during, overlap, contain, equal, follows, precedes
Default: equal
output=name [required]
Name of the output space time raster dataset
basename=basename [required]
Basename for output raster maps
A numerical suffix separated by an underscore will be attached to create a unique identifier
nprocs=integer
Number of r.mapcalc processes to run in parallel
Default: 1

Table of contents

DESCRIPTION

t.rast.mapcalc performs spatio-temporal mapcalc expressions on maps of temporally sampled space time raster datasets (STRDS). Spatial and temporal operators and internal variables are available in the expression string. The description of the spatial operators, functions and internal variables is available in the r.mapcalc manual page. The temporal functions are described in detail below.

This module expects several parameter. All space time raster datasets that are referenced in the mapcalc expression must be listed in the input option. The first space time raster dataset that is listed as input will be used to temporally sample all other space time raster datasets. The temporal sampling method can be chosen using the method option. The order of the STRDS's in the mapcalc expression can be different to the order of the STRDS's in the input option. The resulting space time raster dataset must be specified in the output option together with the base name of generated raster maps that are registered in the resulting STRDS. Empty maps resulting from map-calculation are not registered by default. This behavior can be changed with the -n flag. The flag -s can be used to assure that only spatial related maps in the STRDS's are processed. Spatial related means that temporally related maps overlap in their spatial extent.

The module t.rast.mapcalc supports parallel processing. The option nprocs specifies the number of processes that can be started in parallel.

A mapcalc expression must be provided to process the temporal sampled maps. Temporal internal variables are available in addition to the r.mapcalc spatial operators and functions:

Supported internal variables for relative and absolute time:

Supported internal variables for absolute time of the current sample interval or instance:

The end_* functions are represented by the null() internal variables in case of time instances.

NOTES

We will discuss the internal work of t.rast.mapcalc with an example. Imagine we have two STRDS as input, each with monthly granularity. The first one A has 6 raster maps (a3 ... a8) with a temporal range from March to August. The second STRDS B has 12 raster maps (b1 ... b12) ranging from January to December. The value of the raster maps is the number of the month from their interval start time. Dataset A will be used to sample dataset B to create a dataset C. We want to add all maps with equal time stamps if the month of the start time is May or June, otherwise we multiply the maps. The command will look as follows:

t.rast.mapcalc input=A,B output=C basename=c method=equal \
    expression="if(start_month() == 5 || start_month() == 6, (A + B), (A * B))"

The resulting raster maps in dataset C can be listed with t.rast.list:

name    start_time              min     max
c_1     2001-03-01 00:00:00     9.0     9.0
c_2     2001-04-01 00:00:00     16.0    16.0
c_3     2001-05-01 00:00:00     10.0    10.0
c_4     2001-06-01 00:00:00     12.0    12.0
c_5     2001-07-01 00:00:00     49.0    49.0
c_6     2001-08-01 00:00:00     64.0    64.0

Internally the spatio-temporal expression will be analyzed for each time interval of the sample dataset A, the temporal functions will be replaced by numerical values, the names of the space time raster datasets will be replaced by the corresponding raster maps. The final expression will be passed to r.mapcalc, resulting in 6 runs:

r.mapcalc expression="c_1 = if(3 == 5 || 3 == 6, (a3 + b3), (a3 * b3))"
r.mapcalc expression="c_2 = if(4 == 5 || 4 == 6, (a4 + b4), (a4 * b4))"
r.mapcalc expression="c_3 = if(5 == 5 || 5 == 6, (a5 + b5), (a5 * b5))"
r.mapcalc expression="c_4 = if(6 == 5 || 6 == 6, (a6 + b6), (a6 * b6))"
r.mapcalc expression="c_5 = if(7 == 5 || 7 == 6, (a7 + b7), (a7 * b7))"
r.mapcalc expression="c_6 = if(8 == 5 || 8 == 6, (a8 + b8), (a8 * b8))"

EXAMPLE

The following command it is creating a new raster space time dataset where in the January maps are if the temperature is more than 0 it is setting null otherwise it set the original value. The other months are copied as the original one.
t.rast.mapcalc input=tempmean_monthly output=january_under_0 basename=january_under_0 \
    expression="if(start_month() == 1 && tempmean_monthly > 0, null(), tempmean_monthly)"

# printing the minimum or maximum values only for January
t.rast.list january_under_0 columns=name,start_time,min,max | grep 01-01
name|start_time|min|max
january_under_0_01|2009-01-01 00:00:00|-3.380823|-7e-06
january_under_0_13|2010-01-01 00:00:00|-5.266929|-0.000154
january_under_0_25|2011-01-01 00:00:00|-4.968747|-6.1e-05
january_under_0_37|2012-01-01 00:00:00|-0.534994|-0.014581

# these are the original data, you can see that the maximum is different
t.rast.list tempmean_monthly columns=name,start_time,min,max | grep 01-01
2009_01_tempmean|2009-01-01 00:00:00|-3.380823|7.426054
2010_01_tempmean|2010-01-01 00:00:00|-5.266929|5.71131
2011_01_tempmean|2011-01-01 00:00:00|-4.968747|4.967295
2012_01_tempmean|2012-01-01 00:00:00|-0.534994|9.69511

SEE ALSO

r.mapcalc, t.register, t.rast.list, t.info

Temporal data processing Wiki

AUTHOR

Sören Gebbert, Thünen Institute of Climate-Smart Agriculture

Last changed: $Date: 2015-09-22 01:12:20 -0700 (Tue, 22 Sep 2015) $

SOURCE CODE

Available at: t.rast.mapcalc source code (history)


Note: A new GRASS GIS stable version has been released: GRASS GIS 7.4, available here.
Updated manual page: here

Main index | Temporal index | Topics index | Keywords index | Full index

© 2003-2018 GRASS Development Team, GRASS GIS 7.0.7svn Reference Manual