r.boxplot.html

<h2>DESCRIPTION</h2>

<p>
<em>r.boxplot</em> 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.

<p>
By default, the resulting plot is displayed on screen. 
However, the user can also save the plot to file using the 
<em>output</em> 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.

<p>
The whiskers extend to the most extreme data point, which is no more than
<i>range</i> &#10005; the interquartile range (iqr) from the box. By default,
a <i>range</i> of 1.5 is used, but the user can change this. Note that range
values need to be larger than 0.

<p>
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
<i>map_outliers</i>.

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


<h2>NOTE</h2>
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 <i>range</i> value very low as that may result
in a very large number of outliers. 

<p>
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)'.

<p>
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 
<i>r.colors.out</i> and check if the categories are integers. If not, that
is the problem. If they are all integers, you probably have catched a bug.

<h2>EXAMPLE</h2>

<h3>Example 1</h3>
Draw a boxplot of the values of the <em>elevation</em> layer from the  
<a href="https://grass.osgeo.org/download/data/">NC sample 
dataset</a>. Set the -h flag to print the boxplot horizontally. Set the plot
dimensions to 7 inch wide, 1 inch heigh.

<div class="code"><pre>
g.region raster=elevation
r.boxplot -h input=elevation plot_dimensions="7,1" output="r_boxplot_01.png"
</pre>
</div><br>

<p>
<img src="r_boxplot_01.png"><br>

<h3>Example 2</h3>
Draw boxplots of the values of the <em>elevation</em> layer per category from
the <i>landclass96</i> layer from the same 
<a href="https://grass.osgeo.org/download/data/">NC sample 
dataset</a>. Use the -r flag to rotate the x-asis labels.

<div class="code"><pre>
r.boxplot -r input=elevation zone=landclass96 output="r_boxplot_02.png" 
</pre>
</div><br>

<p>
<img src="r_boxplot_02.png"><br>

<h3>Example 3</h3>
Draw boxplots of the values of the <em>elevation</em> layer per category from
the <i>landclass96</i> layer from the same 
<a href="https://grass.osgeo.org/download/data/">NC sample 
dataset</a>. 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.

<div class="code"><pre>
r.boxplot -o order=ascending input=elevation zones=landclass96 output="r_boxplot_03.png" map_outliers="outliers"
</pre>
</div><br>

<p>
<img src="r_boxplot_03.png"><br>

<p>
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.</p>

<p>
<img src="r_boxplot_map_03.png"><br>

<h3>Example 4</h3>
Draw boxplots of the values of the <em>elevation</em> layer per category from
the <i>landclass96</i> layer from the same 
<a href="https://grass.osgeo.org/download/data/">NC sample 
dataset</a>. 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. 

<div class="code"><pre>
r.boxplot -c order=ascending fontsize=11 input=elevation zones=landclass96 output="r_boxplot_04.png"
</pre>
</div><br>

<p>
<img src="r_boxplot_04.png"><br>


<h2>Acknowledgements</h2>
This work was carried in the framework of the <a href="https://savethetiger.nl/" target="_blank">Save the tiger, save the grassland, save the water</a> 
project by the 
<a href="https://www.has.nl/en/has-research/research-groups/innovative-bio-monitoring-research-group" target="_blank">Innovative Bio-Monitoring research group</a>.  
  
<h2>SEE ALSO</h2> 

<em>
<a href="https://grass.osgeo.org/grass-stable/manuals/addons/r.scatterplot.html">r.scatterplot</a>,
<a href="https://grass.osgeo.org/grass-stable/manuals/r.stats.zonal.html">r.stats.zonal</a>,
<a href="https://grass.osgeo.org/grass-stable/manuals/addons/d.vect.colbp.html">d.vect.colbp</a> 
</em> 

<h2>AUTHOR</h2>

Paulo van Breugel<br>
Applied Geo-information Sciences<br>
<a href="https://www.hasuniversity.nl/">HAS University of Applied Sciences</a><br>