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 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 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 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 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 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 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 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 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 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 Important: the aggregation behaviour is not symmetric
369 C = B {+, during} A --> c1 = b1 + a1
370 c2 = b2 + a1
371 c3 = b3 + a1
372 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 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 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 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
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 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 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 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 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 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 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 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 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
454 r.mapcalc, t.vect.algebra, t.rast3d.algebra, t.select, t.rast3d.map‐
455 calc, t.rast.mapcalc
456 Temporal data processing Wiki
458
460 The use of this module requires the following software to be installed:
461 PLY(Python-Lex-Yacc)
462 # 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 Related publications:
471 • 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 • Gebbert, S., Pebesma, E. 2017. The GRASS GIS temporal frame‐
477 work. International Journal of Geographical Information Science
478 31, 1273-1292 (DOI)
479 • 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
485 v.overlay, v.buffer, v.patch, r.mapcalc
486
488 Thomas Leppelt, Sören Gebbert, Thünen Institute of Climate-Smart
489 Agriculture
490
492 Available at: t.rast.algebra source code (history)
493 Accessed: Saturday Jan 21 21:17:05 2023
495 Main index | Temporal index | Topics index | Keywords index | Graphical
497 index | Full index
498 © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
500GRASS 8.2.1 t.rast.algebra(1)