Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
t.select(1)		    GRASS GIS User's Manual		   t.select(1)

NAME
       t.select	  -  Select maps from space time datasets by topological rela-
       tionships to other space	time datasets using temporal algebra.

KEYWORDS
       temporal, metadata, time

SYNOPSIS
       t.select
       t.select	--help
       t.select	[-sd]  [type=name]  expression=expression   [--help]   [--ver-
       bose]  [--quiet]	 [--ui]

   Flags:
       -s
	   Check  the  spatial	topology of temporally related maps and	select
	   only	spatially related maps

       -d
	   Perform a dry run, compute all dependencies and  module  calls  but
	   don't run them

       --help
	   Print usage summary

       --verbose
	   Verbose module output

       --quiet
	   Quiet module	output

       --ui
	   Force launching GUI dialog

   Parameters:
       type=name
	   Type	of the input space time	dataset
	   Options: strds, stvds, str3ds
	   Default: strds

       expression=expressionA [required]
	   The temporal	mapcalc	expression

DESCRIPTION
       t.select	 performs  selection of	maps that are registered in space time
       datasets	using temporal algebra.

   PROGRAM USE
       The module expects an expression	as input parameter  in	the  following
       form:

       "result = expression"

       The  statement structure	is similar to r.mapcalc, see r.mapcalc.	 Where
       result represents the name of a space time dataset (STDS)that will con-
       tain  the  result of the	calculation that is given as expression	on the
       right side of the equality sign.	 These expression can be any valid  or
       nested  combination  of temporal	operations and functions that are pro-
       vided by	the temporal algebra.
       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	tempo-
       rally  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.

       The type	of the input space time	datasets must be defined with the  in-
       put  parameter  type. Possible options are STRDS, STVDS or STR3DS.  The
       default is set to space time raster datasets (STRDS).

       As default, topological relationships between space time	datasets  will
       be evaluated only temporal. Use the s flag to activate the additionally
       spatial topology	evaluation.

       The expression option must be passed as quoted expression, for example:
       t.select	expression="C =	A : B"
       Where C is the new space	time raster dataset  that  will	 contain  maps
       from  A that are	selected by equal temporal relationships to the	exist-
       ing dataset B in	this case.

TEMPORAL ALGEBRA
       The temporal algebra provides a wide range of  temporal	operators  and
       functions that will be presented	in the following section.

   TEMPORAL RELATIONS
       Several	temporal  topology  relations between registered maps of space
       time datasets are supported:
       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
       The relations must be read as: A	is related to B, like -	A equals B - A
       is during B - A contains	B

       Topological relations must be specified in {} parentheses.

   TEMPORAL OPERATORS
       The  temporal  algebra  defines temporal	operators that can be combined
       with other operators to perform spatio-temporal operations.  The	tempo-
       ral  operators process the time instances and intervals of two temporal
       related maps and	calculate the result temporal extent by	five different
       possibilities.
       LEFT REFERENCE	  l	  Use the time stamp of	the left space time dataset
       INTERSECTION	  i	  Intersection
       DISJOINT	UNION	  d	  Disjoint union
       UNION		  u	  Union
       RIGHT REFERENCE	  r	  Use the time stamp of	the right space	time dataset

   TEMPORAL SELECTION
       The  temporal  selection	 simply	 selects parts of a space time dataset
       without processing raster or vector data.  The algebra provides	a  se-
       lection	operator : that	selects	parts of a space time dataset that are
       temporally equal	to parts of a second one by default. The following ex-
       pression
       C = A : B
       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.

       In addition the inverse selection operator !: is	defined	as the comple-
       ment of the selection operator, hence the following expression
       C = A !:	B
       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.

       To select parts of a STDS by different topological relations  to	 other
       STDS,  the temporal topology selection operator can be used. The	opera-
       tor consists of the temporal selection operator,	the topological	 rela-
       tions, that must	be separated by	the logical OR operator	| and the tem-
       poral extent operator.  All three parts are separated by	comma and sur-
       rounded by curly	braces:
       {"temporal selection operator", "topological relations",	"temporal operator"}
       Examples:
       C = A {:, equals} B
       C = A {!:, equals} B
       We can now define arbitrary topological relations using the OR operator
       "|" to connect them:
       C = A {:,equals|during|overlaps}	B
       Select all parts	of A that are equal to B, during B or overlaps B.
       In addition we can define the temporal extent of	 the  result  STDS  by
       adding the temporal operator.
       C = A {:, during,r} B
       Select  all  parts  of A	that are during	B and use the temporal extents
       from B for C.
       The selection operator is implicitly contained in the temporal topology
       selection  operator,  so	 that the following statements are exactly the
       same:
       C = A : B
       C = A {:} B
       C = A {:,equal} B
       C = A {:,equal,l} B
       Same for	the complementary selection:
       C = A !:	B
       C = A {!:} B
       C = A {!:,equal}	B
       C = A {!:,equal,l} B

   CONDITIONAL STATEMENTS
       Selection operations can	be evaluated within conditional	statements.
       Note A and B can	either be space	time datasets or expressions. The temporal
       relationship between the	conditions and the conclusions can be defined at the
       beginning of the	if statement. The relationship between then and	else conclusion
       must be always equal.
       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.
       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.
       Important: The conditions are evaluated from left to right.

   Logical operators
       Symbol  description
	 ==    equal
	 !=    not equal
	 >     greater than
	 >=    greater than or equal
	 <     less than
	 <=    less than or equal
	 &&    and
	 ||    or

   Temporal functions
       The following temporal function are evaluated only for  the  STDS  that
       must be given in	parenthesis.
       td(A)			Returns	a list of time intervals of STDS A
       start_time(A)		Start time as HH::MM:SS
       start_date(A)		Start date as yyyy-mm-DD
       start_datetime(A)	Start datetime as yyyy-mm-DD HH:MM:SS
       end_time(A)		End time as HH:MM:SS
       end_date(A)		End date as yyyy-mm-DD
       end_datetime(A)		End datetime as	 yyyy-mm-DD HH:MM
       start_doy(A)		Day of year (doy) from the start time [1 - 366]
       start_dow(A)		Day of week (dow) from the start time [1 - 7], the start of the	week is	Monday == 1
       start_year(A)		The year of the	start time [0 -	9999]
       start_month(A)		The month of the start time [1 - 12]
       start_week(A)		Week of	year of	the start time [1 - 54]
       start_day(A)		Day of month from the start time [1 - 31]
       start_hour(A)		The hour of the	start time [0 -	23]
       start_minute(A)		The minute of the start	time [0	- 59]
       start_second(A)		The second of the start	time [0	- 59]
       end_doy(A)		Day of year (doy) from the end time [1 - 366]
       end_dow(A)		Day of week (dow) from the end time [1 - 7], the start of the week is Monday ==	1
       end_year(A)		The year of the	end time [0 - 9999]
       end_month(A)		The month of the end time [1 - 12]
       end_week(A)		Week of	year of	the end	time [1	- 54]
       end_day(A)		Day of month from the start time [1 - 31]
       end_hour(A)		The hour of the	end time [0 - 23]
       end_minute(A)		The minute of the end time [0 -	59]
       end_second(A)		The second of the end time [0 -	59]

   Comparison operator
       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 and the re-
       lated maps.  For	complex	relations the comparison operator can be  used
       to combine conditions:
       The  structure  is similar to the select	operator with the extension of
       an aggregation operator:	 {"comparison  operator",  "topological	 rela-
       tions", aggregation operator, "temporal operator"}
       This aggregation	operator (| or &) define the behaviour if a map	is re-
       lated the more than one map, e.g	for the	 topological  relations	 'con-
       tains'.	 Should	 all (&) conditions for	the related maps be true or is
       it sufficient to	have any (|) condition that  is	 true.	The  resulting
       boolean value is	then compared to the first condition by	the comparison
       operator	(|| or &&).  As	default	the aggregation	operator is related to
       the comparison operator:
       Comparison operator -> aggregation operator:
       || -> | and && -> &
       Examples:
       Condition 1 {||,	equal, r} Condition 2
       Condition 1 {&&,	equal|during, l} Condition 2
       Condition 1 {&&,	equal|contains,	|, l} Condition	2
       Condition 1 {&&,	equal|during, l} Condition 2 &&	Condition 3
       Condition 1 {&&,	equal|during, l} Condition 2 {&&,contains, |, r} Condition 3

   Hash	operator
       Additionally  the  number of maps in intervals can be computed and used
       in conditional statements with the hash (#) operator.
       A{#, contains}B
       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.
       A  list	of integers (scalars) corresponding to the maps	of A that con-
       tain maps from B	will be	returned.

       C = if({equal}, A {#, contains} B > 2, A	{:, contains} B)
       This expression selects all maps	from A	that  temporally  contains  at
       least  2	maps from B and	stores them in space time dataset C. The lead-
       ing equal statement in the if condition specifies the temporal relation
       between	the if and then	part of	the if expression. This	is very	impor-
       tant, so	we do not need to specify a global  time  reference  (a	 space
       time dataset) for temporal processing.

       Furthermore  the	 temporal  algebra allows temporal buffering, shifting
       and snapping with the functions buff_t(), tshift() and tsnap()  respec-
       tively.
       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

   Single map with temporal extent
       The  temporal  algebra  can also	handle single maps with	time stamps in
       the map function.
       tmap()
       For example:
	C = A {:,during} tmap(event)
       This statement select all maps from space time data set A that are dur-
       ing the temporal	extent of single map 'event'

Examples
       Select  all maps	from space time	dataset	A which	have equal time	stamps
       with space time dataset B and C and are earlier that Jan. 1.  2005  and
       store them in space time	dataset	D.
       D = if(start_date(A) < "2005-01-01", A :	B : C)
       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.
       D = if(A	{#, contains} B	> 3, A {:, contains} B,	C)
       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.
       D = if(contains,	td(buff_t(A, "1	days"))	== 3, B, C)

SEE ALSO
	r.mapcalc

REFERENCES
       PLY(Python-Lex-Yacc)

AUTHORS
       Thomas  Leppelt,	 SA<paragraph>ren Gebbert, ThA1/4nen Institute of Cli-
       mate-Smart Agriculture

SOURCE CODE
       Available at: t.select source code (history)

       Main index | Temporal index | Topics index | Keywords index | Graphical
       index | Full index

       A(C) 2003-2020 GRASS Development	Team, GRASS GIS	7.8.3 Reference	Manual

GRASS 7.8.3							   t.select(1)

NAME | KEYWORDS | SYNOPSIS | DESCRIPTION | TEMPORAL ALGEBRA | Examples | SEE ALSO | REFERENCES | AUTHORS | SOURCE CODE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=t.select&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help