1r.univar(1) GRASS GIS User's Manual r.univar(1)
2
6 r.univar - Calculates univariate statistics from the non-null cells of
7 a raster map.
8 Statistics include number of cells counted, minimum and maximum cell
9 values, range, arithmetic mean, population variance, standard devia‐
10 tion, coefficient of variation, and sum.
11
13 raster, statistics, univariate statistics, zonal statistics, parallel
14
16 r.univar
17 r.univar --help
18 r.univar [-getr] map=name[,name,...] [zones=name] [output=name]
19 [percentile=float[,float,...]] [nprocs=integer] [separator=charac‐
20 ter] [--overwrite] [--help] [--verbose] [--quiet] [--ui]
21 Flags:
23 -g
24 Print the stats in shell script style
25 -e
27 Calculate extended statistics
28 -t
30 Table output format instead of standard output format
31 -r
33 Use the native resolution and extent of the raster map, instead of
34 the current region
35 --overwrite
37 Allow output files to overwrite existing files
38 --help
40 Print usage summary
41 --verbose
43 Verbose module output
44 --quiet
46 Quiet module output
47 --ui
49 Force launching GUI dialog
50 Parameters:
52 map=name[,name,...]Â [required]
53 Name of raster map(s)
54 zones=name
56 Raster map used for zoning, must be of type CELL
57 output=name
59 Name for output file (if omitted or "-" output to stdout)
60 percentile=float[,float,...]
62 Percentile to calculate (requires extended statistics flag)
63 Options: 0-100
64 Default: 90
65 nprocs=integer
67 Number of threads for parallel computing
68 Default: 1
69 separator=character
71 Field separator
72 Special characters: pipe, comma, space, tab, newline
73 Default: pipe
74
76 r.univar calculates the univariate statistics of one or several raster
77 map(s). This includes the number of cells counted, minimum and maximum
78 cell values, range, arithmetic mean, population variance, standard de‐
79 viation, coefficient of variation, and sum. Statistics are calculated
80 separately for every category/zone found in the zones input map if
81 given. If the -e extended statistics flag is given the 1st quartile,
82 median, 3rd quartile, and given percentile are calculated. If the -g
83 flag is given the results are presented in a format suitable for use in
84 a shell script. If the -t flag is given the results are presented in
85 tabular format with the given field separator. The table can immedi‐
86 ately be converted to a vector attribute table which can then be linked
87 to a vector, e.g. the vector that was rasterized to create the zones
88 input raster.
89 When multiple input maps are given to r.univar, the overall statistics
91 are calculated. This is useful for a time series of the same variable,
92 as well as for the case of a segmented/tiled dataset. Allowing multiple
93 raster maps to be specified saves the user from using a temporary
94 raster map for the result of r.series or r.patch.
95
97 As with most GRASS raster modules, r.univar operates on the raster ar‐
98 ray defined by the current region settings, not the original extent and
99 resolution of the input map. See g.region, but also the wiki page on
100 the computational region to understand the impact of the region set‐
101 tings on the calculations.
102 This module can use large amounts of system memory when the -e extended
104 statistics flag is used with a very large region setting. If the region
105 is too large the module should exit gracefully with a memory allocation
106 error. Basic statistics can be calculated using any size input region.
107 Extended statistics can be calculated using r.stats.quantile.
108 Without a zones input raster, the r.quantile module will be signifi‐
110 cantly more efficient for calculating percentiles with large maps.
111 For calculating univariate statistics from a raster map based on vector
113 polygon map and uploads statistics to new attribute columns, see
114 v.rast.stats.
115 PERFORMANCE
117 r.univar supports parallel processing using OpenMP. The user can spec‐
118 ify the number of threads to be used with the nprocs parameter. How‐
119 ever, parallelization is disabled when the -e extended statistics flag
120 is used.
121 Due to the differences in summation order, users may encounter small
123 floating points discrepancies when r.univar is run on very large raster
124 files when different nprocs parameters are used. However, since the
125 work allocation among threads is static, users should expect to have
126 the same results when run with the same number of threads.
127 Figure: Benchmark shows execution time for different number of cells
128 and cores. See benchmark scripts in source code.
129
131 Univariate statistics
132 In this example, the raster map elevation in the North Carolina sample
133 dataset is used to calculate univariate statistics:
134 g.region raster=elevation -p
135 # standard output, along with extended statistics
136 r.univar -e elevation percentile=98
137 total null and non-null cells: 2025000
138 total null cells: 0
139 Of the non-null cells:
140 ----------------------
141 n: 2025000
142 minimum: 55.5788
143 maximum: 156.33
144 range: 100.751
145 mean: 110.375
146 mean of absolute values: 110.375
147 standard deviation: 20.3153
148 variance: 412.712
149 variation coefficient: 18.4057 %
150 sum: 223510266.558102
151 1st quartile: 94.79
152 median (even number of cells): 108.88
153 3rd quartile: 126.792
154 98th percentile: 147.727
155 # script style output, along with extended statistics
156 r.univar -ge elevation percentile=98
157 n=2025000
158 null_cells=0
159 cells=2025000
160 min=55.5787925720215
161 max=156.329864501953
162 range=100.751071929932
163 mean=110.375440275606
164 mean_of_abs=110.375440275606
165 stddev=20.3153233205981
166 variance=412.712361620436
167 coeff_var=18.4056555243368
168 sum=223510266.558102
169 first_quartile=94.79
170 median=108.88
171 third_quartile=126.792
172 percentile_98=147.727
173 Zonal statistics
175 In this example, the raster polygon map basins in the North Carolina
176 sample dataset is used to calculate raster statistics for zones for el‐
177 evation raster map:
178 g.region raster=basins -p
179 This will set and print computational region in the format:
180 projection: 99 (Lambert Conformal Conic)
181 zone: 0
182 datum: nad83
183 ellipsoid: a=6378137 es=0.006694380022900787
184 north: 228500
185 south: 215000
186 west: 630000
187 east: 645000
188 nsres: 10
189 ewres: 10
190 rows: 1350
191 cols: 1500
192 cells: 2025000
193 Check basin’s IDs using:
194 r.category basins
195 This will print them in the format:
196 2
197 4
198 6
199 8
200 10
201 12
202 14
203 16
204 18
205 20
206 22
207 24
208 26
209 28
210 30
211 Visualization of them underlying elevation map can be created as:
212 d.mon wx0
213 d.rast map=elevation
214 r.colors map=elevation color=grey
215 d.rast map=basins
216 r.colors map=basins color=bgyr
217 d.legend raster=basins use=2,4,6,8,10,12,14,16,18,20,22,24,26,28,30
218 d.barscale
219 Figure: Zones (basins, opacity: 60%) with underlying elevation map for
220 North Carolina sample dataset.
221 Then statistics for elevation can be calculated separately for every
223 zone, i.e. basin found in the zones parameter:
224 r.univar -t map=elevation zones=basins separator=comma \
225 output=basin_elev_zonal.csv
226 This will print information in the format:
227 zone,label,non_null_cells,null_cells,min,max,range,mean,mean_of_abs,
228 stddev,variance,coeff_var,sum,sum_abs2,,116975,0,55.5787925720215,
229 133.147018432617,77.5682258605957,92.1196971445722,92.1196971445722,
230 15.1475301152556,229.447668592576,16.4433129773355,10775701.5734863,
231 10775701.57348634,,75480,0,61.7890930175781,110.348838806152,
232 48.5597457885742,83.7808205765268,83.7808205765268,11.6451777476995,
233 135.610164775515,13.8995747088232,6323776.33711624,6323776.33711624
234 6,,1137,0,66.9641571044922,83.2070922851562,16.2429351806641,
235 73.1900814395257,73.1900814395257,4.15733292896409,17.2834170822492,
236 5.68018623179036,83217.1225967407,83217.12259674078,,80506,
237 0,67.4670791625977,147.161514282227, ...
238 Comma Separated Values (CSV) file is best viewed through a spreadsheet
239 program such as Microsoft Excel, Libre/Open Office Calc or Google Docs:
240 Figure: Raster statistics for zones (basins, North Carolina sample
241 dataset) viewed through Libre/Open Office Calc.
242
244 To be implemented mode, skewness, kurtosis.
245
247 g.region, r3.univar, r.mode, r.quantile, r.series, r.stats,
248 r.stats.quantile, r.stats.zonal, r.statistics, v.rast.stats, v.univar
249
251 Hamish Bowman, Otago University, New Zealand
252 Extended statistics by Martin Landa
253 Multiple input map support by Ivan Shmakov
254 Zonal loop by Markus Metz
255
257 Available at: r.univar source code (history)
258 Accessed: Saturday Oct 28 18:18:10 2023
260 Main index | Raster index | Topics index | Keywords index | Graphical
262 index | Full index
263 © 2003-2023 GRASS Development Team, GRASS GIS 8.3.1 Reference Manual
265GRASS 8.3.1 r.univar(1)