Skip to content

v.db.univar

Calculates univariate statistics on selected table column for a GRASS vector map.

v.db.univar [-eg] map=name [layer=string] column=name [where=sql_query] [percentile=float [,float,...]] [format=string] [--verbose] [--quiet] [--qq] [--ui]

Example:

v.db.univar map=name column=name

grass.script.parse_command("v.db.univar", map, layer="1", column, where=None, percentile=90, format=None, flags=None, verbose=False, quiet=False, superquiet=False)

Example:

gs.parse_command("v.db.univar", map="name", column="name")

Parameters

map=name [required]
    Name of vector map
    Or data source for direct OGR access
layer=string
    Layer number or name
    Vector features can have category values in different layers. This number determines which layer to use. When used with direct OGR access this is the layer name.
    Default: 1
column=name [required]
    Name of attribute column on which to calculate statistics (must be numeric)
where=sql_query
    WHERE conditions of SQL statement without 'where' keyword
    Example: income < 1000 and population >= 10000
percentile=float [,float,...]
    Percentile to calculate (requires extended statistics flag)
    Allowed values: 0-100
    Default: 90
format=string
    Output format
    Allowed values: plain, json, shell
    plain: Plain text output
    json: JSON (JavaScript Object Notation)
    shell: Shell script style for Bash eval
-e
    Extended statistics (quartiles and 90th percentile)
-g
    Print stats in shell script style
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

map : str, required
    Name of vector map
    Or data source for direct OGR access
    Used as: input, vector, name
layer : str, optional
    Layer number or name
    Vector features can have category values in different layers. This number determines which layer to use. When used with direct OGR access this is the layer name.
    Used as: input, layer
    Default: 1
column : str, required
    Name of attribute column on which to calculate statistics (must be numeric)
    Used as: input, dbcolumn, name
where : str, optional
    WHERE conditions of SQL statement without 'where' keyword
    Example: income < 1000 and population >= 10000
    Used as: input, sql_query, sql_query
percentile : float | list[float] | str, optional
    Percentile to calculate (requires extended statistics flag)
    Allowed values: 0-100
    Default: 90
format : str, optional
    Output format
    Allowed values: plain, json, shell
    plain: Plain text output
    json: JSON (JavaScript Object Notation)
    shell: Shell script style for Bash eval
flags : str, optional
    Allowed values: e, g
    e
        Extended statistics (quartiles and 90th percentile)
    g
        Print stats in shell script style
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

v.db.univar calculates basic univariate statistics for numeric attributes in a vector attribute table. It will calculate minimum, maximum, range, mean, standard deviation, variance, coefficient of variation, quartiles, median, and 90th percentile.

v.db.univar uses db.univar which in turn uses db.select to get the attribute values on which it calculates the statistics. This means that statistics are calculated based on the entries in the attribute table, not based on the features in the map. One attribute value is read from each line in the attribute table, whether there are no, one or several features with the category value referenced by that line, or whether any features have more than one category value. For feature-based, instead of attribute table-based, univariate statistics on attributes see v.univar.

NOTES

A database connection must be defined for the selected vector layer.

EXAMPLES

Univariate statistics on attribute table column

In this example, the 30 years precipitation data table is statistically analysed (North Carolina sample dataset) and univariate statistics performed:

# show columns of attribute table connected to precipitation map
v.info -c precip_30ynormals

# univariate statistics on 30 years annual precipitation in NC
v.db.univar precip_30ynormals column=annual
 Number of values: 136
 Minimum: 947.42
 Maximum: 2329.18
 Range: 1381.76
 Mean: 1289.31147058823
 [...]

Univariate statistics on randomly sampled data points

In this example, random points are sampled from the elevation map (North Carolina sample dataset) and univariate statistics performed:

g.region raster=elevation -p
v.random output=samples n=100
v.db.addtable samples column="heights double precision"
v.what.rast samples raster=elevation column=heights
v.db.select samples

v.db.univar samples column=heights

JSON output

This uses the JSON output of the module which is passed using a pipe (in Bash or other unix-like shell) to the jq tool which selects just the relevant statistic.

v.db.univar precip_30ynormals column=annual format=json | jq .statistics.mean

SEE ALSO

db.univar, r.univar, v.univar, db.select, d.vect.thematic, v.random

GRASS SQL interface

AUTHORS

Michael Barton, Arizona State University

and authors of r.univar.sh (Markus Neteler et al.)

SOURCE CODE

Available at: v.db.univar source code (history)
Latest change: Monday Mar 10 19:11:25 2025 in commit 9137ecc