1r.series(1)                 GRASS GIS User's Manual                r.series(1)
2
3
4

NAME

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

KEYWORDS

10       raster, aggregation, series, parallel
11

SYNOPSIS

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

DESCRIPTION

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

NOTES

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

EXAMPLES

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

SEE ALSO

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

AUTHOR

293       Glynn Clements
294

SOURCE CODE

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)
Impressum