v.univar - GRASS manual
Author: GRASS Development Team
Description: v.univar: Variance and standard deviation is calculated only for points if specified.
Keywords: vector, statistics, univariate statistics, attribute table, geometry

## NAME

v.univar - Calculates univariate statistics of vector map features.
Variance and standard deviation is calculated only for points if specified.

## KEYWORDS

vector, statistics, univariate statistics, attribute table, geometry

## SYNOPSIS

v.univar
v.univar --help
v.univar [-gewd] map=name [layer=string] [type=string[,string,...]] [column=name] [where=sql_query] [percentile=integer] format=name [--help] [--verbose] [--quiet] [--ui]

### Flags:

-g
  Print the stats in shell script style [deprecated]
  This flag is deprecated and will be removed in a future release. Use format=shell instead.
-e
  Calculate extended statistics
-w
  Weigh by line length or area size
-d
  Calculate geometric distances instead of attribute statistics
--help
  Print usage summary
--verbose
  Verbose module output
--quiet
  Quiet module output
--ui
  Force launching GUI dialog

### 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
type=string[,string,...]
  Input feature type
  Options: point, line, boundary, centroid, area
  Default: point,line,area
column=name
  Name of attribute column
where=sql_query
  WHERE conditions of SQL statement without 'where' keyword
  Example: income < 1000 and population >= 10000
percentile=integer
  Percentile to calculate (requires extended statistics flag)
  Options: 0-100
  Default: 90
format=name [required]
  Output format
  Options: plain, shell, json
  Default: plain
  plain: Human readable text output
  shell: shell script style text output
  json: JSON (JavaScript Object Notation)

## DESCRIPTION

v.univar calculates univariate statistics on (by default) an attribute of, or, through the -d flag on distance between, vector map features. Attributes are read per feature and per category value. This means that if the map contains several features with the same category value, the attribute is read as many times as there are features. On the other hand, if a feature has more than one category value, each attribute value linked to each of the category values of the feature is read. For statistics on one attribute per category value, instead of one attribute per feature and per category, see v.db.univar.

Extended statistics (-e) adds median, 1st and 3rd quartiles, and 90th percentile to the output.

## NOTES

When using the -d flag, univariate statistics of distances between vector features are calculated. The distances from all features to all other features are used. Since the distance from feature A to feature B is the same like the distance from feature B to feature A, that distance is considered only once, i.e. all pairwise distances between features are used. Depending on the selected vector type, distances are calculated as follows:

- type=point: point distances are considered;
- type=line: line to line distances are considered;
- type=area: not supported, use type=centroid instead (and see v.distance for calculating distances between areas)

## EXAMPLES

The examples are based on the North Carolina sample dataset.

### Example dataset preparation

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

### Calculate height attribute statistics

    v.univar -e samples column=heights type=point

    number of features with non NULL attribute: 100
    number of missing attributes: 0
    number of NULL attributes: 0
    minimum: 57.2799
    maximum: 148.903
    range: 91.6235
    sum: 10825.6
    mean: 108.256
    mean of absolute values: 108.256
    population standard deviation: 20.2572
    population variance: 410.356
    population coefficient of variation: 0.187123
    sample standard deviation: 20.3593
    sample variance: 414.501
    kurtosis: -0.856767
    skewness: 0.162093
    1st quartile: 90.531
    median (even number of cells): 106.518
    3rd quartile: 126.274
    90th percentile: 135.023

### Compare to statistics of original raster map

    r.univar -e elevation

    total null and non-null cells: 2025000
    total null cells: 0

    Of the non-null cells:
    ----------------------
    n: 2025000
    minimum: 55.5788
    maximum: 156.33
    range: 100.751
    mean: 110.375
    mean of absolute values: 110.375
    standard deviation: 20.3153
    variance: 412.712
    variation coefficient: 18.4057 %
    sum: 223510266.558102
    1st quartile: 94.79
    median (even number of cells): 108.88
    3rd quartile: 126.792
    90th percentile: 138.66

### Calculate statistic of distance between sampling points

    v.univar -d samples type=point

    number of primitives: 100
    number of non zero distances: 4851
    number of zero distances: 0
    minimum: 69.9038
    maximum: 18727.7
    range: 18657.8
    sum: 3.51907e+07
    mean: 7254.33
    mean of absolute values: 7254.33
    population standard deviation: 3468.53
    population variance: 1.20307e+07
    population coefficient of variation: 0.478132
    sample standard deviation: 3468.89
    sample variance: 1.20332e+07
    kurtosis: -0.605406
    skewness: 0.238688

### Output in JSON format

    v.univar -e samples column=heights type=point format=json

will output the results in JSON format:

    {
        "n": 1832,
        "missing": 0,
        "nnull": 0,
        "min": 166.946991,
        "max": 2729482.25,
        "range": 2729315.3030090001,
        "sum": 78876146.145385057,
        "mean": 43054.664926520229,
        "mean_abs": 43054.664926520229,
        "population_stddev": 132689.08650029532,
        "population_variance": 17606393676.282852,
        "population_coeff_variation": 3.0818747916573215,
        "sample_stddev": 132725.31560308655,
        "sample_variance": 17616009401.938931,
        "kurtosis": 139.15698418811229,
        "skewness": 9.7065048189730767,
        "first_quartile": 3699.3234859999998,
        "median": 10308.4453125,
        "third_quartile": 29259.074218999998,
        "percentiles": [
            {
                "percentile": 90,
                "value": 86449.734375
            }
        ]
    }

## SEE ALSO

db.univar, r.univar, v.db.univar, v.distance, v.neighbors, v.qcount

## AUTHORS

Radim Blazek, ITC-irst

extended by:
Hamish Bowman, University of Otago, New Zealand
Martin Landa

## SOURCE CODE

Available at: v.univar source code (history)

Latest change: Thursday Oct 02 14:39:13 2025 in commit: 1850489bf42c72d8dcfe2e4db1738441b4a7dc43

Main index | Vector index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.6.0dev Reference Manual