v.vect.stats(1grass) GRASS GIS User's Manual v.vect.stats(1grass)
NAME
v.vect.stats - Count points in areas, calculate statistics from point
attributes.
KEYWORDS
vector, attribute table, database, univariate statistics, zonal statis-
tics
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 ac-
cess 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
Vector features can have category values in different layers. This
number determines which layer to use. When used with direct OGR ac-
cess 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
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 cre-
ated 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
DESCRIPTION
v.vect.stats counts the number of points in vector map points falling
into each area in vector map areas. Optionally statistics on point at-
tributes 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.
Statistical methods
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 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 exist-
ing. 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 in-
put 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.
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 up-
date of "avg_elev" column and counting of points per polygon, with up-
date of "num_points" column (new columns will be automatically cre-
ated):
# 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 re-
gion. 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 sta-
tistics 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 computa-
tional region extent needs to be enlarged if all points should be con-
sidered). 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 val-
ues 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: unknown
Main index | Vector index | Topics index | Keywords index | Graphical
index | Full index
© 2003-2022 GRASS Development Team, GRASS GIS 7.8.7 Reference Manual
GRASS 7.8.7 v.vect.stats(1grass)
Generated by dwww version 1.14 on Sun Dec 29 19:29:18 CET 2024.