1t.select(1) GRASS GIS User's Manual t.select(1)
2
6 t.select - Select maps from space time datasets by topological rela‐
7 tionships to other space time datasets using temporal algebra.
8
10 temporal, metadata, time
11
13 t.select
14 t.select --help
15 t.select [-sd] [type=name] expression=expression [--help] [--ver‐
16 bose] [--quiet] [--ui]
17 Flags:
19 -s
20 Check the spatial topology of temporally related maps and select
21 only spatially related maps
22 -d
24 Perform a dry run, compute all dependencies and module calls but
25 don’t run them
26 --help
28 Print usage summary
29 --verbose
31 Verbose module output
32 --quiet
34 Quiet module output
35 --ui
37 Force launching GUI dialog
38 Parameters:
40 type=name
41 Type of the input space time dataset
42 Options: strds, stvds, str3ds
43 Default: strds
44 expression=expression [required]
46 The temporal mapcalc expression
47
49 t.select performs selection of maps that are registered in space time
50 datasets using temporal algebra.
51 PROGRAM USE
53 The module expects an expression as input parameter in the following
54 form:
55 "result = expression"
57 The statement structure is similar to r.mapcalc, see r.mapcalc. Where
59 result represents the name of a space time dataset (STDS)that will con‐
60 tain the result of the calculation that is given as expression on the
61 right side of the equality sign. These expression can be any valid or
62 nested combination of temporal operations and functions that are pro‐
63 vided by the temporal algebra.
64 The temporal algebra works with space time datasets of any type (STRDS,
65 STR3DS and STVDS). The algebra provides methods for map selection from
66 STDS based on their temporal relations. It is also possible to tempo‐
67 rally shift maps, to create temporal buffer and to snap time instances
68 to create a valid temporal topology. Furthermore expressions can be
69 nested and evaluated in conditional statements (if, else statements).
70 Within if-statements the algebra provides temporal variables like start
71 time, end time, day of year, time differences or number of maps per
72 time interval to build up conditions. These operations can be assigned
73 to space time datasets or to the results of operations between space
74 time datasets.
75 The type of the input space time datasets must be defined with the in‐
77 put parameter type. Possible options are STRDS, STVDS or STR3DS. The
78 default is set to space time raster datasets (STRDS).
79 As default, topological relationships between space time datasets will
81 be evaluated only temporal. Use the s flag to activate the additionally
82 spatial topology evaluation.
83 The expression option must be passed as quoted expression, for example:
85 t.select expression="C = A : B"
86 Where C is the new space time raster dataset that will contain maps
87 from A that are selected by equal temporal relationships to the exist‐
88 ing dataset B in this case.
89
91 The temporal algebra provides a wide range of temporal operators and
92 functions that will be presented in the following section.
93 TEMPORAL RELATIONS
95 Several temporal topology relations between registered maps of space
96 time datasets are supported:
97 equals A ------
98 B ------
99 during A ----
100 B ------
101 contains A ------
102 B ----
103 starts A ----
104 B ------
105 started A ------
106 B ----
107 finishs A ----
108 B ------
109 finished A ------
110 B ----
111 precedes A ----
112 B ----
113 follows A ----
114 B ----
115 overlapped A ------
116 B ------
117 overlaps A ------
118 B ------
119 over booth overlaps and overlapped
120 The relations must be read as: A is related to B, like - A equals B - A
121 is during B - A contains B
122 Topological relations must be specified in {} parentheses.
124 TEMPORAL OPERATORS
126 The temporal algebra defines temporal operators that can be combined
127 with other operators to perform spatio-temporal operations. The tempo‐
128 ral operators process the time instances and intervals of two temporal
129 related maps and calculate the result temporal extent by five different
130 possibilities.
131 LEFT REFERENCE l Use the time stamp of the left space time dataset
132 INTERSECTION i Intersection
133 DISJOINT UNION d Disjoint union
134 UNION u Union
135 RIGHT REFERENCE r Use the time stamp of the right space time dataset
136 TEMPORAL SELECTION
138 The temporal selection simply selects parts of a space time dataset
139 without processing raster or vector data. The algebra provides a se‐
140 lection operator : that selects parts of a space time dataset that are
141 temporally equal to parts of a second one by default. The following ex‐
142 pression
143 C = A : B
144 means: Select all parts of space time dataset A that are equal to B and
145 store it in space time dataset C. The parts are time stamped maps.
146 In addition the inverse selection operator !: is defined as the comple‐
148 ment of the selection operator, hence the following expression
149 C = A !: B
150 means: select all parts of space time time dataset A that are not equal
151 to B and store it in space time dataset (STDS) C.
152 To select parts of a STDS by different topological relations to other
154 STDS, the temporal topology selection operator can be used. The opera‐
155 tor consists of the temporal selection operator, the topological rela‐
156 tions, that must be separated by the logical OR operator | and the tem‐
157 poral extent operator. All three parts are separated by comma and sur‐
158 rounded by curly braces:
159 {"temporal selection operator", "topological relations", "temporal operator"}
160 Examples:
161 C = A {:, equals} B
162 C = A {!:, equals} B
163 We can now define arbitrary topological relations using the OR operator
164 "|" to connect them:
165 C = A {:,equals|during|overlaps} B
166 Select all parts of A that are equal to B, during B or overlaps B.
167 In addition we can define the temporal extent of the result STDS by
168 adding the temporal operator.
169 C = A {:, during,r} B
170 Select all parts of A that are during B and use the temporal extents
171 from B for C.
172 The selection operator is implicitly contained in the temporal topology
173 selection operator, so that the following statements are exactly the
174 same:
175 C = A : B
176 C = A {:} B
177 C = A {:,equal} B
178 C = A {:,equal,l} B
179 Same for the complementary selection:
180 C = A !: B
181 C = A {!:} B
182 C = A {!:,equal} B
183 C = A {!:,equal,l} B
184 CONDITIONAL STATEMENTS
186 Selection operations can be evaluated within conditional statements.
187 Note A and B can either be space time datasets or expressions. The temporal
188 relationship between the conditions and the conclusions can be defined at the
189 beginning of the if statement. The relationship between then and else conclusion
190 must be always equal.
191 if statement decision option temporal relations
192 if(if, then, else)
193 if(conditions, A) A if conditions are True; temporal topological relation between if and then is equal.
194 if(conditions, A, B) A if conditions are True, B otherwise; temporal topological relation between if, then and else is equal.
195 if(topologies, conditions, A) A if conditions are True; temporal topological relation between if and then is explicit specified by topologies.
196 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.
197 The conditions are comparison expressions that are used to evaluate
198 space time datasets. Specific values of temporal variables are compared
199 by logical operators and evaluated for each map of the STDS.
200 Important: The conditions are evaluated from left to right.
201 Logical operators
203 Symbol description
204 == equal
205 != not equal
206 > greater than
207 >= greater than or equal
208 < less than
209 <= less than or equal
210 && and
211 || or
212 Temporal functions
214 The following temporal function are evaluated only for the STDS that
215 must be given in parenthesis.
216 td(A) Returns a list of time intervals of STDS A
217 start_time(A) Start time as HH::MM:SS
218 start_date(A) Start date as yyyy-mm-DD
219 start_datetime(A) Start datetime as yyyy-mm-DD HH:MM:SS
220 end_time(A) End time as HH:MM:SS
221 end_date(A) End date as yyyy-mm-DD
222 end_datetime(A) End datetime as yyyy-mm-DD HH:MM
223 start_doy(A) Day of year (doy) from the start time [1 - 366]
224 start_dow(A) Day of week (dow) from the start time [1 - 7], the start of the week is Monday == 1
225 start_year(A) The year of the start time [0 - 9999]
226 start_month(A) The month of the start time [1 - 12]
227 start_week(A) Week of year of the start time [1 - 54]
228 start_day(A) Day of month from the start time [1 - 31]
229 start_hour(A) The hour of the start time [0 - 23]
230 start_minute(A) The minute of the start time [0 - 59]
231 start_second(A) The second of the start time [0 - 59]
232 end_doy(A) Day of year (doy) from the end time [1 - 366]
233 end_dow(A) Day of week (dow) from the end time [1 - 7], the start of the week is Monday == 1
234 end_year(A) The year of the end time [0 - 9999]
235 end_month(A) The month of the end time [1 - 12]
236 end_week(A) Week of year of the end time [1 - 54]
237 end_day(A) Day of month from the start time [1 - 31]
238 end_hour(A) The hour of the end time [0 - 23]
239 end_minute(A) The minute of the end time [0 - 59]
240 end_second(A) The second of the end time [0 - 59]
241 Comparison operator
243 The conditions are comparison expressions that are used to evaluate
244 space time datasets. Specific values of temporal variables are compared
245 by logical operators and evaluated for each map of the STDS and the re‐
246 lated maps. For complex relations the comparison operator can be used
247 to combine conditions:
248 The structure is similar to the select operator with the extension of
249 an aggregation operator: {"comparison operator", "topological rela‐
250 tions", aggregation operator, "temporal operator"}
251 This aggregation operator (| or &) define the behaviour if a map is re‐
252 lated the more than one map, e.g for the topological relations ’con‐
253 tains’. Should all (&) conditions for the related maps be true or is
254 it sufficient to have any (|) condition that is true. The resulting
255 boolean value is then compared to the first condition by the comparison
256 operator (|| or &&). As default the aggregation operator is related to
257 the comparison operator:
258 Comparison operator -> aggregation operator:
259 || -> | and && -> &
260 Examples:
261 Condition 1 {||, equal, r} Condition 2
262 Condition 1 {&&, equal|during, l} Condition 2
263 Condition 1 {&&, equal|contains, |, l} Condition 2
264 Condition 1 {&&, equal|during, l} Condition 2 && Condition 3
265 Condition 1 {&&, equal|during, l} Condition 2 {&&,contains, |, r} Condition 3
266 Hash operator
268 Additionally the number of maps in intervals can be computed and used
269 in conditional statements with the hash (#) operator.
270 A{#, contains}B
271 This expression computes the number of maps from space time dataset B
272 which are during the time intervals of maps from space time dataset A.
273 A list of integers (scalars) corresponding to the maps of A that con‐
274 tain maps from B will be returned.
275 C = if({equal}, A {#, contains} B > 2, A {:, contains} B)
277 This expression selects all maps from A that temporally contains at
278 least 2 maps from B and stores them in space time dataset C. The lead‐
279 ing equal statement in the if condition specifies the temporal relation
280 between the if and then part of the if expression. This is very impor‐
281 tant, so we do not need to specify a global time reference (a space
282 time dataset) for temporal processing.
283 Furthermore the temporal algebra allows temporal buffering, shifting
285 and snapping with the functions buff_t(), tshift() and tsnap() respec‐
286 tively.
287 buff_t(A, size) Buffer STDS A with granule ("1 month" or 5)
288 tshift(A, size) Shift STDS A with granule ("1 month" or 5)
289 tsnap(A) Snap time instances and intervals of STDS A
290 Single map with temporal extent
292 The temporal algebra can also handle single maps with time stamps in
293 the map function.
294 tmap()
295 For example:
296 C = A {:,during} tmap(event)
297 This statement select all maps from space time data set A that are dur‐
298 ing the temporal extent of single map ’event’
299
301 Select all maps from space time dataset A which have equal time stamps
302 with space time dataset B and C and are earlier that Jan. 1. 2005 and
303 store them in space time dataset D.
304 D = if(start_date(A) < "2005-01-01", A : B : C)
305 Select all maps from space time dataset A which contains more than
306 three maps of space time dataset B, else select maps from C with time
307 stamps that are not equal to A and store them in space time dataset D.
308 D = if(A {#, contains} B > 3, A {:, contains} B, C)
309 Select all maps from space time dataset B which are during the temporal
310 buffered space time dataset A with a map interval of three days, else
311 select maps from C and store them in space time dataset D.
312 D = if(contains, td(buff_t(A, "1 days")) == 3, B, C)
313
315 PLY(Python-Lex-Yacc)
316 Gebbert, S., Leppelt, T., Pebesma, E., 2019. A topology based spa‐
318 tio-temporal map algebra for big data analysis. Data 4, 86.
319 https://doi.org/10.3390/data4020086
320
322 r.mapcalc
323
325 Thomas Leppelt, Sören Gebbert, Thünen Institute of Climate-Smart
326 Agriculture
327
329 Available at: t.select source code (history)
330 Accessed: Saturday Jan 21 20:41:05 2023
332 Main index | Temporal index | Topics index | Keywords index | Graphical
334 index | Full index
335 © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
337GRASS 8.2.1 t.select(1)