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
76       input  option.  The  first  space time raster dataset that is listed as
77       input 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
82       together 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
99           ·   td() - This internal variable represents the size of  the  cur‐
100               rent  sample  time  interval  in  days and fraction of days for
101               absolute time, and in relative units in case of relative time.
102
103           ·   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
110           ·   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
116               instance.
117
118       The  supported  internal  variables  for the current sample interval or
119       instance for absolute time are:
120
121           ·   start_doy() - Day of year (doy) from the start time [1 - 366]
122
123           ·   start_dow() - Day of week (dow) from the start time  [1  -  7],
124               the start of the week is Monday == 1
125
126           ·   start_year() - The year of the start time [0 - 9999]
127
128           ·   start_month() - The month of the start time [1 - 12]
129
130           ·   start_week() - Week of year of the start time [1 - 54]
131
132           ·   start_day() - Day of month from the start time [1 - 31]
133
134           ·   start_hour() - The hour of the start time [0 - 23]
135
136           ·   start_minute() - The minute of the start time [0 - 59]
137
138           ·   start_second() - The second of the start time [0 - 59]
139
140           ·   end_doy() - Day of year (doy) from the end time [1 - 366]
141
142           ·   end_dow()  -  Day  of week (dow) from the end time [1 - 7], the
143               start of the week is Monday == 1
144
145           ·   end_year() - The year of the end time [0 - 9999]
146
147           ·   end_month() - The month of the end time [1 - 12]
148
149           ·   end_woy() - Week of year (woy) of the end time [1 - 54]
150
151           ·   end_day() - Day of month from the start time [1 - 31]
152
153           ·   end_hour() - The hour of the end time [0 - 23]
154
155           ·   end_minute() - The minute of the end time [0 - 59]
156
157           ·   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

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

EXAMPLE

199       The  following  command  creates  a new space time raster dataset janu‐
200       ary_under_0 that will set to null all cells with temperature above zero
201       in  the January maps while keeping all the rest as in the original time
202       series. This will change the maximum values of all January maps in  the
203       new STRDS as compared to the original one, tempmean_monthly.
204       t.rast.mapcalc input=tempmean_monthly output=january_under_0 basename=january_under_0 \
205           expression="if(start_month() == 1 && tempmean_monthly > 0, null(), tempmean_monthly)"
206       # print minimum and maximum only for January in the new strds
207       t.rast.list january_under_0 columns=name,start_time,min,max | grep 01-01
208       name|start_time|min|max
209       january_under_0_01|2009-01-01 00:00:00|-3.380823|-7e-06
210       january_under_0_13|2010-01-01 00:00:00|-5.266929|-0.000154
211       january_under_0_25|2011-01-01 00:00:00|-4.968747|-6.1e-05
212       january_under_0_37|2012-01-01 00:00:00|-0.534994|-0.014581
213       # print minimum and maximum only for January in the original strds,
214       # note that the maximum is different
215       t.rast.list tempmean_monthly columns=name,start_time,min,max | grep 01-01
216       2009_01_tempmean|2009-01-01 00:00:00|-3.380823|7.426054
217       2010_01_tempmean|2010-01-01 00:00:00|-5.266929|5.71131
218       2011_01_tempmean|2011-01-01 00:00:00|-4.968747|4.967295
219       2012_01_tempmean|2012-01-01 00:00:00|-0.534994|9.69511
220

SEE ALSO

222        r.mapcalc, t.register, t.rast.list, t.info
223
224       Temporal data processing Wiki
225

AUTHOR

227       Sören Gebbert, Thünen Institute of Climate-Smart Agriculture
228

SOURCE CODE

230       Available at: t.rast.mapcalc source code (history)
231
232       Main index | Temporal index | Topics index | Keywords index | Graphical
233       index | Full index
234
235       © 2003-2020 GRASS Development Team, GRASS GIS 7.8.5 Reference Manual
236
237
238
239GRASS 7.8.5                                                  t.rast.mapcalc(1)
Impressum