GRASS logo

NAME

r.boxplot - Draws the boxplot of raster values. Optionally, this is done per category of a zonal raster layer

KEYWORDS

display, raster, plot, boxplot

SYNOPSIS

r.boxplot
r.boxplot --help
r.boxplot [-onhrcs] input=name [zones=name] [output=name] [map_outliers=string] [range=float] [order=string] [fontsize=integer] [plot_dimensions=string] [dpi=integer] [boxplot_width=float] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-o
include outliers
Draw boxplot(s) with outliers
-n
notch
Draw boxplot(s) with notch
-h
horizontal boxplot(s)
Draw the boxplot horizontal
-r
rotate labels
rotate labels
-c
Color boxploxs
Color boxploxs using the colors of the categories of the zonal raster
-s
Show category numbers
Show the category numbers of the zonal map
--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 raster
input raster
zones=name
zonal raster
categorical map with zones
output=name
Name of output image file
Name for output file
map_outliers=string
Name of outlier map
Create a vector point layer of outliers
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
order=string
Sort boxplots
Sort boxplots based on their median values
Options: descending, ascending
fontsize=integer
Font size
Default font size
plot_dimensions=string
Plot dimensions (width,height)
Dimensions (width,height) of the figure in inches
dpi=integer
DPI
resolution of plot
boxplot_width=float
boxplot width
The width of the boxplots (0,1])

Table of contents

DESCRIPTION

r.boxplot draws boxplots of the raster values of a input raster layer. The user has the option to define a zonal (categorical) layer. In that case, a boxplot will be drawn for each zone, using the values of the input raster that fall within that zone.

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 whiskers 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.

By default, outliers are not included in the plot. Set the -o flag to include them in the plot. To also create a point vector map with the locations of the outliers, the user needs to provide the name of the output map using map_outliers.

There are a few layout options, including the option to rotate the plot and the x-axis labels, print the boxplot(s) with notches, sort the boxplot from low to high (ascending) or from high to low (descending) median, color the boxplots according to the corresponding categories of the zonal raster, and set the width of the boxplots.

NOTE

To include outliers, the function converts the raster cell with outlier values to a point vector layer. This may take some time if there are a lot of outliers. So, if you are working with very large raster layers, be cautious to not set the range value very low as that may result in a very large number of outliers.

The zonal map needs to be an integer map. If it is not, the function will exit with the error message, 'The zonal raster must be of type CELL (integer)'.

The option to color boxploxs using the colors of the categories of the zonal raster (-c flag) only works if the zonal map contains a color table. If it does not, the function exits with the error message that 'The zonal map does not have a color table'. If you think there is a color table, run r.colors.out and check if the categories are integers. If not, that is the problem. If they are all integers, you probably have catched a bug.

EXAMPLE

Example 1

Draw a boxplot of the values of the elevation layer from the NC sample dataset. Set the -h flag to print the boxplot horizontally. Set the plot dimensions to 7 inch wide, 1 inch heigh.
g.region raster=elevation
r.boxplot -h input=elevation plot_dimensions="7,1" output="r_boxplot_01.png"


Example 2

Draw boxplots of the values of the elevation layer per category from the landclass96 layer from the same NC sample dataset. Use the -r flag to rotate the x-asis labels.
r.boxplot -r input=elevation zone=landclass96 output="r_boxplot_02.png" 


Example 3

Draw boxplots of the values of the elevation layer per category from the landclass96 layer from the same NC sample dataset. Set the -o flag to include outliers. Use order=ascending to order the boxplots from low to high median. Provide a name for the outlier map to save the outlier locations as a point vector map.
r.boxplot -o order=ascending input=elevation zones=landclass96 output="r_boxplot_03.png" map_outliers="outliers"


Below, part of the landclass96 raster map is shown, with on top the vector point layer with location of outliers. Curiously, for some lakes, only part of the raster cells are outliers.


Example 4

Draw boxplots of the values of the elevation layer per category from the landclass96 layer from the same NC sample dataset. Set the -c flag to color the boxplots, use order=ascending to order the boxplots from low to high median, and set the fontsize to 11.
r.boxplot -c order=ascending fontsize=11 input=elevation zones=landclass96 output="r_boxplot_04.png"


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.

SEE ALSO

r.scatterplot, r.stats.zonal, d.vect.colbp

AUTHOR

Paulo van Breugel
Applied Geo-information Sciences
HAS University of Applied Sciences

SOURCE CODE

Available at: r.boxplot source code (history)

Latest change: Friday May 27 16:14:44 2022 in commit: 1d45d0d9c397f8addce0c7eec8a3131277785943


Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

© 2003-2022 GRASS Development Team, GRASS GIS 8.2.0 Reference Manual