t.rast.series

Performs different aggregation algorithms from r.series on all or a subset of raster maps in a space time raster dataset.

Command linePython (grass.script)

t.rast.series [-tn] input=name method=string [,string,...] [quantile=float [,float,...]] [order=string [,string,...]] [nprocs=integer] [memory=memory in MB] [where=sql_query] output=name [,name,...] [file_limit=integer] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

t.rast.series input=name method=average output=name

grass.script.run_command("t.rast.series", input, method="average", quantile=None, order="start_time", nprocs=1, memory=300, where=None, output, file_limit=1000, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("t.rast.series", input="name", method="average", output="name")

Parameters

Command linePython (grass.script)

input=name [required]
    Name of the input space time raster dataset
method=string [,string,...] [required]
    Aggregate operation to be performed on the raster maps
    Allowed values: average, count, median, mode, minimum, min_raster, maximum, max_raster, stddev, range, sum, variance, diversity, slope, offset, detcoeff, quart1, quart3, perc90, quantile, skewness, kurtosis
    Default: average
quantile=float [,float,...]
    Quantile to calculate for method=quantile
    Allowed values: 0.0-1.0
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
nprocs=integer
    Number of threads for parallel computing
    Default: 1
memory=memory in MB
    Maximum memory to be used (in MB)
    Cache size for raster rows
    Default: 300
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'
output=name [,name,...] [required]
    Name for output raster map(s)
file_limit=integer
    The maximum number of open files allowed for each r.series process
    Default: 1000
-t
    Do not assign the space time raster dataset start and end time to the output map
-n
    Propagate NULLs
--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

input : str, required
    Name of the input space time raster dataset
    Used as: input, strds, name
method : str | list[str], required
    Aggregate operation to be performed on the raster maps
    Allowed values: average, count, median, mode, minimum, min_raster, maximum, max_raster, stddev, range, sum, variance, diversity, slope, offset, detcoeff, quart1, quart3, perc90, quantile, skewness, kurtosis
    Default: average
quantile : float | list[float] | str, optional
    Quantile to calculate for method=quantile
    Allowed values: 0.0-1.0
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
nprocs : int, optional
    Number of threads for parallel computing
    Default: 1
memory : int, optional
    Maximum memory to be used (in MB)
    Cache size for raster rows
    Used as: memory in MB
    Default: 300
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
output : str | list[str], required
    Name for output raster map(s)
    Used as: output, raster, name
file_limit : int, optional
    The maximum number of open files allowed for each r.series process
    Default: 1000
flags : str, optional
    Allowed values: t, n
    t
        Do not assign the space time raster dataset start and end time to the output map
    n
        Propagate NULLs
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

The input of this module is a single space time raster dataset, the output is a single raster map layer. A subset of the input space time raster dataset can be selected using the where option. The sorting of the raster map layer can be set using the order option. Be aware that the order of the maps can significantly influence the result of the aggregation (e.g.: slope). By default the maps are ordered by start_time.

t.rast.series is a simple wrapper for the raster module r.series. It supports a subset of the aggregation methods of r.series.

NOTES

To avoid problems with too many open files, by default, the maximum number of open files is set to 1000. If the number of input raster files exceeds this number, the -z flag will be invoked. Because this will slow down processing, the user can set a higher limit with the file_limit parameter. Note that file_limit limit should not exceed the user-specific limit on open files set by your operating system. See the Wiki for more information.

Performance

To enable parallel processing, the user can specify the number of threads to be used with the nprocs parameter (default 1). The memory parameter (default 300 MB) can also be provided to determine the size of the buffer in MB for computation. Both parameters are passed to r.series. To take advantage of the parallelization, GRASS GIS needs to be compiled with OpenMP enabled.

EXAMPLES

Estimate the average temperature for the whole time series

Here the entire stack of input maps is considered:

t.rast.series input=tempmean_monthly output=tempmean_average method=average

Estimate the average temperature for a subset of the time series

Here the stack of input maps is limited to a certain period of time:

t.rast.series input=tempmean_daily output=tempmean_season method=average \
  where="start_time >= '2012-06' and start_time <= '2012-08'"

Climatology: single month in a multi-annual time series

By considering only a single month in a multi-annual time series the so-called climatology can be computed. Estimate average temperature for all January maps in the time series:

t.rast.series input=tempmean_monthly \
    method=average output=tempmean_january \
    where="strftime('%m', start_time)='01'"

# equivalently, we can use
t.rast.series input=tempmean_monthly \
    output=tempmean_january method=average \
    where="start_time = datetime(start_time, 'start of year', '0 month')"

# if we want also February and March averages

t.rast.series input=tempmean_monthly \
    output=tempmean_february method=average \
    where="start_time = datetime(start_time, 'start of year', '1 month')"

t.rast.series input=tempmean_monthly \
    output=tempmean_march method=average \
    where="start_time = datetime(start_time, 'start of year', '2 month')"

Generalizing a bit, we can estimate monthly climatologies for all months by means of different methods

for i in `seq -w 1 12` ; do
  for m in average stddev minimum maximum ; do
    t.rast.series input=tempmean_monthly method=${m} output=tempmean_${m}_${i} \
    where="strftime('%m', start_time)='${i}'"
  done
done

SEE ALSO

r.series, t.create, t.info

Temporal data processing Wiki

AUTHOR

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

SOURCE CODE

Available at: t.rast.series source code (history)
Latest change: Sunday Feb 23 12:55:32 2025 in commit 0e431b3