v.boxplot - GRASS manual

NAME

v.boxplot - Draws a boxplot of values from a specified attribute column in a vector dataset, with an optional grouping based on categories in another column.

KEYWORDS

display, vector, plot, histogram, boxplot

SYNOPSIS

v.boxplot

v.boxplot --help

v.boxplot [-hnrgo] map=name [layer=string] column=name [group_by=name] [where=sql_query] [output=name] [plot_dimensions=string] [dpi=integer] [fontsize=integer] [order=string] [axis_limits=string] [bx_color=name] [bx_blcolor=name] [bx_width=float] [bx_lw=float] [median_lw=float] [median_color=name] [flier_marker=string] [flier_size=float] [flier_color=name] [map_outliers=name] [overlap_basis=string] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-h: horizontal boxplot(s); Draw the boxplot horizontal
-n: notch; Draw boxplot(s) with notch
-r: Rotate labels; rotate x-axis labels
-g: Add grid lines; Add grid lines
-o: Include outliers; Draw boxplot(s) with outliers
--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:

map=name [required]: Name of vector map; Or data source for direct OGR access
layer=string: Layer number or name; Vector features can have category values in different layers. This number determines which layer to use. When used with direct OGR access this is the layer name.; Default: 1
column=name [required]: Attribute column value to be plotted
group_by=name: Attribute column with categories to group the data by
where=sql_query: WHERE conditions of SQL statement without 'where' keyword; Example: income < 1000 and population >= 10000
output=name: Name of output image file; Name for output file
plot_dimensions=string: Plot dimensions; Dimensions (width,height) of the figure in inches
dpi=integer: DPI; resolution of plot; Default: 100
fontsize=integer: Font size; Default font size; Default: 10
order=string: Sort boxplots; Sort boxplots based on their median values; Options: descending, ascending
axis_limits=string: Limit value axis [min,max]; min and max value of y-axis, or x-axis if -h flag is set)
bx_color=name: Color of the boxplots; Color of boxplots; Default: white
bx_blcolor=name: Color of the borders of the boxplots; Color of the borderlines of the boxplots; Default: black
bx_width=float: Boxplot width; The width of the boxplots (0,1]); Options: 0.1-1; Default: 0.75
bx_lw=float: boxplot linewidth; The boxplots border, whisker and cap line width; Default: 1
median_lw=float: width of the boxplot median line; Default: 1.1
median_color=name: Color of the boxplot median line; Color of median; Default: orange
flier_marker=string: Flier marker; Set flier marker (see https://matplotlib.org/stable/api/markers_api.html for options); Default: o
flier_size=float: Flier size; Set the flier size; Default: 2
flier_color=name: Flier color; Set the flier color; Default: black
map_outliers=name: Vector map with the outliers; Create a vector map with the outlier features, classified by how many other groups they overlap with (n_overlap), on which side and how far they lie from their own group (side, iqr_dist), with matching colors in a GRASSRGB column.
overlap_basis=string: Overlap basis; Range of the other groups an outlier is checked against to count overlaps: whisker (within the other group's whiskers/fences) or box (within its interquartile box); Options: whisker, box; Default: whisker

DESCRIPTION
- appearance
- Outlier map
NOTE
EXAMPLE
- Example 1
- Example 2
SEE ALSO
AUTHOR

DESCRIPTION

The v.boxplot module draws a boxplot of the values in a vector map attribute column. Users can use the where option to select a subset of the attribute table. Values in the column can also be grouped according to the categories in another column (group_by), creating separate boxplots for each group.

appearance

Options to customize the appearance of the plot include rotating the plot and x-axis labels, adding notches, removing outliers, and defining the colors of various boxplot components. By default, the resulting plot is displayed on the screen. However, users can save the plot to a file by specifying the desired width, height, and resolution. The format of the saved file is determined by the provided file extension. For example, if plot_output = outputfile.png, the plot will be saved as a PNG file.

Outlier map

Setting outliers_map creates a vector map with only features whose column value is a boxplot outlier. With group_by, outliers are computed separately per group. The output keeps the original attributes and adds:

side: low or high outlier.
iqr_dist: signed distance beyond the relevant fence, in IQR units.
n_overlap: number of other groups whose value range contains the outlier.
GRASSRGB: color string; high outliers are red, low outliers blue. More exceptional values are darker and more saturated.

The overlap_basis defines the comparison range. With whisker, outliers are compared with other groups non-outlier range, between fences. With box, they are only compared with other groups interquartile range, Q1-Q3.

NOTE

The outlier map is created in addition to the plot; both are derived from the same selection, so the exported outliers always match those shown in the figure. If the selection contains no outliers, the map is not created and a warning is issued.

EXAMPLE

Example 1

Use the vector layer schools_wake from the NC sample dataset to create boxplots of the core capacity of schools in Wake County, North Carolina. Use the Where clause to exclude all records with no data. Use the -o flag to draw outliers.

v.boxplot -n -o map=schools_wake column=CORECAPACI where="CORECAPACI >0"

v.boxplot: Boxplot of core capacity of
schools in Wake County.

Figure 1: Boxplot of core capacity of schools in Wake County.

Example 2

Use the vector layer schools_wake from the NC sample dataset to create boxplots of the core capacity of the schools in Wake County, North Carolina, grouped by city. Use the Where clause to exclude all records with missing data. Use the -o flag to draw outliers.

v.boxplot -h -o map=schools_wake column=CORECAPACI where="CORECAPACI >0" group_by=ADDRCITY order=ascending

v.boxplot:
Boxplot of core capacity of schools in Wake County, grouped by city

Figure 2: Boxplot of core capacity of schools in Wake County, grouped by city.

AUTHOR

Paulo van Breugel, HAS green academy, Innovative Biomonitoring research group, Climate-robust Landscapes research group

SOURCE CODE

Available at: v.boxplot source code (history)

Latest change: Thursday May 28 23:11:58 2026 in commit: 1b9adc940f57eb078fd7dd727423679ada24b232