1r.series(1) GRASS GIS User's Manual r.series(1)
2
3
4
6 r.series - Makes each output cell value a function of the values as‐
7 signed to the corresponding cells in the input raster map layers.
8
10 raster, aggregation, series, parallel
11
13 r.series
14 r.series --help
15 r.series [-nz] [input=name[,name,...]] [file=name] out‐
16 put=name[,name,...] method=string[,string,...] [quan‐
17 tile=float[,float,...]] [weights=float[,float,...]] [range=lo,hi]
18 [nprocs=integer] [memory=memory in MB] [--overwrite] [--help]
19 [--verbose] [--quiet] [--ui]
20
21 Flags:
22 -n
23 Propagate NULLs
24
25 -z
26 Do not keep files open
27
28 --overwrite
29 Allow output files to overwrite existing files
30
31 --help
32 Print usage summary
33
34 --verbose
35 Verbose module output
36
37 --quiet
38 Quiet module output
39
40 --ui
41 Force launching GUI dialog
42
43 Parameters:
44 input=name[,name,...]
45 Name of input raster map(s)
46
47 file=name
48 Input file with one raster map name and optional one weight per
49 line, field separator between name and weight is |
50
51 output=name[,name,...]Â [required]
52 Name for output raster map
53
54 method=string[,string,...]Â [required]
55 Aggregate operation
56 Options: average, count, median, mode, minimum, min_raster, maxi‐
57 mum, max_raster, stddev, range, sum, variance, diversity, slope,
58 offset, detcoeff, tvalue, quart1, quart3, perc90, quantile, skew‐
59 ness, kurtosis
60
61 quantile=float[,float,...]
62 Quantile to calculate for method=quantile
63 Options: 0.0-1.0
64
65 weights=float[,float,...]
66 Weighting factor for each input map, default value is 1.0 for each
67 input map
68
69 range=lo,hi
70 Ignore values outside this range
71
72 nprocs=integer
73 Number of threads for parallel computing
74 Default: 1
75
76 memory=memory in MB
77 Maximum memory to be used (in MB)
78 Cache size for raster rows
79 Default: 300
80
82 r.series makes each output cell value a function of the values assigned
83 to the corresponding cells in the input raster map layers.
84
85 Figure: Illustration for an average of three input rasters
86
87 Following methods are available:
88
89 • average: average value
90
91 • count: count of non-NULL cells
92
93 • median: median value
94
95 • mode: most frequently occurring value
96
97 • minimum: lowest value
98
99 • min_raster: raster map number with the minimum time-series
100 value
101
102 • maximum: highest value
103
104 • max_raster: raster map number with the maximum time-series
105 value
106
107 • stddev: standard deviation
108
109 • range: range of values (max - min)
110
111 • sum: sum of values
112
113 • variance: statistical variance
114
115 • diversity: number of different values
116
117 • slope: linear regression slope
118
119 • offset: linear regression offset
120
121 • detcoeff: linear regression coefficient of determination
122
123 • tvalue: linear regression t-value
124
125 • quart1: first quartile
126
127 • quart3: third quartile
128
129 • perc90: ninetieth percentile
130
131 • quantile: arbitrary quantile
132
133 • skewness: skewness
134
135 • kurtosis: kurtosis
136 Note that most parameters accept multiple answers, allowing multiple
137 aggregates to be computed in a single run, e.g.:
138
139 r.series input=map1,...,mapN \
140 output=map.mean,map.stddev \
141 method=average,stddev
142 or:
143
144 r.series input=map1,...,mapN \
145 output=map.p10,map.p50,map.p90 \
146 method=quantile,quantile,quantile \
147 quantile=0.1,0.5,0.9
148 The same number of values must be provided for all options.
149
151 No-data (NULL) handling
152 With -n flag, any cell for which any of the corresponding input cells
153 are NULL is automatically set to NULL (NULL propagation). The aggre‐
154 gate function is not called, so all methods behave this way with re‐
155 spect to the -n flag.
156
157 Without -n flag, the complete list of inputs for each cell (including
158 NULLs) is passed to the aggregate function. Individual aggregates can
159 handle data as they choose. Mostly, they just compute the aggregate
160 over the non-NULL values, producing a NULL result only if all inputs
161 are NULL.
162
163 Minimum and maximum analysis
164 The min_raster and max_raster methods generate a map with the number of
165 the raster map that holds the minimum/maximum value of the time-series.
166 The numbering starts at 0 up to n for the first and the last raster
167 listed in input=, respectively.
168
169 Range analysis
170 If the range= option is given, any values which fall outside that range
171 will be treated as if they were NULL. The range parameter can be set to
172 low,high thresholds: values outside of this range are treated as NULL
173 (i.e., they will be ignored by most aggregates, or will cause the re‐
174 sult to be NULL if -n is given). The low,high thresholds are floating
175 point, so use -inf or inf for a single threshold (e.g., range=0,inf to
176 ignore negative values, or range=-inf,-200.4 to ignore values above
177 -200.4).
178
179 Linear regression
180 Linear regression (slope, offset, coefficient of determination,
181 t-value) assumes equal time intervals. If the data have irregular time
182 intervals, NULL raster maps can be inserted into time series to make
183 time intervals equal (see example).
184
185 Quantiles
186 r.series can calculate arbitrary quantiles.
187
188 Memory consumption
189 Memory usage is not an issue, as r.series only needs to hold one row
190 from each map at a time.
191
192 Management of open file limits
193 The maximum number of raster maps that can be processed is given by the
194 user-specific limit of the operating system. For example, the soft lim‐
195 its for users are typically 1024 files. The soft limit can be changed
196 with e.g. ulimit -n 4096 (UNIX-based operating systems) but it cannot
197 be higher than the hard limit. If the latter is too low, you can as su‐
198 peruser add an entry in:
199 /etc/security/limits.conf
200 # <domain> <type> <item> <value>
201 your_username hard nofile 4096
202 This will raise the hard limit to 4096 files. Also have a look at the
203 overall limit of the operating system
204 cat /proc/sys/fs/file-max
205 which on modern Linux systems is several 100,000 files.
206
207 For each map a weighting factor can be specified using the weights op‐
208 tion. Using weights can be meaningful when computing the sum or average
209 of maps with different temporal extent. The default weight is 1.0. The
210 number of weights must be identical to the number of input maps and
211 must have the same order. Weights can also be specified in the input
212 file.
213
214 Use the -z flag to analyze large amounts of raster maps without hitting
215 open files limit and the file option to avoid hitting the size limit of
216 command line arguments. Note that the computation using the file op‐
217 tion is slower than with the input option. For every single row in the
218 output map(s) all input maps are opened and closed. The amount of RAM
219 will rise linearly with the number of specified input maps. The input
220 and file options are mutually exclusive: the former is a comma sepa‐
221 rated list of raster map names and the latter is a text file with a new
222 line separated list of raster map names and optional weights. As sepa‐
223 rator between the map name and the weight the character "|" must be
224 used.
225
226 Performance
227 To enable parallel processing, the user can specify the number of
228 threads to be used with the nprocs parameter (default 1). The memory
229 parameter (default 300 MB) can also be provided to determine the size
230 of the buffer in MB for computation.
231 Figure: Benchmark on the left shows execution time for different number
232 of cells, benchmark on the right shows execution time for different
233 memory size for 10000x10000 raster. See benchmark scripts in source
234 code. (Intel Core i9-10940X CPU @ 3.30GHz x 28)
235
236 To reduce the memory requirements to minimum, set option memory to
237 zero. To take advantage of the parallelization, GRASS GIS needs to
238 compiled with OpenMP enabled.
239
241 Using r.series with wildcards:
242 r.series input="`g.list pattern=’insitu_data.*’ sep=,`" \
243 output=insitu_data.stddev method=stddev
244
245 Note the g.list script also supports regular expressions for selecting
246 map names.
247
248 Using r.series with NULL raster maps (in order to consider a "complete"
249 time series):
250 r.mapcalc "dummy = null()"
251 r.series in=map2001,map2002,dummy,dummy,map2005,map2006,dummy,map2008 \
252 out=res_slope,res_offset,res_coeff meth=slope,offset,detcoeff
253
254 Example for multiple aggregates to be computed in one run (3 resulting
255 aggregates from two input maps):
256 r.series in=one,two out=result_avg,res_slope,result_count meth=sum,slope,count
257
258 Example to use the file option of r.series:
259 cat > input.txt << EOF
260 map1
261 map2
262 map3
263 EOF
264 r.series file=input.txt out=result_sum meth=sum
265
266 Example to use the file option of r.series including weights. The
267 weight 0.75 should be assigned to map2. As the other maps do not have
268 weights we can leave it out:
269 cat > input.txt << EOF
270 map1
271 map2|0.75
272 map3
273 EOF
274 r.series file=input.txt out=result_sum meth=sum
275
276 Example for counting the number of days above a certain temperature us‐
277 ing daily average maps (’???’ as DOY wildcard):
278 # Approach for shell based systems
279 r.series input=`g.list rast pattern="temp_2003_???_avg" separator=comma` \
280 output=temp_2003_days_over_25deg range=25.0,100.0 method=count
281 # Approach in two steps (e.g., for Windows systems)
282 g.list rast pattern="temp_2003_???_avg" output=mapnames.txt
283 r.series file=mapnames.txt \
284 output=temp_2003_days_over_25deg range=25.0,100.0 method=count
285
287 g.list, g.region, r.quantile, r.series.accumulate, r.series.interp,
288 r.univar
289
290 Hints for large raster data processing
291
293 Glynn Clements
294
296 Available at: r.series source code (history)
297
298 Accessed: Mon Jun 20 16:46:25 2022
299
300 Main index | Raster index | Topics index | Keywords index | Graphical
301 index | Full index
302
303 © 2003-2022 GRASS Development Team, GRASS GIS 8.2.0 Reference Manual
304
305
306
307GRASS 8.2.0 r.series(1)