| 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 |
> greater than |
| 225 |
>= greater than or equal |
| 226 |
< less than |
| 227 |
<= less than or equal |
| 228 |
&& 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 &) define the behaviour if a map is related the more |
| 284 |
than one map, e.g for the topological relations 'contains'. |
| 285 |
Should all (&) 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 &&). |
| 288 |
As default the aggregation operator is related to the comparison operator: <br> |
| 289 |
|
| 290 |
Comparison operator -> aggregation operator: |
| 291 |
|
| 292 |
<div class="code"><pre> |
| 293 |
|| -> | and && -> & |
| 294 |
</pre></div> |
| 295 |
|
| 296 |
Examples: |
| 297 |
|
| 298 |
<div class="code"><pre> |
| 299 |
Condition 1 {||, equal, r} Condition 2 |
| 300 |
Condition 1 {&&, equal|during, l} Condition 2 |
| 301 |
Condition 1 {&&, equal|contains, |, l} Condition 2 |
| 302 |
Condition 1 {&&, equal|during, l} Condition 2 && Condition 3 |
| 303 |
Condition 1 {&&, equal|during, l} Condition 2 {&&,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 > 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 & 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 --> c1 = a1 & b1 & b2 & b3 |
| 406 |
</pre></div> |
| 407 |
|
| 408 |
Keep attention that the aggregation behaviour is not symmetric: |
| 409 |
|
| 410 |
<div class="code"><pre> |
| 411 |
C = B {&, during} A --> c1 = b1 & a1 |
| 412 |
c2 = b2 & a1 |
| 413 |
c3 = b3 & 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) < "2005-01-01", A & 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) {&,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ünen Institute of Climate-Smart Agriculture |