v.vect.stats(1)

📦

version 8.4.2 · 8 versions

✨ v.vect.stats ✨

okay bestie, this is the GRASS GIS User's Manual page for v.vect.stats(1) and honestly? it's giving main character energy for anyone who's ever needed to count points inside polygons. sit down, grab a strawberry 🍓, let's go.

💖 NAME 💖

v.vect.stats — counts points in areas, and calculates statistics from point attributes. no cap, that's literally what it does.

🏷️ 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. and pssst, the first column is always the 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, plot twist, a data source for direct OGR access.
areas=name [required] — Name of existing vector map with areas. Or data source for direct OGR access too, bestie, same deal.
type=string[,string,...] — Feature type. This is the input feature type. Options are point and centroid. Default: point.
points_layer=string — Layer number for points map. fr fr, vector features can have category values in different layers, and 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,7-9,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. Same situation as the points layer: vector features can have category values in different layers, and 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,7-9,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. heads up: the column of the points map must be numeric.
count_column=name — Column name to upload points count. This column has to hold the points count, must be of type integer, and will be created if it's not already existing 🫶
stats_column=name — Column name to upload statistics. This one holds the statistics, must be of type double, and will be created if not existing.
separator=character — Field separator. Special characters: pipe, comma, space, tab, newline. Default: pipe.

💅 DESCRIPTION 💅

v.vect.stats counts the number of points in vector map points falling into each area in vector map areas. and optionally — because she's flexible like that — 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. pick your vibe ✨

📊 Statistical methods

So the way this works: 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 half-way 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.

📝 NOTES 📝

Points not falling into any area are ignored. Areas without category (no centroid attached, or a centroid without category) are ignored too, sorry girl 💀. 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, then count_column must be of type integer and stats_column of type double precision. that's the rule, periodt.

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. so if she's throwing a fit about types, that's your fix 🧚

🌈 EXAMPLES 🌈

🌱 Preparation for examples

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.

🔢 Count points per polygon with printed output

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

🧮 Count points per polygon with column update

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

📈 Average values of points in polygon with printed output

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

🎯 Average values of points in polygon with column update

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

⬡ Point statistics in a hexagonal grid

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.

v.mkgrid map=hexagons -h

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)

👀 SEE ALSO 👀

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.

👑 AUTHOR 👑

Markus Metz

💾 SOURCE CODE 💾

Available at: v.vect.stats source code (history)

Accessed: Saturday Jan 17 05:41:33 2026

okay that's the whole page bestie, and the tea is: this is GRASS 8.4.2, manual page v.vect.stats(1), accessed Saturday Jan 17 05:41:33 2026 🦋 go count some points, you're gonna slay 💖✨

📦 where this page comes from

fedora 44: grass 8.4.2-4.fc44 · GPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms