Skip to content

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 [-honrg] 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=string] [flier_color=name] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

v.boxplot map=name column=name

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", flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

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 (width,height)
    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 boxlot 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=string
    Flier size
    Set the flier size
    Default: 2
flier_color=name
    Flier color
    Set the flier color
    Default: black
-h
    horizontal boxplot(s)
    Draw the boxplot horizontal
-o
    Include outliers
    Draw boxplot(s) with outliers
-n
    notch
    Draw boxplot(s) with notch
-r
    Rotate labels
    rotate x-axis labels
-g
    Add grid lines
    Add grid lines
--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 (width,height)
    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 boxlot 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 : str, 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
flags : str, optional
    Allowed values: h, o, n, r, g
    h
        horizontal boxplot(s)
        Draw the boxplot horizontal
    o
        Include outliers
        Draw boxplot(s) with outliers
    n
        notch
        Draw boxplot(s) with notch
    r
        Rotate labels
        rotate x-axis labels
    g
        Add grid lines
        Add grid lines
overwrite: bool, optional
    Allow output files to overwrite existing files
    Default: False
verbose: bool, optional
    Verbose module output
    Default: False
quiet: bool, optional
    Quiet module output
    Default: False
superquiet: bool, optional
    Very quiet module output
    Default: False

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.

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.

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"

image-alt
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

image-alt
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

SOURCE CODE

Available at: v.boxplot source code (history)
Latest change: Thursday Feb 20 13:02:26 2025 in commit 53de819