Skip to content

t.rast.what

Sample a space time raster dataset at specific vector point coordinates and write the output to stdout using different layouts

t.rast.what [-niv] [points=name] [coordinates=east,north] strds=name [output=name] [where=sql_query] [null_value=string] [separator=character] [order=string [,string,...]] [layout=string] [nprocs=integer] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

t.rast.what strds=name

grass.script.run_command("t.rast.what", points=None, coordinates=None, strds, output="-", where=None, null_value=None, separator="pipe", order="start_time", layout="row", nprocs=1, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("t.rast.what", strds="name")

Parameters

points=name
    Name of input vector map
    Or data source for direct OGR access
coordinates=east,north
    Comma separated list of coordinates
strds=name [required]
    Name of the input space time raster dataset
output=name
    Name for the output file or "-" in case stdout should be used
    Default: -
where=sql_query
    WHERE conditions of SQL statement without 'where' keyword used in the temporal GIS framework
    Example: start_time > '2001-01-01 12:30:00'
null_value=string
    String representing NULL value
separator=character
    Field separator
    Special characters: pipe, comma, space, tab, newline
    Default: pipe
order=string [,string,...]
    Sort the maps by category
    Allowed values: id, name, creator, mapset, creation_time, modification_time, start_time, end_time, north, south, west, east, min, max
    Default: start_time
layout=string
    The layout of the output. One point per row (row), one point per column (col), all timsteps in one row (timerow)
    Allowed values: row, col, timerow
    Default: row
nprocs=integer
    Number of r.what processes to run in parallel
    Default: 1
-n
    Output header row
-i
    Use stdin as input and ignore coordinates and point option
-v
    Show the category for vector points map
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

points : str, optional
    Name of input vector map
    Or data source for direct OGR access
    Used as: input, vector, name
coordinates : tuple[float, float] | list[float] | str, optional
    Comma separated list of coordinates
    Used as: input, coords, east,north
strds : str, required
    Name of the input space time raster dataset
    Used as: input, strds, name
output : str, optional
    Name for the output file or "-" in case stdout should be used
    Used as: output, file, name
    Default: -
where : str, optional
    WHERE conditions of SQL statement without 'where' keyword used in the temporal GIS framework
    Example: start_time > '2001-01-01 12:30:00'
    Used as: sql_query
null_value : str, optional
    String representing NULL value
    Used as: string
separator : str, optional
    Field separator
    Special characters: pipe, comma, space, tab, newline
    Used as: input, separator, character
    Default: pipe
order : str | list[str], optional
    Sort the maps by category
    Allowed values: id, name, creator, mapset, creation_time, modification_time, start_time, end_time, north, south, west, east, min, max
    Default: start_time
layout : str, optional
    The layout of the output. One point per row (row), one point per column (col), all timsteps in one row (timerow)
    Allowed values: row, col, timerow
    Default: row
nprocs : int, optional
    Number of r.what processes to run in parallel
    Default: 1
flags : str, optional
    Allowed values: n, i, v
    n
        Output header row
    i
        Use stdin as input and ignore coordinates and point option
    v
        Show the category for vector points map
overwrite: bool, optional
    Allow output files to overwrite existing files
    Default: False
verbose: bool, optional
    Verbose module output
    Default: False
quiet: bool, optional
    Quiet module output
    Default: False
superquiet: bool, optional
    Very quiet module output
    Default: False

DESCRIPTION

t.rast.what is designed to sample space time raster datasets at specific point coordinates using r.what internally. The output of r.what is transformed to different output layouts. The output layouts can be specified using the layout option.

Three layouts can be specified:

  • row - Row order, one vector sample point value per row
  • col - Column order, create a column for each vector sample point of a single time step/raster layer
  • timerow - Time order, create a column for each time step, this order is the original r.what output, except that the column names are the timestamps

Please have a look at the example to see the supported layouts.

This module is designed to run several instances of r.what to sample subsets of a space time raster dataset in parallel. Several intermediate text files will be created that are merged into a single file at the end of the processing.

Coordinates can be provided as vector map using the points option or as comma separated coordinate list with the coordinates option.

An output file can be specified using the output option. Stdout will be used if no output is specified or if the output option is set to "-".

EXAMPLES

Data preparation

In the following examples we sample a space time raster dataset that contains 4 raster map layers. First we create the STRDS that will be sampled with t.rast.what.

g.region s=0 n=80 w=0 e=120 b=0 t=50 res=10

# Generate data
r.mapcalc expression="a_1 = 1" -s
r.mapcalc expression="a_2 = 2" -s
r.mapcalc expression="a_3 = 3" -s
r.mapcalc expression="a_4 = 4" -s

t.create type=strds output=A title="A test" descr="A test"

t.register -i type=raster input=A maps=a_1,a_2,a_3,a_4 \
    start='1990-01-01' increment="1 month"

Example 1

The first approach uses text coordinates as input and stdout as output, the layout is one coordinate(point per column:

t.rast.what strds=A coordinates="115,36,79,45" layout=col -n

start|end|115.0000000000;36.0000000000|79.0000000000;45.0000000000
1990-01-01 00:00:00|1990-02-01 00:00:00|1|1
1990-02-01 00:00:00|1990-03-01 00:00:00|2|2
1990-03-01 00:00:00|1990-04-01 00:00:00|3|3
1990-04-01 00:00:00|1990-05-01 00:00:00|4|4

Example 2

A vector map layer can be used as input to sample the STRDS. All three available layouts are demonstrated using the vector map for sampling.

# First create the vector map layer based on random points
v.random output=points n=3 seed=1

# Row layout using a text file as output
t.rast.what strds=A points=points output=result.txt layout=row -n

cat result.txt

115.0043586274|36.3593955783|1990-01-01 00:00:00|1990-02-01 00:00:00|1
115.0043586274|36.3593955783|1990-02-01 00:00:00|1990-03-01 00:00:00|2
115.0043586274|36.3593955783|1990-03-01 00:00:00|1990-04-01 00:00:00|3
115.0043586274|36.3593955783|1990-04-01 00:00:00|1990-05-01 00:00:00|4
79.6816763826|45.2391522853|1990-01-01 00:00:00|1990-02-01 00:00:00|1
79.6816763826|45.2391522853|1990-02-01 00:00:00|1990-03-01 00:00:00|2
79.6816763826|45.2391522853|1990-03-01 00:00:00|1990-04-01 00:00:00|3
79.6816763826|45.2391522853|1990-04-01 00:00:00|1990-05-01 00:00:00|4
97.4892579600|79.2347263950|1990-01-01 00:00:00|1990-02-01 00:00:00|1
97.4892579600|79.2347263950|1990-02-01 00:00:00|1990-03-01 00:00:00|2
97.4892579600|79.2347263950|1990-03-01 00:00:00|1990-04-01 00:00:00|3
97.4892579600|79.2347263950|1990-04-01 00:00:00|1990-05-01 00:00:00|4


# Column layout order using stdout as output
t.rast.what strds=A points=points layout=col -n

start|end|115.0043586274;36.3593955783|79.6816763826;45.2391522853|97.4892579600;79.2347263950
1990-01-01 00:00:00|1990-02-01 00:00:00|1|1|1
1990-02-01 00:00:00|1990-03-01 00:00:00|2|2|2
1990-03-01 00:00:00|1990-04-01 00:00:00|3|3|3
1990-04-01 00:00:00|1990-05-01 00:00:00|4|4|4

# Timerow layout, one time series per row
# using the where statement to select a subset of the STRDS
# and stdout as output
t.rast.what strds=A points=points \
    where="start_time >= '1990-03-01'" layout=timerow -n

x|y|1990-03-01 00:00:00;1990-04-01 00:00:00|1990-04-01 00:00:00;1990-05-01 00:00:00
115.004358627375|36.3593955782903|3|4
79.681676382576|45.2391522852909|3|4
97.4892579600048|79.2347263950131|3|4

SEE ALSO

g.region, r.mask r.neighbors, r.what, t.info, t.rast.aggregate.ds, t.rast.extract, v.what.strds

AUTHOR

Sören Gebbert, Thünen Institute of Climate-Smart Agriculture

SOURCE CODE

Available at: t.rast.what source code (history)
Latest change: Friday Feb 07 19:16:09 2025 in commit a82a39f