= Temporal GIS Algebra for Raster and Vector Data = The idea is to implement a temporal GIS algebra to process space time datasets of type raster and vector, the new spatio-temporal datatypes in GRASS GIS 7. Space time datasets represent time series of raster, 3D raster and vector maps. The GRASS GIS temporal framework implements a snapshot approach, so that time and space are separated from each other. Hence, space time datasets are not truly 4 dimensional datatypes, time and space can only be processed separately from each other. The spatial capabilities of GRASS GIS are used to perform the spatial processing of the time stamped maps that are registered in the space time datasets. We use the modules r.mapcalc for raster processing and v.buffer, v.overlay, v.patch for vector map processing in the algebra. The temporal processing is provided by the GRASS GIS temporal framework that supports time intervals and time instances. Mixing time instance and time intervals as well as gaps, overlapping or inclusion of intervals and instances is possible. Hence this framework allows an arbitrary layout of the time dimension. The only way to process several space time datasets with arbitrary temporal layout is to use their temporal relationships. Or more precisely, the temporal relationships of the time stamped maps that are registered in the space time datasets. The spatial operations between maps (sum, union, ...) can be performed after the temporal related maps are identified. This concept leads the design of the temporal GIS algebra. The algebra provides the functionality to define spatio-temporal operators that process time and space in a single expression. == Temporal Algebra == The temporal part of the temporal GIS algebra is designed to be used as is in the temporal vector algebra and the temporal raster algebra. Hence it works with space time datasets of any type (STRDS, STR3DS and STVDS). The algebra provides methods select maps 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. These operations can be assigned to space time datasets or to the results of operations between space time datasets. ==== Temporal selection ==== Here an example of the temporal algebra that simply selects parts of a space time dataset without processing raster or vector data: We have defined the selection operator ''':''' that by default selects parts of a space time dataset that are temporally equal to parts of a second one. The following expression {{{ 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 in this case time stamped maps. In addition we define the inverse 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. We have defined the operator {"selection operator", "topological relations", "temporal operator"} to perform selection with different temporal topology relations. Examples: {{{ C = A {:,equals} B is exactly the same as C = A : B C = A {!:,equals} B is exactly the same as C = A !: B }}} We can now define arbitrary topological relations using logical OR operator to connect them: {{{ C = A {:,equals|during|overlaps} B }}} Select all parts of A that are equal B, during B or overlaps B. ==== Temporal buffer ==== Buffer time instances or time intervals: {{{ buff_t(STDS, "time interval") }}} Example: {{{ C = buff_t(A, "1 day") }}} Buffer all maps of STDS A with a temporal buffer of one day. ==== Temporal shift ==== Temporally shift all maps in a space time dataset by an interval: {{{ tshift(STDS, "time interval") }}} Example: {{{ tshift(A, "2 months") }}} Temporally shift all maps of space time dataset A by two months. ==== Temporally snap ==== Temporally snap time instances to its temporal nearest neighbor in the future and close gaps between time intervals. {{{ tsnap(STDS) }}} ==== Conditional statements ==== Spatiotemporal 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 conditions conclusion option temporal relations if(if, then, else) if(conditions, A) A if conditions are True; Topological relation between conditions(if) and conclusion(then) is equal. if(conditions, A, B) A if conditions are True, B otherwise; Topological relation between conditions(if) and conclusions(then + else) is equal. if({topologies}, conditions, A) A if conditions are True; Topological relation between conditions(if) and conclusions(then) is explicit specified by topologies. if({topologies}, conditions, A, B) A if conditions are True, B otherwise; Topological relation between conditions(if) and conclusions(then + 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. The supported 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] }}} Additionally the number of maps in intervals can be computed and used in conditional statements with the hash (#) operator. ==== The hash operator ==== It is of important interest how many maps are located in the time interval of a single map when processing two space time datasets. For this reason the hash operator '''#''' was introduced. In addition to the hash operator the temporal relation can be specified that should be analysed. Example: {{{ 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 leading '''equal''' statement in the '''if''' condition specifies the temporal relation between the if and then part of the if expression. This is very important, so we do not need to specify a global time reference (a space time dataset) for temporal processing. ==== Single map with temporal extent ==== The temporal algebra can also handle single maps with time stamps in the tmap function. tmap() For example: {{{ C = A {:,during} tmap(event) }}} This statement select all maps from space time data set A that are during the temporal extent of single map 'event' == Temporal Vector Algebra == The temporal vector algebra includes all functions from the temporal algebra and adds spatial Boolean and buffer operations that can be performed on temporal related vector maps that are registered in space time vector datasets. === Spatio-Temporal Operators === These are the spatial operators that are supported: {{{ AND & Intersection (v.overlay operator=and) OR | Union (v.overlay operator=or) DISJOINT OR + Disjoint union (v.patch) XOR ^ Symmetric difference (v.overlay operator=xor) NOT ~ Complement (v.overlay operator=not) }}} We combine the spatial operators, the temporal topology relations and the temporal operators to create spatio-temporal operators: {{{ {"spatial operator", "list of temporal relations", "temporal operator"} }}} The spatial operator can be used stand-alone. In this case the temporal topology relation "equal" and the temporal operator "left reference =" is assumed and used as default. This allows the convenient use of the spatial operators in case of space time vector datasets with equal time stamps. Example: Compute the spatial intersection between maps of STVDS A and B that are temporally equal, resulting spatial intersection maps are stored in C with time stamps from A: {{{ C = A & B }}} Compute the spatio-temporal intersection between maps of STVDS A and B that temporally overlap, resulting spatial intersection maps are stored in C with new time stamps resulting from temporal intersection: {{{ C = A {&,overlap,&} B }}} Perform a spatial union and a temporal disjoint union between all maps of STVDS A and B that are temporally equal or overlap and are later than 1990, resulting spatial union maps are stored in C with new time stamps resulting from temporal disjoint union: {{{ C = if({equal|overlap},start_year(A) > 1990, A {|,equal|overlap,+} B) }}} The temporal vector algebra provides point, line and area buffer functions in addition to the operators. == Temporal Raster Algebra == The temporal raster algebra uses all operators and functions of the temporal algebra and adds a subset of the arithmetic operators and functions from r.mapcalc. New spatio-temporal operators are defined that include temporal topology relations, temporal operators and arithmetic operators. ==== Arithmetic operators ==== {{{ Symbol Description + Addition - Substraction * Multiplication / Division % Modulus }}} ==== Arithmetic function ==== {{{ Symbol exp log sqrt abs cos acos sin asin tan double float int isnull isntnull null exist }}} Examples: Create the sum of all maps from STRDS A and B that have equal time stamps and store the new maps in STRDS C: {{{ C = A + B }}} Same expression with explicit definition of the temporal topology relation and temporal operators: {{{ C = A {+,equal,l} B }}} Select all cells from STRDS B with equal temporal relations to STRDS A, if the cells of A are in the range of [100.0, 1600] of time intervals that have more then 30 days (Jan, Mar, Mai, Jul, Aug, Oct, Dec): {{{ C = if(A > 100 && A < 1600 && td(A) > 30, B) }}} Same expression with explicit definition of the temporal topology relation and temporal operators: {{{ C = if({equal}, A > 100 && A < 1600 {&&,equal} td(A) > 30, B) }}} Compute the recharge in meter per second for all cells of precipitation STRDS "Prec" if the mean temperature specified in STRDS "Temp" is higher than 10 degrees. Computation is performed if STRDS "Prec" and "Temp" have equal time stamps. The number of days or fraction of days per interval is computed using the td() function that has as argument the STRDS "Prec": {{{ C = if(Temp > 10.0, Prec / 3600.0 /24.0 / td(Prec)) }}} Same expression with explicit definition of the temporal topology relation and temporal operators: {{{ C = if({equal}, Temp > 10.0, Prec / 3600.0 / 24.0 {/,equal,l} td(Prec)) }}} Compute the mean value of all maps from STRDS A that are located during time intervals of STRDS B if more than one map of A is contained in an interval of B, use A otherwise, the resulting time intervals are either from B or A: {{{ C = if(B {#,contain} A > 1, (B {+,contain,l} A - B) / (B {#,contain} A), A) }}} Same expression with explicit definition of the temporal topology relation and temporal operators: {{{ C = if({equal}, B {#,contain} A > 1, (B {+,contain,l} A {-,equal,l} B) {equal,=/} (B {#,contain} A), A) }}} ==== Single raster map function ==== The temporal raster algebra feature also a function to integrate single raster maps without time stamps into the expressions. map() For example: {{{ C = A * map(constant_value) }}} This statement multiply all raster maps from space time raster data set A with the raster map 'constant_value' ==== Implicit aggregation for spatio-temporal operators ==== The algebra evaluates the stated STDS by their temporal topologies and apply the given spatio temporal operators in a aggregated form. If we have two STDS A and B, B has three maps: b1, b2, b3 that are all during the temporal extent of the single map a1 of A, then the following arithemtic calculations would implicitly aggregate all maps of B into one result map for a1 of A: {{{ C = A {+, contains} B --> c1 = a1 + b1 + b2 + b3 }}} Keep attention that the aggregation behaviour is not symmetric: {{{ C = B {+, during} A --> c1 = b1 + a1 c2 = b2 + a1 c3 = b3 + a1 }}} = Overview of all supported spatio-temporal operators and functions = == Temporal topology relations == {{{ equal 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 A is related to B, like - A equals B - A is during B - A contains B Topological relations must be specified in {} parentheses {{{ A {equal} B }}} Topological relations are always combined with other temporal operators in the {} parentheses == Temporal operators == The temporal algebra defines temporal operators that can be combined later with spatial operators to perform spatio-temporal operations. The temporal operators process the time instances and intervals of temporal related maps. {{{ 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 }}} For example we can compute the intersection, union or disjoint union from time stamps of maps that temporally overlap, or we can just keep the time stamp of the left STDS. Temporal operators that work on time intervals and instances of maps in space time datasets: '''Left Reference l''' Examples with time intervals a, b and left referenced c: {{{ a ------ b ---- c ------ a ---- b ---- c ---- a --- b --- c --- a --- b --- c --- }}} '''Intersection i ''' Examples with time intervals a, b and intersection c: {{{ a ------ b ---- c ---- a ---- b ---- c -- a --- b --- c }}} '''Disjoint Union d''' Examples with time intervals a, b and disjoint union c: {{{ a ------ b ---- c ------ a ---- b ---- c ------ a --- b --- c ------ a --- b --- c ------- }}} '''Union u''' Examples with time intervals a, b and union c: {{{ a ------ b ---- c ------ a ---- b ---- c ------ a --- b --- c ------ a --- b --- c }}} '''Right Reference r''' Examples with time intervals a, b and right referenced c: {{{ a ------ b ---- c ------ a ---- b ---- c ---- a --- b --- c --- a --- b --- c --- }}} The l operator ignores indexing operators for space time datasets: A[i] Temporal selection operators to select parts of space time datasets: ''' Selection :'''[[BR]] ''' Inverse selection !:''' Temporal operators have no precedence. Examples: * Select all maps from space time dataset A that have equal time intervals with space time dataset B and store them in space time datasets C. {{{ C = A : B C = A {:} B C = A {:,equal} B }}} * Select all maps from space time dataset A that have unequal time intervals with space time dataset B and store them in space time datasets C. {{{ C = A !: B C = A {!:} B C = A {!:,equal} B }}} * Select all maps from space time dataset A that are during time intervals of space time dataset B and store them in space time datasets C. {{{ C = A {:,during} B }}} * Select all maps from space time dataset A that are during B and during C and during D. {{{ E = A {:,during} B {:,during} C {:,during} D }}} Operator number of maps in interval [[BR]] '''Number of maps #''' Compute the number of maps from space time dataset B that are during the time intervals