NAME
v.vect.stats  Count points in areas, calculate statistics from point attributes.
KEYWORDS
vector,
attribute table,
database,
univariate statistics,
zonal statistics
SYNOPSIS
v.vect.stats
v.vect.stats help
v.vect.stats [p] points=name areas=name [type=string[,string,...]] [points_layer=string] [points_cats=range] [points_where=sql_query] [areas_layer=string] [areas_cats=range] [areas_where=sql_query] [method=string] [points_column=name] [count_column=name] [stats_column=name] [separator=character] [help] [verbose] [quiet] [ui]
Flags:
 p
 Print output to stdout, do not update attribute table
 First column is always area category
 help
 Print usage summary
 verbose
 Verbose module output
 quiet
 Quiet module output
 ui
 Force launching GUI dialog
Parameters:
 points=name [required]
 Name of existing vector map with points
 Or data source for direct OGR access
 areas=name [required]
 Name of existing vector map with areas
 Or data source for direct OGR access
 type=string[,string,...]
 Feature type
 Input feature type
 Options: point, centroid
 Default: point
 points_layer=string
 Layer number for points map
 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
 points_cats=range
 Category values for points map
 Example: 1,3,79,13
 points_where=sql_query
 WHERE conditions of SQL statement without 'where' keyword for points map
 Example: income < 1000 and population >= 10000
 areas_layer=string
 Layer number for area map
 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
 areas_cats=range
 Category values for area map
 Example: 1,3,79,13
 areas_where=sql_query
 WHERE conditions of SQL statement without 'where' keyword for area map
 Example: income < 1000 and population >= 10000
 method=string
 Method for aggregate statistics
 Options: sum, average, median, mode, minimum, min_cat, maximum, max_cat, range, stddev, variance, diversity
 points_column=name
 Column name of points map to use for statistics
 Column of points map must be numeric
 count_column=name
 Column name to upload points count
 Column to hold points count, must be of type integer, will be created if not existing
 stats_column=name
 Column name to upload statistics
 Column to hold statistics, must be of type double, will be created if not existing
 separator=character
 Field separator
 Special characters: pipe, comma, space, tab, newline
 Default: pipe
v.vect.stats counts the number of points in vector map
points falling into each area in vector map
areas.
Optionally statistics on point attributes in
points are
calculated for each area. The results are either uploaded to the
attribute table of the vector map
areas or printed to stdout.
Using numeric attribute values of all points falling into a given area,
a new value is determined with the selected method.
v.vect.stats can perform the following operations:
 sum
 The sum of values.
 average
 The average value of all point attributes (sum / count).
 median
 The value found halfway through a list of the
attribute values, when these are ranged in numerical order.
 mode
 The most frequently occurring value.
 minimum
 The minimum observed value.
 min_cat
 The point category corresponding to the minimum observed value.
 maximum
 The maximum observed value.
 max_cat
 The point category corresponding to the maximum observed value.
 range
 The range of the observed values.
 stddev
 The statistical standard deviation of the attribute values.
 variance
 The statistical variance of the attribute values.
 diversity
 The number of different attribute values.
Points not falling into any area are ignored. Areas without category
(no centroid attached or centroid without category) are ignored.
If no points are falling into a given area, the point count is set to 0
(zero) and the statistics result to "null".
The columns count_column and stats_column are created if not
yet existing. If they do already exist, the count_column must be of
type integer and the stats_column of type double precision.
In case that v.vect.stats complains about the points_column
of the input points vector map not being numeric, the module
v.db.update can be used to perform type casting, i.e. adding and
populating an additional numeric column with the values type converted from
string attributes to floating point numbers.
The subsequent examples are based on randomly sampled
elevation data (North Carolina sample database):
# work on map copy for attribute editing
g.copy vector=zipcodes_wake,myzipcodes_wake
# set computational region: extent of ZIP code map, raster pixels
# aligned to raster map
g.region vector=myzipcodes_wake align=elev_state_500m p
# generate random elevation points
r.random elev_state_500m vector=rand5000 n=5000
v.colors rand5000 color=elevation
# visualization
d.mon wx0
d.vect myzipcodes_wake c
d.vect rand5000
These vector maps are used for the examples below.
See above for the creation of the input maps.
Counting points per polygon, print results to terminal:
v.vect.stats points=rand5000 area=myzipcodes_wake p
See above for the creation of the input maps.
Counting of points per polygon, with update of "num_points" column
(will be automatically created):
v.vect.stats points=rand5000 area=myzipcodes_wake count_column=num_points
# verify result
v.db.select myzipcodes_wake column=ZIPCODE_,ZIPNAME,num_points
See above for the creation of the input maps.
Calculation of average point elevation per ZIP code
polygon, printed to terminal in comma separated style:
# check name of point map column:
v.info c rand5000
v.vect.stats points=rand5000 area=myzipcodes_wake \
method=average points_column=value separator=comma p
See above for the creation of the input maps.
Calculation of average point elevation per ZIP code polygon,
with update of "avg_elev" column and counting of points per polygon,
with update of "num_points" column (new columns will be automatically
created):
# check name of point map column:
v.info c rand5000
v.vect.stats points=rand5000 area=myzipcodes_wake count_column=num_points \
method=average points_column=value stats_column=avg_elev
# verify result
v.db.select myzipcodes_wake column=ZIPCODE_,ZIPNAME,avg_elev
The grid extent and size is influenced by the current computational
region. The extent is based on the vector map
points_of_interest from the basic North Carolina sample dataset.
g.region vector=points_of_interest res=2000 pa
The hexagonal grid is created using
the
v.mkgrid module
as a vector map based on the previously
selected extent and size of the grid.
The
v.vect.stats module
counts the number of points and does one statistics on a selected
column (here:
elev_m).
v.vect.stats points=points_of_interest areas=hexagons method=average \
points_column=elev_m count_column=count stats_column=average
User should note that some of the points may be outside the grid
since the hexagons cannot cover all the area around the edges
(the computational region extent needs to be enlarged if all points
should be considered).
The last command sets the vector map color table to
viridis
based on the
count
column.
v.colors map=hexagons use=attr column=average color=viridis
Point statistics in a hexagonal grid (count of points, average of values
associated with point, standard deviation)

v.rast.stats
for zonal statistics of raster maps using vector zones
(univariate statistics of a raster map),

r.stats.zonal
for zonal statistics of raster map using raster zones
(univariate statistics using two raster maps),

v.what.vect
for querying one vector map by another,

v.distance
for finding nearest features,

r.distance
for computing distances between objects in raster maps,

v.mkgrid
for creating vector grids to aggregate point data.
Markus Metz
SOURCE CODE
Available at:
v.vect.stats source code
(history)
Main index 
Vector index 
Topics index 
Keywords index 
Graphical index 
Full index
© 20032021
GRASS Development Team,
GRASS GIS 7.9.dev Reference Manual