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

NAME

6       t.rast.list  - Lists registered maps of a space time raster dataset.
7

KEYWORDS

9       temporal, map management, raster, list, time
10

SYNOPSIS

12       t.rast.list
13       t.rast.list --help
14       t.rast.list   [-u]   input=name    [order=string[,string,...]]    [col‐
15       umns=string[,string,...]]       [where=sql_query]       [method=string]
16       [granule=string]     [format=string]     [separator=character]    [out‐
17       put=name]   [--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]
18
19   Flags:
20       -u
21           Suppress printing of column names
22
23       --overwrite
24           Allow output files to overwrite existing files
25
26       --help
27           Print usage summary
28
29       --verbose
30           Verbose module output
31
32       --quiet
33           Quiet module output
34
35       --ui
36           Force launching GUI dialog
37
38   Parameters:
39       input=name [required]
40           Name of the input space time raster dataset
41
42       order=string[,string,...]
43           Sort the space time dataset by category
44           Options: id, name, semantic_label, creator, mapset,  temporal_type,
45           creation_time,  start_time,  end_time,  north,  south,  west, east,
46           nsres, ewres, cols, rows, number_of_cells, min, max
47
48       columns=string[,string,...]
49           Columns to be printed to stdout
50           Options: id, name, semantic_label, creator, mapset,  temporal_type,
51           creation_time,  start_time,  end_time,  north,  south,  west, east,
52           nsres,  ewres,  cols,  rows,  number_of_cells,  min,  max,   inter‐
53           val_length, distance_from_begin
54
55       where=sql_query
56           WHERE  conditions  of SQL statement without ’where’ keyword used in
57           the temporal GIS framework
58           Example: start_time > ’2001-01-01 12:30:00’
59
60       method=string
61           Method used for data listing
62           Options: list, cols, comma, delta, deltagaps, gran
63           Default: list
64
65       granule=string
66           The granule to be used for listing. The granule must  be  specified
67           as string eg.: absolute time "1 months" or relative time "1"
68
69       format=string
70           Output format
71           Options: plain, line, json, yaml, csv
72
73       separator=character
74           Field separator character between the output columns
75           Special characters: pipe, comma, space, tab, newline
76           Default: pipe
77
78       output=name
79           Name for output file
80

DESCRIPTION

82       List time stamped raster map layers that are registered in a space time
83       raster dataset. t.rast.list provides several options to list map layers
84       and  their  metadata.  Listing of map layer can be ordered by metadata,
85       metadata columns can be specified and SQL where conditions can be  pro‐
86       vided  to  select  a  map  layer  subset of the input space time raster
87       dataset. Most of the raster map  specific  metadata  is  available  for
88       column  selection,  sorting and SQL where statements.  Using the method
89       option allows the specification of different methods to list  map  lay‐
90       ers.  Method list is the default option and sensitive to the column,or‐
91       der and where options.
92
93       To print interval length in days and distance from the begin use method
94       delta.  Method  deltagap  will additionally print temporal gaps between
95       map layer. The gran method allows the listing of map layer sampled by a
96       user  defined  granule.  As  default  the granularity of the space time
97       raster dataset is used for sampling.
98
99       While method list supports all columns except for  interval_length  and
100       distance_from_begin, methods delta, deltagap, and gran support only the
101       following columns:  id,  name,  mapset,  start_time,  end_time,  inter‐
102       val_length,  and  distance_from_begin.  The option order is only avail‐
103       able with method list.
104
105       Methods cols and comma are depreciated.  The cols method is replaced by
106       the plain format and the comma method is replaced by the line format.
107
108       The format option specifies the format of the output data.  The default
109       plain format will simply print user specified metadata columns  of  one
110       map  layer  per  line  separated by a pipe by default.  The line format
111       will list fully qualified map names (name and mapset) as a  comma-sepa‐
112       rated  list  of  values  that can be used as input for spatial modules.
113       The csv format will print data in the CSV format  using  comma  as  the
114       value  separator  (delimiter)  and double quote for text field quoting.
115       The json format generates JSON and, if the PyYAML package is installed,
116       The  yaml format generates YAML.  The column (or item) separator can be
117       specified with the separator option for plain, line, and csv.
118

EXAMPLES

120       This example shows several options that are available  for  map  layers
121       listing.
122
123   Default query
124       The  following  command is the default one, returning standard informa‐
125       tion like name, mapset, start_time, end_time of each map in  the  space
126       time dataset
127
128       t.rast.list tempmean_monthly
129       name|mapset|start_time|end_time
130       2009_01_tempmean|climate_2000_2012|2009-01-01 00:00:00|2009-02-01 00:00:00
131       2009_02_tempmean|climate_2000_2012|2009-02-01 00:00:00|2009-03-01 00:00:00
132       ....
133       2012_11_tempmean|climate_2000_2012|2012-11-01 00:00:00|2012-12-01 00:00:00
134       2012_12_tempmean|climate_2000_2012|2012-12-01 00:00:00|2013-01-01 00:00:00
135
136   Add more info
137       The following command let the user to choose the columns to show
138
139       t.rast.list tempmean_monthly columns=name,start_time,min,max
140       name|start_time|min|max
141       2009_01_tempmean|2009-01-01 00:00:00|-3.380823|7.426054
142       2009_02_tempmean|2009-02-01 00:00:00|-1.820261|8.006386
143       ...
144       2009_01_tempmean|2009-01-01 00:00:00|-3.380823|7.426054
145       2009_02_tempmean|2009-02-01 00:00:00|-1.820261|8.006386
146
147   Filtering the result by value
148       In  this  example the result is filtered showing only the maps with max
149       value major than 24
150
151       t.rast.list tempmean_monthly columns=name,start_time,min,max where="max > 24"
152       name|start_time|min|max
153       2009_06_tempmean|2009-06-01 00:00:00|15.962669|25.819681
154       2009_07_tempmean|2009-07-01 00:00:00|15.32852|26.103664
155       2009_08_tempmean|2009-08-01 00:00:00|16.37995|27.293282
156       ....
157       2012_06_tempmean|2012-06-01 00:00:00|14.929379|24.000651
158       2012_07_tempmean|2012-07-01 00:00:00|18.455802|28.794653
159       2012_08_tempmean|2012-08-01 00:00:00|15.718526|26.151115
160
161   Filtering the result by time range
162       In this example the result is filtered showing only the maps which fall
163       into a specified time range (from .. to):
164
165       t.rast.list tempmean_monthly columns=name,start_time,min,max \
166         where="start_time > ’2009-06-01 00:00:00’ and start_time < ’2012-08-01 00:00:00’"
167       name|start_time|min|max
168       2009_06_tempmean|2009-06-01 00:00:00|15.962669|25.819681
169       2009_07_tempmean|2009-07-01 00:00:00|15.32852|26.103664
170       2009_08_tempmean|2009-08-01 00:00:00|16.37995|27.293282
171       ....
172       2012_06_tempmean|2012-06-01 00:00:00|14.929379|24.000651
173       2012_07_tempmean|2012-07-01 00:00:00|18.455802|28.794653
174       2012_08_tempmean|2012-08-01 00:00:00|15.718526|26.151115
175
176   Filtering the result by selecting recurring timestamps
177       In this example the result is filtered showing only the maps which fall
178       into a specified recurring time range (here one month per year):
179       t.rast.list Tseasonal_fieldata_garda where="strftime(’%m’, start_time)=’06’"
180
181   Using method option
182       Method option is able to show raster in different way. By default  cols
183       value  is used, the value comma will print only the list of maps inside
184       the space time dataset:
185
186       t.rast.list method=comma input=tempmean_monthly
187       2009_01_tempmean@climate_2009_2012,2009_02_tempmean@climate_2009_2012,2009_03_tempmean@climate_2009_2012, \
188       2009_04_tempmean@climate_2009_2012,2009_05_tempmean@climate_2009_2012,2009_06_tempmean@climate_2009_2012, \
189       2009_07_tempmean@climate_2009_2012,2009_08_tempmean@climate_2009_2012,2009_09_tempmean@climate_2009_2012, \
190       2009_10_tempmean@climate_2009_2012,2009_11_tempmean@climate_2009_2012,2009_12_tempmean@climate_2009_2012, \
191       2010_01_tempmean@climate_2009_2012,2010_02_tempmean@climate_2009_2012,2010_03_tempmean@climate_2009_2012, \
192       2010_04_tempmean@climate_2009_2012,2010_05_tempmean@climate_2009_2012,2010_06_tempmean@climate_2009_2012, \
193       2010_07_tempmean@climate_2009_2012,2010_08_tempmean@climate_2009_2012,2010_09_tempmean@climate_2009_2012, \
194       2010_10_tempmean@climate_2009_2012,2010_11_tempmean@climate_2009_2012,2010_12_tempmean@climate_2009_2012, \
195       2011_01_tempmean@climate_2009_2012,2011_02_tempmean@climate_2009_2012,2011_03_tempmean@climate_2009_2012, \
196       2011_04_tempmean@climate_2009_2012,2011_05_tempmean@climate_2009_2012,2011_06_tempmean@climate_2009_2012, \
197       2011_07_tempmean@climate_2009_2012,2011_08_tempmean@climate_2009_2012,2011_09_tempmean@climate_2009_2012, \
198       2011_10_tempmean@climate_2009_2012,2011_11_tempmean@climate_2009_2012,2011_12_tempmean@climate_2009_2012, \
199       2012_01_tempmean@climate_2009_2012,2012_02_tempmean@climate_2009_2012,2012_03_tempmean@climate_2009_2012, \
200       2012_04_tempmean@climate_2009_2012,2012_05_tempmean@climate_2009_2012,2012_06_tempmean@climate_2009_2012, \
201       2012_07_tempmean@climate_2009_2012,2012_08_tempmean@climate_2009_2012,2012_09_tempmean@climate_2009_2012, \
202       2012_10_tempmean@climate_2009_2012,2012_11_tempmean@climate_2009_2012,2012_12_tempmean@climate_2009_2012
203       The delta value calculate the interval between maps  and  the  distance
204       from the first map:
205
206       t.rast.list method=delta input=tempmean_monthly
207       id|name|mapset|start_time|end_time|interval_length|distance_from_begin
208       2009_01_tempmean@climate_2000_2012|2009_01_tempmean|climate_2000_2012|2009-01-01 00:00:00|2009-02-01 00:00:00|31.0|0.0
209       2009_02_tempmean@climate_2000_2012|2009_02_tempmean|climate_2000_2012|2009-02-01 00:00:00|2009-03-01 00:00:00|28.0|31.0
210       2009_03_tempmean@climate_2000_2012|2009_03_tempmean|climate_2000_2012|2009-03-01 00:00:00|2009-04-01 00:00:00|31.0|59.0
211       ...
212       2012_10_tempmean@climate_2000_2012|2012_10_tempmean|climate_2000_2012|2012-10-01 00:00:00|2012-11-01 00:00:00|31.0|1369.0
213       2012_11_tempmean@climate_2000_2012|2012_11_tempmean|climate_2000_2012|2012-11-01 00:00:00|2012-12-01 00:00:00|30.0|1400.0
214       2012_12_tempmean@climate_2000_2012|2012_12_tempmean|climate_2000_2012|2012-12-01 00:00:00|2013-01-01 00:00:00|31.0|1430.0
215       The  gran  value  it  is  used to return data sampled by a user defined
216       granule. As default the granularity of the space time raster dataset is
217       used for sampling.
218
219       t.rast.list  method=gran input=tempmean_monthly
220       id|name|mapset|start_time|end_time|interval_length|distance_from_begin
221       2009_01_tempmean@climate_2009_2012|2009_01_tempmean|climate_2009_2012|2009-01-01 00:00:00|2009-02-01 00:00:00|31.0|0.0
222       2009_02_tempmean@climate_2009_2012|2009_02_tempmean|climate_2009_2012|2009-02-01 00:00:00|2009-03-01 00:00:00|28.0|31.0
223       2009_03_tempmean@climate_2009_2012|2009_03_tempmean|climate_2009_2012|2009-03-01 00:00:00|2009-04-01 00:00:00|31.0|59.0
224       2009_04_tempmean@climate_2009_2012|2009_04_tempmean|climate_2009_2012|2009-04-01 00:00:00|2009-05-01 00:00:00|30.0|90.0
225       ....
226       2012_09_tempmean@climate_2009_2012|2012_09_tempmean|climate_2009_2012|2012-09-01 00:00:00|2012-10-01 00:00:00|30.0|1339.0
227       2012_10_tempmean@climate_2009_2012|2012_10_tempmean|climate_2009_2012|2012-10-01 00:00:00|2012-11-01 00:00:00|31.0|1369.0
228       2012_11_tempmean@climate_2009_2012|2012_11_tempmean|climate_2009_2012|2012-11-01 00:00:00|2012-12-01 00:00:00|30.0|1400.0
229       2012_12_tempmean@climate_2009_2012|2012_12_tempmean|climate_2009_2012|2012-12-01 00:00:00|2013-01-01 00:00:00|31.0|1430.0
230
231       t.rast.list  method=gran input=tempmean_monthly gran="2 months"
232       id|name|mapset|start_time|end_time|interval_length|distance_from_begin
233       2009_01_tempmean@climate_2009_2012|2009_01_tempmean|climate_2009_2012|2009-01-01 00:00:00|2009-03-01 00:00:00|59.0|0.0
234       2009_03_tempmean@climate_2009_2012|2009_03_tempmean|climate_2009_2012|2009-03-01 00:00:00|2009-05-01 00:00:00|61.0|59.0
235       2009_05_tempmean@climate_2009_2012|2009_05_tempmean|climate_2009_2012|2009-05-01 00:00:00|2009-07-01 00:00:00|61.0|120.0
236       ....
237       2012_07_tempmean@climate_2009_2012|2012_07_tempmean|climate_2009_2012|2012-07-01 00:00:00|2012-09-01 00:00:00|62.0|1277.0
238       2012_09_tempmean@climate_2009_2012|2012_09_tempmean|climate_2009_2012|2012-09-01 00:00:00|2012-11-01 00:00:00|61.0|1339.0
239       2012_11_tempmean@climate_2009_2012|2012_11_tempmean|climate_2009_2012|2012-11-01 00:00:00|2013-01-01 00:00:00|61.0|1400.0
240       For  the  deltagaps value you can see the example for space time vector
241       dataset t.vect.list
242
243   Reading raster names in Python
244       result = json.loads(
245           gs.read_command(
246               "t.rast.list", input="tempmean_monthly", format="json"
247           )
248       )
249       for item in result["data"]:
250           print(item["name"])
251
252   Filtering the result by semantic label
253       Semantic label can be assigned to raster maps by r.semantic.label  mod‐
254       ule or even when registrating raster maps into STRDS by t.register.
255
256       Name  of  STRDS  can  be extended by semantic label used for filtering.
257       Name of STRDS and semantic label is split by a single dot.
258       t.rast.list input=test.S2_1
259       Note that semantic label filtering is supported by  all  temporal  mod‐
260       ules.
261
262       Also  note that only STRDS can be filtered by semantic label, see r.se‐
263       mantic.label for current limitations.
264

SEE ALSO

266        g.list, t.create, t.info, t.list, t.rast3d.list, t.vect.list
267
268       Temporal data processing Wiki
269

AUTHOR

271       Sören Gebbert, Thünen Institute of Climate-Smart Agriculture
272

SOURCE CODE

274       Available at: t.rast.list source code (history)
275
276       Accessed: Saturday Jan 21 21:17:05 2023
277
278       Main index | Temporal index | Topics index | Keywords index | Graphical
279       index | Full index
280
281       © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
282
283
284
285GRASS 8.2.1                                                     t.rast.list(1)