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