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 [nprocs=inte‐
16 ger] [--help] [--verbose] [--quiet] [--ui]
17 Flags:
19 -s
20 Check the spatial topology of temporally related maps and process
21 only spatially related maps
22 -n
24 Register Null maps
25 -g
27 Use granularity sampling instead of the temporal topology approach
28 -d
30 Perform a dry run, compute all dependencies and module calls but
31 don’t run them
32 --help
34 Print usage summary
35 --verbose
37 Verbose module output
38 --quiet
40 Quiet module output
41 --ui
43 Force launching GUI dialog
44 Parameters:
46 expression=string [required]
47 r.mapcalc expression for temporal and spatial analysis of space
48 time raster datasets
49 basename=string [required]
51 Basename of the new generated output maps
52 A numerical suffix separated by an underscore will be attached to
53 create a unique identifier
54 nprocs=integer
56 Number of r.mapcalc processes to run in parallel
57 Default: 1
58
60 t.rast.algebra performs temporal and spatial map algebra operations on
61 space time raster datasets (STRDS) using the temporal raster algebra.
62 PROGRAM USE
64 The module expects an expression as input parameter in the following
65 form:
66 "result = expression"
68 The statement structure is similar to that of r.mapcalc. In this
70 statement, result represents the name of the space time raster dataset
71 (STRDS) that will contain the result of the calculation that is given
72 as expression on the right side of the equality sign. These expres‐
73 sions can be any valid or nested combination of temporal operations and
74 spatial overlay or buffer functions that are provided by the temporal
75 algebra.
76 The temporal raster algebra works only with space time raster datasets
78 (STRDS). The algebra provides methods for map selection based on their
79 temporal relations. It is also possible to temporally shift maps, to
80 create temporal buffer and to snap time instances to create a valid
81 temporal topology. Furthermore, expressions can be nested and evaluated
82 in conditional statements (if, else statements). Within if-statements,
83 the algebra provides temporal variables like start time, end time, day
84 of year, time differences or number of maps per time interval to build
85 up conditions.
86 In addition the algebra provides a subset of the spatial operations
87 from r.mapcalc. All these operations can be assigned to STRDS or to the
88 map lists resulting of operations between STRDS.
89 By default, only temporal topological relations among space time
91 datasets (STDS) are evaluated. The -s flag can be used to additionally
92 activate the evaluation of the spatial topology based on the spatial
93 extent of maps.
94 The expression option must be passed as quoted expression, for example:
96 t.rast.algebra expression="C = A + B" basename=result
97 Where C is the new space time raster dataset that will contain maps
98 with the basename "result" and a numerical suffix separated by an
99 underscore that represent the sum of maps from the STRDS A and tempo‐
100 rally equal maps (i.e., maps with equal temporal topology relation)
101 from the STRDS B.
102 The map basename for the result STRDS must always be specified.
104
106 The temporal algebra provides a wide range of temporal operators and
107 functions that will be presented in the following section.
108 TEMPORAL RELATIONS
110 Several temporal topology relations are supported between maps regis‐
111 tered in space time datasets:
112 equals A ------
113 B ------
114 during A ----
115 B ------
116 contains A ------
117 B ----
118 starts A ----
119 B ------
120 started A ------
121 B ----
122 finishs A ----
123 B ------
124 finished A ------
125 B ----
126 precedes A ----
127 B ----
128 follows A ----
129 B ----
130 overlapped A ------
131 B ------
132 overlaps A ------
133 B ------
134 over both overlaps and overlapped
135 The relations must be read as: A is related to B, like - A equals B - A
136 is during B - A contains B.
137 Topological relations must be specified with curly brackets {}.
139 TEMPORAL OPERATORS
141 The temporal algebra defines temporal operators that can be combined
142 with other operators to perform spatio-temporal operations. The tempo‐
143 ral operators process the time instances and intervals of two tempo‐
144 rally related maps and calculate the resulting temporal extent in five
145 possible different ways.
146 LEFT REFERENCE l Use the time stamp of the left space time dataset
147 INTERSECTION i Intersection
148 DISJOINT UNION d Disjoint union
149 UNION u Union
150 RIGHT REFERENCE r Use the time stamp of the right space time dataset
151 TEMPORAL SELECTION
153 The temporal selection simply selects parts of a space time dataset
154 without processing any raster or vector data. The algebra provides a
155 selection operator : that by default selects parts of a space time
156 dataset that are temporally equal to parts of a second space time
157 dataset. The following expression
158 C = A : B
159 means: select all parts of space time dataset A that are equal to B and
160 store them in space time dataset C. These parts are time stamped maps.
161 In addition, the inverse selection operator !: is defined as the com‐
163 plement of the selection operator, hence the following expression
164 C = A !: B
165 means: select all parts of space time time dataset A that are not equal
166 to B and store them in space time dataset C.
167 To select parts of a STRDS using different topological relations
169 regarding to other STRDS, the temporal topology selection operator can
170 be used. This operator consists of the temporal selection operator, the
171 topological relations that must be separated by the logical OR operator
172 | and, the temporal extent operator. All three parts are separated by
173 comma and surrounded by curly brackets as follows: {"temporal selection
174 operator", "topological relations", "temporal operator"}.
175 Examples:
177 C = A {:,equals} B
178 C = A {!:,equals} B
179 We can now define arbitrary topological relations using the OR operator
180 "|" to connect them:
181 C = A {:,equals|during|overlaps} B
182 Select all parts of A that are equal to B, during B or overlaps B.
183 In addition, we can define the temporal extent of the resulting STRDS
184 by adding the temporal operator.
185 C = A {:,during,r} B
186 Select all parts of A that are during B and use the temporal extents
187 from B for C.
188 The selection operator is implicitly contained in the temporal topology
189 selection operator, so that the following statements are exactly the
190 same:
191 C = A : B
192 C = A {:} B
193 C = A {:,equal} B
194 C = A {:,equal,l} B
195 Same for the complementary selection:
196 C = A !: B
197 C = A {!:} B
198 C = A {!:,equal} B
199 C = A {!:,equal,l} B
200 CONDITIONAL STATEMENTS
202 Selection operations can be evaluated within conditional statements as
203 showed below. Note that A and B can be either space time datasets or
204 expressions. The temporal relationship between the conditions and the
205 conclusions can be defined at the beginning of the if statement (third
206 and fourth examples below). The relationship between then and else con‐
207 clusion must be always equal.
208 if statement decision option temporal relations
209 if(if, then, else)
210 if(conditions, A) A if conditions are True; temporal topological relation between if and then is equal.
211 if(conditions, A, B) A if conditions are True, B otherwise; temporal topological relation between if, then and else is equal.
212 if(topologies, conditions, A) A if conditions are True; temporal topological relation between if and then is explicitly specified by topologies.
213 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.
214 The conditions are comparison expressions that are used to evaluate
215 space time datasets. Specific values of temporal variables are compared
216 by logical operators and evaluated for each map of the STRDS.
217 Important: The conditions are evaluated from left to right.
218 Logical operators
220 Symbol description
221 == equal
222 != not equal
223 > greater than
224 >= greater than or equal
225 < less than
226 <= less than or equal
227 && and
228 || or
229 Temporal functions
231 The following temporal functions are evaluated only for the STDS that
232 must be given in parenthesis.
233 td(A) Returns a list of time intervals of STDS A
234 start_time(A) Start time as HH::MM:SS
235 start_date(A) Start date as yyyy-mm-DD
236 start_datetime(A) Start datetime as yyyy-mm-DD HH:MM:SS
237 end_time(A) End time as HH:MM:SS
238 end_date(A) End date as yyyy-mm-DD
239 end_datetime(A) End datetime as yyyy-mm-DD HH:MM
240 start_doy(A) Day of year (doy) from the start time [1 - 366]
241 start_dow(A) Day of week (dow) from the start time [1 - 7], the start of the week is Monday == 1
242 start_year(A) The year of the start time [0 - 9999]
243 start_month(A) The month of the start time [1 - 12]
244 start_week(A) Week of year of the start time [1 - 54]
245 start_day(A) Day of month from the start time [1 - 31]
246 start_hour(A) The hour of the start time [0 - 23]
247 start_minute(A) The minute of the start time [0 - 59]
248 start_second(A) The second of the start time [0 - 59]
249 end_doy(A) Day of year (doy) from the end time [1 - 366]
250 end_dow(A) Day of week (dow) from the end time [1 - 7], the start of the week is Monday == 1
251 end_year(A) The year of the end time [0 - 9999]
252 end_month(A) The month of the end time [1 - 12]
253 end_week(A) Week of year of the end time [1 - 54]
254 end_day(A) Day of month from the start time [1 - 31]
255 end_hour(A) The hour of the end time [0 - 23]
256 end_minute(A) The minute of the end time [0 - 59]
257 end_second(A) The second of the end time [0 - 59]
258 Comparison operator
260 As mentioned above, the conditions are comparison expressions that are
261 used to evaluate space time datasets. Specific values of temporal vari‐
262 ables are compared by logical operators and evaluated for each map of
263 the STDS and (optionally) related maps. For complex relations, the
264 comparison operator can be used to combine conditions.
265 The structure is similar to the select operator with the addition of an
266 aggregation operator: {"comparison operator", "topological relations",
267 aggregation operator, "temporal operator"}
268 This aggregation operator (| or &) defines the behaviour when a map is
269 related to more than one map, e.g. for the topological relation ’con‐
270 tains’. Should all (&) conditions for the related maps be true or is
271 it sufficient to have any (|) condition that is true. The resulting
272 boolean value is then compared to the first condition by the comparison
273 operator (|| or &&). By default, the aggregation operator is related
274 to the comparison operator:
275 comparison operator -> aggregation operator:
276 || -> | and && -> &
277 Examples:
278 Condition 1 {||, equal, r} Condition 2
279 Condition 1 {&&, equal|during, l} Condition 2
280 Condition 1 {&&, equal|contains, |, l} Condition 2
281 Condition 1 {&&, equal|during, l} Condition 2 && Condition 3
282 Condition 1 {&&, equal|during, l} Condition 2 {&&,contains, |, r} Condition 3
283 Hash operator
285 Additionally, the number of maps in intervals can be computed and used
286 in conditional statements with the hash (#) operator.
287 A {#, contains} B
288 This expression computes the number of maps from space time dataset B
289 which are during the time intervals of maps from space time dataset A.
290 A list of integers (scalars) corresponding to the maps of A that con‐
291 tain maps from B will be returned.
292 C = if({equal}, A {#, contains} B > 2, A {:, contains} B)
293 This expression selects all maps from A that temporally contain at
294 least 2 maps from B and stores them in space time dataset C. The lead‐
295 ing equal statement in the if condition specifies the temporal relation
296 between the if and then part of the if expression. This is very impor‐
297 tant, so we do not need to specify a global time reference (a space
298 time dataset) for temporal processing.
299 Furthermore, the temporal algebra allows temporal buffering, shifting
301 and snapping with the functions buff_t(), tshift() and tsnap(), respec‐
302 tively.
303 buff_t(A, size) Buffer STDS A with granule ("1 month" or 5)
304 tshift(A, size) Shift STDS A with granule ("1 month" or 5)
305 tsnap(A) Snap time instances and intervals of STDS A
306 Single map with temporal extent
308 The temporal algebra can also handle single maps with time stamps in
309 the tmap() function.
310 tmap()
311 For example:
312 C = A {:, during} tmap(event)
313 This statement selects all maps from space time data set A that are
314 during the temporal extent of the single map ’event’
315 Spatial raster operators
317 The module supports the following raster operations:
318 Symbol description precedence
319 % modulus 1
320 / division 1
321 * multiplication 1
322 + addition 2
323 - subtraction 2
324 And raster functions:
325 abs(x) return absolute value of x
326 float(x) convert x to foating point
327 int(x) convert x to integer [ truncates ]
328 log(x) natural log of x
329 sqrt(x) square root of x
330 tan(x) tangent of x (x is in degrees)
331 round(x) round x to nearest integer
332 sin(x) sine of x (x is in degrees)
333 isnull(x) check if x = NULL
334 isntnull(x) check if x is not NULL
335 null set null value
336 exist(x) Check if x is in the current mapset
337 Single raster map
339 The temporal raster algebra features also a function to integrate sin‐
340 gle raster maps without time stamps into the expressions.
341 map()
342 For example:
343 C = A * map(constant_value)
344 This statement multiplies all raster maps from space time raster data
345 set A with the raster map ’constant_value’
346 Combinations of temporal, raster and select operators
348 The user can combine the temporal topology relations, the temporal
349 operators and the spatial/select operators to create spatio-temporal
350 operators as follows:
351 {"spatial or select operator", "list of temporal relations", "temporal operator"}
352 For multiple topological relations or several related maps the spa‐
353 tio-temporal operators feature implicit aggregation. The algebra eval‐
354 uates the stated STDS by their temporal topologies and apply the given
355 spatio-temporal operators in a aggregated form. If we have two STDS A
356 and B, B has three maps: b1, b2, b3 that are all during the temporal
357 extent of the single map a1 of A, then the following arithmetic calcu‐
358 lations would implicitly aggregate all maps of B into one result map
359 for a1 of A:
360 C = A {+, contains} B --> c1 = a1 + b1 + b2 + b3
361 Important: the aggregation behaviour is not symmetric
363 C = B {+, during} A --> c1 = b1 + a1
364 c2 = b2 + a1
365 c3 = b3 + a1
366 Temporal neighbourhood modifier
368 The neighbourhood modifier of r.mapcalc is extended for the temporal
369 raster algebra with the temporal dimension. The format is strds[t,r,c],
370 where t is the temporal offset, r is the row offset and c is the column
371 offset.
372 strds[2]
373 refers to the second successor of the current map.
374 strds[1,2]
376 refers to the cell one row below and two columns to the right of the
377 current cell in the current map.
378 strds[1,-2,-1]
380 refers to the cell two rows above and one column to the left of the
381 current cell of the first successor map.
382 strds[-2,0,1]
384 refers to the cell one column to the right of the current cell in the
385 second predecessor map.
386
388 Computation of NDVI
389 # Sentinel-2 bands are stored separately in two STDRS "S2_b4" and "S2_b8"
390 g.region raster=sentinel2_B04_10m -p
391 t.rast.list S2_b4
392 t.rast.list S2_b8
393 t.rast.algebra basename=ndvi expression="ndvi = float(S2_b8 - S2_b4) / ( S2_b8 + S2_b4 )"
394 t.rast.colors input=ndvi color=ndvi
395 Sum of space-time raster datasets
397 Sum maps from STRDS A with maps from STRDS B which have equal time
398 stamps and are temporally before Jan. 1. 2005 and store them in STRDS
399 D:
400 D = if(start_date(A) < "2005-01-01", A + B)
401 Create the sum of all maps from STRDS A and B that have equal time
402 stamps and store the new maps in STRDS C:
403 C = A + B
404 Sum of space-time raster datasets with temporal topology relation
406 Same expression with explicit definition of the temporal topology rela‐
407 tion and temporal operators:
408 C = A {+,equal,l} B
409 Selection of raster cells
411 Select all cells from STRDS B with equal temporal relations to STRDS A,
412 if the cells of A are in the range [100.0, 1600] of time intervals that
413 have more than 30 days (Jan, Mar, May, Jul, Aug, Oct, Dec):
414 C = if(A > 100 && A < 1600 && td(A) > 30, B)
415 Selection of raster cells with temporal topology relation
417 Same expression with explicit definition of the temporal topology rela‐
418 tion and temporal operators:
419 C = if({equal}, A > 100 && A < 1600 {&&,equal} td(A) > 30, B)
420 Conditional computation
422 Compute the recharge in meters per second for all cells of precipita‐
423 tion STRDS "Prec" if the mean temperature specified in STRDS "Temp" is
424 higher than 10 degrees. Computation is performed if STRDS "Prec" and
425 "Temp" have equal time stamps. The number of days or fraction of days
426 per interval is computed using the td() function that has as argument
427 the STRDS "Prec":
428 C = if(Temp > 10.0, Prec / 3600.0 / 24.0 / td(Prec))
429 Conditional computation with temporal topology relation
431 Same expression with explicit definition of the temporal topology rela‐
432 tion and temporal operators:
433 C = if({equal}, Temp > 10.0, Prec / 3600.0 / 24.0 {/,equal,l} td(Prec))
434 Computation with time intervals
436 Compute the mean value of all maps from STRDS A that are located during
437 time intervals of STRDS B if more than one map of A is contained in an
438 interval of B, use A otherwise. The resulting time intervals are either
439 from B or A:
440 C = if(B {#,contain} A > 1, (B {+,contain,l} A - B) / (B {#,contain} A), A)
441 Computation with time intervals with temporal topology relation
443 Same expression with explicit definition of the temporal topology rela‐
444 tion and temporal operators:
445 C = if({equal}, B {#,contain} A > 1, (B {+,contain,l} A {-,equal,l} B) {equal,=/} (B {#,contain} A), A)
446
448 r.mapcalc, t.vect.algebra, t.rast3d.algebra, t.select, t.rast3d.map‐
449 calc, t.rast.mapcalc
450 Temporal data processing Wiki
452
454 The use of this module requires the following software to be installed:
455 PLY(Python-Lex-Yacc)
456 # Ubuntu/Debian
458 sudo apt-get install python-ply
459 # Fedora
460 sudo dnf install python-ply
461 # MS-Windows (OSGeo4W: requires "python-pip" package to be installed)
462 python-pip install ply
463
465 v.overlay, v.buffer, v.patch, r.mapcalc
466
468 Thomas Leppelt, Sören Gebbert, Thünen Institute of Climate-Smart Agri‐
469 culture
470 Last changed: $Date: 2018-08-24 15:04:37 +0200 (Fri, 24 Aug 2018) $
472
474 Available at: t.rast.algebra source code (history)
475 Main index | Temporal index | Topics index | Keywords index | Graphical
477 index | Full index
478 © 2003-2019 GRASS Development Team, GRASS GIS 7.4.4 Reference Manual
480GRASS 7.4.4 t.rast.algebra(1)