The adegraphics package

Alice Julien-Laferrière, Aurélie Siberchicot and Stéphane Dray

2023-10-11




The adegraphics package (Siberchicot et al. 2017) is a complete reimplementation of the graphical functionalities of the ade4 package (Dray and Dufour 2007). The package has been initially designed to improve the representation of the outputs of multivariate analyses performed with ade4 but as its graphical functionalities are very general, they can be used for other purposes.

The adegraphics package provides a flexible environment to produce, edit and manipulate graphs. We adopted an object oriented approach (a graph is an object) using S4 classes and methods and used the visualization system provided by the lattice (Sarkar 2008) and grid (Murrell 2005) packages. In adegraphics, graphs are R objects that can be edited, stored, combined, saved, removed, etc.

Note that we tried to facilitate the handling of adegraphics by ade4 users. Hence, the name of functions and parameters has been preserved in many cases. The main changes are listed in the appendix of this vignette so that it should be quite easy to use adegraphics. However, several new functionalities (graphical parameters, creation and manipulation of graphical objects, etc.) are now available and detailed in this vignette.

The adelist mailing list can be used to send questions and/or comments on adegraphics (see https://listes.univ-lyon1.fr/sympa/info/adelist)

1 An overview of object classes

In adegraphics, a user-level function produces a plot that is stored (and returned) as an object. The class architecture of the objects created by adegraphics functions is described in Figure 1.


Figure 1: Classes structure and user-level functions


This class management highlights a hierarchy with two parent classes:

The ADEg class has five child classes which are also subdivided in several child classes. Each of these five child classes is dedicated for a particular graphical data representation:

The ADEg class and its five child classes are virtual: it is not allowed to create object belonging to these classes. Users can only create objects belonging to child classes by calls to user functions (see the User functions section).

2 Simple graph (ADEg object)

In the adegraphics package, a graph is created by a call to a user function and stored as an R object. These functions allow to display the raw data but also the outputs of a multivariate analysis. The following sections describe the different graphical functions available in the package.

2.1 User functions

Several user functions are available to create a simple graph (stored as an ADEg object in R). Each function creates an object of a given class (see Figure 1). Table 1 lists the different functions, their corresponding classes and a short description. The ade4 users would not be lost: many functions have kept their names in adegraphics. The main changes are listed in Table 2.


Table 1: Graphical functions available in adegraphics

Function Class of the returned object Description
s1d.barchart C1.barchart 1-D plot of a numeric score by bars
s1d.curve C1.curve 1-D plot of a numeric score linked by curves
s1d.curves C1.curves 1-D plot of multiple scores linked by curves
s1d.density C1.density 1-D plot of a numeric score by density curves
s1d.dotplot C1.dotplot 1-D plot of a numeric score by dots
s1d.gauss C1.gauss 1-D plot of a numeric score by Gaussian curves
s1d.hist C1.hist 1-D plot of a numeric score by bars
s1d.interval C1.interval 1-D plot of the interval between two numeric scores
s1d.boxplot S1.boxplot 1-D box plot of a numeric score partitioned in classes
s1d.class S1.class 1-D plot of a numeric score partitioned in classes
s1d.distri S1.distri 1-D plot of a numeric score by means/tandard deviations computed using an external table of weights
s1d.label S1.label 1-D plot of a numeric score with labels
s1d.match S1.match 1-D plot of the matching between two numeric scores
s.arrow S2.arrow 2-D scatter plot with arrows
s.class S2.class 2-D scatter plot with a partition in classes
s.corcircle S2.corcircle Correlation circle
s.density S2.density 2-D scatter plot with kernel density estimation
s.distri S2.distri 2-D scatter plot with means/standard deviations computed using an external table of weights
s.image S2.image 2-D scatter plot with loess estimation of an additional numeric score
s.label S2.label 2-D scatter plot with labels
s.logo S2.logo 2-D scatter plot with logos (pixmap objects)
s.match S2.match 2-D scatter plot of the matching between two sets of coordinates
s.Spatial S2.label Mapping of a Spatial* object
s.traject S2.traject 2-D scatter plot with trajectories
s.value S2.value 2-D scatter plot with proportional symbols
table.image T.image Heat map-like representation with colored cells
table.value T.value or T.cont Heat map-like representation with proportional symbols
triangle.class Tr.class Ternary plot with a partition in classes
triangle.label Tr.label Ternary plot with labels
triangle.match Tr.match Ternary plot of the matching between two sets of coordinates
triangle.traject Tr.match Ternary plot with trajectories


Table 2: Changes in functions names between ade4 and adegraphics

Function in ade4 Equivalence in adegraphics
table.cont, table.dist, table.value table.value1
table.paint table.image
sco.boxplot s1d.boxplot
sco.class s1d.class
sco.distri s1d.distri
sco.gauss s1d.gauss
sco.label s1d.label
sco.match s1d.match
sco.quant no equivalence
s.chull s.class2
s.kde2d s.density
s.match.class superposition of s.match and s.class
triangle.biplot triangle.match
triangle.plot triangle.label
s.multinom triangle.multinom

2.2 Arguments

The list of arguments of a function are given by the args function.

library(ade4)
library(adegraphics)
## The legacy packages maptools, rgdal, and rgeos, underpinning the sp package,
## which was just loaded, will retire in October 2023.
## Please refer to R-spatial evolution reports for details, especially
## https://r-spatial.org/r/2023/05/15/evolution4.html.
## It may be desirable to make the sf package available;
## package maintainers should consider adding sf to Suggests:.
## The sp package is now running under evolution status 2
##      (status 2 uses the sf package in place of rgdal)
## Registered S3 methods overwritten by 'adegraphics':
##   method         from
##   biplot.dudi    ade4
##   kplot.foucart  ade4
##   kplot.mcoa     ade4
##   kplot.mfa      ade4
##   kplot.pta      ade4
##   kplot.sepan    ade4
##   kplot.statis   ade4
##   scatter.coa    ade4
##   scatter.dudi   ade4
##   scatter.nipals ade4
##   scatter.pco    ade4
##   score.acm      ade4
##   score.mix      ade4
##   score.pca      ade4
##   screeplot.dudi ade4
## 
## Attachement du package : 'adegraphics'
## Les objets suivants sont masqués depuis 'package:ade4':
## 
##     kplotsepan.coa, s.arrow, s.class, s.corcircle, s.distri, s.image,
##     s.label, s.logo, s.match, s.traject, s.value, table.value,
##     triangle.class
args(s.label)
## function (dfxy, labels = rownames(dfxy), xax = 1, yax = 2, facets = NULL, 
##     plot = TRUE, storeData = TRUE, add = FALSE, pos = -1, ...) 
## NULL

Some arguments are very general and present in all user functions:

Some other arguments influence the graphical outputs and t