1t.rast.algebra(1)             Grass User's Manual            t.rast.algebra(1)
2
3
4

NAME

6       t.rast.algebra   -  Apply temporal and spatial operations on space time
7       raster datasets using temporal raster algebra.
8

KEYWORDS

10       temporal, algebra, raster, time
11

SYNOPSIS

13       t.rast.algebra
14       t.rast.algebra --help
15       t.rast.algebra   [-sngd]   expression=string   basename=string    [suf‐
16       fix=string]     [nprocs=integer]     [--help]   [--verbose]   [--quiet]
17       [--ui]
18
19   Flags:
20       -s
21           Check the spatial topology of temporally related maps  and  process
22           only spatially related maps
23
24       -n
25           Register Null maps
26
27       -g
28           Use granularity sampling instead of the temporal topology approach
29
30       -d
31           Perform  a  dry  run, compute all dependencies and module calls but
32           don’t run them
33
34       --help
35           Print usage summary
36
37       --verbose
38           Verbose module output
39
40       --quiet
41           Quiet module output
42
43       --ui
44           Force launching GUI dialog
45
46   Parameters:
47       expression=string [required]
48           r.mapcalc expression for temporal and  spatial  analysis  of  space
49           time raster datasets
50
51       basename=string [required]
52           Basename of the new generated output maps
53           A  numerical  suffix separated by an underscore will be attached to
54           create a unique identifier
55
56       suffix=string
57           Suffix to add at basename: set ’gran’ for granularity,  ’time’  for
58           the  full  time  format, ’num’ for numerical suffix with a specific
59           number of digits (default %05)
60           Default: num
61
62       nprocs=integer
63           Number of r.mapcalc processes to run in parallel
64           Default: 1
65

DESCRIPTION

67       t.rast.algebra performs temporal and spatial map algebra operations  on
68       space time raster datasets (STRDS) using the temporal raster algebra.
69
70   PROGRAM USE
71       The  module  expects  an expression as input parameter in the following
72       form:
73
74       "result = expression"
75
76       The statement structure is similar  to  that  of  r.mapcalc.   In  this
77       statement,  result represents the name of the space time raster dataset
78       (STRDS) that will contain the result of the calculation that  is  given
79       as  expression  on  the right side of the equality sign.  These expres‐
80       sions can be any valid or nested combination of temporal operations and
81       spatial  overlay  or buffer functions that are provided by the temporal
82       algebra.
83
84       The temporal raster algebra works only with space time raster  datasets
85       (STRDS).  The algebra provides methods for map selection based on their
86       temporal relations. It is also possible to temporally  shift  maps,  to
87       create  temporal  buffer  and  to snap time instances to create a valid
88       temporal topology. Furthermore, expressions can be nested and evaluated
89       in  conditional statements (if, else statements). Within if-statements,
90       the algebra provides temporal variables like start time, end time,  day
91       of  year, time differences or number of maps per time interval to build
92       up conditions.
93       In addition the algebra provides a subset  of  the  spatial  operations
94       from r.mapcalc. All these operations can be assigned to STRDS or to the
95       map lists resulting of operations between STRDS.
96
97       By default,  only  temporal  topological  relations  among  space  time
98       datasets  (STDS) are evaluated. The -s flag can be used to additionally
99       activate the evaluation of the spatial topology based  on  the  spatial
100       extent of maps.
101
102       The expression option must be passed as quoted expression, for example:
103       t.rast.algebra expression="C = A + B" basename=result
104       Where  C  is  the  new space time raster dataset that will contain maps
105       with the basename "result" and  a  numerical  suffix  separated  by  an
106       underscore  that  represent the sum of maps from the STRDS A and tempo‐
107       rally equal maps (i.e., maps with  equal  temporal  topology  relation)
108       from the STRDS B.
109
110       The map basename for the result STRDS must always be specified.
111

TEMPORAL RASTER ALGEBRA

113       The  temporal  algebra  provides a wide range of temporal operators and
114       functions that will be presented in the following section.
115
116   TEMPORAL RELATIONS
117       Several temporal topology relations are supported between  maps  regis‐
118       tered in space time datasets:
119       equals            A ------
120                         B ------
121       during            A  ----
122                         B ------
123       contains          A ------
124                         B  ----
125       starts            A ----
126                         B ------
127       started           A ------
128                         B ----
129       finishs           A   ----
130                         B ------
131       finished          A ------
132                         B   ----
133       precedes          A ----
134                         B     ----
135       follows           A     ----
136                         B ----
137       overlapped        A   ------
138                         B ------
139       overlaps          A ------
140                         B   ------
141       over              both overlaps and overlapped
142       The relations must be read as: A is related to B, like - A equals B - A
143       is during B - A contains B.
144
145       Topological relations must be specified with curly brackets {}.
146
147   TEMPORAL OPERATORS
148       The temporal algebra defines temporal operators that  can  be  combined
149       with other operators to perform spatio-temporal operations.  The tempo‐
150       ral operators process the time instances and intervals  of  two  tempo‐
151       rally  related maps and calculate the resulting temporal extent in five
152       possible different ways.
153       LEFT REFERENCE     l       Use the time stamp of the left space time dataset
154       INTERSECTION       i       Intersection
155       DISJOINT UNION     d       Disjoint union
156       UNION              u       Union
157       RIGHT REFERENCE    r       Use the time stamp of the right space time dataset
158
159   TEMPORAL SELECTION
160       The temporal selection simply selects parts of  a  space  time  dataset
161       without  processing  any  raster or vector data. The algebra provides a
162       selection operator : that by default selects  parts  of  a  space  time
163       dataset  that  are  temporally  equal  to  parts of a second space time
164       dataset. The following expression
165       C = A : B
166       means: select all parts of space time dataset A that are equal to B and
167       store them in space time dataset C. These parts are time stamped maps.
168
169       In  addition,  the inverse selection operator !: is defined as the com‐
170       plement of the selection operator, hence the following expression
171       C = A !: B
172       means: select all parts of space time time dataset A that are not equal
173       to B and store them in space time dataset C.
174
175       To  select  parts  of  a  STRDS  using  different topological relations
176       regarding to other STRDS, the temporal topology selection operator  can
177       be used. This operator consists of the temporal selection operator, the
178       topological relations that must be separated by the logical OR operator
179       |  and,  the temporal extent operator. All three parts are separated by
180       comma and surrounded by curly brackets as follows: {"temporal selection
181       operator", "topological relations", "temporal operator"}.
182
183       Examples:
184       C = A {:,equals} B
185       C = A {!:,equals} B
186       We can now define arbitrary topological relations using the OR operator
187       "|" to connect them:
188       C = A {:,equals|during|overlaps} B
189       Select all parts of A that are equal to B, during B or overlaps B.
190       In addition, we can define the temporal extent of the  resulting  STRDS
191       by adding the temporal operator.
192       C = A {:,during,r} B
193       Select  all  parts  of A that are during B and use the temporal extents
194       from B for C.
195       The selection operator is implicitly contained in the temporal topology
196       selection  operator,  so  that the following statements are exactly the
197       same:
198       C = A : B
199       C = A {:} B
200       C = A {:,equal} B
201       C = A {:,equal,l} B
202       Same for the complementary selection:
203       C = A !: B
204       C = A {!:} B
205       C = A {!:,equal} B
206       C = A {!:,equal,l} B
207
208   CONDITIONAL STATEMENTS
209       Selection operations can be evaluated within conditional statements  as
210       showed  below.  Note  that A and B can be either space time datasets or
211       expressions. The temporal relationship between the conditions  and  the
212       conclusions  can be defined at the beginning of the if statement (third
213       and fourth examples below). The relationship between then and else con‐
214       clusion must be always equal.
215       if statement                        decision option                        temporal relations
216         if(if, then, else)
217         if(conditions, A)                   A if conditions are True;              temporal topological relation between if and then is equal.
218         if(conditions, A, B)                A if conditions are True, B otherwise; temporal topological relation between if, then and else is equal.
219         if(topologies, conditions, A)       A if conditions are True;              temporal topological relation between if and then is explicitly specified by topologies.
220         if(topologies, conditions, A, B)    A if conditions are True, B otherwise; temporal topological relation between if, then and else is explicitly specified by topologies.
221       The  conditions  are  comparison  expressions that are used to evaluate
222       space time datasets. Specific values of temporal variables are compared
223       by logical operators and evaluated for each map of the STRDS.
224       Important: The conditions are evaluated from left to right.
225
226   Logical operators
227       Symbol  description
228         ==    equal
229         !=    not equal
230         >     greater than
231         >=    greater than or equal
232         <     less than
233         <=    less than or equal
234         &&    and
235         ||    or
236
237   Temporal functions
238       The  following  temporal functions are evaluated only for the STDS that
239       must be given in parenthesis.
240       td(A)                    Returns a list of time intervals of STDS A
241       start_time(A)            Start time as HH::MM:SS
242       start_date(A)            Start date as yyyy-mm-DD
243       start_datetime(A)        Start datetime as yyyy-mm-DD HH:MM:SS
244       end_time(A)              End time as HH:MM:SS
245       end_date(A)              End date as yyyy-mm-DD
246       end_datetime(A)          End datetime as  yyyy-mm-DD HH:MM
247       start_doy(A)             Day of year (doy) from the start time [1 - 366]
248       start_dow(A)             Day of week (dow) from the start time [1 - 7], the start of the week is Monday == 1
249       start_year(A)            The year of the start time [0 - 9999]
250       start_month(A)           The month of the start time [1 - 12]
251       start_week(A)            Week of year of the start time [1 - 54]
252       start_day(A)             Day of month from the start time [1 - 31]
253       start_hour(A)            The hour of the start time [0 - 23]
254       start_minute(A)          The minute of the start time [0 - 59]
255       start_second(A)          The second of the start time [0 - 59]
256       end_doy(A)               Day of year (doy) from the end time [1 - 366]
257       end_dow(A)               Day of week (dow) from the end time [1 - 7], the start of the week is Monday == 1
258       end_year(A)              The year of the end time [0 - 9999]
259       end_month(A)             The month of the end time [1 - 12]
260       end_week(A)              Week of year of the end time [1 - 54]
261       end_day(A)               Day of month from the start time [1 - 31]
262       end_hour(A)              The hour of the end time [0 - 23]
263       end_minute(A)            The minute of the end time [0 - 59]
264       end_second(A)            The second of the end time [0 - 59]
265
266   Comparison operator
267       As mentioned above, the conditions are comparison expressions that  are
268       used to evaluate space time datasets. Specific values of temporal vari‐
269       ables are compared by logical operators and evaluated for each  map  of
270       the  STDS  and  (optionally)  related maps.  For complex relations, the
271       comparison operator can be used to combine conditions.
272       The structure is similar to the select operator with the addition of an
273       aggregation  operator: {"comparison operator", "topological relations",
274       aggregation operator, "temporal operator"}
275       This aggregation operator (| or &) defines the behaviour when a map  is
276       related  to  more than one map, e.g. for the topological relation ’con‐
277       tains’.  Should all (&) conditions for the related maps be true  or  is
278       it  sufficient  to  have  any (|) condition that is true. The resulting
279       boolean value is then compared to the first condition by the comparison
280       operator  (||  or &&).  By default, the aggregation operator is related
281       to the comparison operator:
282       comparison operator -> aggregation operator:
283       || -> | and && -> &
284       Examples:
285       Condition 1 {||, equal, r} Condition 2
286       Condition 1 {&&, equal|during, l} Condition 2
287       Condition 1 {&&, equal|contains, |, l} Condition 2
288       Condition 1 {&&, equal|during, l} Condition 2 && Condition 3
289       Condition 1 {&&, equal|during, l} Condition 2 {&&,contains, |, r} Condition 3
290
291   Hash operator
292       Additionally, the number of maps in intervals can be computed and  used
293       in conditional statements with the hash (#) operator.
294       A {#, contains} B
295       This  expression  computes the number of maps from space time dataset B
296       which are during the time intervals of maps from space time dataset A.
297       A list of integers (scalars) corresponding to the maps of A  that  con‐
298       tain maps from B will be returned.
299       C = if({equal}, A {#, contains} B > 2, A {:, contains} B)
300       This  expression  selects  all  maps  from A that temporally contain at
301       least 2 maps from B and stores them in space time dataset C. The  lead‐
302       ing equal statement in the if condition specifies the temporal relation
303       between the if and then part of the if expression. This is very  impor‐
304       tant,  so  we  do  not need to specify a global time reference (a space
305       time dataset) for temporal processing.
306
307       Furthermore, the temporal algebra allows temporal  buffering,  shifting
308       and snapping with the functions buff_t(), tshift() and tsnap(), respec‐
309       tively.
310       buff_t(A, size)         Buffer STDS A with granule ("1 month" or 5)
311       tshift(A, size)         Shift STDS A with granule ("1 month" or 5)
312       tsnap(A)                Snap time instances and intervals of STDS A
313
314   Single map with temporal extent
315       The temporal algebra can also handle single maps with  time  stamps  in
316       the tmap() function.
317       tmap()
318       For example:
319       C = A {:, during} tmap(event)
320       This  statement  selects  all  maps from space time data set A that are
321       during the temporal extent of the single map ’event’
322
323   Spatial raster operators
324       The module supports the following raster operations:
325       Symbol  description     precedence
326         %     modulus         1
327         /     division        1
328         *     multiplication  1
329         +     addition        2
330         -     subtraction     2
331       And raster functions:
332       abs(x)                  return absolute value of x
333       float(x)                convert x to foating point
334       int(x)                  convert x to integer [ truncates ]
335       log(x)                  natural log of x
336       sqrt(x)                 square root of x
337       tan(x)                  tangent of x (x is in degrees)
338       round(x)                round x to nearest integer
339       sin(x)                  sine of x (x is in degrees)
340       isnull(x)               check if x = NULL
341       isntnull(x)             check if x is not NULL
342       null                    set null value
343       exist(x)                Check if x is in the current mapset
344
345   Single raster map
346       The temporal raster algebra features also a function to integrate  sin‐
347       gle raster maps without time stamps into the expressions.
348       map()
349       For example:
350       C = A * map(constant_value)
351       This  statement  multiplies all raster maps from space time raster data
352       set A with the raster map ’constant_value’
353
354   Combinations of temporal, raster and select operators
355       The user can combine the  temporal  topology  relations,  the  temporal
356       operators  and  the  spatial/select operators to create spatio-temporal
357       operators as follows:
358       {"spatial or select operator", "list of temporal relations", "temporal operator"}
359       For multiple topological relations or several  related  maps  the  spa‐
360       tio-temporal operators feature implicit aggregation.  The algebra eval‐
361       uates the stated STDS by their temporal topologies and apply the  given
362       spatio-temporal  operators in a aggregated form.  If we have two STDS A
363       and B, B has three maps: b1, b2, b3 that are all  during  the  temporal
364       extent  of the single map a1 of A, then the following arithmetic calcu‐
365       lations would implicitly aggregate all maps of B into  one  result  map
366       for a1 of A:
367        C = A {+, contains} B --> c1 = a1 + b1 + b2 + b3
368
369       Important: the aggregation behaviour is not symmetric
370        C = B {+, during} A --> c1 = b1 + a1
371                                c2 = b2 + a1
372                                c3 = b3 + a1
373
374   Temporal neighbourhood modifier
375       The  neighbourhood  modifier  of r.mapcalc is extended for the temporal
376       raster algebra with the temporal dimension. The format is strds[t,r,c],
377       where t is the temporal offset, r is the row offset and c is the column
378       offset.
379       strds[2]
380       refers to the second successor of the current map.
381
382       strds[1,2]
383       refers to the cell one row below and two columns to the  right  of  the
384       current cell in the current map.
385
386       strds[1,-2,-1]
387       refers  to  the  cell  two rows above and one column to the left of the
388       current cell of the first successor map.
389
390       strds[-2,0,1]
391       refers to the cell one column to the right of the current cell  in  the
392       second predecessor map.
393

EXAMPLES

395   Computation of NDVI
396       # Sentinel-2 bands are stored separately in two STDRS "S2_b4" and "S2_b8"
397       g.region raster=sentinel2_B04_10m -p
398       t.rast.list S2_b4
399       t.rast.list S2_b8
400       t.rast.algebra basename=ndvi expression="ndvi = float(S2_b8 - S2_b4) / ( S2_b8 + S2_b4 )"
401       t.rast.colors input=ndvi color=ndvi
402
403   Sum of space-time raster datasets
404       Sum  maps  from  STRDS  A  with maps from STRDS B which have equal time
405       stamps and are temporally before Jan. 1. 2005 and store them  in  STRDS
406       D:
407       D = if(start_date(A) < "2005-01-01", A + B)
408       Create  the  sum  of  all  maps from STRDS A and B that have equal time
409       stamps and store the new maps in STRDS C:
410       C = A + B
411
412   Sum of space-time raster datasets with temporal topology relation
413       Same expression with explicit definition of the temporal topology rela‐
414       tion and temporal operators:
415       C = A {+,equal,l} B
416
417   Selection of raster cells
418       Select all cells from STRDS B with equal temporal relations to STRDS A,
419       if the cells of A are in the range [100.0, 1600] of time intervals that
420       have more than 30 days (Jan, Mar, May, Jul, Aug, Oct, Dec):
421       C = if(A > 100 && A < 1600 && td(A) > 30, B)
422
423   Selection of raster cells with temporal topology relation
424       Same expression with explicit definition of the temporal topology rela‐
425       tion and temporal operators:
426       C = if({equal}, A > 100 && A < 1600 {&&,equal} td(A) > 30, B)
427
428   Conditional computation
429       Compute the recharge in meters per second for all cells  of  precipita‐
430       tion  STRDS "Prec" if the mean temperature specified in STRDS "Temp" is
431       higher than 10 degrees. Computation is performed if  STRDS  "Prec"  and
432       "Temp"  have  equal time stamps. The number of days or fraction of days
433       per interval is computed using the td() function that has  as  argument
434       the STRDS "Prec":
435       C = if(Temp > 10.0, Prec / 3600.0 / 24.0 / td(Prec))
436
437   Conditional computation with temporal topology relation
438       Same expression with explicit definition of the temporal topology rela‐
439       tion and temporal operators:
440       C = if({equal}, Temp > 10.0, Prec / 3600.0 / 24.0 {/,equal,l} td(Prec))
441
442   Computation with time intervals
443       Compute the mean value of all maps from STRDS A that are located during
444       time  intervals of STRDS B if more than one map of A is contained in an
445       interval of B, use A otherwise. The resulting time intervals are either
446       from B or A:
447       C = if(B {#,contain} A > 1, (B {+,contain,l} A - B) / (B {#,contain} A), A)
448
449   Computation with time intervals with temporal topology relation
450       Same expression with explicit definition of the temporal topology rela‐
451       tion and temporal operators:
452       C = if({equal}, B {#,contain} A > 1, (B {+,contain,l} A {-,equal,l} B) {equal,=/} (B {#,contain} A), A)
453

SEE ALSO

455        r.mapcalc, t.vect.algebra, t.rast3d.algebra,  t.select,  t.rast3d.map‐
456       calc, t.rast.mapcalc
457
458       Temporal data processing Wiki
459

REFERENCES

461       The use of this module requires the following software to be installed:
462       PLY(Python-Lex-Yacc)
463
464       # Ubuntu/Debian
465       sudo apt-get install python3-ply
466       # Fedora
467       sudo dnf install python3-ply
468       # MS-Windows (OSGeo4W: requires "python3-pip" package to be installed)
469       python3-pip install ply
470
471       Related publications:
472
473           ·   Gebbert, S., Pebesma, E. 2014. TGRASS: A temporal GIS for field
474               based  environmental modeling.  Environmental Modelling & Soft‐
475               ware 53, 1-12 (DOI) - preprint PDF
476
477           ·   Gebbert, S., Pebesma, E. 2017. The GRASS  GIS  temporal  frame‐
478               work. International Journal of Geographical Information Science
479               31, 1273-1292 (DOI)
480
481           ·   Gebbert, S., Leppelt, T., Pebesma, E., 2019. A  topology  based
482               spatio-temporal map algebra for big data analysis.  Data 4, 86.
483               (DOI)
484

SEE ALSO

486        v.overlay, v.buffer, v.patch, r.mapcalc
487

AUTHORS

489       Thomas Leppelt, Sören  Gebbert,  Thünen  Institute  of  Climate-Smart
490       Agriculture
491

SOURCE CODE

493       Available at: t.rast.algebra source code (history)
494
495       Main index | Temporal index | Topics index | Keywords index | Graphical
496       index | Full index
497
498       © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual
499
500
501
502GRASS 7.8.2                                                  t.rast.algebra(1)
Impressum