t.rast.line
Draws line plots of the raster maps in a space-time raster dataset
t.rast.line [-gl] input=name [where=sql_query] [zones=name] [output=name] [dpi=integer] [plot_dimensions=string] [error=string] [n=float] [rotate_labels=float] [y_label=string] [x_value=string] [fontsize=integer] [date_interval=string] [date_format=string] [y_axis_limits=string] [line_width=float] [line_color=name] [alpha=float] [nprocs=integer] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]
Example:
t.rast.line input=name
grass.script.run_command("t.rast.line", input, where=None, zones=None, output=None, dpi=None, plot_dimensions=None, error=None, n=None, rotate_labels=None, y_label=None, x_value="mid", fontsize=10, date_interval=None, date_format=None, y_axis_limits=None, line_width=1, line_color="blue", alpha=0.2, nprocs=1, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)
Example:
gs.run_command("t.rast.line", input="name")
Parameters
input=name [required]
Name of the input space time raster dataset
where=sql_query
WHERE conditions of SQL statement without 'where' keyword used in the temporal GIS framework
Example: start_time > '2001-01-01 12:30:00'
zones=name
Zonal raster
Categorical map with zones for which the trend lines need to be drawn.
output=name
Name of output image file.
Name for output file
dpi=integer
DPI
Plot resolution in DPI.
plot_dimensions=string
Plot dimensions (width,height)
Dimensions (width,height) of the figure in inches.
error=string
error bar
Error bar to indicate the error or uncertainty per category. Options are error bar in standard deviations (sd) or standard error (se). Leave empty to ommit the error bar.
Allowed values: sd, se
n=float
multiply sd/se
Width of error bar in terms of number of standard error or standard deviation.
rotate_labels=float
Rotate labels x-axis
Rotate labels (degrees).
Allowed values: -90-90
y_label=string
y-axis label
Define the title on the y-axis
x_value=string
date points
For maps with time intervals, choose to use the start date, end date or date in between these two (default) as x-values.
Allowed values: start, end, mid
Default: mid
fontsize=integer
Font size
Font size of labels.
Default: 10
date_interval=string
Date interval
Set interval for plotting of the dates/times
Allowed values: year, month, week, day, hour, minute
date_format=string
Date format
Set date format (see https://strftime.org/ for options).
y_axis_limits=string
Set value range y-axis
Set the min and max value of y-axis.
line_width=float
Line width
The width of the line(s).
Default: 1
line_color=name
Line color
Color of the line. See manual page for color notation options. Cannot be used together with the zonal raster.
Default: blue
alpha=float
Transparency of the error band.
Allowed values: 0-1
Default: 0.2
nprocs=integer
Number of threads for parallel computing
Default: 1
-g
Add grid lines
Add grid lines.
-l
Legend
Select this if you want to plot the legend. This only works if a cover layer is provided.
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--qq
Very quiet module output
--ui
Force launching GUI dialog
input : str, required
Name of the input space time raster dataset
Used as: input, strds, name
where : str, optional
WHERE conditions of SQL statement without 'where' keyword used in the temporal GIS framework
Example: start_time > '2001-01-01 12:30:00'
Used as: sql_query
zones : str, optional
Zonal raster
Categorical map with zones for which the trend lines need to be drawn.
Used as: input, raster, name
output : str, optional
Name of output image file.
Name for output file
Used as: output, file, name
dpi : int, optional
DPI
Plot resolution in DPI.
plot_dimensions : str, optional
Plot dimensions (width,height)
Dimensions (width,height) of the figure in inches.
error : str, optional
error bar
Error bar to indicate the error or uncertainty per category. Options are error bar in standard deviations (sd) or standard error (se). Leave empty to ommit the error bar.
Allowed values: sd, se
n : float, optional
multiply sd/se
Width of error bar in terms of number of standard error or standard deviation.
rotate_labels : float, optional
Rotate labels x-axis
Rotate labels (degrees).
Allowed values: -90-90
y_label : str, optional
y-axis label
Define the title on the y-axis
x_value : str, optional
date points
For maps with time intervals, choose to use the start date, end date or date in between these two (default) as x-values.
Allowed values: start, end, mid
Default: mid
fontsize : int, optional
Font size
Font size of labels.
Default: 10
date_interval : str, optional
Date interval
Set interval for plotting of the dates/times
Allowed values: year, month, week, day, hour, minute
date_format : str, optional
Date format
Set date format (see https://strftime.org/ for options).
y_axis_limits : str, optional
Set value range y-axis
Set the min and max value of y-axis.
line_width : float, optional
Line width
The width of the line(s).
Default: 1
line_color : str, optional
Line color
Color of the line. See manual page for color notation options. Cannot be used together with the zonal raster.
Used as: input, color, name
Default: blue
alpha : float, optional
Transparency of the error band.
Allowed values: 0-1
Default: 0.2
nprocs : int, optional
Number of threads for parallel computing
Default: 1
flags : str, optional
Allowed values: g, l
g
Add grid lines
Add grid lines.
l
Legend
Select this if you want to plot the legend. This only works if a cover layer is provided.
overwrite: bool, optional
Allow output files to overwrite existing files
Default: False
verbose: bool, optional
Verbose module output
Default: False
quiet: bool, optional
Quiet module output
Default: False
superquiet: bool, optional
Very quiet module output
Default: False
DESCRIPTION
t.rast.line draws trend lines of the average values of the input raster layers in a space-time raster dataset (strds). The trend line represents the average values of the current computational region. The user can optionally show an error bar for each trend line using the error option. The error bar can be based on the standard deviation (SD) or standard error (SE). The user can multiply the SD or SE to increase or decrease the width of the error band using the n option.
If a zonal raster map is provided, using the zones option, trend lines are plotted for each zone (category) in the zonal raster layer. The zonal raster should be a single, static integer raster map.
Trend lines (average ± SD) for three land cover categories of the
FCover for the fraction of green vegetation cover for the period
2014-2019.
The function will plot all rasters in the strds. Alternatively, the user can select a subset of the raster layers using the WHERE conditions.
By default, the resulting plot is displayed on a new screen. However, the user can also save the plot to a file using the output option. The format is determined by the extension given by the user. So, if output = outputfile.png, the plot will be saved as a *png* file. The user can set the output size (in inches) and resolution (dpi).
There are a few plot format and layout options, including the option to plot grid lines and the legend, rotate the labels, change the font size of the labels, and change the date format.
If a zonal map is provided, the lines will take the colors of the categories on that map. If the zonal map does not have a color table, the lines will be assigned random colors.
The default format of the date-time labels on the x-axis depend on the temporal granularity of the data. This can be changed by the user using the date_format option. For a list of options, see the Python strftime cheatsheet.
The where options allows allows performing different selections of maps registered in the space-time datasets. For example, with start_time \< '2020-01-01' the time series is limited to all maps with a start time before the given date. For more details, see this page for more details.
NOTE
The user can specify the number of threads to be used with the nprocs parameter. However, note that parallelization does not work when the MASK is set. If speed is an issue, it is recommended to create a new zonal layer using, e.g., r.mapcalc, remove the MASK and use the newly created zonal layer.
The t.rast.line module operates on the raster array defined by the current region settings, not the original extent and resolution of the input map. See g.region to understand the impact of the region settings on the calculations.
EXAMPLE
The next two examples use the North Carolina full (NC) and North Carolina Climate 2000-2012 data sets, which can be downloaded from (this download page).
First step is to create temporal datasets tempmean and precip_sum for the rainfall and temperature time series respectively, as described in this tutorial. These will serve as input for the examples below. The landclass_96 raster layer in the PERMANENT mapset of the NC project (location) will be used as zonal map.
Example 1
Plot the tempmean time series. Note that you can speed up the process considerably by making use of the cores and threads of your computer. You can set the number of threads to be used with the nprocs option.
g.region raster=2000_01_tempmean
t.rast.line input=tempmean nprocs=10
Example 2
Plot the rainfall time series. Set the color of the line to green, and choose the option to plot an error band based on the standard deviation using the error option.
t.rast.line input=precip_sum error=sd line_color=0:128:0:255 nprocs=10
Example 3
Now, compare the temporal rainfall patterns in the inland Avery County and Brunswick County on the coast. Set the flag -l to include a legend.
# Create a zonal map
echo "11 = 1 Avery
19 = 2 Brunswick
* = NULL" > recl.txt
r.reclass input=boundary_county_500m output=comparison_counties rules=recl.txt
t.rast.line -l input=tempmean zones=comparison_counties error=sd nprocs=10
Because the zonal map does not have a color table, the lines have a random color.
Example 4
If you want the colors of the trend lines to match the color of the zonal categories, make sure to define the category colors.
# Define colors
echo "1 purple
2 green"> color_rules.txt
r.colors map=comparison_counties rules=color_rules.txt
# Create the plot
t.rast.line -l -g input=tempmean zones=comparison_counties error=sd nprocs=10
Whether this was the right color choice is debatable, but, the colors of the graph match those of the zones of the map. Note that with the g flag, vertical grid lines are drawn.
Example 5
You can zoom in on a specific period using the where option. For example, to plot the trend line for the time period 01-01-2004 to 01-01-2010, you can use the following:
t.rast.line -l -g input=tempmean zones=comparison_counties error=sd nprocs=10 \
where="start_time > '2004-01-01 00:00:00' AND start_time < '2010-01-01'"
When using greater than (>), the date alone is not enough, also also the time needs to be set explicitly. This is not needed when using smaller than (\<).
Example 6
If you want to create and compare two plots, it might be useful to force both to use a specific scale by using the y_axis_limits parameter and the same y-axis label by using the y_label parameter.
t.rast.line -l -g input=tempmean \
zones=comparison_counties error=sd nprocs=10 \
y_axis_limits=-10,40 y_label="mean temperature"
Acknowledgements
This work was carried out within the framework of the Save the Tiger, Save the Grassland, Save the Water project by the Innovative Bio-Monitoring research group of the HAS University of Applied Sciences.
SEE ALSO
r.boxplot, r.boxplot, r.series.boxplot, d.vect.colbp, r.scatterplot, r.stats.zonal,
AUTHOR
Paulo van Breugel
Applied Geo-information Sciences
HAS green academy, University of Applied
Sciences
SOURCE CODE
Available at: t.rast.line source code
(history)
Latest change: Thursday Feb 20 13:02:26 2025 in commit 53de819