t.select(1)

📦
version 8.4.2 · 8 versions
, in fedora 44

💫 t.select — the GRASS GIS User's Manual glow-up 💫

okay bestie, welcome to t.select(1) from the GRASS GIS User's Manual — she's giving temporal algebra main character energy and honestly? obsessed. 🎀

✨ NAME ✨

t.select — select maps from space time datasets by topological relationships to other space time datasets, using temporal algebra. yes she really said "topological relationships." no cap. 💅

🌸 KEYWORDS 🌸

temporal, metadata, time — the holy trinity, fr fr. ⭐

🦋 SYNOPSIS 🦋

t.select
t.select --help
t.select [-sd]  [type=name]  expression=expression  [--help]
[--verbose]  [--quiet]  [--ui]

🎀 Flags 🎀

  • -s — check the spatial topology of temporally related maps and select only the maps that are spatially related too. like, temporal match isn't enough, she wants the full vibe check. ✨
  • -d — do a dry run: compute all the dependencies and module calls but don't actually run them. window shopping, not buying. 🛍️
  • --help — print the usage summary. your lil emergency cheat sheet. 💖
  • --verbose — verbose module output. she will tell you everything. 😭
  • --quiet — quiet module output. she will tell you nothing. shhh. 🤫
  • --ui — force launching the GUI dialog. mouse girlies rise. 🖱️✨

💜 Parameters 💜

  • type=name — type of the input space time dataset.
    • Options: strds, stvds, str3ds
    • Default: strds
  • expression=expression — the temporal mapcalc expression. required, so like... you actually have to give her one. 🫶

🌈 DESCRIPTION 🌈

t.select performs selection of maps that are registered in space time datasets using temporal algebra. that's the whole job description and she's iconic at it. 👑

🧚 PROGRAM USE 🧚

okay so first things first: the module expects an expression as an input parameter, and it looks like this:

"result = expression"

The statement structure is similar to r.mapcalc — see r.mapcalc for the deets, iykyk. And where result represents the name of a space time dataset (STDS) that will contain the result of the calculation given as expression on the right side of the equality sign. 🟰

These *expression*s can be any valid or nested combination of temporal operations and functions that are provided by the temporal algebra. nesting like a lil matryoshka doll, we love to see it. 🪆

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
  • create temporal buffer
  • snap time instances to create a valid temporal topology

and beyond! ✨ 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 — all so you can build up conditions. 🧠💅 These operations can be assigned to space time datasets or to the results of operations between space time datasets. so meta. so powerful. 💀

The type of the input space time datasets must be defined with the input 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 temporally. Use the -s flag to activate the additionally spatial topology evaluation. (yes that's the flag from up there, she's back for a cameo 🎬)

The expression option must be passed as a 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 existing dataset B in this case. match made in heaven, honestly. 💞

🌟 bestie reminder: every option, value, default, flag and example lives here exactly as the original wrote them — I just gave them a wardrobe change. 💅

(part 1 done, more coming — don't go anywhere, the rest is loading… 🦋)

✨ TEMPORAL ALGEBRA ✨

Okay bestie, deep breath — this is the whole reason we're here. The temporal algebra is a whole buffet of temporal operators and functions, and I'm gonna walk you through every single one. No skipping, no skimming. 🫶

🌸 TEMPORAL RELATIONS 🌸

So when you've got registered maps inside space time datasets, they can be related to each other in a bunch of temporal topology ways. Here's the full lineup:

equals            A ------
                  B ------
during            A  ----
                  B ------
contains          A ------
                  B  ----
starts            A ----
                  B ------
started           A ------
                  B ----
finishes          A   ----
                  B ------
finished          A ------
                  B   ----
precedes          A ----
                  B     ----
follows           A     ----
                  B ----
overlapped        A   ------
                  B ------
overlaps          A ------
                  B   ------
over              both overlaps and overlapped

The way you read these is: A is related to B, like A equals B, A is during B, A contains B. That's it, that's the whole vibe check. 🎀

Topological relations must be specified in {} parentheses. Don't forget your curly braces, bestie — it's literally the difference between slaying and erroring out. 💅

🔥 TEMPORAL OPERATORS 🔥

The temporal algebra defines temporal operators that you can combine with other operators to do spatio-temporal operations. These operators take the time instances and intervals of two temporally related maps and calculate the result temporal extent in five different ways:

  • 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 👑

Temporal selection is the low-key genius move: it just selects parts of a space time dataset without processing any raster or vector data. Zero processing, zero drama. ✨

The algebra gives you the selection operator : — and by default it selects the parts of one space time dataset that are temporally equal to parts of a second one. So this:

C = A : B

means: select all the parts of space time dataset A that are equal to B, and store them in space time dataset C. And those parts? Time stamped maps, obviously. Not me stating the obvious but it matters. 😭

There's also the inverse selection operator !: — literally defined as the complement of the selection operator. So:

C = A !: B

means: select all the parts of space time dataset A that are not equal to B, and store them in space time dataset (STDS) C. Petty? No. Correct? Yes. 💅

Now, if you wanna select parts of an STDS by different topological relations to other STDSs, that's where the temporal topology selection operator comes in. It's built from three pieces:

  1. the temporal selection operator
  2. the topological relations — these must be separated by the logical OR operator |
  3. the temporal extent operator

All three parts get separated by commas and surrounded by curly braces, like:

{"temporal selection operator", "topological relations", "temporal operator"}

Examples, because we love a demo:

C = A {:, equals} B
C = A {!:, equals} B

And now you can go absolutely feral with the OR operator | and define arbitrary topological relations:

C = A {:,equals|during|overlaps} B

That one selects all the parts of A that are equal to B, during B, or overlap B. Three for one, ate. 🔥

You can also define the temporal extent of the result STDS by adding the temporal operator:

C = A {:, during,r} B

Which selects all parts of A that are during B, and uses the temporal extents from B for C.

Here's the tea though — the selection operator is implicitly contained in the temporal topology selection operator, so all of these statements are exactly the same:

C = A : B
C = A {:} B
C = A {:,equal} B
C = A {:,equal,l} B

And same energy for the complementary selection:

C = A !: B
C = A {!:} B
C = A {!:,equal} B
C = A {!:,equal,l} B

💖 CONDITIONAL STATEMENTS 💖

You can evaluate selection operations inside conditional statements. Quick note before we go: A and B can be either space time datasets or expressions. Either one, no cap.

The temporal relationship between the conditions and the conclusions gets defined at the beginning of the if statement. And the relationship between the then and else conclusion must always be equal. That part is non-negotiable.

Here's the whole lineup — 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 get used to evaluate space time datasets. Specific values of temporal variables get compared by logical operators and evaluated for each map of the STDS.

Important: the conditions are evaluated from left to right. Remember that. 👑

🌈 Logical operators 🌈

  • == — equal
  • != — not equal
  • > — greater than
  • >= — greater than or equal
  • < — less than
  • <= — less than or equal
  • && — and
  • || — or

🦋 Temporal functions 🦋

These temporal functions only get evaluated for the STDS, which you must put in parenthesis. Don't skip the parens, they're not optional.

  • 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 ⭐

Conditions are comparison expressions used to evaluate space time datasets. Specific values of temporal variables get compared by logical operators and evaluated for each map of the STDS and the related maps. For complex relations, you can use the comparison operator to combine conditions.

The structure is basically the select operator with an aggregation operator added on:

{"comparison operator", "topological relations", aggregation operator, "temporal operator"}

That aggregation operator (| or &) defines the behaviour when a map is related to more than one map — say, for the topological relation contains. Should all (&) the conditions for the related maps be true, or is it enough to have any (|) condition that's true? The resulting boolean value then gets compared to the first condition by the comparison operator (|| or &&).

By default, the aggregation operator is related to the comparison operator like this:

Comparison operator -> aggregation operator:
|| -> | and && -> &

Examples, bestie:

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 🧚

Bonus round: 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 that are during the time intervals of maps from space time dataset A. What you get back is a list of integers (scalars) corresponding to the maps of A that contain maps from B.

C = if({equal}, A {#, contains} B > 2, A {:, contains} B)

This expression selects all maps from A that temporally contain 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, because it means we do not need to specify a global time reference (a space time dataset) for temporal processing. Iconic behaviour, honestly. 💅

Also! The temporal algebra lets you do temporal buffering, shifting and snapping with the functions buff_t(), tshift() and tsnap():

  • 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 selects all maps from space time data set A that are during the temporal extent of the single map event.

🔥 EXAMPLES 🔥

Number one: select all maps from space time dataset A that have equal time stamps with space time datasets B and C and are earlier than Jan. 1. 2005, and store them in space time dataset D.

D = if(start_date(A) < "2005-01-01", A : B : C)

Number two: select all maps from space time dataset A that contain 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)

Number three: select all maps from space time dataset B that 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)

💖 REFERENCES 💖

Okay bestie, if you wanna go to the source of the source, here's the reading list:

  • PLY(Python-Lex-Yacc) — yes, the parser generator. The grammar gremlins live here. 🐍
  • Gebbert, S., Leppelt, T., Pebesma, E., 2019. A topology based spatio-temporal map algebra for big data analysis. Data 4, 86. https://doi.org/10.3390/data4020086
If you're out here writing a paper about space-time map algebra, cite these people. They did the homework so you don't have to. 🫶

🌈 SEE ALSO 🌈

  • r.mapcalc

That's the raster one, the non-temporal cousin. Same energy, no time dimension. Go say hi. 👋

👑 AUTHORS 👑

The literal legends who made this happen:

  • Thomas Leppelt
  • Sören Gebbert
  • Thünen Institute of Climate-Smart Agriculture

Not me getting emotional over a list of names in a manpage. 😭 Main character energy from all three of them, fr fr. ✨

📦 SOURCE CODE 📦

You want the actual code? Say less:

Available at: t.select source code (history)

Accessed: Saturday Jan 17 05:41:54 2026

Yeah she's timestamped, that's just how we do it here. 💅

And for your navigation needs, the index squad:

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

© 2003-2025 GRASS Development Team, GRASS GIS 8.4.2 Reference Manual

And that's the whole page, bestie!! 🎀 This was GRASS 8.4.2's t.select(1) — go select some space-time data with confidence, you've absolutely got this. Study the references, credit the authors, respect the r.mapcalc crossover, and remember: no cap, this manpage ate. ✨💖🦋💅

📦 where this page comes from