1t.rast.algebra(1) GRASS GIS User's Manual t.rast.algebra(1)
2
6 t.rast.algebra - Apply temporal and spatial operations on space time
7 raster datasets using temporal raster algebra.
8
10 temporal, algebra, raster, time
11
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 Flags:
20 -s
21 Check the spatial topology of temporally related maps and process
22 only spatially related maps
23 -n
25 Register Null maps
26 -g
28 Use granularity sampling instead of the temporal topology approach
29 -d
31 Perform a dry run, compute all dependencies and module calls but
32 don’t run them
33 --help
35 Print usage summary
36 --verbose
38 Verbose module output
39 --quiet
41 Quiet module output
42 --ui
44 Force launching GUI dialog
45 Parameters:
47 expression=string [required]
48 r.mapcalc expression for temporal and spatial analysis of space
49 time raster datasets
50 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 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 nprocs=integer
63 Number of r.mapcalc processes to run in parallel
64 Default: 1
65
67 t.rast.algebra performs temporal and spatial map algebra operations on
68 space time raster datasets (STRDS) using the temporal raster algebra.
69 The module expects an expression as input parameter in the following
71 form:
72 "result = expression"
74 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 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 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 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 The map basename for the result STRDS must always be specified.
110
112 The temporal algebra provides a wide range of temporal operators and
113 functions that will be presented in the following section.
114 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 finishes 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 Topological relations must be specified with curly brackets {}.
145 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 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 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 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 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 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 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 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 In order to use the numbers returned by the functions in the last block
265 above, an offset value needs to be added. For example, start_doy(A, 0)
266 would return the DOY of the current map in STDS A. end_hour(A, -1)
267 would return the end hour of the previous map in STDS A.
268 Comparison operator
270 As mentioned above, the conditions are comparison expressions that are
271 used to evaluate space time datasets. Specific values of temporal vari‐
272 ables are compared by logical operators and evaluated for each map of
273 the STDS and (optionally) related maps. For complex relations, the
274 comparison operator can be used to combine conditions.
275 The structure is similar to the select operator with the addition of an
276 aggregation operator: {"comparison operator", "topological relations",
277 aggregation operator, "temporal operator"}
278 This aggregation operator (| or &) defines the behaviour when a map is
279 related to more than one map, e.g. for the topological relation ’con‐
280 tains’. Should all (&) conditions for the related maps be true or is
281 it sufficient to have any (|) condition that is true. The resulting
282 boolean value is then compared to the first condition by the comparison
283 operator (|| or &&). By default, the aggregation operator is related
284 to the comparison operator:
285 comparison operator -> aggregation operator:
286 || -> | and && -> &
287 Examples:
288 Condition 1 {||, equal, r} Condition 2
289 Condition 1 {&&, equal|during, l} Condition 2
290 Condition 1 {&&, equal|contains, |, l} Condition 2
291 Condition 1 {&&, equal|during, l} Condition 2 && Condition 3
292 Condition 1 {&&, equal|during, l} Condition 2 {&&,contains, |, r} Condition 3
293 Hash operator
295 Additionally, the number of maps in intervals can be computed and used
296 in conditional statements with the hash (#) operator.
297 A {#, contains} B
298 This expression computes the number of maps from space time dataset B
299 which are during the time intervals of maps from space time dataset A.
300 A list of integers (scalars) corresponding to the maps of A that con‐
301 tain maps from B will be returned.
302 C = if({equal}, A {#, contains} B > 2, A {:, contains} B)
303 This expression selects all maps from A that temporally contain at
304 least 2 maps from B and stores them in space time dataset C. The lead‐
305 ing equal statement in the if condition specifies the temporal relation
306 between the if and then part of the if expression. This is very impor‐
307 tant, so we do not need to specify a global time reference (a space
308 time dataset) for temporal processing.
309 Furthermore, the temporal algebra allows temporal buffering, shifting
311 and snapping with the functions buff_t(), tshift() and tsnap(), respec‐
312 tively.
313 buff_t(A, size) Buffer STDS A with granule ("1 month" or 5)
314 tshift(A, size) Shift STDS A with granule ("1 month" or 5)
315 tsnap(A) Snap time instances and intervals of STDS A
316 Single map with temporal extent
318 The temporal algebra can also handle single maps with time stamps in
319 the tmap() function.
320 tmap()
321 For example:
322 C = A {:, during} tmap(event)
323 This statement selects all maps from space time data set A that are
324 during the temporal extent of the single map ’event’
325 Spatial raster operators
327 The module supports the following raster operations:
328 Symbol description precedence
329 % modulus 1
330 / division 1
331 * multiplication 1
332 + addition 2
333 - subtraction 2
334 And raster functions:
335 abs(x) return absolute value of x
336 float(x) convert x to foating point
337 int(x) convert x to integer [ truncates ]
338 log(x) natural log of x
339 sqrt(x) square root of x
340 tan(x) tangent of x (x is in degrees)
341 round(x) round x to nearest integer
342 sin(x) sine of x (x is in degrees)
343 isnull(x) check if x = NULL
344 isntnull(x) check if x is not NULL
345 null set null value
346 exist(x) Check if x is in the current mapset
347 Single raster map
349 The temporal raster algebra features also a function to integrate sin‐
350 gle raster maps without time stamps into the expressions.
351 map()
352 For example:
353 C = A * map(constant_value)
354 This statement multiplies all raster maps from space time raster data
355 set A with the raster map ’constant_value’
356 Combinations of temporal, raster and select operators
358 The user can combine the temporal topology relations, the temporal op‐
359 erators and the spatial/select operators to create spatio-temporal op‐
360 erators as follows:
361 {"spatial or select operator", "list of temporal relations", "temporal operator"}
362 For multiple topological relations or several related maps the spa‐
363 tio-temporal operators feature implicit aggregation. The algebra eval‐
364 uates the stated STDS by their temporal topologies and apply the given
365 spatio-temporal operators in a aggregated form. If we have two STDS A
366 and B, B has three maps: b1, b2, b3 that are all during the temporal
367 extent of the single map a1 of A, then the following arithmetic calcu‐
368 lations would implicitly aggregate all maps of B into one result map
369 for a1 of A:
370 C = A {+, contains} B --> c1 = a1 + b1 + b2 + b3
371 Important: the aggregation behaviour is not symmetric
373 C = B {+, during} A --> c1 = b1 + a1
374 c2 = b2 + a1
375 c3 = b3 + a1
376 Temporal neighbourhood modifier
378 The neighbourhood modifier of r.mapcalc is extended for the temporal
379 raster algebra with the temporal dimension. The format is strds[t,r,c],
380 where t is the temporal offset, r is the row offset and c is the column
381 offset. A single neighborhood modifier is interpreted as temporal off‐
382 set [t], while two neighborhood modifiers are interpreted as row and
383 column offsets [r,c].
384 strds[2]
385 refers to the second successor of the current map.
386 strds[1,2]
388 refers to the cell one row below and two columns to the right of the
389 current cell in the current map.
390 strds[1,-2,-1]
392 refers to the cell two rows above and one column to the left of the
393 current cell of the first successor map.
394 strds[-2,0,1]
396 refers to the cell one column to the right of the current cell in the
397 second predecessor map.
398
400 Computation of NDVI
401 # Sentinel-2 bands are stored separately in two STDRS "S2_b4" and "S2_b8"
402 g.region raster=sentinel2_B04_10m -p
403 t.rast.list S2_b4
404 t.rast.list S2_b8
405 t.rast.algebra basename=ndvi expression="ndvi = float(S2_b8 - S2_b4) / ( S2_b8 + S2_b4 )"
406 t.rast.colors input=ndvi color=ndvi
407 Sum of space-time raster datasets
409 Sum maps from STRDS A with maps from STRDS B which have equal time
410 stamps and are temporally before Jan. 1. 2005 and store them in STRDS
411 D:
412 D = if(start_date(A) < "2005-01-01", A + B)
413 Create the sum of all maps from STRDS A and B that have equal time
414 stamps and store the new maps in STRDS C:
415 C = A + B
416 Sum of space-time raster datasets with temporal topology relation
418 Same expression with explicit definition of the temporal topology rela‐
419 tion and temporal operators:
420 C = A {+,equal,l} B
421 Selection of raster cells
423 Select all cells from STRDS B with equal temporal relations to STRDS A,
424 if the cells of A are in the range [100.0, 1600] of time intervals that
425 have more than 30 days (Jan, Mar, May, Jul, Aug, Oct, Dec):
426 C = if(A > 100 && A < 1600 && td(A) > 30, B)
427 Selection of raster cells with temporal topology relation
429 Same expression with explicit definition of the temporal topology rela‐
430 tion and temporal operators:
431 C = if({equal}, A > 100 && A < 1600 {&&,equal} td(A) > 30, B)
432 Conditional computation
434 Compute the recharge in meters per second for all cells of precipita‐
435 tion STRDS "Prec" if the mean temperature specified in STRDS "Temp" is
436 higher than 10 degrees. Computation is performed if STRDS "Prec" and
437 "Temp" have equal time stamps. The number of days or fraction of days
438 per interval is computed using the td() function that has as argument
439 the STRDS "Prec":
440 C = if(Temp > 10.0, Prec / 3600.0 / 24.0 / td(Prec))
441 Conditional computation with temporal topology relation
443 Same expression with explicit definition of the temporal topology rela‐
444 tion and temporal operators:
445 C = if({equal}, Temp > 10.0, Prec / 3600.0 / 24.0 {/,equal,l} td(Prec))
446 Computation with time intervals
448 Compute the mean value of all maps from STRDS A that are located during
449 time intervals of STRDS B if more than one map of A is contained in an
450 interval of B, use A otherwise. The resulting time intervals are either
451 from B or A:
452 C = if(B {#,contain} A > 1, (B {+,contain,l} A - B) / (B {#,contain} A), A)
453 Computation with time intervals with temporal topology relation
455 Same expression with explicit definition of the temporal topology rela‐
456 tion and temporal operators:
457 C = if({equal}, B {#,contain} A > 1, (B {+,contain,l} A {-,equal,l} B) {equal,=/} (B {#,contain} A), A)
458 Compute DOY for spatio-temporal conditions
460 Compute the DOY for all maps from STRDS A where conditions are met at
461 three consecutive time intervals (e.g. temperature > 0):
462 B = if(A > 0.0 && A[-1] > 0.0 && A[-2] > 0.0, start_doy(A, -1), 0)"
463
465 r.mapcalc, t.vect.algebra, t.rast3d.algebra, t.select, t.rast3d.map‐
466 calc, t.rast.mapcalc
467 Temporal data processing Wiki
469
471 The use of this module requires the following software to be installed:
472 PLY(Python-Lex-Yacc)
473 # Ubuntu/Debian
475 sudo apt-get install python3-ply
476 # Fedora
477 sudo dnf install python3-ply
478 # MS-Windows (OSGeo4W: requires "python3-pip" package to be installed)
479 python3-pip install ply
480 Related publications:
482 • Gebbert, S., Pebesma, E. 2014. TGRASS: A temporal GIS for field
484 based environmental modeling. Environmental Modelling & Soft‐
485 ware 53, 1-12 (DOI) - preprint PDF
486 • Gebbert, S., Pebesma, E. 2017. The GRASS GIS temporal frame‐
488 work. International Journal of Geographical Information Science
489 31, 1273-1292 (DOI)
490 • Gebbert, S., Leppelt, T., Pebesma, E., 2019. A topology based
492 spatio-temporal map algebra for big data analysis. Data 4, 86.
493 (DOI)
494
496 v.overlay, v.buffer, v.patch, r.mapcalc
497
499 Thomas Leppelt, Sören Gebbert, Thünen Institute of Climate-Smart
500 Agriculture
501
503 Available at: t.rast.algebra source code (history)
504 Accessed: Saturday Oct 28 18:19:23 2023
506 Main index | Temporal index | Topics index | Keywords index | Graphical
508 index | Full index
509 © 2003-2023 GRASS Development Team, GRASS GIS 8.3.1 Reference Manual
511GRASS 8.3.1 t.rast.algebra(1)