1t.rast.mapcalc(1)           GRASS GIS User's Manual          t.rast.mapcalc(1)
2
3
4

NAME

6       t.rast.mapcalc   - Performs spatio-temporal mapcalc expressions on tem‐
7       porally sampled maps of space time raster datasets.
8

KEYWORDS

10       temporal, algebra, raster, time
11

SYNOPSIS

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
19   Flags:
20       -n
21           Register Null maps
22
23       -s
24           Check the spatial topology of temporally related maps  and  process
25           only spatially related maps
26
27       --overwrite
28           Allow output files to overwrite existing files
29
30       --help
31           Print usage summary
32
33       --verbose
34           Verbose module output
35
36       --quiet
37           Quiet module output
38
39       --ui
40           Force launching GUI dialog
41
42   Parameters:
43       inputs=name[,name,...] [required]
44           Name of the input space time raster datasets
45
46       expression=string [required]
47           Spatio-temporal mapcalc expression
48
49       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
54       output=name [required]
55           Name of the output space time raster dataset
56
57       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
62       nprocs=integer
63           Number of r.mapcalc processes to run in parallel
64           Default: 1
65

DESCRIPTION

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
74       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
89       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
93       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
97       The supported internal variables for relative and absolute time are:
98
99td() - 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
103start_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
110end_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
118       The supported internal variables for the current sample interval or in‐
119       stance for absolute time are:
120
121start_doy() - Day of year (doy) from the start time [1 - 366]
122
123start_dow() - Day of week (dow) from the start time  [1  -  7],
124               the start of the week is Monday == 1
125
126start_year() - The year of the start time [0 - 9999]
127
128start_month() - The month of the start time [1 - 12]
129
130start_week() - Week of year of the start time [1 - 54]
131
132start_day() - Day of month from the start time [1 - 31]
133
134start_hour() - The hour of the start time [0 - 23]
135
136start_minute() - The minute of the start time [0 - 59]
137
138start_second() - The second of the start time [0 - 59]
139
140end_doy() - Day of year (doy) from the end time [1 - 366]
141
142end_dow()  -  Day  of week (dow) from the end time [1 - 7], the
143               start of the week is Monday == 1
144
145end_year() - The year of the end time [0 - 9999]
146
147end_month() - The month of the end time [1 - 12]
148
149end_woy() - Week of year (woy) of the end time [1 - 54]
150
151end_day() - Day of month from the start time [1 - 31]
152
153end_hour() - The hour of the end time [0 - 23]
154
155end_minute() - The minute of the end time [0 - 59]
156
157end_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

NOTES

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
172       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
175       The resulting raster maps in dataset C can be listed with t.rast.list:
176
177       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
185       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
191       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
198       Semantic  labels present in the sample dataset A will be transferred to
199       the output dataset.
200

EXAMPLES

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
224   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

SEE ALSO

234        r.mapcalc, t.register, t.rast.list, t.info
235
236       Temporal data processing Wiki
237

AUTHOR

239       Sören Gebbert, Thünen Institute of Climate-Smart Agriculture
240

SOURCE CODE

242       Available at: t.rast.mapcalc source code (history)
243
244       Accessed: Saturday Jan 21 21:17:05 2023
245
246       Main index | Temporal index | Topics index | Keywords index | Graphical
247       index | Full index
248
249       © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
250
251
252
253GRASS 8.2.1                                                  t.rast.mapcalc(1)
Impressum