`adegraphics`

packageThe `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)

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.

This class management highlights a hierarchy with two parent classes:

`ADEg`

for simple graphs. It contains the display of a single data set using only one kind of representation (e.g., arrows, points, lines, etc.)`ADEgS`

for multiple graphs. It contains a collection of at least two simple graphs (`ADEg`

,`trellis`

or`ADEgS`

)

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:

`ADEg.S1`

: unidimensional graph of a numeric score`ADEg.S2`

: bidimensional graph of xy coordinates (`matrix`

or`data.frame`

object)`ADEg.C1`

: bidimensional graph of a numeric score (bar chart or curve)`ADEg.T`

: heat map-like representation of a data table (`matrix`

,`data.frame`

,`dist`

or`table`

object)`ADEg.Tr`

: ternary plot of xyz coordinates (`matrix`

or`data.frame`

object)

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).

`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.

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.value` ^{1} |

`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.class` ^{2} |

`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` |

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

function.

```
## 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
```

```
## 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:

`plot`

: a logical value indicating if the graph should be displayed`storeData`

: a logical value indicating if the data should be stored in the returned object. If`FALSE`

, only the names of the data are stored. This allows to reduce the size of the returned object but it implies that the data should not be modified in the environment to plot again the graph.`add`

: a logical value indicating if the graph should be superposed on the graph already displayed in the current device (it replaces the argument`add.plot`

in`ade4`

).`pos`

: an integer indicating the position of the environment where the data are stored, relative to the environment where the function is called. Useful only if`storeData`

is`FALSE`

.`…`

: additional graphical parameters (see below)

Some other arguments influence the graphical outputs and they are thus specific to the type of produced graph. Figure 2 summarizes some of these graphical parameters available for the different functions. We only reported the parameters stored in the `g.args`

slot of the returned object (see the Parameters in `g.args`

section).