1v.vect.stats(1)             GRASS GIS User's Manual            v.vect.stats(1)
2
3
4

NAME

6       v.vect.stats   - Count points in areas, calculate statistics from point
7       attributes.
8

KEYWORDS

10       vector, attribute table, database, univariate statistics, zonal statis‐
11       tics
12

SYNOPSIS

14       v.vect.stats
15       v.vect.stats --help
16       v.vect.stats  [-p]  points=name  areas=name  [type=string[,string,...]]
17       [points_layer=string]   [points_cats=range]    [points_where=sql_query]
18       [areas_layer=string]     [areas_cats=range]     [areas_where=sql_query]
19       [method=string]        [points_column=name]         [count_column=name]
20       [stats_column=name]     [separator=character]    [--help]   [--verbose]
21       [--quiet]  [--ui]
22
23   Flags:
24       -p
25           Print output to stdout, do not update attribute table
26           First column is always area category
27
28       --help
29           Print usage summary
30
31       --verbose
32           Verbose module output
33
34       --quiet
35           Quiet module output
36
37       --ui
38           Force launching GUI dialog
39
40   Parameters:
41       points=name [required]
42           Name of existing vector map with points
43           Or data source for direct OGR access
44
45       areas=name [required]
46           Name of existing vector map with areas
47           Or data source for direct OGR access
48
49       type=string[,string,...]
50           Feature type
51           Input feature type
52           Options: point, centroid
53           Default: point
54
55       points_layer=string
56           Layer number for points map
57           Vector features can have category values in different layers.  This
58           number  determines  which  layer  to use. When used with direct OGR
59           access this is the layer name.
60           Default: 1
61
62       points_cats=range
63           Category values for points map
64           Example: 1,3,7-9,13
65
66       points_where=sql_query
67           WHERE conditions of  SQL  statement  without  ’where’  keyword  for
68           points map
69           Example: income < 1000 and population >= 10000
70
71       areas_layer=string
72           Layer number for area map
73           Vector  features can have category values in different layers. This
74           number determines which layer to use. When  used  with  direct  OGR
75           access this is the layer name.
76           Default: 1
77
78       areas_cats=range
79           Category values for area map
80           Example: 1,3,7-9,13
81
82       areas_where=sql_query
83           WHERE  conditions of SQL statement without ’where’ keyword for area
84           map
85           Example: income < 1000 and population >= 10000
86
87       method=string
88           Method for aggregate statistics
89           Options: sum, average, median,  mode,  minimum,  min_cat,  maximum,
90           max_cat, range, stddev, variance, diversity
91
92       points_column=name
93           Column name of points map to use for statistics
94           Column of points map must be numeric
95
96       count_column=name
97           Column name to upload points count
98           Column  to hold points count, must be of type integer, will be cre‐
99           ated if not existing
100
101       stats_column=name
102           Column name to upload statistics
103           Column to hold statistics, must be of type double, will be  created
104           if not existing
105
106       separator=character
107           Field separator
108           Special characters: pipe, comma, space, tab, newline
109           Default: pipe
110

DESCRIPTION

112       v.vect.stats  counts  the number of points in vector map points falling
113       into each area in vector map areas.   Optionally  statistics  on  point
114       attributes  in  points  are  calculated  for each area. The results are
115       either uploaded to the attribute table  of  the  vector  map  areas  or
116       printed to stdout.
117
118   Statistical methods
119       Using numeric attribute values of all points falling into a given area,
120       a new value is determined with the selected method.   v.vect.stats  can
121       perform the following operations:
122
123       sum
124           The sum of values.
125
126       average
127           The average value of all point attributes (sum / count).
128
129       median
130           The  value  found  half-way through a list of the attribute values,
131           when these are ranged in numerical order.
132
133       mode
134           The most frequently occurring value.
135
136       minimum
137           The minimum observed value.
138
139       min_cat
140           The point category corresponding to the minimum observed value.
141
142       maximum
143           The maximum observed value.
144
145       max_cat
146           The point category corresponding to the maximum observed value.
147
148       range
149           The range of the observed values.
150
151       stddev
152           The statistical standard deviation of the attribute values.
153
154       variance
155           The statistical variance of the attribute values.
156
157       diversity
158           The number of different attribute values.
159

NOTES

161       Points not falling into any area are ignored.  Areas  without  category
162       (no centroid attached or centroid without category) are ignored.  If no
163       points are falling into a given area, the  point  count  is  set  to  0
164       (zero) and the statistics result to "null".
165
166       The columns count_column and stats_column are created if not yet exist‐
167       ing. If they do already exist, the count_column must be of type integer
168       and the stats_column of type double precision.
169
170       In  case  that  v.vect.stats  complains  about the points_column of the
171       input points vector map not being numeric, the module  v.db.update  can
172       be  used  to  perform type casting, i.e. adding and populating an addi‐
173       tional numeric column  with  the  values  type  converted  from  string
174       attributes to floating point numbers.
175

EXAMPLES

177   Preparation for examples
178       The  subsequent  examples  are based on randomly sampled elevation data
179       (North Carolina sample database):
180       # work on map copy for attribute editing
181       g.copy vector=zipcodes_wake,myzipcodes_wake
182       # set computational region: extent of ZIP code map, raster pixels
183       # aligned to raster map
184       g.region vector=myzipcodes_wake align=elev_state_500m -p
185       #  generate random elevation points
186       r.random elev_state_500m vector=rand5000 n=5000
187       v.colors rand5000 color=elevation
188       # visualization
189       d.mon wx0
190       d.vect myzipcodes_wake -c
191       d.vect rand5000
192       These vector maps are used for the examples below.
193
194   Count points per polygon with printed output
195       See above for the creation of the input maps.
196
197       Counting points per polygon, print results to terminal:
198       v.vect.stats points=rand5000 area=myzipcodes_wake -p
199
200   Count points per polygon with column update
201       See above for the creation of the input maps.
202
203       Counting of points per polygon,  with  update  of  "num_points"  column
204       (will be automatically created):
205       v.vect.stats points=rand5000 area=myzipcodes_wake count_column=num_points
206       # verify result
207       v.db.select myzipcodes_wake column=ZIPCODE_,ZIPNAME,num_points
208
209   Average values of points in polygon with printed output
210       See above for the creation of the input maps.
211
212       Calculation of average point elevation per ZIP code polygon, printed to
213       terminal in comma separated style:
214       # check name of point map column:
215       v.info -c rand5000
216       v.vect.stats points=rand5000 area=myzipcodes_wake \
217         method=average points_column=value separator=comma -p
218
219   Average values of points in polygon with column update
220       See above for the creation of the input maps.
221
222       Calculation of average point  elevation  per  ZIP  code  polygon,  with
223       update  of  "avg_elev"  column and counting of points per polygon, with
224       update of "num_points" column (new columns will be  automatically  cre‐
225       ated):
226       # check name of point map column:
227       v.info -c rand5000
228       v.vect.stats points=rand5000 area=myzipcodes_wake count_column=num_points \
229         method=average points_column=value stats_column=avg_elev
230       # verify result
231       v.db.select myzipcodes_wake column=ZIPCODE_,ZIPNAME,avg_elev
232
233   Point statistics in a hexagonal grid
234       The  grid  extent  and  size is influenced by the current computational
235       region. The extent is based on the vector map  points_of_interest  from
236       the basic North Carolina sample dataset.
237       g.region vector=points_of_interest res=2000 -pa
238       The hexagonal grid is created using the v.mkgrid module as a vector map
239       based on the previously selected extent and size of the grid.
240       v.mkgrid map=hexagons -h
241       The v.vect.stats module counts the number of points and does  one  sta‐
242       tistics on a selected column (here: elev_m).
243       v.vect.stats points=points_of_interest areas=hexagons method=average \
244         points_column=elev_m count_column=count stats_column=average
245       User  should note that some of the points may be outside the grid since
246       the hexagons cannot cover all the area around the edges  (the  computa‐
247       tional  region extent needs to be enlarged if all points should be con‐
248       sidered).  The last command sets the vector map color table to  viridis
249       based on the count column.
250       v.colors map=hexagons use=attr column=average color=viridis
251       Point  statistics in a hexagonal grid (count of points, average of val‐
252       ues associated with point, standard deviation)
253

SEE ALSO

255           ·   v.rast.stats for zonal statistics of raster maps  using  vector
256               zones (univariate statistics of a raster map),
257
258           ·   r.stats.zonal  for  zonal statistics of raster map using raster
259               zones (univariate statistics using two raster maps),
260
261           ·   v.what.vect for querying one vector map by another,
262
263           ·   v.distance for finding nearest features,
264
265           ·   r.distance for computing distances between  objects  in  raster
266               maps,
267
268           ·   v.mkgrid for creating vector grids to aggregate point data.
269

AUTHOR

271       Markus Metz
272

SOURCE CODE

274       Available at: v.vect.stats source code (history)
275
276       Main  index  | Vector index | Topics index | Keywords index | Graphical
277       index | Full index
278
279       © 2003-2020 GRASS Development Team, GRASS GIS 7.8.5 Reference Manual
280
281
282
283GRASS 7.8.5                                                    v.vect.stats(1)
Impressum