1v.vect.stats(1) GRASS GIS User's Manual v.vect.stats(1)
2
3
4
6 v.vect.stats - Count points in areas, calculate statistics from point
7 attributes.
8
10 vector, attribute table, database, univariate statistics, zonal statis‐
11 tics
12
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 ac‐
59 cess 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 ac‐
75 cess 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
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 at‐
114 tributes in points are calculated for each area. The results are either
115 uploaded to the attribute table of the vector map areas or printed to
116 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
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 in‐
171 put points vector map not being numeric, the module v.db.update can be
172 used to perform type casting, i.e. adding and populating an additional
173 numeric column with the values type converted from string attributes to
174 floating point numbers.
175
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 up‐
223 date of "avg_elev" column and counting of points per polygon, with up‐
224 date 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 re‐
235 gion. The extent is based on the vector map points_of_interest from the
236 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
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
271 Markus Metz
272
274 Available at: v.vect.stats source code (history)
275
276 Accessed: Mon Jun 20 16:47:19 2022
277
278 Main index | Vector index | Topics index | Keywords index | Graphical
279 index | Full index
280
281 © 2003-2022 GRASS Development Team, GRASS GIS 8.2.0 Reference Manual
282
283
284
285GRASS 8.2.0 v.vect.stats(1)