1t.rast.mapcalc(1) GRASS GIS User's Manual t.rast.mapcalc(1)
2
6 t.rast.mapcalc - Performs spatio-temporal mapcalc expressions on tem‐
7 porally sampled maps of space time raster datasets.
8
10 temporal, algebra, raster, time
11
13 t.rast.mapcalc
14 t.rast.mapcalc --help
15 t.rast.mapcalc [-ns] inputs=name[,name,...] expression=string
16 [method=name[,name,...]] output=name basename=basename [nprocs=inte‐
17 ger] [--overwrite] [--help] [--verbose] [--quiet] [--ui]
18 Flags:
20 -n
21 Register Null maps
22 -s
24 Check the spatial topology of temporally related maps and process
25 only spatially related maps
26 --overwrite
28 Allow output files to overwrite existing files
29 --help
31 Print usage summary
32 --verbose
34 Verbose module output
35 --quiet
37 Quiet module output
38 --ui
40 Force launching GUI dialog
41 Parameters:
43 inputs=name[,name,...]Â [required]
44 Name of the input space time raster datasets
45 expression=string [required]
47 Spatio-temporal mapcalc expression
48 method=name[,name,...]
50 The method to be used for sampling the input dataset
51 Options: start, during, overlap, contain, equal, follows, precedes
52 Default: equal
53 output=name [required]
55 Name of the output space time raster dataset
56 basename=basename [required]
58 Basename for output raster maps
59 A numerical suffix separated by an underscore will be attached to
60 create a unique identifier
61 nprocs=integer
63 Number of r.mapcalc processes to run in parallel
64 Default: 1
65
67 t.rast.mapcalc performs spatio-temporal mapcalc expressions on maps of
68 temporally sampled space time raster datasets (STRDS). Spatial and tem‐
69 poral operators and internal variables are available in the expression
70 string. The description of the spatial operators, functions and inter‐
71 nal variables is available in the r.mapcalc manual page. The temporal
72 functions are described in detail below.
73 This module expects several parameters. All space time raster datasets
75 that are referenced in the mapcalc expression must be listed in the in‐
76 puts option. The first space time raster dataset that is listed as in‐
77 put will be used to temporally sample all other space time raster
78 datasets. The temporal sampling method can be chosen using the method
79 option. The order of the STRDS’s in the mapcalc expression can be dif‐
80 ferent to the order of the STRDS’s in the input option. The resulting
81 space time raster dataset must be specified in the output option to‐
82 gether with the basename of generated raster maps that are registered
83 in the resulting STRDS. Empty maps resulting from map-calculation are
84 not registered by default. This behavior can be changed with the -n
85 flag. The flag -s can be used to assure that only spatially related
86 maps in the STRDS’s are processed. Spatially related means that tempo‐
87 rally related maps overlap in their spatial extent.
88 The module t.rast.mapcalc supports parallel processing. The option
90 nprocs specifies the number of processes that can be started in paral‐
91 lel.
92 A mapcalc expression must be provided to process the temporal sampled
94 maps. Temporal internal variables are available in addition to the
95 r.mapcalc spatial operators and functions:
96 The supported internal variables for relative and absolute time are:
98 • td() - This internal variable represents the size of the cur‐
100 rent sample time interval in days and fraction of days for ab‐
101 solute time, and in relative units in case of relative time.
102 • start_time() - This internal variable represents the time dif‐
104 ference between the start time of the sample space time raster
105 dataset and the start time of the current sample interval or
106 instance. The time is measured in days and fraction of days
107 for absolute time, and in relative units in case of relative
108 time.
109 • end_time() - This internal variable represents the time differ‐
111 ence between the start time of the sample space time raster
112 dataset and the end time of the current sample interval. The
113 time is measured in days and fraction of days for absolute
114 time, and in relative units in case of relative time. The
115 end_time() will be represented by null() in case of a time in‐
116 stance.
117 The supported internal variables for the current sample interval or in‐
119 stance for absolute time are:
120 • start_doy() - Day of year (doy) from the start time [1 - 366]
122 • start_dow() - Day of week (dow) from the start time [1 - 7],
124 the start of the week is Monday == 1
125 • start_year() - The year of the start time [0 - 9999]
127 • start_month() - The month of the start time [1 - 12]
129 • start_week() - Week of year of the start time [1 - 54]
131 • start_day() - Day of month from the start time [1 - 31]
133 • start_hour() - The hour of the start time [0 - 23]
135 • start_minute() - The minute of the start time [0 - 59]
137 • start_second() - The second of the start time [0 - 59]
139 • end_doy() - Day of year (doy) from the end time [1 - 366]
141 • end_dow() - Day of week (dow) from the end time [1 - 7], the
143 start of the week is Monday == 1
144 • end_year() - The year of the end time [0 - 9999]
146 • end_month() - The month of the end time [1 - 12]
148 • end_woy() - Week of year (woy) of the end time [1 - 54]
150 • end_day() - Day of month from the start time [1 - 31]
152 • end_hour() - The hour of the end time [0 - 23]
154 • end_minute() - The minute of the end time [0 - 59]
156 • end_second() - The second of the end time [0 - 59].
158 The end_* functions are represented by the null() internal variable in
159 case of time instances.
160
162 We will discuss the internal work of t.rast.mapcalc with an example.
163 Imagine we have two STRDS as input, each one of monthly granularity.
164 The first one A has 6 raster maps (a3 ... a8) with a temporal range
165 from March to August. The second STRDS B has 12 raster maps (b1 ...
166 b12) ranging from January to December. The value of the raster maps is
167 the number of the month from their interval start time. Dataset A will
168 be used to sample dataset B to create a dataset C. We want to add all
169 maps with equal time stamps if the month of the start time is May or
170 June, otherwise we multiply the maps. The command will look as follows:
171 t.rast.mapcalc input=A,B output=C basename=c method=equal \
173 expression="if(start_month() == 5 || start_month() == 6, (A + B), (A * B))"
174 The resulting raster maps in dataset C can be listed with t.rast.list:
176 name start_time min max
178 c_1 2001-03-01 00:00:00 9.0 9.0
179 c_2 2001-04-01 00:00:00 16.0 16.0
180 c_3 2001-05-01 00:00:00 10.0 10.0
181 c_4 2001-06-01 00:00:00 12.0 12.0
182 c_5 2001-07-01 00:00:00 49.0 49.0
183 c_6 2001-08-01 00:00:00 64.0 64.0
184 Internally the spatio-temporal expression will be analyzed for each
186 time interval of the sample dataset A, the temporal functions will be
187 replaced by numerical values, the names of the space time raster
188 datasets will be replaced by the corresponding raster maps. The final
189 expression will be passed to r.mapcalc, resulting in 6 runs:
190 r.mapcalc expression="c_1 = if(3 == 5 || 3 == 6, (a3 + b3), (a3 * b3))"
192 r.mapcalc expression="c_2 = if(4 == 5 || 4 == 6, (a4 + b4), (a4 * b4))"
193 r.mapcalc expression="c_3 = if(5 == 5 || 5 == 6, (a5 + b5), (a5 * b5))"
194 r.mapcalc expression="c_4 = if(6 == 5 || 6 == 6, (a6 + b6), (a6 * b6))"
195 r.mapcalc expression="c_5 = if(7 == 5 || 7 == 6, (a7 + b7), (a7 * b7))"
196 r.mapcalc expression="c_6 = if(8 == 5 || 8 == 6, (a8 + b8), (a8 * b8))"
197 Semantic labels present in the sample dataset A will be transferred to
199 the output dataset.
200
202 The following command creates a new space time raster dataset janu‐
203 ary_under_0 that will set to null all cells with temperature above zero
204 in the January maps while keeping all the rest as in the original time
205 series. This will change the maximum values of all January maps in the
206 new STRDS as compared to the original one, tempmean_monthly.
207 t.rast.mapcalc input=tempmean_monthly output=january_under_0 basename=january_under_0 \
208 expression="if(start_month() == 1 && tempmean_monthly > 0, null(), tempmean_monthly)"
209 # print minimum and maximum only for January in the new strds
210 t.rast.list january_under_0 columns=name,start_time,min,max | grep 01-01
211 name|start_time|min|max
212 january_under_0_01|2009-01-01 00:00:00|-3.380823|-7e-06
213 january_under_0_13|2010-01-01 00:00:00|-5.266929|-0.000154
214 january_under_0_25|2011-01-01 00:00:00|-4.968747|-6.1e-05
215 january_under_0_37|2012-01-01 00:00:00|-0.534994|-0.014581
216 # print minimum and maximum only for January in the original strds,
217 # note that the maximum is different
218 t.rast.list tempmean_monthly columns=name,start_time,min,max | grep 01-01
219 2009_01_tempmean|2009-01-01 00:00:00|-3.380823|7.426054
220 2010_01_tempmean|2010-01-01 00:00:00|-5.266929|5.71131
221 2011_01_tempmean|2011-01-01 00:00:00|-4.968747|4.967295
222 2012_01_tempmean|2012-01-01 00:00:00|-0.534994|9.69511
223 Semantic label filtering
225 t.rast.mapcalc supports semantic label filtering similarly to
226 t.rast.list. In example below a new STRDS will be created and filled by
227 NDVI products.
228 t.rast.mapcalc inputs=test.S2_8,test.S2_4 output=ndvi basename=ndvi \
229 expression="float(test.S2_8 - test.S2_4) / (test.S2_8 + test.S2_4)"
230 For more information about semantic label concept see i.band.library
231 module.
232
234 r.mapcalc, t.register, t.rast.list, t.info
235 Temporal data processing Wiki
237
239 Sören Gebbert, Thünen Institute of Climate-Smart Agriculture
240
242 Available at: t.rast.mapcalc source code (history)
243 Accessed: Saturday Jan 21 21:17:05 2023
245 Main index | Temporal index | Topics index | Keywords index | Graphical
247 index | Full index
248 © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
250GRASS 8.2.1 t.rast.mapcalc(1)