1t.register(1) GRASS GIS User's Manual t.register(1)
2
3
4
6 t.register - Assigns timestamps and registers raster, vector and
7 raster3d maps in a space time dataset.
8
10 temporal, map management, register, time
11
13 t.register
14 t.register --help
15 t.register [-i] [input=name] [maps=name[,name,...]] [type=name]
16 [file=name] [start=string] [end=string] [unit=string] [incre‐
17 ment=string] [separator=character] [--overwrite] [--help] [--ver‐
18 bose] [--quiet] [--ui]
19
20 Flags:
21 -i
22 Create an interval (start and end time) in case an increment and
23 the start time are provided
24
25 --overwrite
26 Allow output files to overwrite existing files
27
28 --help
29 Print usage summary
30
31 --verbose
32 Verbose module output
33
34 --quiet
35 Quiet module output
36
37 --ui
38 Force launching GUI dialog
39
40 Parameters:
41 input=name
42 Name of the input space time dataset
43
44 maps=name[,name,...]
45 Name of the input maps
46
47 type=name
48 Type of the input map
49 Options: raster, vector, raster_3d
50 Default: raster
51
52 file=name
53 Input file with map names, one per line
54 Additionally the start time and the end time can be specified per
55 line
56
57 start=string
58 Valid start date and time of the first map
59 Format for absolute time: "yyyy-mm-dd HH:MM:SS +HHMM", relative
60 time is of type integer.
61
62 end=string
63 Valid end date and time of all map
64 Format for absolute time: "yyyy-mm-dd HH:MM:SS +HHMM", relative
65 time is of type integer.
66
67 unit=string
68 Time stamp unit
69 Unit must be set in case of relative timestamps
70 Options: years, months, days, hours, minutes, seconds
71
72 increment=string
73 Time increment, works only in conjunction with start option
74 Time increment between maps for creation of valid time intervals
75 (format for absolute time: NNN seconds, minutes, hours, days,
76 weeks, months, years; format for relative time is of type integer:
77 5)
78
79 separator=character
80 Field separator character of the input file
81 Special characters: pipe, comma, space, tab, newline
82 Default: pipe
83
85 The module t.register has double functionality: it either only assigns
86 timestamps to raster, 3D raster and vector maps in the temporal data‐
87 base (if input option is not provided, see below) or additionally, it
88 also registers them within input space time datasets (stds). The exist‐
89 ing timestamp modules r.timestamp, r3.timestamp and v.timestamp do not
90 register the maps in the temporal database of GRASS GIS. However, time‐
91 stamps that have been created with these modules can be read and used
92 by t.register. This works only for maps that are not already registered
93 in the temporal database.
94
95 If the input option is not used (i.e., no stds is provided), maps will
96 be only registered in the temporal database with assigned timestamps.
97 If, on the other hand, the input option is used and a stds is provided,
98 maps will be first registered in the temporal database (if not regis‐
99 tered before) and then, in the stds specified. If the user wants to
100 register maps that are already registered in the temporal database in a
101 different stds, there is no need to pass information regarding start
102 and end time, t.register will read timestamps from the temporal data‐
103 base (i.e., in this case only passing map names will be enough).
104
105 Maps can be specified both with their fully qualified map name, meaning
106 e.g. map@mapset and without the mapset name included. If the mapset
107 name is not provided in the input, t.register will look for the given
108 map on the current search path and assign the matching mapset. If the
109 map is not found on the current search path the module will fail.
110 Thus, registering maps with fully qualified map name is slightly
111 faster.
112
113 The module t.register supports absolute and relative time. The absolute
114 temporal type refers to a fixed date while the relative temporal type
115 refers to data without fixed timestamps (e.g., sequential maps used to
116 calculate multi-decadal averages).
117
118 Maps can be registered by command line argument (i.e., a list of comma
119 separated map names) or using an input file. The start time, end time
120 and a temporal increment can be provided through command line or in the
121 input file. End time and increment are mutually exclusive. The user can
122 register single maps or a list of maps at once. Maps can be registered
123 in several space time datasets using the same timestamp. For the case
124 of vector time series, the user can also register a single vector map
125 connected to different layers representing time steps using the
126 map:layer notation (See example below).
127
128 The increment option and the -i flag (to create time intervals) work
129 only in conjunction with the start option. If an input file with time‐
130 stamps (either start time or start time and end time) is used, then the
131 increment option and the -i flag are not supported.
132
133 Start time and end time with absolute time must be provided using the
134 format yyyy-mm-dd HH:MM:SS +HHMM. It is also supported to specify only
135 the date yyyy-mm-dd. In case of relative time, the temporal unit
136 (years, months, days, hours, minutes or seconds) must be provided. In
137 this case, the relative start time, end time and increment are inte‐
138 gers.
139
141 The timestamps of registered maps will be stored in the temporal data‐
142 base and in the metadata of the grass maps in the spatial database.
143 This assures that timestamps can always be accessed with (r|r3|v).time‐
144 stamp and the temporal modules. Timestamps should only be modified with
145 t.register because the (r|r3|v).timestamp modules have no access to the
146 temporal database.
147
149 There are several options to register maps by means of a file. The in‐
150 put file consists of a list of map names, optionally along with time‐
151 stamps. Each map name (and timestaps if provided) should be stored in a
152 new line in this file.
153
154 When only map names are provided, the increment option and the -i flag
155 are supported. However, when along with map names any kind of timestamp
156 is provided, as well, the increment option and the -i are no longer
157 supported.
158
159 Specification of map names only (increment option and -i flag sup‐
160 ported):
161 terra_lst_day20020113
162 terra_lst_day20020114
163 terra_lst_day20020115
164 terra_lst_day20020116
165 terra_lst_day20020117
166
167 Specification of map names and absolute start time (date) of the time
168 instances (no support for increment option nor -i flag):
169 terra_lst_day20020113|2002-01-13
170 terra_lst_day20020114|2002-01-14
171 terra_lst_day20020115|2002-01-15
172 terra_lst_day20020116|2002-01-16
173 terra_lst_day20020117|2002-01-17
174
175 Specification of map names and absolute start time (datetime) of the
176 time instances (no support for increment option nor -i flag):
177 terra_lst_day20020113|2002-01-13 10:30
178 terra_lst_day20020114|2002-01-14 10:30
179 terra_lst_day20020115|2002-01-15 10:30
180 terra_lst_day20020116|2002-01-16 10:30
181 terra_lst_day20020117|2002-01-17 10:30
182
183 Specification of map names and absolute time interval with start and
184 end time (no support for increment option nor -i flag):
185 prec_1|2001-01-01|2001-04-01
186 prec_2|2001-04-01|2001-07-01
187 prec_3|2001-07-01|2001-10-01
188 prec_4|2001-10-01|2002-01-01
189 prec_5|2002-01-01|2002-04-01
190 prec_6|2002-04-01|2002-07-01
191
192 Same as above but with fully qualified map names (no support for incre‐
193 ment option nor -i flag):
194 prec_1@PERMANENT|2001-01-01|2001-04-01
195 prec_2@PERMANENT|2001-04-01|2001-07-01
196 prec_3@PERMANENT|2001-07-01|2001-10-01
197 prec_4@PERMANENT|2001-10-01|2002-01-01
198 prec_5@PERMANENT|2002-01-01|2002-04-01
199 prec_6@PERMANENT|2002-04-01|2002-07-01
200
201 Support for semantic labels
202 For more information about semantic labels and image collections see
203 i.band.library module.
204
205 Specification of map names and absolute start time (datetime) of the
206 time instances. The last column indicates related semantic label.
207 T33UYP_20190331T094039_B01|2019-03-31 09:40:39|S2_1
208 T33UYP_20190331T094039_B10|2019-03-31 09:40:39|S2_10
209 T33UYP_20190331T094039_B02|2019-03-31 09:40:39|S2_2
210 T33UYP_20190331T094039_B05|2019-03-31 09:40:39|S2_5
211 T33UYP_20190331T094039_B11|2019-03-31 09:40:39|S2_11
212 T33UYP_20190331T094039_B08|2019-03-31 09:40:39|S2_8
213 T33UYP_20190331T094039_B12|2019-03-31 09:40:39|S2_12
214 T33UYP_20190331T094039_B8A|2019-03-31 09:40:39|S2_8A
215 T33UYP_20190331T094039_B06|2019-03-31 09:40:39|S2_6
216 T33UYP_20190331T094039_B04|2019-03-31 09:40:39|S2_4
217 T33UYP_20190331T094039_B03|2019-03-31 09:40:39|S2_3
218 T33UYP_20190331T094039_B09|2019-03-31 09:40:39|S2_9
219 In this case t.register assigns to given raster maps a semantic label
220 similarly as r.semantic.label does. Such registered raster maps is
221 possible to filter by a semantic label.
222
223 Please note that raster maps with semantic labels assigned can be reg‐
224 istered only in STRDS created in TGIS DB version 3 or higher. Older
225 versions of TGIS DB are not supported. TGIS DB version can be checked
226 t.connect module.
227
229 North Carolina dataset
230 Using a text file
231 Register maps in an absolute space time dataset, creating a time inter‐
232 val
233 # first: prepare a text file with a list of input maps (see above)
234 # second: register maps
235 t.register -i type=raster input=precipitation_monthly \
236 file=list_of_input_maps.txt start="2009-01-01" \
237 increment="1 months"
238
239 Using g.list to generate the input
240 Register maps in an absolute space time dataset, creating a time inter‐
241 val
242 t.register -i type=raster input=precipitation_monthly \
243 maps=`g.list raster pattern="*precip*" sep=comma` start="2009-01-01" \
244 increment="1 months"
245
246 Register a vector map with layers representing time steps
247 Assume a vector map of points that represent meteorological stations
248 and it is connected to different layers depicting daily time steps. In
249 this example, only the fifth layer of the vector map will be regis‐
250 tered.
251 # the layer is specified behind the colon
252 t.register type=vector input=meteo_stations_nc_daily \
253 maps=meteo_stations_nc:5 start="2009-01-05"
254
255 Synthetic maps
256 In this example we create 6 raster maps that will be registered in a
257 single space time raster dataset named precip_abs using a monthly tem‐
258 poral granularity. The -i flag generates time intervals of the provided
259 increment. The generated timestamps will be inspected using r.timestamp
260 and t.rast.list. We will register an additional map with a timestamp
261 that was set with r.timestamp.
262 r.mapcalc expression="prec_1 = 100"
263 r.mapcalc expression="prec_2 = 200"
264 r.mapcalc expression="prec_3 = 300"
265 r.mapcalc expression="prec_4 = 400"
266 r.mapcalc expression="prec_5 = 500"
267 r.mapcalc expression="prec_6 = 600"
268 t.create type=strds temporaltype=absolute \
269 output=precip_abs title="Example" \
270 descr="Example"
271 t.register -i type=raster input=precip_abs \
272 maps=prec_1,prec_2,prec_3,prec_4,prec_5,prec_6 \
273 start="2001-01-01" increment="1 months"
274 r.timestamp prec_1
275 1 Jan 2001 00:00:00 / 1 Feb 2001 00:00:00
276 r.timestamp prec_2
277 1 Feb 2001 00:00:00 / 1 Mar 2001 00:00:00
278 t.rast.list input=precip_abs
279 name|mapset|start_time|end_time
280 prec_1|PERMANENT|2001-01-01 00:00:00|2001-02-01 00:00:00
281 prec_2|PERMANENT|2001-02-01 00:00:00|2001-03-01 00:00:00
282 prec_3|PERMANENT|2001-03-01 00:00:00|2001-04-01 00:00:00
283 prec_4|PERMANENT|2001-04-01 00:00:00|2001-05-01 00:00:00
284 prec_5|PERMANENT|2001-05-01 00:00:00|2001-06-01 00:00:00
285 prec_6|PERMANENT|2001-06-01 00:00:00|2001-07-01 00:00:00
286 r.mapcalc expression="prec_7 = 700"
287 r.timestamp map=prec_7 date="1 jul 2001 / 1 aug 2001"
288 t.register type=raster input=precip_abs maps=prec_7
289 t.rast.list input=precip_abs
290 name|mapset|start_time|end_time
291 prec_1|PERMANENT|2001-01-01 00:00:00|2001-02-01 00:00:00
292 prec_2|PERMANENT|2001-02-01 00:00:00|2001-03-01 00:00:00
293 prec_3|PERMANENT|2001-03-01 00:00:00|2001-04-01 00:00:00
294 prec_4|PERMANENT|2001-04-01 00:00:00|2001-05-01 00:00:00
295 prec_5|PERMANENT|2001-05-01 00:00:00|2001-06-01 00:00:00
296 prec_6|PERMANENT|2001-06-01 00:00:00|2001-07-01 00:00:00
297 prec_7|PERMANENT|2001-07-01 00:00:00|2001-08-01 00:00:00
298
299 Importing and registering ECA&D climatic data
300 The European Climate Assessment & Dataset (ECA&D) project offers the
301 E-OBS dataset which is a daily gridded observational dataset for pre‐
302 cipitation, temperature and sea level pressure in Europe based on ECA&D
303 information. Download and decompress mean temperature data from: here
304 by accepting their Terms of use.
305 # import E-OBS V12 into a lat-long location (alternatively, use r.external)
306 r.in.gdal -oe input=tg_0.25deg_reg_1950-1964_v12.0.nc \
307 output=temperature_mean offset=0
308 r.in.gdal -oe input=tg_0.25deg_reg_1965-1979_v12.0.nc \
309 output=temperature_mean offset=5479 --o
310 r.in.gdal -oe input=tg_0.25deg_reg_1980-1994_v12.0.nc \
311 output=temperature_mean offset=10957 --o
312 r.in.gdal -oe input=tg_0.25deg_reg_1995-2015_v12.0.nc \
313 output=temperature_mean offset=16436 --o
314 # create STRDS
315 t.create type=strds output=temperature_mean_1950_2015_daily \
316 temporaltype=absolute semantictype=mean \
317 title="European mean temperature 1950-2015" \
318 description="The European daily mean temperature from ECAD"
319 # create text file with all temperature_mean rasters, one per line,
320 # a) using a shell script
321 for i in `seq 1 23922` ; do
322 echo temperature_mean.$i >> map_list.txt
323 done
324 # b) using a Python script
325 file = open("map_list.txt", "w")
326 for i in range(23922):
327 file.write("temperature_mean.%i\n" % (i + 1))
328 file.close()
329 # register daily maps using the file created above
330 t.register -i type=raster input=temperature_mean_1950_2015_daily \
331 file=map_list.txt start="1950-01-01" increment="1 days"
332
334 r.timestamp, t.create, t.info
335
336 Maps registration examples in Temporal data processing Wiki
337
339 Sören Gebbert, Thünen Institute of Climate-Smart Agriculture
340
342 Available at: t.register source code (history)
343
344 Accessed: Saturday Oct 28 18:19:22 2023
345
346 Main index | Temporal index | Topics index | Keywords index | Graphical
347 index | Full index
348
349 © 2003-2023 GRASS Development Team, GRASS GIS 8.3.1 Reference Manual
350
351
352
353GRASS 8.3.1 t.register(1)