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

TEMPORAL RASTER ALGEBRA

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

EXAMPLES

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

SEE ALSO

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

REFERENCES

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

SEE ALSO

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

AUTHORS

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

SOURCE CODE

492       Available at: t.rast.algebra source code (history)
493
494       Accessed: Saturday Jan 21 21:17:05 2023
495
496       Main index | Temporal index | Topics index | Keywords index | Graphical
497       index | Full index
498
499       © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
500
501
502
503GRASS 8.2.1                                                  t.rast.algebra(1)
Impressum