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