t.rast.boxplot
Draws the boxplot of the raster maps of a space-time raster dataset
t.rast.boxplot [-onhgd] input=name [output=File name] [dpi=integer] [range=float] [plot_dimensions=string] [rotate_labels=float] [font_size=integer] [date_format=string] [axis_limits=string] [bx_width=float] [bx_color=name] [bx_lw=float] [median_lw=float] [median_color=name] [whisker_linewidth=float] [flier_marker=string] [flier_size=string] [flier_color=name] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]
Example:
t.rast.boxplot input=name
grass.script.run_command("t.rast.boxplot", input, output=None, dpi=None, range=1.5, plot_dimensions=None, rotate_labels=None, font_size=10, date_format=None, axis_limits=None, bx_width=None, bx_color="white", bx_lw=1, median_lw=1.1, median_color="orange", whisker_linewidth=1, flier_marker="o", flier_size="2", flier_color="black", flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)
Example:
gs.run_command("t.rast.boxplot", input="name")
Parameters
input=name [required]
input space-time raster dataset
output=File name
Name of output image file
Name for output file
dpi=integer
DPI
Resolution of plot
range=float
Range (value > 0)
This determines how far the plot whiskers extend out from the box. If range is positive, the whiskers extend to the most extreme data point which is no more than range times the interquartile range from the box. A value of zero causes the whiskers to extend to the data extremes.
Default: 1.5
plot_dimensions=string
Plot dimensions (width,height)
Dimensions (width,height) of the figure in inches
rotate_labels=float
Rotate labels
Rotate labels (degrees)
Allowed values: -90-90
font_size=integer
Font size
Font size of labels
Default: 10
date_format=string
Date format
Set date format (see https://strftime.org/ for options)
axis_limits=string
limit value axis
min and max value of y-axis, or x-axis if -h flag is set)
bx_width=float
Boxplot width
The width of the boxplots
bx_color=name
Boxplot color
Color of the boxplots. See manual page for color notation options.
Default: white
bx_lw=float
boxplot linewidth
The linewidth of the boxplots
Default: 1
median_lw=float
width of the boxplot median line
Default: 1.1
median_color=name
Color of the boxlot median line
Color of median
Default: orange
whisker_linewidth=float
Whisker and cap linewidth
The linewidth of the whiskers and caps
Default: 1
flier_marker=string
Flier marker
Set flier marker (see https://matplotlib.org/stable/api/markers_api.html for options)
Default: o
flier_size=string
Flier size
Set the flier size
Default: 2
flier_color=name
Flier color
Set the flier color
Default: black
-o
Include outliers
Draw boxplot(s) with outliers
-n
Draw notch
Draw boxplot(s) with notch
-h
Horizontal boxplot(s)
Draw the boxplot horizontal
-g
Add grid lines
Add grid lines
-d
ConciseDateFormatter
Us date format as compact as possible while still having complete date information. This will override the data_format setting.
--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
input space-time raster dataset
Used as: input, strds, name
output : str, optional
Name of output image file
Name for output file
Used as: output, file, File name
dpi : int, optional
DPI
Resolution of plot
range : float, optional
Range (value > 0)
This determines how far the plot whiskers extend out from the box. If range is positive, the whiskers extend to the most extreme data point which is no more than range times the interquartile range from the box. A value of zero causes the whiskers to extend to the data extremes.
Default: 1.5
plot_dimensions : str, optional
Plot dimensions (width,height)
Dimensions (width,height) of the figure in inches
rotate_labels : float, optional
Rotate labels
Rotate labels (degrees)
Allowed values: -90-90
font_size : int, optional
Font size
Font size of labels
Default: 10
date_format : str, optional
Date format
Set date format (see https://strftime.org/ for options)
axis_limits : str, optional
limit value axis
min and max value of y-axis, or x-axis if -h flag is set)
bx_width : float, optional
Boxplot width
The width of the boxplots
bx_color : str, optional
Boxplot color
Color of the boxplots. See manual page for color notation options.
Used as: input, color, name
Default: white
bx_lw : float, optional
boxplot linewidth
The linewidth of the boxplots
Default: 1
median_lw : float, optional
width of the boxplot median line
Default: 1.1
median_color : str, optional
Color of the boxlot median line
Color of median
Used as: input, color, name
Default: orange
whisker_linewidth : float, optional
Whisker and cap linewidth
The linewidth of the whiskers and caps
Default: 1
flier_marker : str, optional
Flier marker
Set flier marker (see https://matplotlib.org/stable/api/markers_api.html for options)
Default: o
flier_size : str, optional
Flier size
Set the flier size
Default: 2
flier_color : str, optional
Flier color
Set the flier color
Used as: input, color, name
Default: black
flags : str, optional
Allowed values: o, n, h, g, d
o
Include outliers
Draw boxplot(s) with outliers
n
Draw notch
Draw boxplot(s) with notch
h
Horizontal boxplot(s)
Draw the boxplot horizontal
g
Add grid lines
Add grid lines
d
ConciseDateFormatter
Us date format as compact as possible while still having complete date information. This will override the data_format setting.
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.boxplot draws boxplots of the raster in a space-time raster data set (strds). The module can be used to display changes over time, and how this varies within a area. It will plot all rasters in a strds. To display a subset of a strds, the user first needs to create a new strds with the required subset of raster layers. It will furthermore, plot the boxplots using the temporal granularity of the strds.
The whiskers of the boxplots extend to the most extreme data point, which is no more than range ✕ the interquartile range (iqr) from the box. By default, a range of 1.5 is used, but the user can change this. Note that range values need to be larger than 0.
There are a few plot format/layout options, including the option to rotate the plot and the x-axis labels, print the boxplot(s) with notches, and to include the outliers (by default, they are not included). You can also set the limits of the y-axis (or the x-axis if the -h flag is set). This makes it easier to compare the boxplots of two time-series of, e.g., two different areas.
There are various options to format the boxplots, e.g., setting the width and color of the boxplots, the color and thickness of the median line(s), whisker line width, and flier marker type and color.
The default format of the date-time labels on the x-axis (or y-axis in case the boxplots are plotted horizontally) depend on the temporal granularity of the data. This can be changed by the user. For a list of options, see the Python strftime cheatsheet.
Alternatively, the user can set the d flag. With this option, an attempt is made to figure out the best tick locations and format to use, and to make the format as compact as possible while still having complete date information. Note, this will override the data_format setting. With this option, often not all boxplots will get a label.
By default, the resulting plot is displayed on screen. However, the user can also save the plot to 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) of the output image.
NOTE
If you work with a large number of raster layers, or if the raster layers are very large, try to avoid setting the range value very low, as that may result in a massive number of outliers, slowing down the computations and rendering of the plot.
The t.rast.boxplot 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.
You can change the width of the boxplot using the bx_width parameter. The default value is 0.75, which means that the boxplot is 0.75 the maximum width between two consecutive periods. Importantly, the function uses the time stamp unit (see t.register) to determine the maximum width. This means that if the time stamp unit is in days, but the raster layers represent e.g., 10-day periods, you need to multiply the bx_width value you would normally use by 10 to get the same relative width. See this post for an example.
EXAMPLE
The first two examples use the MODIS Land Surface Temperature mapset. First download the North Carolina sample data set from this link. Unzip the sample GRASS GIS dataset to a convenient location on your computer. Next, download the MODIS LST mapset and unzip it within the NC project. Now, open the mapset in GRASS GIS.
Example 1
Plot the time series, using the default settings, except that we set the dimension of the plot to 12 inch (ca. 30 cm) wide and 8 inch (ca. 20 cm) height, and a dpi of 200
g.region raster=landclass96
t.rast.boxplot input=LST_Day_monthly@modis_lst \
plot_dimensions=12,8 dpi=200
Example 2
We use the same example as above, but this time, we change the color of the boxplots and median lines to respectively green (bx_color=green) and white (median_color=white), use the default plot dimensions, set the font size to 8, and include the outliers (o flag). Note that by plotting the outliers will increase the time required to create the plot considerably.
For the outliers (fliers) we use orange squares (flier_marker=s & flier_color=orange). We furthermore plot the boxplots horizontally (h flag) and add grid lines (g flag). Note that for horizontal plots, the labels are plotted horizontally (equal to rotate_labels=0) by default.
t.rast.boxplot -o -h -g input=LST_Day_monthly@modis_lst \
bx_color=green median_color=white median_lw=0.8 bx_lw=0.8 \
flier_color=orange flier_size=1 flier_marker=s font_size=8
See here for the different formats in which colors can be specified.
Example 3
In the following example, the date labels are changed, showing the abbreviated name of the month, followed by the year (date_format="%B %Y"). The boxplot colors are set to white, and for the median line we set the color to orange and the line width to 2. Lastly, the labels are rotated 90℃ (the default for vertical plots is rotate_labels=45).
t.rast.boxplot input=LST_Day_monthly@modis_lst rotate_labels=90 \
date_format="%B %Y" bx_color=white median_lw=2 median_color=red \
font_size=9
Example 4
If we want to plot 3-monthly patterns instead, we first need to create a new strds. In the example below, the function t.rast.aggregate is used to aggregate the LST_Day_monthly to a 3 month granularity.
t.rast.aggregate input=LST_Day_monthly@modis_lst output=LST_Day_3monthly \
basename=LST_3monthly granularity="3 months" method=average
Now, we can plot the 3-monthly temporal pattern using the newly created strds as input.
t.rast.boxplot input=LST_Day_3monthly@modis_lst
As you can see below, the plot plots the boxplots using the 3-month granularity of the input strds.
Acknowledgements
This work was carried in 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.series.boxplot, d.vect.colbp, r.scatterplot, r.stats.zonal, t.rast.aggregate
AUTHOR
Paulo van Breugel
Applied Geo-information Sciences
HAS University of Applied Sciences
SOURCE CODE
Available at: t.rast.boxplot source code
(history)
Latest change: Thursday Feb 20 13:02:26 2025 in commit 53de819