|
@@ -0,0 +1,280 @@
|
|
|
+<h2>DESCRIPTION</h2>
|
|
|
+
|
|
|
+t.select performs selection of maps that are registered in space time datasets using temporal algebra.
|
|
|
+
|
|
|
+<h3>PROGRAM USE</h3>
|
|
|
+The module expects an <b>expression</b> as input parameter in the following form: <br>
|
|
|
+<br>
|
|
|
+<b> "result = expression" </b>
|
|
|
+<br>
|
|
|
+<br>
|
|
|
+
|
|
|
+The statement structure is similar to r.mapcalc, see <a href="r.mapcalc.html">r.mapcalc</a>.
|
|
|
+Where <b>result</b> represents the name of a space time dataset (STDS)that will
|
|
|
+contain the result of the calculation that is given as <b>expression</b>
|
|
|
+on the right side of the equality sign.
|
|
|
+These expression can be any valid or nested combination of temporal
|
|
|
+operations and functions that are provided by the temporal algebra. <br>
|
|
|
+The temporal algebra works with space time datasets of any type (STRDS, STR3DS and STVDS).
|
|
|
+The algebra provides methods for map selection from STDS based on their temporal relations.
|
|
|
+It is also possible to temporally shift maps, to create temporal buffer and to snap time
|
|
|
+instances to create a valid temporal topology. Furthermore expressions can be nested and
|
|
|
+evaluated in conditional statements (if, else statements). Within if-statements the algebra
|
|
|
+provides temporal variables like start time, end time, day of year, time differences or
|
|
|
+number of maps per time interval to build up conditions. These operations can be assigned
|
|
|
+to space time datasets or to the results of operations between space time datasets.
|
|
|
+<br>
|
|
|
+<br>
|
|
|
+The type of the input space time datasets must be defined with the input
|
|
|
+parameter <b>type</b>. Possible options are STRDS, STVDS or STR3DS.
|
|
|
+The default is set to space time raster datasets (STRDS).
|
|
|
+<br>
|
|
|
+<br>
|
|
|
+As default, topological relationships between space time datasets will be
|
|
|
+evaluated only temporal. Use the <b>s</b> flag to activate the
|
|
|
+additionally spatial topology evaluation.
|
|
|
+<br>
|
|
|
+<br>
|
|
|
+The expression option must be passed as <b>quoted</b>
|
|
|
+expression, for example: <br>
|
|
|
+<div class="code"><pre>t.select expression="C = A : B"</pre></div>
|
|
|
+Where <b>C</b> is the new space time raster dataset that will contain maps
|
|
|
+from <b>A</b> that are selected by equal temporal relationships
|
|
|
+to the existing dataset <b>B</b> in this case. <br>
|
|
|
+<br>
|
|
|
+<h2>TEMPORAL ALGEBRA</h2>
|
|
|
+
|
|
|
+The temporal algebra provides a wide range of temporal operators and
|
|
|
+functions that will be presented in the following section. <br>
|
|
|
+<br>
|
|
|
+
|
|
|
+<h3>TEMPORAL RELATIONS</h3>
|
|
|
+
|
|
|
+Several temporal topology relations between registered maps of space
|
|
|
+time datasets are supported: <br>
|
|
|
+<div class="code"><pre>
|
|
|
+equals A ------
|
|
|
+ B ------
|
|
|
+
|
|
|
+during A ----
|
|
|
+ B ------
|
|
|
+
|
|
|
+contains A ------
|
|
|
+ B ----
|
|
|
+
|
|
|
+starts A ----
|
|
|
+ B ------
|
|
|
+
|
|
|
+started A ------
|
|
|
+ B ----
|
|
|
+
|
|
|
+finishs A ----
|
|
|
+ B ------
|
|
|
+
|
|
|
+finished A ------
|
|
|
+ B ----
|
|
|
+
|
|
|
+precedes A ----
|
|
|
+ B ----
|
|
|
+
|
|
|
+follows A ----
|
|
|
+ B ----
|
|
|
+
|
|
|
+overlapped A ------
|
|
|
+ B ------
|
|
|
+
|
|
|
+overlaps A ------
|
|
|
+ B ------
|
|
|
+
|
|
|
+over booth overlaps and overlapped
|
|
|
+
|
|
|
+</pre></div>
|
|
|
+The relations must be read as: A is related to B, like - A equals B - A is
|
|
|
+during B - A contains B <br>
|
|
|
+<br>
|
|
|
+Topological relations must be specified in {} parentheses. <br>
|
|
|
+
|
|
|
+<h3>TEMPORAL SELECTION</h3>
|
|
|
+
|
|
|
+The temporal selection simply selects parts of a space time dataset without
|
|
|
+processing raster or vector data.
|
|
|
+
|
|
|
+The algebra provides a selection operator <b>:</b> that selects parts
|
|
|
+of a space time dataset that are temporally equal to parts of a second one
|
|
|
+by default. The following expression
|
|
|
+<div class="code"><pre>
|
|
|
+C = A : B
|
|
|
+</pre></div>
|
|
|
+means: Select all parts of space time dataset A that are equal to B and store
|
|
|
+it in space time dataset C. The parts are time stamped maps. <br>
|
|
|
+<br>
|
|
|
+In addition the inverse selection operator <b>!:</b> is defined as the complement of
|
|
|
+the selection operator, hence the following expression
|
|
|
+<div class="code"><pre>
|
|
|
+C = A !: B
|
|
|
+</pre></div>
|
|
|
+means: select all parts of space time time dataset A that are not equal to B
|
|
|
+and store it in space time dataset (STDS) C. <br>
|
|
|
+<br>
|
|
|
+To select parts of a STDS by different topological relations to other STDS,
|
|
|
+the temporal topology selection operator can be used. The operator consists of
|
|
|
+topological relations, that must be separated by the logical OR operator
|
|
|
+<b>||</b> and the temporal selection operator. Both parts are separated by
|
|
|
+comma and surrounded by curly braces:
|
|
|
+{"topological relations", "temporal selection operator"} <br>
|
|
|
+<br>
|
|
|
+Examples:
|
|
|
+<div class="code"><pre>
|
|
|
+C = A {equals,:} B
|
|
|
+C = A {equals,!:} B
|
|
|
+</pre></div>
|
|
|
+We can now define arbitrary topological relations using the OR operator "|"
|
|
|
+to connect them:
|
|
|
+<div class="code"><pre>
|
|
|
+C = A {equals|during|overlaps,:} B
|
|
|
+</pre></div>
|
|
|
+Select all parts of A that are equal to B, during B or overlaps B. <br>
|
|
|
+<br>
|
|
|
+The selection operator is implicitly contained in the temporal topology
|
|
|
+selection operator, so that the following statements are exactly the same:
|
|
|
+<div class="code"><pre>
|
|
|
+C = A : B
|
|
|
+C = A {:} B
|
|
|
+C = A {equal,:} B
|
|
|
+</pre></div>
|
|
|
+
|
|
|
+Same for the complementary selection:
|
|
|
+<div class="code"><pre>
|
|
|
+C = A !: B
|
|
|
+C = A {!:} B
|
|
|
+C = A {equal,!:} B
|
|
|
+</pre></div>
|
|
|
+
|
|
|
+<h3>CONDITIONAL STATEMENTS</h3>
|
|
|
+
|
|
|
+Selection operations can be evaluated within conditional statements.
|
|
|
+<br>
|
|
|
+<div class="code"><pre>
|
|
|
+Note A and B can either be space time datasets or expressions.
|
|
|
+
|
|
|
+if statement decision option temporal relations
|
|
|
+ if(if, then, else)
|
|
|
+ if(conditions, A) A if conditions are True; temporal topological relation between if and then is equal.
|
|
|
+ if(conditions, A, B) A if conditions are True, B otherwise; temporal topological relation between if, then and else is equal.
|
|
|
+ if(topologies, conditions, A) A if conditions are True; temporal topological relation between if and then is explicit specified by topologies.
|
|
|
+ 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.
|
|
|
+</pre></div>
|
|
|
+The conditions are comparison expressions that are used to evaluate
|
|
|
+space time datasets. Specific values of temporal variables are
|
|
|
+compared by logical operators and evaluated for each map of the STDS.
|
|
|
+<br>
|
|
|
+<br>
|
|
|
+The supported logical operators:
|
|
|
+<div class="code"><pre>
|
|
|
+Symbol description
|
|
|
+
|
|
|
+ == equal
|
|
|
+ != not equal
|
|
|
+ > greater than
|
|
|
+ >= greater than or equal
|
|
|
+ < less than
|
|
|
+ <= less than or equal
|
|
|
+ && and
|
|
|
+ || or
|
|
|
+</pre></div>
|
|
|
+
|
|
|
+Temporal functions: <br>
|
|
|
+<div class="code"><pre>
|
|
|
+
|
|
|
+td(A) Returns a list of time intervals of STDS A
|
|
|
+
|
|
|
+start_time() Start time as HH::MM:SS
|
|
|
+start_date() Start date as yyyy-mm-DD
|
|
|
+start_datetime() Start datetime as yyyy-mm-DD HH:MM:SS
|
|
|
+end_time() End time as HH:MM:SS
|
|
|
+end_date() End date as yyyy-mm-DD
|
|
|
+end_datetime() End datetime as yyyy-mm-DD HH:MM
|
|
|
+
|
|
|
+start_doy() Day of year (doy) from the start time [1 - 366]
|
|
|
+start_dow() Day of week (dow) from the start time [1 - 7], the start of the week is Monday == 1
|
|
|
+start_year() The year of the start time [0 - 9999]
|
|
|
+start_month() The month of the start time [1 - 12]
|
|
|
+start_week() Week of year of the start time [1 - 54]
|
|
|
+start_day() Day of month from the start time [1 - 31]
|
|
|
+start_hour() The hour of the start time [0 - 23]
|
|
|
+start_minute() The minute of the start time [0 - 59]
|
|
|
+start_second() The second of the start time [0 - 59]
|
|
|
+end_doy() Day of year (doy) from the end time [1 - 366]
|
|
|
+end_dow() Day of week (dow) from the end time [1 - 7], the start of the week is Monday == 1
|
|
|
+end_year() The year of the end time [0 - 9999]
|
|
|
+end_month() The month of the end time [1 - 12]
|
|
|
+end_week() Week of year of the end time [1 - 54]
|
|
|
+end_day() Day of month from the start time [1 - 31]
|
|
|
+end_hour() The hour of the end time [0 - 23]
|
|
|
+end_minute() The minute of the end time [0 - 59]
|
|
|
+end_second() The second of the end time [0 - 59]
|
|
|
+</pre></div>
|
|
|
+
|
|
|
+Additionally the number of maps in intervals can be computed and
|
|
|
+used in conditional statements. <br>
|
|
|
+The operator to count the number of maps
|
|
|
+is the hash <b>#</b>.
|
|
|
+<div class="code"><pre>
|
|
|
+A{contains,#}B
|
|
|
+</pre></div>
|
|
|
+This expression computes the number of maps from space
|
|
|
+time dataset B which are during the time intervals of maps from
|
|
|
+space time dataset A.<br>
|
|
|
+A list of integers (scalars) corresponding to the maps of A
|
|
|
+that contain maps from B will be returned. <br>
|
|
|
+<br>
|
|
|
+
|
|
|
+Furthermore the temporal algebra allows temporal buffering, shifting
|
|
|
+and snapping with the functions buff_t(), tshift() and tsnap()
|
|
|
+respectively.
|
|
|
+<div class="code"><pre>
|
|
|
+buff_t(A, size) Buffer STDS A with granule ("1 month" or 5)
|
|
|
+tshift(A, size) Shift STDS A with granule ("1 month" or 5)
|
|
|
+tsnap(A) Snap time instances and intervals of STDS A
|
|
|
+</pre></div>
|
|
|
+
|
|
|
+<h3>Examples: </h3>
|
|
|
+
|
|
|
+Select all maps from space time dataset A which have equal time stamps
|
|
|
+with space time dataset B and C and are ealier that Jan. 1. 2005 and
|
|
|
+store them in space time dataset D.
|
|
|
+<div class="code"><pre>
|
|
|
+D = if(start_date() < "2005-01-01", A : B : C)
|
|
|
+</pre></div>
|
|
|
+
|
|
|
+Select all maps from space time dataset A which contains more than three
|
|
|
+maps of space time dataset B, else select maps from C with time
|
|
|
+stamps that are not equal to A and store them in space time dataset D.
|
|
|
+<div class="code"><pre>
|
|
|
+D = if(A {contain, #} B > 3, A {contain, :} B, C)
|
|
|
+</pre></div>
|
|
|
+
|
|
|
+Select all maps from space time dataset B which are during the temporal
|
|
|
+buffered space time dataset A with a map interval of three days, else
|
|
|
+select maps from C and store them in space time dataset D.
|
|
|
+<div class="code"><pre>
|
|
|
+D = if(contain, td(buff_t(A, "1 days")) == 3, B, C)
|
|
|
+</pre></div>
|
|
|
+
|
|
|
+<h2>REFERENCES</h2>
|
|
|
+
|
|
|
+<tt><a href="http://www.dabeaz.com/ply/">PLY(Python-Lex-Yacc)</a></tt>
|
|
|
+
|
|
|
+<h2>SEE ALSO</h2>
|
|
|
+
|
|
|
+<em>
|
|
|
+<a href="r.mapcalc.html">r.mapcalc</a>
|
|
|
+</em>
|
|
|
+
|
|
|
+
|
|
|
+<h2>AUTHORS</h2>
|
|
|
+
|
|
|
+Thomas Leppelt, Soeren Gebbert, Thuenen Institut, Germany <br>
|
|
|
+
|
|
|
+<p><i>Last changed: $Date: 2013-07-24 17:35:20 +0100 (Thu, 24 Jul 2013) $</i>
|
|
|
+
|