NAME
t.rast.boxplot - Draws the boxplot of the raster maps of a space-time raster dataset
KEYWORDS
display,
raster,
plot,
boxplot,
statistics
SYNOPSIS
t.rast.boxplot
t.rast.boxplot --help
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] [--help] [--verbose] [--quiet] [--ui]
Flags:
- -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
- --ui
- Force launching GUI dialog
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)
- Options: -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
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.
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.
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.
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
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.
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
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.
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.
r.boxplot,
r.series.boxplot,
d.vect.colbp,
r.scatterplot,
r.stats.zonal,
t.rast.aggregate
Paulo van Breugel
Applied Geo-information Sciences
HAS University of Applied
Sciences
SOURCE CODE
Available at:
t.rast.boxplot source code
(history)
Latest change: Monday Jun 24 08:16:48 2024 in commit: 8939a985d18de5366340b88037ab0fe3a0814c9b
Main index |
Temporal index |
Topics index |
Keywords index |
Graphical index |
Full index
© 2003-2024
GRASS Development Team,
GRASS GIS 8.4.1dev Reference Manual