# v.vect.stats.1grass man page

**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*] [**areas_layer**=*string*] [**method**=*string*] [**points_column**=*name*] [**count_column**=*string*] [**stats_column**=*string*] [**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 input vector map

Name of existing vector map with points **areas**=*name***[required]**- Name of input vector map

Name of existing vector map with areas **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* **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* **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**=*string*- Column name to upload points count

Column to hold points count, must be of type integer, will be created if not existing **stats_column**=*string*- 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 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.

*Statistical Methods:* Using numeric attribute values of all points falling into a given area, a new value is detmined 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 existing. If they do already exist, the *count_column* must be of type integer and the *stats_column* of type double precision.

## 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
```

## See Also

*v.distance, r.distance, v.rast.stats, v.what.vect*

## Author

Markus Metz

*Last changed: $Date: 2015-01-01 13:07:46 +0100 (Thu, 01 Jan 2015) $*

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

© 2003-2016 GRASS Development Team, GRASS GIS 7.0.4 Reference Manual