1t.vect.algebra(1) GRASS GIS User's Manual t.vect.algebra(1)
2
6 t.vect.algebra - Apply temporal and spatial operations on space time
7 vector datasets using temporal vector algebra.
8
10 temporal, algebra, vector, time
11
13 t.vect.algebra
14 t.vect.algebra --help
15 t.vect.algebra [-s] expression=expression basename=basename [--help]
16 [--verbose] [--quiet] [--ui]
17 Flags:
19 -s
20 Check the spatial topology of temporally related maps and process
21 only spatially related maps
22 --help
24 Print usage summary
25 --verbose
27 Verbose module output
28 --quiet
30 Quiet module output
31 --ui
33 Force launching GUI dialog
34 Parameters:
36 expression=expression [required]
37 Spatio-temporal mapcalc expression
38 basename=basename [required]
40 Basename of the new generated output maps
41 A numerical suffix separated by an underscore will be attached to
42 create a unique identifier
43
45 t.vect.algebra performs temporal and spatial overlay and buffer func‐
46 tions on space time vector datasets (STVDS) by using the temporal vec‐
47 tor algebra. New STVDS can be created, which are expressions of exist‐
48 ing STVDS.
49 The module expects an expression as input parameter in the following
51 form:
52 "result = expression"
54 The statement structure is similar to r.mapcalc, see r.mapcalc. Where
55 result represents the name of a space time dataset (STVDS) that will
56 contain the result of the calculation that is given as expression on
57 the right side of the equality sign. These expression can be any valid
58 or nested combination of temporal operations and functions that are
59 provided by the temporal vector algebra.
60 The algebra provides methods for map selection from STDS based on their
61 temporal relations. It is also possible to temporally shift maps, to
62 create temporal buffer and to snap time instances to create a valid
63 temporal topology. Furthermore expressions can be nested and evaluated
64 in conditional statements (if, else statements). Within if-statements
65 the algebra provides temporal variables like start time, end time, day
66 of year, time differences or number of maps per time interval to build
67 up conditions. These operations can be assigned to space time datasets
68 or to the results of operations between space time datasets.
69 As default, topological relationships between space time datasets will
71 be evaluated only temporal. Use the s flag to activate the additionally
72 spatial topology evaluation.
73 The expression option must be passed as quoted expression, for example:
75 t.select expression="C = A : B"
76 Where C is the new space time raster dataset that will contain maps
77 from A that are selected by equal temporal relationships to the exist‐
78 ing dataset B in this case.
79
81 The temporal algebra provides a wide range of temporal operators and
82 functions that will be presented in the following section.
83 TEMPORAL RELATIONS
85 Several temporal topology relations between registered maps of space
86 time datasets are supported:
87 equals A ------
88 B ------
89 during A ----
90 B ------
91 contains A ------
92 B ----
93 starts A ----
94 B ------
95 started A ------
96 B ----
97 finishs A ----
98 B ------
99 finished A ------
100 B ----
101 precedes A ----
102 B ----
103 follows A ----
104 B ----
105 overlapped A ------
106 B ------
107 overlaps A ------
108 B ------
109 over booth overlaps and overlapped
110 The relations must be read as: A is related to B, like - A equals B - A
111 is during B - A contains B
112 Topological relations must be specified in {} parentheses.
114 TEMPORAL OPERATORS
116 The temporal algebra defines temporal operators that can be combined
117 with other operators to perform spatio-temporal operations. The tempo‐
118 ral operators process the time instances and intervals of two temporal
119 related maps and calculate the result temporal extent by five different
120 possibilities.
121 LEFT REFERENCE l Use the time stamp of the left space time dataset
122 INTERSECTION i Intersection
123 DISJOINT UNION d Disjoint union
124 UNION u Union
125 RIGHT REFERENCE r Use the time stamp of the right space time dataset
126 TEMPORAL SELECTION
128 The temporal selection simply selects parts of a space time dataset
129 without processing raster or vector data. The algebra provides a se‐
130 lection operator : that selects parts of a space time dataset that are
131 temporally equal to parts of a second one by default. The following ex‐
132 pression
133 C = A : B
134 means: Select all parts of space time dataset A that are equal to B and
135 store it in space time dataset C. The parts are time stamped maps.
136 In addition the inverse selection operator !: is defined as the comple‐
138 ment of the selection operator, hence the following expression
139 C = A !: B
140 means: select all parts of space time time dataset A that are not equal
141 to B and store it in space time dataset (STDS) C.
142 To select parts of a STDS by different topological relations to other
144 STDS, the temporal topology selection operator can be used. The opera‐
145 tor consists of the temporal selection operator, the topological rela‐
146 tions, that must be separated by the logical OR operator | and the tem‐
147 poral extent operator. All three parts are separated by comma and sur‐
148 rounded by curly braces:
149 {"temporal selection operator", "topological relations", "temporal operator"}
150 Examples:
152 C = A {:, equals} B
153 C = A {!:, equals} B
154 We can now define arbitrary topological relations using the OR operator
155 "|" to connect them:
156 C = A {:,equals|during|overlaps} B
157 Select all parts of A that are equal to B, during B or overlaps B.
158 In addition we can define the temporal extent of the result STDS by
159 adding the temporal operator.
160 C = A {:, during,r} B
161 Select all parts of A that are during B and use the temporal extents
162 from B for C.
163 The selection operator is implicitly contained in the temporal topology
165 selection operator, so that the following statements are exactly the
166 same:
167 C = A : B
168 C = A {:} B
169 C = A {:,equal} B
170 C = A {:,equal,l} B
171 Same for the complementary selection:
172 C = A !: B
173 C = A {!:} B
174 C = A {!:,equal} B
175 C = A {!:,equal,l} B
176 CONDITIONAL STATEMENTS
178 Selection operations can be evaluated within conditional statements.
179 Note A and B can either be space time datasets or expressions. The tem‐
180 poral relationship between the conditions and the conclusions can be
181 defined at the beginning of the if statement. The relationship between
182 then and else conclusion must be always equal.
183 if statement decision option temporal relations
184 if(if, then, else)
185 if(conditions, A) A if conditions are True; temporal topological relation between if and then is equal.
186 if(conditions, A, B) A if conditions are True, B otherwise; temporal topological relation between if, then and else is equal.
187 if(topologies, conditions, A) A if conditions are True; temporal topological relation between if and then is explicit specified by topologies.
188 if(topologies, conditions, A, B) A if conditions are True, B otherwise; temporal topological relation between if, then and else is explicit specified by topologies.
189 Logical operators
191 Symbol description
192 == equal
193 != not equal
194 > greater than
195 >= greater than or equal
196 < less than
197 <= less than or equal
198 && and
199 || or
200 Temporal functions
202 The following temporal function are evaluated only for the STDS that
203 must be given in parenthesis.
204 td(A) Returns a list of time intervals of STDS A
205 start_time(A) Start time as HH::MM:SS
206 start_date(A) Start date as yyyy-mm-DD
207 start_datetime(A) Start datetime as yyyy-mm-DD HH:MM:SS
208 end_time(A) End time as HH:MM:SS
209 end_date(A) End date as yyyy-mm-DD
210 end_datetime(A) End datetime as yyyy-mm-DD HH:MM
211 start_doy(A) Day of year (doy) from the start time [1 - 366]
212 start_dow(A) Day of week (dow) from the start time [1 - 7], the start of the week is Monday == 1
213 start_year(A) The year of the start time [0 - 9999]
214 start_month(A) The month of the start time [1 - 12]
215 start_week(A) Week of year of the start time [1 - 54]
216 start_day(A) Day of month from the start time [1 - 31]
217 start_hour(A) The hour of the start time [0 - 23]
218 start_minute(A) The minute of the start time [0 - 59]
219 start_second(A) The second of the start time [0 - 59]
220 end_doy(A) Day of year (doy) from the end time [1 - 366]
221 end_dow(A) Day of week (dow) from the end time [1 - 7], the start of the week is Monday == 1
222 end_year(A) The year of the end time [0 - 9999]
223 end_month(A) The month of the end time [1 - 12]
224 end_week(A) Week of year of the end time [1 - 54]
225 end_day(A) Day of month from the start time [1 - 31]
226 end_hour(A) The hour of the end time [0 - 23]
227 end_minute(A) The minute of the end time [0 - 59]
228 end_second(A) The second of the end time [0 - 59]
229 Comparison operator
231 The conditions are comparison expressions that are used to evaluate
232 space time datasets. Specific values of temporal variables are compared
233 by logical operators and evaluated for each map of the STDS and the re‐
234 lated maps. For complex relations the comparison operator can be used
235 to combine conditions:
236 The structure is similar to the select operator with the extension of
237 an aggregation operator:
238 {"comparison operator", "topological relations", aggregation operator, "temporal operator"}
239 This aggregation operator (| or &) define the behaviour if a map is re‐
240 lated the more than one map, e.g for the topological relations ’con‐
241 tains’. Should all (&) conditions for the related maps be true or is
242 it sufficient to have any (|) condition that is true. The resulting
243 boolean value is then compared to the first condition by the comparison
244 operator (|| or &&). As default the aggregation operator is related to
245 the comparison operator:
246 Comparison operator -> aggregation operator:
247 || -> | and && -> &
248 Examples:
249 Condition 1 {||, equal, r} Condition 2
250 Condition 1 {&&, equal|during, l} Condition 2
251 Condition 1 {&&, equal|contains, |, l} Condition 2
252 Condition 1 {&&, equal|during, l} Condition 2 && Condition 3
253 Condition 1 {&&, equal|during, l} Condition 2 {&&,contains, |, r} Condition 3
254 Hash operator
256 Additionally the number of maps in intervals can be computed and used
257 in conditional statements with the hash (#) operator.
258 A{#, contains}B
259 This expression computes the number of maps from space time dataset B
260 which are during the time intervals of maps from space time dataset A.
261 A list of integers (scalars) corresponding to the maps of A that con‐
262 tain maps from B will be returned.
263 C = if({equal}, A {#, contains} B > 2, A {:, contains} B)
265 This expression selects all maps from A that temporally contains at
266 least 2 maps from B and stores them in space time dataset C. The lead‐
267 ing equal statement in the if condition specifies the temporal relation
268 between the if and then part of the if expression. This is very impor‐
269 tant, so we do not need to specify a global time reference (a space
270 time dataset) for temporal processing.
271 Furthermore the temporal algebra allows temporal buffering, shifting
273 and snapping with the functions buff_t(), tshift() and tsnap() respec‐
274 tively.
275 buff_t(A, size) Buffer STDS A with granule ("1 month" or 5)
276 tshift(A, size) Shift STDS A with granule ("1 month" or 5)
277 tsnap(A) Snap time instances and intervals of STDS A
278 Single map with temporal extent
280 The temporal algebra can also handle single maps with time stamps in
281 the tmap function.
282 tmap()
283 For example:
284 C = A {:,during} tmap(event)
285 This statement select all maps from space time data set A that are dur‐
286 ing the temporal extent of single map ’event’
287 Spatial vector operators
289 The module supports the following boolean vector operations:
290 Boolean Name Operator Meaning Precedence Correspondent function
291 ----------------------------------------------------------------------------------
292 AND & Intersection 1 (v.overlay operator=and)
293 OR | Union 1 (v.overlay operator=or)
294 DISJOINT OR + Disjoint union 1 (v.patch)
295 XOR ^ Symmetric difference 1 (v.overlay operator=xor)
296 NOT ~ Complement 1 (v.overlay operator=not)
297 And vector functions:
298 buff_p(A, size) Buffer the points of vector map layer A with size
299 buff_l(A, size) Buffer the lines of vector map layer A with size
300 buff_a(A, size) Buffer the areas of vector map layer A with size
301 Combinations of temporal, vector and select operators
303 We combine the temporal topology relations, the temporal operators and
304 the spatial/select operators to create spatio-temporal vector opera‐
305 tors:
306 {"spatial or select operator" , "list of temporal relations", "temporal operator" }
307 For multiple topological relations or several related maps the spa‐
309 tio-temporal operators feature implicit aggregation. The algebra eval‐
310 uates the stated STDS by their temporal topologies and apply the given
311 spatio temporal operators in a aggregated form. If we have two STDS A
312 and B, B has three maps: b1, b2, b3 that are all during the temporal
313 extent of the single map a1 of A, then the following overlay calcula‐
314 tions would implicitly aggregate all maps of B into one result map for
315 a1 of A:
316 C = A {&, contains} B --> c1 = a1 & b1 & b2 & b3
317 Keep attention that the aggregation behaviour is not symmetric:
318 C = B {&, during} A --> c1 = b1 & a1
319 c2 = b2 & a1
320 c3 = b3 & a1
321 Examples:
323 Spatio-temporal intersect all maps from space time dataset A with all
324 maps from space time dataset B which have equal time stamps and are
325 temporary before Jan. 1. 2005 and store them in space time dataset D.
326 D = if(start_date(A) < "2005-01-01", A & B)
327 Buffer all vector points from space time vector dataset A and B with a
328 distance of one and intersect the results with overlapping, containing,
329 during and equal temporal relations to store the result in space time
330 vector dataset D with intersected time stamps.
331 D = buff_p(A, 1) {&,overlaps|overlapped|equal|during|contains,i} buff_p(B, 1)
332 Select all maps from space time dataset B which are during the temporal
333 buffered space time dataset A with a map interval of three days, else
334 select maps from C and store them in space time dataset D.
335 D = if(contains, td(buff_t(A, "1 days")) == 3, B, C)
336
338 PLY(Python-Lex-Yacc)
339
341 t.select
342
344 Thomas Leppelt, Soeren Gebbert, Thünen Institute of Climate-Smart
345 Agriculture
346
348 Available at: t.vect.algebra source code (history)
349 Accessed: Saturday Jan 21 21:17:06 2023
351 Main index | Temporal index | Topics index | Keywords index | Graphical
353 index | Full index
354 © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
356GRASS 8.2.1 t.vect.algebra(1)