StatisticalPlots.pl - A macro to create statistical plots to include in PG problems.
This macro includes a number of methods to include statistical plots in PG problems. This is based on plots.pl which will draw using either TikZ (default for hardcopy) or JSXGraph (default for HTML).
The statistical plots that are available are
Create a StatPlot object with
loadMacros('StatisticalPlots.pl');
$statPlot = StatPlot(
xmin => -1,
xmax => 8,
ymin => -1.5,
ymax => 10,
xtick_delta => 1,
ytick_delta => 4,
aria_label => 'Bar plot of a set of data'
);The StatPlot method accepts all of the same options that the Plot method from the plots.pl macro accepts.
After a StatPlot object is created then specific plots can be added to the axes. For example,
$statPlot->add_barplot(
[ 1 .. 6 ],
[3, 6, 7, 8, 4, 1],
fill_color => 'yellow',
stroke_width => 1,
bar_width => 0.9
);will add a bar plot to the axes. See below for more details about creating a bar plot.
The following plots are available to add to a StatPlot object.
A bar plot can be added with the add_barplot method. The general form is
$statPlot->add_barplot($xdata, $ydata, %opts);This adds a bar plot with bars centered at the coordinates in the array referenced to by $xdata and heights in the array referenced to by $ydata.
The following options which are specific to configuring the bar plot can be passed in addition to any of the dataset options accepted by the add_rectangle method which draws the bars (see dataset options).
This can be either 'vertical' (default) or 'horizontal' to create vertical or horizontal bars. An example with horizontal bars was given above, and the following is an example with with vertical bars
$statPlot->add_barplot(
[3, 6, 7, 8, 4, 1],
[ 1 .. 6 ],
orientation => 'horizontal',
fill_color => 'yellow',
stroke_width => 1,
bar_width => 0.9
);This is a number from 0 to 1 that specifies the width of the bars as a fraction of the distance between the bar base coordinates (the x-coordinates for a vertical bar plot or the y-coordinates for a horizontal bar plot). If bar_width => 1 (the default), then the bar width will be the distance between the bar base coordinates (and so there is no gap between bars). In the example above, with bar_width => 0.9 the bar width will be 90% of the distance between the bar base coordinates.
This sets the color of the bar borders. It is an alias for the color dataset option option of the add_rectangle method. See color options for more details on specifying colors.
This sets the width of the rectangle borders. This is an alias for the width dataset option.
This is either the name of a color palette, a reference to an array of colors, or a reference to a hash containing the name of a color palette (palette_name) and number of colors to generate (num_colors) (see "COLOR PALETTES" for more information). If this is a reference to an array and the length of the array is smaller than the number of data values in the array referenced to by $data, then the colors will be cycled.
If fill_color is included in the list of options, this will apply the same color to each bar. If neither fill_color nor fill_colors is included, then the 'rainbow' palette will be used as default.
For example,
fill_colors => 'rainbow'
fill_colors => ['green', 'OliveGreen', 'DarkGreen', 'ForestGreen', 'PineGreen']
fill_colors => { palette_name => 'random', num_colors => 7 }An histogram can be added to a StatPlot with the add_histogram method. The general form is
$statPlot->add_histogram($data, %options);where $data is a reference to an array of univariate data. The %options parameter includes options for the histogram such as the number of bins as well as options for drawing the bars.
The following example generates a data set using the urand function which produces a random set of normally distributed data values, and constructs a histogram for that data set.
loadMacros('StatisticalPlots.pl', 'PGstatisticsmacros.pl');
$statPlot = StatPlot(
xmin => 0,
xmax => 65,
ymin => 0,
ymax => 12,
xtick_delta => 10,
ytick_delta => 2
);
$statPlot->add_histogram(
[ urand(30, 9, 50, 6) ],
min => 10,
max => 60,
bins => 10,
fill_color => 'LightGreen',
width => 1
);The following options which are specific to configuring the histogram can be passed in addition to any of the dataset options accepted by the add_rectangle method which draws the bars for the histogram (see dataset options). Note that if the fill_color option is set, then fill => 'self' is automatically set, and so you do not need to specify that option.
This can be either 'vertical' (default) or 'horizontal' to create vertical or horizontal bars.
The left edge of the leftmost bar. If not defined, the minimum value in the $data array is used.
The right edge of the rightmost bar. If not defined, the maximum value in $data is used.
The number of bins/bars to use for the histogram. This must be an integer greater than 0. The default value is 10.
If this is set to 0 (the default), then the height of each bar is the number of data values in the bin. If this is 1, then the heights are scaled so the sum of the heights of the bars is 1.
This sets the color of the bar borders. It is an alias for the color dataset option option of the add_rectangle method. See color options for more details on specifying colors.
This sets the width of the rectangle borders. This is an alias for the width dataset option.
A box plot (also called a box and whiskers plot) can be created with the add_boxplot method. The general form for adding a single box plot is
$statPlot->add_boxplot($data, %options);or to add multiple box plots is
$statPlot->add_boxplot([$data1, $data2, ...], %options);where $data (or $data1, $data2, ...) is a reference to an array of univariate data or a reference to a hash of the box plot characteristics. Box plots are created using the five number summary (minimum, first quartile, median, third quartile, maximum) of the data which is calculated using the five_point_summary method.
An example of creating a box plot with a reference to an array of univariate data is
$statPlot = StatPlot(
xmin => 0,
xmax => 200,
ymin => -5,
ymax => 25,
xtick_delta => 25,
yvisible => 0,
show_grid => 0,
aspect_ratio => 4,
rounded_corners => 1
);
$statPlot->add_boxplot(
[ urand(100, 25, 75, 6) ],
fill_color => 'LightBlue',
stroke_width => 1
);If $data is a hash reference, then it must contains the fields min, q1, median, q3, max that form the five number summary. Optionally, the field outliers may also be included which is a reference to an array of values which will be plotted outside of the whiskers. For example,
$boxplot = StatPlot(
xmin => 100,
xmax => 400,
ymin => -5,
ymax => 25,
xtick_delta => 50,
yvisible => 0,
show_grid => 0,
aspect_ratio => 4
);
$boxplot->add_boxplot({
min => random(150, 175, 5),
q1 => random(180, 225, 5),
median => random(250, 275, 5),
q3 => random(280, 320, 10),
max => random(325, 350, 5),
outliers => [115, 130]
});The following options which are specific to configuring the box plot can be passed in addition to any of the dataset options. Note that if the fill_color option is set, then fill => 'self' is automatically set, and so you do not need to specify that option.
This is the direction of the box plot and can be either 'horizontal' (the default) or 'vertical'.
The location of the center of the box. This is optional and if not defined the box plot will be centered in the range of the minor axis (the y-axis for horizontal box plots and the x-axis for vertical box plots).
If multiple box plots are being added and this option is not set, then the box plots will be equally spaced in the range of the minor axis.
If included, this option must be a reference to an array of values (in the x-direction for vertical plots and y-direction for horizontal plots) at which to center the added box plots. The number of entries in the array must be the same as the number of box plots that are being added. For example, if three box plots are being added this could be
box_center => [3, 6, 9]The width of the box in the direction perpendicular to the orientation. The default is to use half of the range of the minor axis.
If multiple box plots are defined, this should only be a single value.
This should be set to 0 (default) or 1. If this value is 1, lines that are perpendicular to the whiskers will be added at the ends of the whiskers of the box plot. The length of the lines are determined by the cap_width option.
The width of the cap as a fraction of the box width. Default value is 0.2.
The shape of the mark to use for outliers. The default is 'plus'. See the dataset options for other mark options.
This sets the color of the boundary of the box and the whiskers. It is an alias for the color dataset option. See color options for more details on specifying colors.
This sets the width of the boundary of the rectangle and the whiskers. This is an alias for the width dataset option.
A scatter plot can be created with the add_scatterplot method. The general form for adding a scatter plot is
$statPlot->add_scatterplot($data, %options);where $data is a reference to an array of array references of x, y pairs. For example,
$statPlot = StatPlot(
xmin => -1,
xmax => 15,
ymin => -1,
ymax => 15,
xtick_delta => 5,
ytick_delta => 5,
);
$statPlot->add_scatterplot(
[ [1, 1], [2, 3], [3, 4], [5, 5], [7, 8], [10, 9], [12, 10] ],
marks => 'diamond',
mark_size => 5,
color => 'orange'
);This method simply calls the add_dataset method with the following dataset options set. Any of these can be changed or any of the other data set options set in the %options parameter.
This sets the style of the lines between the marks is set to 'none' by this method, so that lines are not drawn between the points.
This sets the symbol to use for the marks and is set to 'circle' by this method. See the dataset options for other mark options.
This sets the size of the marks and is set to 3 by this method.
This sets the color of the marks and is an alias for the color dataset options option. See color options for more details on specifying colors.
If more than one dataset is to be plotted, then call the add_scatterplot method multiple times. This can be done with a single add_dataset method call, but this wrapper is convenient when the default options above are desired.
A pie chart is a circle that divided into sectors whose size is proportional to an input array. The sectors are each assigned a color and a label. This method will also produce donut charts (or ring charts), which is a pie chart with a hole.
The general form for calling the add_piechart method is
$statPlot->add_piechart($data, %options);where $data is a reference to an array of values.
The following options which are specific to configuring the pie chart can be passed in addition to any of the dataset options.
The center of the circle as an array reference. The default value is [0, 0].
The radius of the circle. The default value of 4 is chosen to fit nicely with the default values for the bounding box of the StatPlot which ranges from -5 to 5 in both the x and y directions.
This is the radius of the inner circle of the chart. Set this to a value less than the radius for a donut or ring chart. The default value is 0.
This is the angle in degrees from the positive horizontal axis at which the first sector begins. This is 0 by default.
This is either the name of a color palette, a reference to an array of colors, or a reference to a hash containing the name of a color palette (palette_name) and number of colors to generate (num_colors) (see "COLOR PALETTES" for more information). If this is a reference to an array and the length of the array is smaller than the number of data values in the array referenced to by $data, then the colors will be cycled. The default is to use the 'rainbow' color palette.
For example,
fill_colors => 'rainbow'
fill_colors => ['green', 'OliveGreen', 'DarkGreen', 'ForestGreen', 'PineGreen']
fill_colors => { palette_name => 'random', num_colors => 7 }If this is 1 (the default), then colors are used for the pie chart. If 0, then the sectors are not filled. See "COLOR PALETTES" for details on selecting colors.
The labels for the sector as a array reference of strings or values. The default is for no labels. If this is used, the length of this must be the same as the $data array reference.
The color palettes for the bar plots and pie charts can be selected with the color_palette function. This allows a number of built-in or generated color palettes. To get an array reference of either named or generated colors call
color_palette($name, $numColors);For example,
color_palette('rainbow');returns the 6 colors of the rainbow. Some of the palettes have fixed numbers of colors, whereas others have variable numbers. If $numColors is not defined, then some palettes return a fixed number (like 'rainbow') and if the $numColors is needed, then the default of 10 is assumed.
The 6 colors of the rainbow from violet to red. The $numColors value is ignored for this palette.
This will return a selection of red colors. The $numColors value is ignored for this palette.
This will return a selection of blue colors. The $numColors value is ignored for this palette.
This will return a selection of green colors. The $numColors value is ignored for this palette.
This will return $numColors random colors from the defined SVG colors.