Produce grid of subplots depicting pairwise relationships in a dataset. This package maps each variable in a list onto a column and row in a grid of multiple axes.
It can also represent an additional level of conditionalization with the 'factor' argument (a series) which plots different subsets of data in different colors and/or point/circle types. This is used to resolve elements on a third dimension.
Please report bugs or comments on the gretl mailing list, report an issue on github (https://github.com/atecon/PairPlot/issues) or write to [email protected].
The function PairPlot()
can be accessed through the GUI. The menu entry is "View->Graph specified vars->Pair Plot". However, via scripting the user can control many more details.
PairPlot(const list L, const series factor[null], bundle opts[null])
Main function for creating pair-plots.
L
: list, Series to plot against each otherfactor
: series, Categorical (numeric or string-valued) variable for mapping plot aspects to different colors and/or points/ circles (optional, default: null).opts
: bundle, Optional for passing additional parameters. See below for explanation (default: null)
An integer of value '0' (FALSE) if no error occurs, otherwise 1 (TRUE).
The user can control the following aspects by adding the respective parameter to the 'opts' bundle.
-
centroid
: string, Highlight the centroid of the 2-dim. data. Possible options aremean
,median
andnone
(default: "none"). If afactor
series is passed, the centroid for each distinct factor is shown. -
centroid_label
: bool, Show the label of the centroid statistics of TRUE, otherwise do not show of FALSE (default: FALSE). -
centroid_linewidth
: scalar, Width of the point (default: 2). -
centroid_pointsize
: scalar, Size of the point (default: 2). -
filename
: string, Path plus filename plus file type. (optional, default:display
which draws the resulting plot directly at the screen). Currently figures can only be stored in png format. -
fontsize
: int, Control the font size of the labels (default: 16) . -
grid
: bool, Draw a grid in the background if TRUE (=1) (default: FALSE) -
height
: scalar, Height of the canvas plot (default: 600). -
title
: string: set an overall title for the plot(s). -
key
: bool, If thefactor
series is provided, a legend shows the color and point pattern for each distinct value of thefactor
variable. Default: 1 (TRUE). -
key_fontsize
int, Control the font size for the key. Default: 14 -
key_position
: string, Controls the position of the legend in each subplot (use standard gnuplot options). default: "top left". -
offset_level
: scalar, Provides a mechanism to put a boundary around the data inside of an auto-scaled graph. For details see: http://gnuplot.sourceforge.net/docs_4.2/node209.html, Default: 0.02. -
pointsize
: int, Control the size of points (default: 2). No support for circles. -
pointtype
: matrix, Control the type of points. Can be either an integer entry such that points associated to different levels offactor
are of the same type. One may also provide a vector of integers for each distinct value of thefactor
series. Default: 7. See also: https://i.imgur.com/xNZa7Rz.png -
tics
: bool, Print x-tics and y-tics if 1 (TRUE, default), or not if 0 (FALSE). -
tics_fontsize
int, Control the font size of the x-y tics. Default: 12 -
transparency_level
: int, Controls the transparency level of points and circles (between 0 (no transparency) and 255 (full transparency)). Default: 90. -
type
: string, Select the type of plot (default: "triangle"). The following types are supported: -
(i) "matrix": Scatterplot matrix which draws a scatter plot between all combinations of variables included in list
L
. -
(ii) "triangle": Lower triangular version of the scatterplot "matrix" type.
-
(iii) "row": Plot the first series element in list
L
in a single row against all remaining list members. -
(iv) "column": Works like type "row" but subplots are arranged in a single column instead.
-
use_circles
: bool, Draw circles instead of points if set to 1 (TRUE), default: 0 (FALSE). -
width
: scalar, Width of the canvas plot (default: 900).
-
v0.99 (Jule 2024)
- Add new parameter
title
for setting an overall title - Internal refactoring: Switch to gretl's built-in gridplot aparatus which means that all the graphics file formats supported by gretl can be used.
- It also means that usage via gretlcli in "display" mode works.
- In case the user's specification calls for just a single plot, no "multiplot" is created.
- The graphical interface is enhanced, with more options.
- Add new parameter
-
v0.98 (April 2024)
- Make width, height, fontsizes and pointsize a function of the number of variables for better readability in case of many variables.
- Set parameter `transparency per default to 90.
- Minor update of the sample script
-
v0.97 (February 2024)
- Error in case of CLI-mode if a plot is expected to appear on the screen (filename="display")
-
v0.96 (February 2024)
- Set all terminals to 'noenhanced' mode to respect eventual underscores in variable names
- Allow the parameters 'centroid_pointsize', 'centroid_linewidth', 'width' and 'height' to be scalar values instead of integers.
-
v0.95 (December 2023)
- Bugfix: Path with blanks failed under Windows sometimes.
- Bugfix: An error occured with negative values in some cases
- Bugfix: An error occured of the name of the last variable in the list starts with 'e' (or 'E')
- Fix handling of transparency
- Add
grid
option for (optionally) drawing a grid in the background - Add options
key_fontsize
andtics_fontsize
. - Add support for drawing centroids of 2-dimensional space.
- Remove the
font
option for setting the font (controlled by gretl now) - Increase default font size to 12
- Switch to markdown-based help file
- Increase minimum gretl version to 2022d
-
v0.9 (October 2022)
- Fix bug with
const
inheritance: its illegal for a function which receives an argument A that is declared as const to pass A on in pointer form to another function which does not promise to treat it asconst
.
- Fix bug with
-
v0.8 (January 2022)
- Handle eventual missing values in passed series.
- Bugfix of gnuplot's
offset
option: More than at maximum 4 were passed in case of more than 4 features to plot. - Bugfix: Works now with more than 8 features.
-
v0.7 (October 2021)
- Enforce full sample instead of using
--replace
option - Changed ordering of the colours when plotting distinct factors
- Change the colour palette to "dark2"
- Enforce full sample instead of using
-
v0.6 (March 2021)
- New API for
PairPlot()
-- backward-incompatible - update help text
- enforce decimal point when print numerical data to gnuplot file
- substantial internal refactoring and clean up
- gain of speed
- new minimum gretl version is 2020e
- New API for
-
v0.5 (Oct. 2019)
- Initial version