---
name: t.rast.univar
description: "Calculates univariate statistics from the non-null cells for each registered raster map of a space time raster dataset."
keywords: [ temporal, statistics, raster, time, parallel ]
---

# t.rast.univar

Calculates univariate statistics from the non-null cells for each registered raster map of a space time raster dataset.

=== "Command line"

    **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:

    ```sh
    t.rast.univar input=name format=plain
    ```

=== "Python (grass.tools)"

    *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:

    ```python
    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.

=== "Python (grass.script)"

    *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:

    ```python
    gs.parse_command("t.rast.univar", input="name", format="json")
    ```

## Parameters

=== "Command line"

    **input**=*name* **[required]**  
    &nbsp;&nbsp;&nbsp;&nbsp;Name of the input space time raster dataset  
    **zones**=*name*  
    &nbsp;&nbsp;&nbsp;&nbsp;Raster map used for zoning, must be of type CELL  
    **nprocs**=*integer*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of threads for parallel computing  
    &nbsp;&nbsp;&nbsp;&nbsp;0: use OpenMP default; &gt;0: use nprocs; &lt;0: use MAX-nprocs  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *0*  
    **output**=*name*  
    &nbsp;&nbsp;&nbsp;&nbsp;Name for output file  
    **percentile**=*float* [,*float*,...]  
    &nbsp;&nbsp;&nbsp;&nbsp;Percentile to calculate (requires extended statistics flag)  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *0-100*  
    **where**=*sql_query*  
    &nbsp;&nbsp;&nbsp;&nbsp;WHERE conditions of SQL statement without 'where' keyword used in the temporal GIS framework  
    &nbsp;&nbsp;&nbsp;&nbsp;Example: start_time &gt; '2001-01-01 12:30:00'  
    **region_relation**=*string*  
    &nbsp;&nbsp;&nbsp;&nbsp;Process only maps with this spatial relation to the current computational region  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *overlaps, contains, is_contained*  
    **separator**=*character*  
    &nbsp;&nbsp;&nbsp;&nbsp;Field separator character between the output columns  
    &nbsp;&nbsp;&nbsp;&nbsp;Special characters: pipe, comma, space, tab, newline  
    **format**=*name* **[required]**  
    &nbsp;&nbsp;&nbsp;&nbsp;Output format  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *plain, json, csv*  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *plain*  
    &nbsp;&nbsp;&nbsp;&nbsp;**plain**: Plain text output  
    &nbsp;&nbsp;&nbsp;&nbsp;**json**: JSON (JavaScript Object Notation)  
    &nbsp;&nbsp;&nbsp;&nbsp;**csv**: CSV (Comma Separated Values)  
    **-e**  
    &nbsp;&nbsp;&nbsp;&nbsp;Calculate extended statistics  
    **-r**  
    &nbsp;&nbsp;&nbsp;&nbsp;Use the raster map regions for univar statistical calculation instead of the current region  
    **-u**  
    &nbsp;&nbsp;&nbsp;&nbsp;Suppress printing of column names  
    **--overwrite**  
    &nbsp;&nbsp;&nbsp;&nbsp;Allow output files to overwrite existing files  
    **--help**  
    &nbsp;&nbsp;&nbsp;&nbsp;Print usage summary  
    **--verbose**  
    &nbsp;&nbsp;&nbsp;&nbsp;Verbose module output  
    **--quiet**  
    &nbsp;&nbsp;&nbsp;&nbsp;Quiet module output  
    **--qq**  
    &nbsp;&nbsp;&nbsp;&nbsp;Very quiet module output  
    **--ui**  
    &nbsp;&nbsp;&nbsp;&nbsp;Force launching GUI dialog

=== "Python (grass.tools)"

    **input** : str, *required*  
    &nbsp;&nbsp;&nbsp;&nbsp;Name of the input space time raster dataset  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, strds, *name*  
    **zones** : str | np.ndarray, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Raster map used for zoning, must be of type CELL  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, raster, *name*  
    **nprocs** : int, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of threads for parallel computing  
    &nbsp;&nbsp;&nbsp;&nbsp;0: use OpenMP default; &gt;0: use nprocs; &lt;0: use MAX-nprocs  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *0*  
    **output** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Name for output file  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: output, file, *name*  
    **percentile** : float | list[float] | str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Percentile to calculate (requires extended statistics flag)  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *0-100*  
    **where** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;WHERE conditions of SQL statement without 'where' keyword used in the temporal GIS framework  
    &nbsp;&nbsp;&nbsp;&nbsp;Example: start_time &gt; '2001-01-01 12:30:00'  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *sql_query*  
    **region_relation** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Process only maps with this spatial relation to the current computational region  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *overlaps, contains, is_contained*  
    **separator** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Field separator character between the output columns  
    &nbsp;&nbsp;&nbsp;&nbsp;Special characters: pipe, comma, space, tab, newline  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, separator, *character*  
    **format** : str, *required*  
    &nbsp;&nbsp;&nbsp;&nbsp;Output format  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *name*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *plain, json, csv*  
    &nbsp;&nbsp;&nbsp;&nbsp;**plain**: Plain text output  
    &nbsp;&nbsp;&nbsp;&nbsp;**json**: JSON (JavaScript Object Notation)  
    &nbsp;&nbsp;&nbsp;&nbsp;**csv**: CSV (Comma Separated Values)  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *plain*  
    **flags** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *e*, *r*, *u*  
    &nbsp;&nbsp;&nbsp;&nbsp;**e**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Calculate extended statistics  
    &nbsp;&nbsp;&nbsp;&nbsp;**r**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Use the raster map regions for univar statistical calculation instead of the current region  
    &nbsp;&nbsp;&nbsp;&nbsp;**u**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Suppress printing of column names  
    **overwrite** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allow output files to overwrite existing files  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **verbose** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Verbose module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **quiet** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Quiet module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **superquiet** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Very quiet module output  
    &nbsp;&nbsp;&nbsp;&nbsp;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.

=== "Python (grass.script)"

    **input** : str, *required*  
    &nbsp;&nbsp;&nbsp;&nbsp;Name of the input space time raster dataset  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, strds, *name*  
    **zones** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Raster map used for zoning, must be of type CELL  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, raster, *name*  
    **nprocs** : int, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of threads for parallel computing  
    &nbsp;&nbsp;&nbsp;&nbsp;0: use OpenMP default; &gt;0: use nprocs; &lt;0: use MAX-nprocs  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *0*  
    **output** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Name for output file  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: output, file, *name*  
    **percentile** : float | list[float] | str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Percentile to calculate (requires extended statistics flag)  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *0-100*  
    **where** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;WHERE conditions of SQL statement without 'where' keyword used in the temporal GIS framework  
    &nbsp;&nbsp;&nbsp;&nbsp;Example: start_time &gt; '2001-01-01 12:30:00'  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *sql_query*  
    **region_relation** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Process only maps with this spatial relation to the current computational region  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *overlaps, contains, is_contained*  
    **separator** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Field separator character between the output columns  
    &nbsp;&nbsp;&nbsp;&nbsp;Special characters: pipe, comma, space, tab, newline  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, separator, *character*  
    **format** : str, *required*  
    &nbsp;&nbsp;&nbsp;&nbsp;Output format  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: *name*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *plain, json, csv*  
    &nbsp;&nbsp;&nbsp;&nbsp;**plain**: Plain text output  
    &nbsp;&nbsp;&nbsp;&nbsp;**json**: JSON (JavaScript Object Notation)  
    &nbsp;&nbsp;&nbsp;&nbsp;**csv**: CSV (Comma Separated Values)  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *plain*  
    **flags** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *e*, *r*, *u*  
    &nbsp;&nbsp;&nbsp;&nbsp;**e**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Calculate extended statistics  
    &nbsp;&nbsp;&nbsp;&nbsp;**r**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Use the raster map regions for univar statistical calculation instead of the current region  
    &nbsp;&nbsp;&nbsp;&nbsp;**u**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Suppress printing of column names  
    **overwrite** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allow output files to overwrite existing files  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **verbose** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Verbose module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **quiet** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Quiet module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **superquiet** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Very quiet module output  
    &nbsp;&nbsp;&nbsp;&nbsp;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):

```sh
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:

```sh
t.rast.univar -e input=nc_lst_daily format=json
```

```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

*[t.create](t.create.md), [t.info](t.info.md) [r.univar](r.univar.md),*

## 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](https://github.com/OSGeo/grass/tree/main/temporal/t.rast.univar)
([history](https://github.com/OSGeo/grass/commits/main/temporal/t.rast.univar))  
Latest change: Thursday Jun 18 10:00:27 2026 in commit [8f00822](https://github.com/OSGeo/grass/commit/8f00822fc974b415faca42889ae430a13a8e6cc7)
