1t.rast.algebra(1) Grass 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 PROGRAM USE
71 The module expects an expression as input parameter in the following
72 form:
73 "result = expression"
75 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 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 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 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 The map basename for the result STRDS must always be specified.
111
113 The temporal algebra provides a wide range of temporal operators and
114 functions that will be presented in the following section.
115 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 Topological relations must be specified with curly brackets {}.
146 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 Important: the aggregation behaviour is not symmetric
370 C = B {+, during} A --> c1 = b1 + a1
371 c2 = b2 + a1
372 c3 = b3 + a1
373 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 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 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 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
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 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 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 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 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 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 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 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 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
455 r.mapcalc, t.vect.algebra, t.rast3d.algebra, t.select, t.rast3d.map‐
456 calc, t.rast.mapcalc
457 Temporal data processing Wiki
459
461 The use of this module requires the following software to be installed:
462 PLY(Python-Lex-Yacc)
463 # 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 Related publications:
472 · 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 · Gebbert, S., Pebesma, E. 2017. The GRASS GIS temporal frame‐
478 work. International Journal of Geographical Information Science
479 31, 1273-1292 (DOI)
480 · 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
486 v.overlay, v.buffer, v.patch, r.mapcalc
487
489 Thomas Leppelt, Sören Gebbert, Thünen Institute of Climate-Smart
490 Agriculture
491
493 Available at: t.rast.algebra source code (history)
494 Main index | Temporal index | Topics index | Keywords index | Graphical
496 index | Full index
497 © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual
499GRASS 7.8.2 t.rast.algebra(1)