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.
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] [--verbose] [--quiet] [--qq] [--ui]
Example:
v.boxplot map=name column=name
grass.tools.Tools.v_boxplot(map, layer="1", column, group_by=None, where=None, output=None, plot_dimensions=None, dpi=100, fontsize=10, order=None, axis_limits=None, bx_color="white", bx_blcolor="black", bx_width=0.75, bx_lw=1, median_lw=1.1, median_color="orange", flier_marker="o", flier_size=2, flier_color="black", map_outliers=None, overlap_basis="whisker", flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
tools = Tools()
tools.v_boxplot(map="name", column="name")
This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.
grass.script.run_command("v.boxplot", map, layer="1", column, group_by=None, where=None, output=None, plot_dimensions=None, dpi=100, fontsize=10, order=None, axis_limits=None, bx_color="white", bx_blcolor="black", bx_width=0.75, bx_lw=1, median_lw=1.1, median_color="orange", flier_marker="o", flier_size=2, flier_color="black", map_outliers=None, overlap_basis="whisker", flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
gs.run_command("v.boxplot", map="name", column="name")
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
Allowed values: 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])
Allowed values: 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)
Allowed values: whisker, box
Default: whisker
-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
--qq
Very quiet module output
--ui
Force launching GUI dialog
map : str, required
Name of vector map
Or data source for direct OGR access
Used as: input, vector, name
layer : str, optional
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.
Used as: input, layer
Default: 1
column : str, required
Attribute column value to be plotted
Used as: input, dbcolumn, name
group_by : str, optional
Attribute column with categories to group the data by
Used as: input, dbcolumn, name
where : str, optional
WHERE conditions of SQL statement without 'where' keyword
Example: income < 1000 and population >= 10000
Used as: input, sql_query, sql_query
output : str, optional
Name of output image file
Name for output file
Used as: output, file, name
plot_dimensions : str, optional
Plot dimensions
Dimensions (width,height) of the figure in inches
dpi : int, optional
DPI
resolution of plot
Default: 100
fontsize : int, optional
Font size
Default font size
Default: 10
order : str, optional
Sort boxplots
Sort boxplots based on their median values
Allowed values: descending, ascending
axis_limits : str, optional
Limit value axis [min,max]
min and max value of y-axis, or x-axis if -h flag is set)
bx_color : str, optional
Color of the boxplots
Color of boxplots
Used as: input, color, name
Default: white
bx_blcolor : str, optional
Color of the borders of the boxplots
Color of the borderlines of the boxplots
Used as: input, color, name
Default: black
bx_width : float, optional
Boxplot width
The width of the boxplots (0,1])
Allowed values: 0.1-1
Default: 0.75
bx_lw : float, optional
boxplot linewidth
The boxplots border, whisker and cap line width
Default: 1
median_lw : float, optional
width of the boxplot median line
Default: 1.1
median_color : str, optional
Color of the boxplot median line
Color of median
Used as: input, color, name
Default: orange
flier_marker : str, optional
Flier marker
Set flier marker (see https://matplotlib.org/stable/api/markers_api.html for options)
Default: o
flier_size : float, 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
map_outliers : str, optional
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.
Used as: output, vector, name
overlap_basis : str, optional
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)
Allowed values: whisker, box
Default: whisker
flags : str, optional
Allowed values: h, n, r, g, o
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 : bool, optional
Allow output files to overwrite existing files
Default: None
verbose : bool, optional
Verbose module output
Default: None
quiet : bool, optional
Quiet module output
Default: None
superquiet : bool, optional
Very quiet module output
Default: None
Returns:
result : grass.tools.support.ToolResult | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned.
Raises:
grass.tools.ToolError: When the tool ended with an error.
map : str, required
Name of vector map
Or data source for direct OGR access
Used as: input, vector, name
layer : str, optional
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.
Used as: input, layer
Default: 1
column : str, required
Attribute column value to be plotted
Used as: input, dbcolumn, name
group_by : str, optional
Attribute column with categories to group the data by
Used as: input, dbcolumn, name
where : str, optional
WHERE conditions of SQL statement without 'where' keyword
Example: income < 1000 and population >= 10000
Used as: input, sql_query, sql_query
output : str, optional
Name of output image file
Name for output file
Used as: output, file, name
plot_dimensions : str, optional
Plot dimensions
Dimensions (width,height) of the figure in inches
dpi : int, optional
DPI
resolution of plot
Default: 100
fontsize : int, optional
Font size
Default font size
Default: 10
order : str, optional
Sort boxplots
Sort boxplots based on their median values
Allowed values: descending, ascending
axis_limits : str, optional
Limit value axis [min,max]
min and max value of y-axis, or x-axis if -h flag is set)
bx_color : str, optional
Color of the boxplots
Color of boxplots
Used as: input, color, name
Default: white
bx_blcolor : str, optional
Color of the borders of the boxplots
Color of the borderlines of the boxplots
Used as: input, color, name
Default: black
bx_width : float, optional
Boxplot width
The width of the boxplots (0,1])
Allowed values: 0.1-1
Default: 0.75
bx_lw : float, optional
boxplot linewidth
The boxplots border, whisker and cap line width
Default: 1
median_lw : float, optional
width of the boxplot median line
Default: 1.1
median_color : str, optional
Color of the boxplot median line
Color of median
Used as: input, color, name
Default: orange
flier_marker : str, optional
Flier marker
Set flier marker (see https://matplotlib.org/stable/api/markers_api.html for options)
Default: o
flier_size : float, 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
map_outliers : str, optional
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.
Used as: output, vector, name
overlap_basis : str, optional
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)
Allowed values: whisker, box
Default: whisker
flags : str, optional
Allowed values: h, n, r, g, o
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 : bool, optional
Allow output files to overwrite existing files
Default: None
verbose : bool, optional
Verbose module output
Default: None
quiet : bool, optional
Quiet module output
Default: None
superquiet : bool, optional
Very quiet module output
Default: None
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:
loworhighoutlier. - 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.
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.
n_overlap is the number of other groups whose value range contains the outlier’s value. It distinguishes outliers that are exceptional relative to all groups (n_overlap = 0) from those that are unusual only within their own group (n_overlap > 0). For predicted classes, n_overlap > 0 marks features that may be difficult to classify because their values are typical of one or more other classes. In contrast, n_overlap = 0 marks values distinct from every other class. Mapping n_overlap therefore shows where class ambiguity is geographically concentrated.
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"
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
Figure 2: Boxplot of core capacity of schools in Wake County, grouped
by city.
SEE ALSO
v.scatterplot, d.vect.colhist, r.boxplot, r.series.boxplot, t.rast.boxplot, r.scatterplot r3.scatterplot
AUTHOR
Paulo van Breugel, HAS green academy, Innovative Biomonitoring research group, Climate-robust Landscapes research group