Debian Codegraph @

temporal/t.vect.algebra/t.vect.algebra.html

raw
1 <h2>DESCRIPTION</h2>
2
3 <em>t.vect.algebra</em> performs temporal and spatial overlay and
4 buffer functions on space time vector datasets (STVDS) by using the
5 temporal vector algebra. New STVDS can be created, which are
6 expressions of existing STVDS.
7
8 <p>
9 The module expects an <b>expression</b> as input parameter in the following form:
10 <p>
11
12 <div class="code"><pre>
13 "result = expression"
14 </pre></div>
15
16 The statement structure is similar to r.mapcalc, see <a href="r.mapcalc.html">r.mapcalc</a>.
17 Where <b>result</b> represents the name of a space time dataset (STVDS) that will
18 contain the result of the calculation that is given as <b>expression</b>
19 on the right side of the equality sign.
20
21 These expression can be any valid or nested combination of temporal
22 operations and functions that are provided by the temporal vector
23 algebra.<br>
24 The algebra provides methods for map selection from STDS based on their
25 temporal relations. It is also possible to temporally shift maps, to
26 create temporal buffer and to snap time instances to create a valid
27 temporal topology. Furthermore expressions can be nested and evaluated
28 in conditional statements (if, else statements). Within if-statements
29 the algebra provides temporal variables like start time, end time, day
30 of year, time differences or number of maps per time interval to build
31 up conditions. These operations can be assigned to space time datasets
32 or to the results of operations between space time datasets.
33
34 <p> As default, topological relationships between space time datasets
35 will be evaluated only temporal. Use the <b>s</b> flag to activate the
36 additionally spatial topology evaluation. <p> The expression option
37 must be passed as <b>quoted</b> expression, for example: <br>
38
39 <div class="code"><pre>
40 t.select expression="C = A : B"
41 </pre></div>
42
43 Where <b>C</b> is the new space time raster dataset that will contain
44 maps from <b>A</b> that are selected by equal temporal relationships to
45 the existing dataset <b>B</b> in this case.
46
47 <h2>TEMPORAL VECTOR ALGEBRA</h2>
48
49 The temporal algebra provides a wide range of temporal operators and
50 functions that will be presented in the following section. <p>
51
52 <h3>TEMPORAL RELATIONS</h3>
53
54 Several temporal topology relations between registered maps of space
55 time datasets are supported: <br>
56 <div class="code"><pre>
57 equals A ------
58 B ------
59
60 during A ----
61 B ------
62
63 contains A ------
64 B ----
65
66 starts A ----
67 B ------
68
69 started A ------
70 B ----
71
72 finishes A ----
73 B ------
74
75 finished A ------
76 B ----
77
78 precedes A ----
79 B ----
80
81 follows A ----
82 B ----
83
84 overlapped A ------
85 B ------
86
87 overlaps A ------
88 B ------
89
90 over booth overlaps and overlapped
91 </pre></div>
92
93 The relations must be read as: A is related to B, like - A equals B - A is
94 during B - A contains B <p>
95 Topological relations must be specified in {} parentheses. <br>
96
97 <h3>TEMPORAL OPERATORS</h3>
98
99 The temporal algebra defines temporal operators that can be combined
100 with other operators to perform spatio-temporal operations. The
101 temporal operators process the time instances and intervals of two
102 temporal related maps and calculate the result temporal extent by five
103 different possibilities.
104
105 <div class="code"><pre>
106 LEFT REFERENCE l Use the time stamp of the left space time dataset
107 INTERSECTION i Intersection
108 DISJOINT UNION d Disjoint union
109 UNION u Union
110 RIGHT REFERENCE r Use the time stamp of the right space time dataset
111 </pre></div>
112
113 <h3>TEMPORAL SELECTION</h3>
114
115 The temporal selection simply selects parts of a space time dataset without
116 processing raster or vector data.
117
118 The algebra provides a selection operator <b>:</b> that selects parts
119 of a space time dataset that are temporally equal to parts of a second one
120 by default. The following expression
121
122 <div class="code"><pre>
123 C = A : B
124 </pre></div>
125
126 means: Select all parts of space time dataset A that are equal to B and
127 store it in space time dataset C. The parts are time stamped maps.
128
129 <p>
130 In addition the inverse selection operator <b>!:</b> is defined as
131 the complement of the selection operator, hence the following
132 expression
133
134 <div class="code"><pre>
135 C = A !: B
136 </pre></div>
137
138 means: select all parts of space time time dataset A that are not equal to B
139 and store it in space time dataset (STDS) C.<p>
140
141 To select parts of a STDS by different topological relations to other
142 STDS, the temporal topology selection operator can be used. The
143 operator consists of the temporal selection operator, the topological
144 relations, that must be separated by the logical OR operator <b>|</b>
145 and the temporal extent operator. All three parts are separated by
146 comma and surrounded by curly braces:
147
148 <div class="code"><pre>
149 {"temporal selection operator", "topological relations", "temporal operator"}
150 </pre></div>
151
152 <p>
153
154 Examples:
155 <div class="code"><pre>
156 C = A {:, equals} B
157 C = A {!:, equals} B
158 </pre></div>
159
160 We can now define arbitrary topological relations using the OR operator "|"
161 to connect them:
162
163 <div class="code"><pre>
164 C = A {:,equals|during|overlaps} B
165 </pre></div>
166
167 Select all parts of A that are equal to B, during B or overlaps B. <br>
168
169 In addition we can define the temporal extent of the result STDS by adding the
170 temporal operator.
171
172 <div class="code"><pre>
173 C = A {:, during,r} B
174 </pre></div>
175
176 Select all parts of A that are during B and use the temporal extents
177 from B for C.
178 <p>
179
180 The selection operator is implicitly contained in the temporal topology
181 selection operator, so that the following statements are exactly the same:
182
183 <div class="code"><pre>
184 C = A : B
185 C = A {:} B
186 C = A {:,equal} B
187 C = A {:,equal,l} B
188 </pre></div>
189
190 Same for the complementary selection:
191
192 <div class="code"><pre>
193 C = A !: B
194 C = A {!:} B
195 C = A {!:,equal} B
196 C = A {!:,equal,l} B
197 </pre></div>
198
199 <h3>CONDITIONAL STATEMENTS</h3>
200
201 Selection operations can be evaluated within conditional statements.
202 <br>
203 Note A and B can either be space time datasets or expressions. The temporal
204 relationship between the conditions and the conclusions can be defined at the
205 beginning of the if statement. The relationship between then and else conclusion
206 must be always equal.
207
208 <div class="code"><pre>
209 if statement decision option temporal relations
210 if(if, then, else)
211 if(conditions, A) A if conditions are True; temporal topological relation between if and then is equal.
212 if(conditions, A, B) A if conditions are True, B otherwise; temporal topological relation between if, then and else is equal.
213 if(topologies, conditions, A) A if conditions are True; temporal topological relation between if and then is explicit specified by topologies.
214 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.
215 </pre></div>
216
217 <h4>Logical operators</h4>
218
219 <div class="code"><pre>
220 Symbol description
221
222 == equal
223 != not equal
224 &gt; greater than
225 &gt;= greater than or equal
226 &lt; less than
227 &lt;= less than or equal
228 &amp;&amp; and
229 || or
230 </pre></div>
231
232 <h4>Temporal functions</h4>
233
234 The following temporal function are evaluated only for the STDS that
235 must be given in parenthesis.
236
237 <div class="code"><pre>
238 td(A) Returns a list of time intervals of STDS A
239
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
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 </pre></div>
266
267 <h4>Comparison operator</h4>
268
269 The conditions are comparison expressions that are used to evaluate
270 space time datasets. Specific values of temporal variables are
271 compared by logical operators and evaluated for each map of the STDS and
272 the related maps.
273 For complex relations the comparison operator can be used to combine conditions:
274 <br>
275
276 The structure is similar to the select operator with the extension of an aggregation operator:
277
278 <div class="code"><pre>
279 {"comparison operator", "topological relations", aggregation operator, "temporal operator"}
280 </pre></div>
281
282 <br>
283 This aggregation operator (| or &amp;) define the behaviour if a map is related the more
284 than one map, e.g for the topological relations 'contains'.
285 Should all (&amp;) conditions for the related maps be true or is it sufficient to
286 have any (|) condition that is true. The resulting boolean value is then compared
287 to the first condition by the comparison operator (|| or &amp;&amp;).
288 As default the aggregation operator is related to the comparison operator: <br>
289
290 Comparison operator -&gt; aggregation operator:
291
292 <div class="code"><pre>
293 || -&gt; | and &amp;&amp; -&gt; &amp;
294 </pre></div>
295
296 Examples:
297
298 <div class="code"><pre>
299 Condition 1 {||, equal, r} Condition 2
300 Condition 1 {&amp;&amp;, equal|during, l} Condition 2
301 Condition 1 {&amp;&amp;, equal|contains, |, l} Condition 2
302 Condition 1 {&amp;&amp;, equal|during, l} Condition 2 &amp;&amp; Condition 3
303 Condition 1 {&amp;&amp;, equal|during, l} Condition 2 {&amp;&amp;,contains, |, r} Condition 3
304 </pre></div>
305
306 <h4>Hash operator</h4>
307
308 Additionally the number of maps in intervals can be computed and used in
309 conditional statements with the hash (#) operator. <br>
310
311 <div class="code"><pre>
312 A{#, contains}B
313 </pre></div>
314
315 This expression computes the number of maps from space
316 time dataset B which are during the time intervals of maps from
317 space time dataset A.<br>
318 A list of integers (scalars) corresponding to the maps of A
319 that contain maps from B will be returned.
320 <p>
321
322 <div class="code"><pre>
323 C = if({equal}, A {#, contains} B &gt; 2, A {:, contains} B)
324 </pre></div>
325
326 This expression selects all maps from A that temporally contains at least 2
327 maps from B and stores them in space time dataset C. The leading equal statement
328 in the if condition specifies the temporal relation between the if and then part
329 of the if expression. This is very important, so we do not need to specify a
330 global time reference (a space time dataset) for temporal processing.
331 <p>
332 Furthermore the temporal algebra allows temporal buffering, shifting
333 and snapping with the functions buff_t(), tshift() and tsnap()
334 respectively.
335
336 <div class="code"><pre>
337 buff_t(A, size) Buffer STDS A with granule ("1 month" or 5)
338 tshift(A, size) Shift STDS A with granule ("1 month" or 5)
339 tsnap(A) Snap time instances and intervals of STDS A
340 </pre></div>
341
342
343 <h4>Single map with temporal extent</h4>
344
345 The temporal algebra can also handle single maps with time stamps in
346 the tmap function.
347
348 <div class="code"><pre>
349 tmap()
350 </pre></div>
351
352 For example:
353
354 <div class="code"><pre>
355 C = A {:,during} tmap(event)
356 </pre></div>
357
358 This statement select all maps from space time data set A that are
359 during the temporal extent of single map 'event'
360
361 <h3>Spatial vector operators</h3>
362
363 The module supports the following boolean vector operations:<br>
364
365 <div class="code"><pre>
366 Boolean Name Operator Meaning Precedence Correspondent function
367 ----------------------------------------------------------------------------------
368 AND &amp; Intersection 1 (v.overlay operator=and)
369 OR | Union 1 (v.overlay operator=or)
370 DISJOINT OR + Disjoint union 1 (v.patch)
371 XOR ^ Symmetric difference 1 (v.overlay operator=xor)
372 NOT ~ Complement 1 (v.overlay operator=not)
373 </pre></div>
374
375 And vector functions:
376
377 <div class="code"><pre>
378 buff_p(A, size) Buffer the points of vector map layer A with size
379 buff_l(A, size) Buffer the lines of vector map layer A with size
380 buff_a(A, size) Buffer the areas of vector map layer A with size
381 </pre></div>
382
383 <h3>Combinations of temporal, vector and select operators</h3>
384
385 We combine the temporal topology relations, the temporal operators and
386 the spatial/select operators to create spatio-temporal vector
387 operators:
388
389 <pre class="code">
390 {"spatial or select operator" , "list of temporal relations", "temporal operator" }
391 </pre><p>
392
393 For multiple topological relations or several related maps the spatio-temporal
394 operators feature implicit aggregation.
395
396 The algebra evaluates the stated STDS by their temporal topologies and apply
397 the given spatio temporal operators in a aggregated form.
398
399 If we have two STDS A and B, B has three maps: b1, b2, b3 that are all during
400 the temporal extent of the single map a1 of A, then the following overlay
401 calculations would implicitly aggregate all maps of B into one result map for
402 a1 of A:
403
404 <div class="code"><pre>
405 C = A {&, contains} B --&gt; c1 = a1 &amp; b1 &amp; b2 &amp; b3
406 </pre></div>
407
408 Keep attention that the aggregation behaviour is not symmetric:
409
410 <div class="code"><pre>
411 C = B {&amp;, during} A --&gt; c1 = b1 &amp; a1
412 c2 = b2 &amp; a1
413 c3 = b3 &amp; a1
414 </pre></div>
415
416 <h3>Examples: </h3>
417
418 Spatio-temporal intersect all maps from space time dataset A with all
419 maps from space time dataset B which have equal time stamps and are
420 temporary before Jan. 1. 2005 and store them in space time dataset D.
421
422 <div class="code"><pre>
423 D = if(start_date(A) &lt; "2005-01-01", A &amp; B)
424 </pre></div>
425
426 Buffer all vector points from space time vector dataset A and B with a
427 distance of one and intersect the results with overlapping, containing,
428 during and equal temporal relations to store the result in space time
429 vector dataset D with intersected time stamps.
430
431 <div class="code"><pre>
432 D = buff_p(A, 1) {&amp;,overlaps|overlapped|equal|during|contains,i} buff_p(B, 1)
433 </pre></div>
434
435 Select all maps from space time dataset B which are during the temporal
436 buffered space time dataset A with a map interval of three days, else
437 select maps from C and store them in space time dataset D.
438
439 <div class="code"><pre>
440 D = if(contains, td(buff_t(A, "1 days")) == 3, B, C)
441 </pre></div>
442
443 <h2>SEE ALSO</h2>
444
445 <em>
446 <a href="t.select.html">t.select</a>
447 </em>
448
449 <h2>AUTHORS</h2>
450
451 Thomas Leppelt, Soeren Gebbert, Th&uuml;nen Institute of Climate-Smart Agriculture