t.rast.univar.openmp - GRASS manual

NAME

t.rast.univar.openmp - Calculates univariate statistics from the non-null cells for each registered raster map of a space time raster dataset.
Single-process, OpenMP row-parallel alternative to t.rast.univar: each registered map is processed by one thread team instead of one r.univar subprocess. Only the sqlite temporal database driver and STRDS with absolute time are supported.

KEYWORDS

temporal, statistics, raster, time, parallel

SYNOPSIS

t.rast.univar.openmp

t.rast.univar.openmp --help

t.rast.univar.openmp [-eru] input=name [zones=name] [nprocs=integer] [output=name] [percentile=float[,float,...]] [where=sql_query] [separator=character] format=name [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-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
--ui: Force launching GUI dialog

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; Number of OpenMP threads used to process each map; Default: 0
output=name: Name for output file
percentile=float[,float,...]: Percentile to calculate (requires extended statistics flag); Options: 0-100; Default: 90
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'
separator=character: Field separator; Special characters: pipe, comma, space, tab, newline
format=name [required]: Output format; Options: plain, json, csv; Default: plain; plain: Plain text output; json: JSON (JavaScript Object Notation); csv: CSV (Comma Separated Values)

DESCRIPTION
LIMITATIONS
EXAMPLE
SEE ALSO
AUTHORS

DESCRIPTION

t.rast.univar.openmp calculates univariate statistics from the non-null cells for each registered raster map of a space time raster dataset. It computes the same statistics as t.rast.univar, but as a single compiled C program instead of a Python script that shells out to r.univar once per map.

t.rast.univar processes maps with a multiprocessing.Pool of nprocs worker processes, each running its own r.univar subprocess on one map at a time. t.rast.univar.openmp instead runs one process for the whole STRDS: it reads the list of registered maps directly from the temporal SQLite database (via GRASS's dbmi C library, bypassing grass.temporal), then processes maps one at a time, splitting each map's rows across nprocs OpenMP threads. The per-map statistics pass is adapted from r.univar's own C implementation, so the numbers it produces are the same, down to the same Kahan-summation approach for floating-point sums (small differences may appear in the last one or two significant digits between runs, or against t.rast.univar, because OpenMP threads can sum row groups in a different order each run; this is normal floating-point behavior, not a bug, and r.univar itself is subject to it too).

The two strategies favor different datasets, for the same reason as t.rast.univar.openmp's earlier Python-wrapper prototype:

Many maps, each small: t.rast.univar's multiprocessing usually wins, since whole maps are processed independently and concurrently.
Few maps, each large: t.rast.univar.openmp usually wins, since it avoids repeated subprocess and interpreter startup and lets all threads cooperate on a single map's rows.

Because maps are processed one at a time, the -r flag (use each map's own region instead of the current computational region) is fully supported: only one region is active at any time, so there is no risk of one thread reading a map under another map's region. -r and zones cannot be combined, the same restriction r.univar itself applies (the zoning raster is read once, under one fixed region, for all maps).

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 value, 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.

LIMITATIONS

This module reads the temporal database directly, in C, rather than through grass.temporal, which is normally the only interface to it. To keep that scope manageable, two things t.rast.univar supports are intentionally not supported here:

Only the sqlite temporal database driver is supported. STRDS connected through the PostgreSQL driver are rejected with an error; use t.rast.univar for those.
Only STRDS with absolute time are supported. STRDS with relative time are rejected with an error; use t.rast.univar for those.
The region_relation option (filtering registered maps by their spatial relation to the current region) is not available.

EXAMPLE

Obtain the univariate statistics for the raster space time dataset "nc_lst_daily", using up to 4 OpenMP threads per map:

t.rast.univar.openmp -e input=nc_lst_daily nprocs=4

AUTHORS

Yann Chemin; the per-map statistics pass is adapted from r.univar (Hamish Bowman, University of Otago, New Zealand; extended stats, Martin Landa; zonal stats, Markus Metz; OpenMP support, Soeren Gebbert and contributors).
t.rast.univar itself: 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.openmp source code (history)

Accessed: Sunday Sep 13 08:29:59 2026