.TH t.rast.list 1grass "" "GRASS 8.3.1" "GRASS GIS User's Manual"
.SH NAME
\fI\fBt.rast.list\fR\fR  \- Lists registered maps of a space time raster dataset.
.SH KEYWORDS
temporal, map management, raster, list, time
.SH SYNOPSIS
\fBt.rast.list\fR
.br
\fBt.rast.list \-\-help\fR
.br
\fBt.rast.list\fR [\-\fBu\fR] \fBinput\fR=\fIname\fR  [\fBorder\fR=\fIstring\fR[,\fIstring\fR,...]]   [\fBcolumns\fR=\fIstring\fR[,\fIstring\fR,...]]   [\fBwhere\fR=\fIsql_query\fR]   [\fBmethod\fR=\fIstring\fR]   [\fBgranule\fR=\fIstring\fR]   [\fBformat\fR=\fIstring\fR]   [\fBseparator\fR=\fIcharacter\fR]   [\fBoutput\fR=\fIname\fR]   [\-\-\fBoverwrite\fR]  [\-\-\fBhelp\fR]  [\-\-\fBverbose\fR]  [\-\-\fBquiet\fR]  [\-\-\fBui\fR]
.SS Flags:
.IP "\fB\-u\fR" 4m
.br
Suppress printing of column names
.IP "\fB\-\-overwrite\fR" 4m
.br
Allow output files to overwrite existing files
.IP "\fB\-\-help\fR" 4m
.br
Print usage summary
.IP "\fB\-\-verbose\fR" 4m
.br
Verbose module output
.IP "\fB\-\-quiet\fR" 4m
.br
Quiet module output
.IP "\fB\-\-ui\fR" 4m
.br
Force launching GUI dialog
.SS Parameters:
.IP "\fBinput\fR=\fIname\fR \fB[required]\fR" 4m
.br
Name of the input space time raster dataset
.IP "\fBorder\fR=\fIstring[,\fIstring\fR,...]\fR" 4m
.br
Sort the space time dataset by category
.br
Options: \fIid, name, semantic_label, creator, mapset, temporal_type, creation_time, start_time, end_time, north, south, west, east, nsres, ewres, cols, rows, number_of_cells, min, max\fR
.IP "\fBcolumns\fR=\fIstring[,\fIstring\fR,...]\fR" 4m
.br
Columns to be printed to stdout
.br
Options: \fIid, name, semantic_label, creator, mapset, temporal_type, creation_time, start_time, end_time, north, south, west, east, nsres, ewres, cols, rows, number_of_cells, min, max, interval_length, distance_from_begin\fR
.IP "\fBwhere\fR=\fIsql_query\fR" 4m
.br
WHERE conditions of SQL statement without \(cqwhere\(cq keyword used in the temporal GIS framework
.br
Example: start_time > \(cq2001\-01\-01 12:30:00\(cq
.IP "\fBmethod\fR=\fIstring\fR" 4m
.br
Method used for data listing
.br
Options: \fIlist, cols, comma, delta, deltagaps, gran\fR
.br
Default: \fIlist\fR
.IP "\fBgranule\fR=\fIstring\fR" 4m
.br
The granule to be used for listing. The granule must be specified as string eg.: absolute time \(dq1 months\(dq or relative time \(dq1\(dq
.IP "\fBformat\fR=\fIstring\fR" 4m
.br
Output format
.br
Options: \fIplain, line, json, yaml, csv\fR
.IP "\fBseparator\fR=\fIcharacter\fR" 4m
.br
Field separator character between the output columns
.br
Special characters: pipe, comma, space, tab, newline
.br
Default: \fIpipe\fR
.IP "\fBoutput\fR=\fIname\fR" 4m
.br
Name for output file
.SH DESCRIPTION
List time stamped raster map layers that are registered in a space time
raster dataset. \fIt.rast.list\fR provides several options to list map layers
and their metadata. Listing of map layer can be ordered by metadata,
metadata columns can be specified and SQL where conditions can be
provided to select a map layer subset of the input space time raster
dataset. Most of the raster map  specific metadata is available for
column selection, sorting and SQL where statements.
Using the \fBmethod\fR option allows the specification of different
methods to list map layers. Method \fIlist\fR is the default option and
sensitive to the \fBcolumn\fR,\fBorder\fR and \fBwhere\fR options.
.PP
To print interval length in days and distance from the begin use method
\fIdelta\fR. Method \fIdeltagap\fR will additionally print temporal
gaps between map layer. The \fIgran\fR method allows the listing of
map layer sampled by a user defined \fBgranule\fR. As default the
granularity of the space time raster dataset is used for sampling.
.PP
While method \fIlist\fR supports all columns except for
interval_length and distance_from_begin,
methods \fIdelta\fR, \fIdeltagap\fR, and \fIgran\fR support only the following
columns: id, name, mapset, start_time, end_time, interval_length, and distance_from_begin.
The option \fBorder\fR is only available with method \fIlist\fR.
.PP
Methods \fIcols\fR and \fIcomma\fR are depreciated.
The \fIcols\fR method is replaced by the \fIplain\fR format and
the \fIcomma\fR method is replaced by the \fIline\fR format.
.PP
The \fBformat\fR option specifies the format of the output data.
The default \fIplain\fR format will simply print user specified metadata
columns of one map layer per line separated by a pipe by default.
The \fIline\fR format will list fully qualified map names (name and mapset)
as a comma\-separated list of values that can be used as input for spatial modules.
The \fIcsv\fR format will print data in the CSV format using
comma as the value separator (delimiter) and double quote for text field quoting.
The \fIjson\fR format generates JSON and, if the PyYAML package is installed,
The \fIyaml\fR format generates YAML.
The column (or item) separator can be specified with the \fBseparator\fR
option for \fIplain\fR, \fIline\fR, and \fIcsv\fR.
.SH EXAMPLES
This example shows several options that are available for map layers listing.
.SS Default query
The following command is the default one, returning standard information
like name, mapset, start_time, end_time of each map in the space time dataset
.PP
.br
.nf
\fC
t.rast.list tempmean_monthly
name|mapset|start_time|end_time
2009_01_tempmean|climate_2000_2012|2009\-01\-01 00:00:00|2009\-02\-01 00:00:00
2009_02_tempmean|climate_2000_2012|2009\-02\-01 00:00:00|2009\-03\-01 00:00:00
\&....
2012_11_tempmean|climate_2000_2012|2012\-11\-01 00:00:00|2012\-12\-01 00:00:00
2012_12_tempmean|climate_2000_2012|2012\-12\-01 00:00:00|2013\-01\-01 00:00:00
\fR
.fi
.SS Add more info
The following command let the user to choose the columns to show
.PP
.br
.nf
\fC
t.rast.list tempmean_monthly columns=name,start_time,min,max
name|start_time|min|max
2009_01_tempmean|2009\-01\-01 00:00:00|\-3.380823|7.426054
2009_02_tempmean|2009\-02\-01 00:00:00|\-1.820261|8.006386
\&...
2009_01_tempmean|2009\-01\-01 00:00:00|\-3.380823|7.426054
2009_02_tempmean|2009\-02\-01 00:00:00|\-1.820261|8.006386
\fR
.fi
.SS Filtering the result by value
In this example the result is filtered showing only the maps with max
value major than 24
.PP
.br
.nf
\fC
t.rast.list tempmean_monthly columns=name,start_time,min,max where=\(dqmax > 24\(dq
name|start_time|min|max
2009_06_tempmean|2009\-06\-01 00:00:00|15.962669|25.819681
2009_07_tempmean|2009\-07\-01 00:00:00|15.32852|26.103664
2009_08_tempmean|2009\-08\-01 00:00:00|16.37995|27.293282
\&....
2012_06_tempmean|2012\-06\-01 00:00:00|14.929379|24.000651
2012_07_tempmean|2012\-07\-01 00:00:00|18.455802|28.794653
2012_08_tempmean|2012\-08\-01 00:00:00|15.718526|26.151115
\fR
.fi
.SS Filtering the result by time range
In this example the result is filtered showing only the maps which
fall into a specified time range (from .. to):
.PP
.br
.nf
\fC
t.rast.list tempmean_monthly columns=name,start_time,min,max \(rs
  where=\(dqstart_time > \(cq2009\-06\-01 00:00:00\(cq and start_time < \(cq2012\-08\-01 00:00:00\(cq\(dq
name|start_time|min|max
2009_06_tempmean|2009\-06\-01 00:00:00|15.962669|25.819681
2009_07_tempmean|2009\-07\-01 00:00:00|15.32852|26.103664
2009_08_tempmean|2009\-08\-01 00:00:00|16.37995|27.293282
\&....
2012_06_tempmean|2012\-06\-01 00:00:00|14.929379|24.000651
2012_07_tempmean|2012\-07\-01 00:00:00|18.455802|28.794653
2012_08_tempmean|2012\-08\-01 00:00:00|15.718526|26.151115
\fR
.fi
.SS Filtering the result by selecting recurring timestamps
In this example the result is filtered showing only the maps which
fall into a specified recurring time range (here one month per year):
.br
.nf
\fC
t.rast.list Tseasonal_fieldata_garda where=\(dqstrftime(\(cq%m\(cq, start_time)=\(cq06\(cq\(dq
\fR
.fi
.SS Using method option
Method option is able to show raster in different way. By default \fIcols\fR
value is used, the value \fIcomma\fR will print only the list of maps
inside the space time dataset:
.PP
.br
.nf
\fC
t.rast.list method=comma input=tempmean_monthly
2009_01_tempmean@climate_2009_2012,2009_02_tempmean@climate_2009_2012,2009_03_tempmean@climate_2009_2012, \(rs
2009_04_tempmean@climate_2009_2012,2009_05_tempmean@climate_2009_2012,2009_06_tempmean@climate_2009_2012, \(rs
2009_07_tempmean@climate_2009_2012,2009_08_tempmean@climate_2009_2012,2009_09_tempmean@climate_2009_2012, \(rs
2009_10_tempmean@climate_2009_2012,2009_11_tempmean@climate_2009_2012,2009_12_tempmean@climate_2009_2012, \(rs
2010_01_tempmean@climate_2009_2012,2010_02_tempmean@climate_2009_2012,2010_03_tempmean@climate_2009_2012, \(rs
2010_04_tempmean@climate_2009_2012,2010_05_tempmean@climate_2009_2012,2010_06_tempmean@climate_2009_2012, \(rs
2010_07_tempmean@climate_2009_2012,2010_08_tempmean@climate_2009_2012,2010_09_tempmean@climate_2009_2012, \(rs
2010_10_tempmean@climate_2009_2012,2010_11_tempmean@climate_2009_2012,2010_12_tempmean@climate_2009_2012, \(rs
2011_01_tempmean@climate_2009_2012,2011_02_tempmean@climate_2009_2012,2011_03_tempmean@climate_2009_2012, \(rs
2011_04_tempmean@climate_2009_2012,2011_05_tempmean@climate_2009_2012,2011_06_tempmean@climate_2009_2012, \(rs
2011_07_tempmean@climate_2009_2012,2011_08_tempmean@climate_2009_2012,2011_09_tempmean@climate_2009_2012, \(rs
2011_10_tempmean@climate_2009_2012,2011_11_tempmean@climate_2009_2012,2011_12_tempmean@climate_2009_2012, \(rs
2012_01_tempmean@climate_2009_2012,2012_02_tempmean@climate_2009_2012,2012_03_tempmean@climate_2009_2012, \(rs
2012_04_tempmean@climate_2009_2012,2012_05_tempmean@climate_2009_2012,2012_06_tempmean@climate_2009_2012, \(rs
2012_07_tempmean@climate_2009_2012,2012_08_tempmean@climate_2009_2012,2012_09_tempmean@climate_2009_2012, \(rs
2012_10_tempmean@climate_2009_2012,2012_11_tempmean@climate_2009_2012,2012_12_tempmean@climate_2009_2012
\fR
.fi
The \fIdelta\fR value calculate the interval between maps and the
distance from the first map:
.PP
.br
.nf
\fC
t.rast.list method=delta input=tempmean_monthly
id|name|mapset|start_time|end_time|interval_length|distance_from_begin
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
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
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
\&...
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
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
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
\fR
.fi
The \fIgran\fR value it is used to return data sampled by a user
defined granule. As default the granularity of the space time raster
dataset is used for sampling.
.PP
.br
.nf
\fC
t.rast.list  method=gran input=tempmean_monthly
id|name|mapset|start_time|end_time|interval_length|distance_from_begin
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
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
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
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
\&....
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
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
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
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
\fR
.fi
.PP
.br
.nf
\fC
t.rast.list  method=gran input=tempmean_monthly gran=\(dq2 months\(dq
id|name|mapset|start_time|end_time|interval_length|distance_from_begin
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
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
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
\&....
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
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
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
\fR
.fi
For the \fIdeltagaps\fR value you can see the example for space time
vector dataset t.vect.list
.SS Reading raster names in Python
.br
.nf
\fC
result = json.loads(
    gs.read_command(
        \(dqt.rast.list\(dq, input=\(dqtempmean_monthly\(dq, format=\(dqjson\(dq
    )
)
for item in result[\(dqdata\(dq]:
    print(item[\(dqname\(dq])
\fR
.fi
.SS Filtering the result by semantic label
Semantic label can be assigned to raster maps
by \fIr.semantic.label\fR module or even when
registrating raster maps into STRDS
by \fIt.register\fR.
.PP
Name of STRDS can be extended by semantic label used for
filtering. Name of STRDS and semantic label is split by a \fIsingle
dot\fR.
.br
.nf
\fC
t.rast.list input=test.S2_1
\fR
.fi
Note that semantic label filtering is \fIsupported by all temporal
modules\fR.
.PP
Also note that only STRDS can be filtered by semantic label,
see \fIr.semantic.label\fR for
current limitations.
.SH SEE ALSO
\fI
g.list,
t.create,
t.info,
t.list,
t.rast3d.list,
t.vect.list
\fR
.PP
Temporal data processing Wiki
.SH AUTHOR
Sören Gebbert, Thünen Institute of Climate\-Smart Agriculture
.SH SOURCE CODE
.PP
Available at:
t.rast.list source code
(history)
.PP
Accessed: Sunday Dec 17 17:22:53 2023
.PP
Main index |
Temporal index |
Topics index |
Keywords index |
Graphical index |
Full index
.PP
© 2003\-2023
GRASS Development Team,
GRASS GIS 8.3.1 Reference Manual