t.rast.univar
Calculates univariate statistics from the non-null cells for each registered raster map of a space time raster dataset.
t.rast.univar [-eru] input=name [zones=name] [nprocs=integer] [output=name] [percentile=float [,float,...]] [where=sql_query] [region_relation=string] [separator=character] format=name [--overwrite] [--verbose] [--quiet] [--qq] [--ui]
Example:
t.rast.univar input=name format=plain
grass.tools.Tools.t_rast_univar(input, zones=None, nprocs=0, output=None, percentile=None, where=None, region_relation=None, separator="", format="plain", flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
tools = Tools()
tools.t_rast_univar(input="name", format="json")
This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.
grass.script.parse_command("t.rast.univar", input, zones=None, nprocs=0, output=None, percentile=None, where=None, region_relation=None, separator="", format="plain", flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
gs.parse_command("t.rast.univar", input="name", format="json")
Parameters
input=name [required]
Name of the input space time raster dataset
zones=name
Raster map used for zoning, must be of type CELL
nprocs=integer
Number of threads for parallel computing
0: use OpenMP default; >0: use nprocs; <0: use MAX-nprocs
Default: 0
output=name
Name for output file
percentile=float [,float,...]
Percentile to calculate (requires extended statistics flag)
Allowed values: 0-100
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'
region_relation=string
Process only maps with this spatial relation to the current computational region
Allowed values: overlaps, contains, is_contained
separator=character
Field separator character between the output columns
Special characters: pipe, comma, space, tab, newline
format=name [required]
Output format
Allowed values: plain, json, csv
Default: plain
plain: Plain text output
json: JSON (JavaScript Object Notation)
csv: CSV (Comma Separated Values)
-e
Calculate extended statistics
-r
Use the raster map regions for univar statistical calculation instead of the current region
-u
Suppress printing of column names
--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
zones : str | np.ndarray, optional
Raster map used for zoning, must be of type CELL
Used as: input, raster, name
nprocs : int, optional
Number of threads for parallel computing
0: use OpenMP default; >0: use nprocs; <0: use MAX-nprocs
Default: 0
output : str, optional
Name for output file
Used as: output, file, name
percentile : float | list[float] | str, optional
Percentile to calculate (requires extended statistics flag)
Allowed values: 0-100
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
region_relation : str, optional
Process only maps with this spatial relation to the current computational region
Allowed values: overlaps, contains, is_contained
separator : str, optional
Field separator character between the output columns
Special characters: pipe, comma, space, tab, newline
Used as: input, separator, character
format : str, required
Output format
Used as: name
Allowed values: plain, json, csv
plain: Plain text output
json: JSON (JavaScript Object Notation)
csv: CSV (Comma Separated Values)
Default: plain
flags : str, optional
Allowed values: e, r, u
e
Calculate extended statistics
r
Use the raster map regions for univar statistical calculation instead of the current region
u
Suppress printing of column names
overwrite : bool, optional
Allow output files to overwrite existing files
Default: None
verbose : bool, optional
Verbose module output
Default: None
quiet : bool, optional
Quiet module output
Default: None
superquiet : bool, optional
Very quiet module output
Default: None
Returns:
result : grass.tools.support.ToolResult | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned.
Raises:
grass.tools.ToolError: When the tool ended with an error.
input : str, required
Name of the input space time raster dataset
Used as: input, strds, name
zones : str, optional
Raster map used for zoning, must be of type CELL
Used as: input, raster, name
nprocs : int, optional
Number of threads for parallel computing
0: use OpenMP default; >0: use nprocs; <0: use MAX-nprocs
Default: 0
output : str, optional
Name for output file
Used as: output, file, name
percentile : float | list[float] | str, optional
Percentile to calculate (requires extended statistics flag)
Allowed values: 0-100
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
region_relation : str, optional
Process only maps with this spatial relation to the current computational region
Allowed values: overlaps, contains, is_contained
separator : str, optional
Field separator character between the output columns
Special characters: pipe, comma, space, tab, newline
Used as: input, separator, character
format : str, required
Output format
Used as: name
Allowed values: plain, json, csv
plain: Plain text output
json: JSON (JavaScript Object Notation)
csv: CSV (Comma Separated Values)
Default: plain
flags : str, optional
Allowed values: e, r, u
e
Calculate extended statistics
r
Use the raster map regions for univar statistical calculation instead of the current region
u
Suppress printing of column names
overwrite : bool, optional
Allow output files to overwrite existing files
Default: None
verbose : bool, optional
Verbose module output
Default: None
quiet : bool, optional
Quiet module output
Default: None
superquiet : bool, optional
Very quiet module output
Default: None
DESCRIPTION
t.rast.univar calculates univariate statistics from the non-null cells for each registered raster map of a space time raster dataset.
By default it returns the name of the map, the semantic label of the map, the start and end date of the map and the following values: mean, minimum and maximum vale, mean_of_abs, standard deviation, variance, coeff_var, number of null cells, total number of cells.
Using the e flag it can calculate also extended statistics: first quartile, median value, third quartile and percentile 90.
If a zones raster map is provided, statistics are computed for each zone (category) in that input raster map. The zones option does not support space time raster datasets (STRDS) but only a single, static raster map.
Space time raster datasets may contain raster maps with varying spatial extent like for example series of scenes of satellite images. With the region_relation option, computations can be limited to maps of the space time raster dataset that have a given spatial relation to the current computational region. Supported spatial relations are:
- "overlaps": process only maps that spatially overlap ("intersect") with the current computational region
- "is_contained": process only maps that are fully within the current computational region
- "contains": process only maps that contain (fully cover) the current computational region
EXAMPLE
Obtain the univariate statistics for the raster space time dataset "tempmean_monthly" (precision reduced to 2 decimals in this example):
t.rast.univar -e input=nc_lst_daily
id|semantic_label|start|end|non_null_cells|null_cells|min|max|range|mean|mean_of_abs|stddev|variance|coeff_var|sum|sum_abs|first_quartile|median|third_quartile|percentile_90
aqua_lst_day20020705@modis2002lst||2002-07-05 00:00:00|2002-07-06 00:00:00|448428|390977|25.730000000000018|45.77000000000004|20.04000000000002|36.24265068193782|36.24265068193782|2.6171016196159838|6.849220887396605|7.221054670044495|16252219.360000012|16252219.360000012|34.49000000000001|36.07000000000005|37.83000000000004|40.01000000000005
aqua_lst_day20020706@modis2002lst||2002-07-06 00:00:00|2002-07-07 00:00:00|246658|592747|25.630000000000052|34.81|9.17999999999995|28.219656852808374|28.219656852808374|1.6350578714604542|2.6734142430247916|5.794038814819025|6960604.120000008|6960604.120000008|27.110000000000014|27.970000000000027|28.970000000000027|30.450000000000045
aqua_lst_day20020707@modis2002lst||2002-07-07 00:00:00|2002-07-08 00:00:00|714454|124951|25.630000000000052|44.670000000000016|19.039999999999964|32.642155464172674|32.642155464172674|3.1874224286049917|10.159661738374142|9.764742503305083|23321318.54000002|23321318.54000002|30.350000000000023|32.450000000000045|34.77000000000004|36.950000000000045
You can use format options as well to output the statistics in JSON, CSV or Plain (default) formats. For example, to get JSON output with extended statistics:
t.rast.univar -e input=nc_lst_daily format=json
[
{
"id": "aqua_lst_day20020705@modis2002lst",
"semantic_label": null,
"start": "2002-07-05 00:00:00",
"end": "2002-07-06 00:00:00",
"n": 448428,
"null_cells": 390977,
"cells": 839405,
"min": 25.730000000000018,
"max": 45.77000000000004,
"range": 20.04000000000002,
"mean": 36.24265068193782,
"mean_of_abs": 36.24265068193782,
"stddev": 2.6171016196159838,
"variance": 6.849220887396605,
"coeff_var": 7.221054670044495,
"sum": 16252219.360000012,
"first_quartile": 34.49000000000001,
"median": 36.07000000000005,
"third_quartile": 37.83000000000004,
"percentiles": [
{
"percentile": 90,
"value": 40.01000000000005
}
]
},
{
"id": "aqua_lst_day20020706@modis2002lst",
"semantic_label": null,
"start": "2002-07-06 00:00:00",
"end": "2002-07-07 00:00:00",
"n": 246658,
"null_cells": 592747,
"cells": 839405,
"min": 25.630000000000052,
"max": 34.81,
"range": 9.17999999999995,
"mean": 28.219656852808374,
"mean_of_abs": 28.219656852808374,
"stddev": 1.6350578714604542,
"variance": 2.6734142430247916,
"coeff_var": 5.794038814819025,
"sum": 6960604.120000008,
"first_quartile": 27.110000000000014,
"median": 27.970000000000027,
"third_quartile": 28.970000000000027,
"percentiles": [
{
"percentile": 90,
"value": 30.450000000000045
}
]
},
{
"id": "aqua_lst_day20020707@modis2002lst",
"semantic_label": null,
"start": "2002-07-07 00:00:00",
"end": "2002-07-08 00:00:00",
"n": 714454,
"null_cells": 124951,
"cells": 839405,
"min": 25.630000000000052,
"max": 44.670000000000016,
"range": 19.039999999999964,
"mean": 32.642155464172674,
"mean_of_abs": 32.642155464172674,
"stddev": 3.1874224286049917,
"variance": 10.159661738374142,
"coeff_var": 9.764742503305083,
"sum": 23321318.54000002,
"first_quartile": 30.350000000000023,
"median": 32.450000000000045,
"third_quartile": 34.77000000000004,
"percentiles": [
{
"percentile": 90,
"value": 36.950000000000045
}
]
},
...
]
SEE ALSO
AUTHOR
Sören Gebbert, Thünen Institute of Climate-Smart Agriculture
Stefan Blumentrath (support for zones, parallel processing, and spatial
relations)
SOURCE CODE
Available at: t.rast.univar source code
(history)
Latest change: Thursday Jun 18 10:00:27 2026 in commit 8f00822