R: Plot of Individuals (Experimental Units)

plotIndiv {mixOmics} | R Documentation

## Plot of Individuals (Experimental Units)

### Description

This function provides scatter plots for individuals (experimental units) representation in (sparse)(I)PCA, (regularized)CCA, (sparse)PLS(DA) and (sparse)(R)GCCA(DA).

### Usage

    ## S3 method for class 'pls'
    plotIndiv(object, comp = NULL, rep.space = NULL, ind.names = TRUE, group, col.per.group,
    style = "ggplot2", ellipse = FALSE, ellipse.level = 0.95, centroid = FALSE, star = FALSE,
    title = NULL, subtitle, legend = FALSE,
    X.label = NULL, Y.label = NULL, Z.label = NULL, abline = FALSE,
    xlim = NULL, ylim = NULL, col, cex, pch, pch.levels, alpha = 0.2, axes.box = "box",
    layout = NULL,
    size.title = rel(2), size.subtitle = rel(1.5), size.xlabel = rel(1),
    size.ylabel = rel(1), size.axis = rel(0.8), size.legend = rel(1),
    size.legend.title = rel(1.1), legend.title = "Legend", legend.title.pch = "Legend",
    legend.position = "right",
    point.lwd = 1, background = NULL, ... )

    ## S3 method for class 'mint.spls'
    plotIndiv(object, comp = NULL, study = "global", rep.space = NULL, group, col.per.group,
    style = "ggplot2", ellipse = FALSE, ellipse.level = 0.95, centroid = FALSE, star = FALSE,
    title = NULL, subtitle, legend=FALSE,
    X.label = NULL, Y.label = NULL, abline = FALSE,
    xlim = NULL, ylim = NULL, col, cex, pch, layout = NULL,
    size.title = rel(2), size.subtitle = rel(1.5), size.xlabel = rel(1),
    size.ylabel = rel(1), size.axis = rel(0.8), size.legend = rel(1),
    size.legend.title = rel(1.1), legend.title = "Legend", legend.position = "right",
    point.lwd = 1, ... )

    ## S3 method for class 'sgcca'
    plotIndiv(object, comp = NULL, blocks = NULL, ind.names = TRUE, group, col.per.group,
    style = "ggplot2", ellipse = FALSE, ellipse.level = 0.95, centroid = FALSE, star = FALSE,
    title = NULL, subtitle, legend = FALSE,
    X.label = NULL, Y.label = NULL, Z.label = NULL, abline = FALSE,
    xlim = NULL, ylim = NULL, col, cex, pch, pch.levels,
    alpha = 0.2, axes.box = "box", layout = NULL,
    size.title = rel(2), size.subtitle = rel(1.5), size.xlabel = rel(1),
    size.ylabel = rel(1), size.axis = rel(0.8), size.legend = rel(1),
    size.legend.title = rel(1.1), legend.title = "Legend", legend.title.pch = "Legend",
    legend.position = "right",
    point.lwd = 1, ... )

### Arguments

`object` | object of class inheriting from any mixOmics: `PLS, sPLS, PLS-DA, SPLS-DA, rCC, PCA, sPCA, IPCA, sIPCA, rGCCA, sGCCA, sGCCDA`
`comp` | integer vector of length two (or three to 3d). The components that will be used on the horizontal and the vertical axis respectively to project the individuals.
`rep.space` | For objects of class `"rcc"`, `"pls"`, `"spls"`, character string, (partially) matching one of `"X-variate"`, `"Y-variate"` ,or `"XY-variate"`, determining the subspace to project the individuals. Defaults to `"X-variate"` `"pca"` object and for `"plsda"` objects. For objects of class `"pls"` and `"rcc"`,defaults, the tree subspaces represent the individuals. For objects of class `"rgcca"` and `"sgcca"`, numerical value indicating the block data set form which to represent the individuals.
`blocks` | integer value of name of a block to be plotted using the GCCA module. See examples.
`study` | Indicates which study-specific outputs to plot. A character vector containing some levels of `object$study`, "all.partial" to plot all studies or "global" is expected. Default to "global".
`ind.names` | either a character vector of names for the individuals to be plotted, or `FALSE` for no names. If `TRUE`, the row names of the first (or second) data matrix is used as names (see Details).
`group` | factor indicating the group membership for each sample, useful for ellipse plots. Coded as default for the supervised methods `PLS-DA, SPLS-DA,sGCCDA`, but needs to be input for the unsupervised methods `PCA, sPCA, IPCA, sIPCA, PLS, sPLS, rCC, rGCCA, sGCCA`
`col.per.group` | character (or symbol) color to be used when 'group' is defined. Vector of the same length than the number of groups.
`style` | argument to be set to either `'graphics'`, `'lattice'`, `'ggplot2'` or `'3d'` for a style of plotting. Default set to 'ggplot2'. See details. `3d` is not available for MINT objects.
`ellipse` | boolean indicating if ellipse confidence region plots should be plotted. In the non supervised objects `PCA, sPCA, IPCA, sIPCA, PLS, sPLS, rCC, rGCCA, sGCCA` ellipse plot is only be plotted if the argument `group` is provided. In the `PLS-DA, SPLS-DA,sGCCDA` supervised object, by default the ellipse will be plotted accoding to the outcome `Y`.
`ellipse.level` | Numerical value indicating the confidence level of ellipse being plotted when `ellipse =TRUE` (i.e. the size of the ellipse). The default is set to 0.95, for a 95% region.
`centroid` | boolean indicating whether centroid points should be plotted. In the non supervised objects `PCA, sPCA, IPCA, sIPCA, PLS, sPLS, rCC, rGCCA, sGCCA` the centroid will only be plotted if the argument `group` is provided. The centroid will be calculated based on the group categories. In the supervised objects `PLS-DA, SPLS-DA,sGCCDA` the centroid will be calculated according to the outcome `Y`.
`star` | boolean indicating whether a star plot should be plotted, with arrows starting from the centroid (see argument `centroid`, and ending for each sample belonging to each group or outcome. In the non supervised objects `PCA, sPCA, IPCA, sIPCA, PLS, sPLS, rCC, rGCCA, sGCCA` star plot is only be plotted if the argument `group` is provided. In the supervised objects `PLS-DA, SPLS-DA,sGCCDA` the star plot is plotted according to the outcome `Y`.
`title` | set of characters indicating the title plot.
`subtitle` | subtitle for each plot, only used when several `block` or `study` are plotted.
`legend` | boolean. Whether the legend should be added. Default is FALSE.
`X.label` | x axis titles.
`Y.label` | y axis titles.
`Z.label` | z axis titles (when style = '3d').
`abline` | should the vertical and horizontal line through the center be plotted? Default set to `FALSE`
`xlim,ylim` | numeric list of vectors of length 2 and length =length(blocks), giving the x and y coordinates ranges.
`col` | character (or symbol) color to be used, possibly vector.
`cex` | numeric character (or symbol) expansion, possibly vector.
`pch` | plot character. A character string or a vector of single characters or integers. See `points` for all alternatives.
`pch.levels` | Only used when `pch` is different from `col` or `col.per.group`, ie when `pch` creates a second factor. Only used for the legend.
`alpha` | Semi-transparent colors (0 < `'alpha'` < 1)
`axes.box` | for style '3d', argument to be set to either `'axes'`, `'box'`, `'bbox'` or `'all'`, defining the shape of the box.
`layout` | layout parameter passed to mfrow. Only used when `study` is not "global"
`size.title` | size of the title
`size.subtitle` | size of the subtitle
`size.xlabel` | size of xlabel
`size.ylabel` | size of ylabel
`size.axis` | size of the axis
`size.legend` | size of the legend
`size.legend.title` | size of the legend title
`legend.title` | title of the legend
`legend.title.pch` | title of the second legend created by `pch`, if any.
`legend.position` | position of the legend, one of "bottom", "left", "top" and "right".
`point.lwd` | `lwd` of the points, used when `ind.names = FALSE`
`background` | color the background by the predicted class, see `background.predict`
`...` | external arguments or type par can be added with `style = 'graphics'`

### Details

`plotIndiv` method makes scatter plot for individuals representation depending on the subspace of projection. Each point corresponds to an individual.

If `ind.names=TRUE` and row names is `NULL`, then `ind.names=1:n`, where `n` is the number of individuals. Also, if `pch` is an input, then `ind.names` is set to FALSE as we do not show both names and shapes.

`plotIndiv` can have a two layers legend. This is especially convenient when you have two grouping factors, such as a gender effect and a study effect, and you want to highlight both simulatenously on the graphical output. A first layer is coded by the `group` factor, the second by the `pch` argument. When `pch` is missing, a single layer legend is shown. If the `group` factor is missing, the `col` argument is used to create the grouping factor `group`. When a second grouping factor is needed and added via `pch`, `pch` needs to be a vector of length the number of samples. In the case where `pch` is a vector or length the number of groups, then we consider that the user wants a different `pch` for each level of `group`. This leads to a single layer legend and we merge `col` and `pch`. In the similar case where `pch` is a single value, then this value is used to represent all samples. See examples below for object of class plsda and splsda.

In the specific case of a single 'omics supervised model (`plsda`, `splsda`), users can overlay prediction results to sample plots in order to visualise the prediction areas of each class, via the `background` input parameter. Note that this functionality is only available for models with less than 2 components as the surfaces obtained for higher order components cannot be projected onto a 2D representation in a meaningful way. For more details, see `background.predict`

For customized plots (i.e. adding points, text), use the style = 'graphics' (default is ggplot2).

Note: the ellipse options were borrowed from the ellipse, see `?ellipse` for more details about how the confidence region is calculated.

### Author(s)

Ignacio González, Benoit Gautier, Francois Bartolo, Florian Rohart

### See Also

`text`, `background.predict`, `points` and http://mixOmics.org/graphics for more details.

### Examples

    ## plot of individuals for objects of class 'rcc'
    # ----------------------------------------------------
    data(nutrimouse)
    X <- nutrimouse$lipid
    Y <- nutrimouse$gene
    nutri.res <- rcc(X, Y, ncomp = 3, lambda1 = 0.064, lambda2 = 0.008)

    # default, only in the X space
    plotIndiv(nutri.res)

    ## Not run:
        # ellipse with respect to genotype in the XY space,
        # names also indicate genotype
        plotIndiv(nutri.res, rep.space= 'XY-variate',
        ellipse = TRUE, ellipse.level = 0.9,
        group = nutrimouse$genotype, ind.names = nutrimouse$genotype)

        # ellipse with respect to genotype in the XY space, with legend
        plotIndiv(nutri.res, rep.space= 'XY-variate', group = nutrimouse$genotype,
        legend = TRUE)

        # lattice style
        plotIndiv(nutri.res, rep.space= 'XY-variate', group = nutrimouse$genotype,
        legend = TRUE, style = 'lattice')

        # classic style, in the Y space
        plotIndiv(nutri.res, rep.space= 'Y-variate', group = nutrimouse$genotype,
        legend = TRUE, style = 'graphics')

    ## End(Not run)

    ## plot of individuals for objects of class 'pls' or 'spls'
    # ----------------------------------------------------
    data(liver.toxicity)
    X <- liver.toxicity$gene
    Y <- liver.toxicity$clinic
    toxicity.spls <- spls(X, Y, ncomp = 3, keepX = c(50, 50, 50),
    keepY = c(10, 10, 10))

    #default
    plotIndiv(toxicity.spls)

    ## Not run:
    # two layers legend: a first grouping with Time.Group and 'group'
    # and a second with Dose.Group and 'pch'
    plotIndiv(toxicity.spls, rep.space="X-variate", ind.name = FALSE,
    group = liver.toxicity$treatment[, 'Time.Group'], # first factor
    pch = as.numeric(factor(liver.toxicity$treatment$Dose.Group)), #second factor
    pch.levels =liver.toxicity$treatment$Dose.Group, #levels of the second factor, for the legend
    legend = TRUE)

    ## End(Not run)

    # indicating the centroid
    plotIndiv(toxicity.spls, rep.space= 'X-variate', ind.names = FALSE,
              group = liver.toxicity$treatment[, 'Time.Group'], centroid = TRUE)

    # indicating the star and centroid
    plotIndiv(toxicity.spls, rep.space= 'X-variate', ind.names = FALSE,
              group = liver.toxicity$treatment[, 'Time.Group'], centroid = TRUE, star = TRUE)

    # indicating the star and ellipse
    plotIndiv(toxicity.spls, rep.space= 'X-variate', ind.names = FALSE,
              group = liver.toxicity$treatment[, 'Time.Group'], centroid = TRUE,
                star = TRUE, ellipse = TRUE)

        # in the Y space, colors indicate time of necropsy, text is the dose
        plotIndiv(toxicity.spls, rep.space= 'Y-variate',
        group = liver.toxicity$treatment[, 'Time.Group'],
        ind.names = liver.toxicity$treatment[, 'Dose.Group'],
        legend = TRUE)

    ## plot of individuals for objects of class 'plsda' or 'splsda'
    # ----------------------------------------------------
    data(breast.tumors)
    X <- breast.tumors$gene.exp
    Y <- breast.tumors$sample$treatment

    splsda.breast <- splsda(X, Y,keepX=c(10,10),ncomp=2)

    # default option: note the outcome color is included by default!
    plotIndiv(splsda.breast)

    # also check ?background.predict for to visualise the prediction
    # area with a plsda or splsda object!

    ## Not run:
        # default option with no ind name: pch and color are set automatically
        plotIndiv(splsda.breast, ind.names = FALSE, comp = c(1, 2))

        # default option with no ind name: pch and color are set automatically, with legend
        plotIndiv(splsda.breast, ind.names = FALSE, comp = c(1, 2), legend = TRUE)

        # trying the different styles
        plotIndiv(splsda.breast, ind.names = TRUE, comp = c(1, 2),
        ellipse = TRUE, style = "ggplot2", cex = c(1, 1))
        plotIndiv(splsda.breast, ind.names = TRUE, comp = c(1, 2),
        ellipse = TRUE, style = "lattice", cex = c(1, 1))

        # changing pch of the two groups
        plotIndiv(splsda.breast, ind.names = FALSE, comp = c(1, 2),
        pch = c(15,16), legend = TRUE)

        # creating a second grouping factor with a pch of length 3,
        #  which is recycled to obtain a vector of length n
        plotIndiv(splsda.breast, ind.names = FALSE, comp = c(1, 2),
        pch = c(15,16,17), legend = TRUE)

        #same thing as
        pch.indiv = c(rep(15:17,15), 15, 16) # length n
        plotIndiv(splsda.breast, ind.names = FALSE, comp = c(1, 2),
        pch = pch.indiv, legend = TRUE)

        # change the names of the second legend with pch.levels
        plotIndiv(splsda.breast, ind.names = FALSE, comp = c(1, 2),
        pch = 15:17, pch.levels = c("a","b","c"),legend = TRUE)

    ## End(Not run)

    ## plot of individuals for objects of class 'mint.plsda' or 'mint.splsda'
    # ----------------------------------------------------
    data(stemcells)
    res = mint.splsda(X = stemcells$gene, Y = stemcells$celltype, ncomp = 2, keepX = c(10, 5),
    study = stemcells$study)

    plotIndiv(res)

    ## Not run:
    #plot study-specific outputs for all studies
    plotIndiv(res, study = "all.partial")

    #plot study-specific outputs for study "2"
    plotIndiv(res, study = "2")

    ## End(Not run)

    ## variable representation for objects of class 'sgcca' (or 'rgcca')
    # ----------------------------------------------------
    ## Not run:
    data(nutrimouse)
    Y = unmap(nutrimouse$diet)
    data = list(gene = nutrimouse$gene, lipid = nutrimouse$lipid, Y = Y)
    design1 = matrix(c(0,1,1,1,0,1,1,1,0), ncol = 3, nrow = 3, byrow = TRUE)
    nutrimouse.sgcca <- wrapper.sgcca(X = data,
    design = design1,
    penalty = c(0.3, 0.5, 1),
    ncomp = 3,
    scheme = "horst")

    # default style: one panel for each block
    plotIndiv(nutrimouse.sgcca)

        # for the block 'lipid' with ellipse plots and legend, different styles
        plotIndiv(nutrimouse.sgcca, group = nutrimouse$diet, legend =TRUE,
        ellipse = TRUE, ellipse.level = 0.5, blocks = "lipid", title = 'my plot')
        plotIndiv(nutrimouse.sgcca, style = "lattice", group = nutrimouse$diet,
        legend = TRUE, ellipse = TRUE, ellipse.level = 0.5, blocks = "lipid",
        title = 'my plot')
        plotIndiv(nutrimouse.sgcca, style = "graphics", group = nutrimouse$diet,
        legend = TRUE, ellipse = TRUE, ellipse.level = 0.5, blocks = "lipid",
        title = 'my plot')

    ## End(Not run)

    ## variable representation for objects of class 'sgccda'
    # ----------------------------------------------------
    ## Not run:
    # Note: the code differs from above as we use a 'supervised' GCCA analysis
    data(nutrimouse)
    Y = nutrimouse$diet
    data = list(gene = nutrimouse$gene, lipid = nutrimouse$lipid)
    design1 = matrix(c(0,1,0,1), ncol = 2, nrow = 2, byrow = TRUE)

    nutrimouse.sgccda1 <- wrapper.sgccda(X = data,
    Y = Y,
    design = design1,
    ncomp = 2,
    keepX = list(gene = c(10,10), lipid = c(15,15)),
    scheme = "centroid")

    # plotIndiv
    # ----------

    # displaying all blocks. bu default colors correspond to outcome Y
    plotIndiv(nutrimouse.sgccda1)

        # displaying only 2 blocks
        plotIndiv(nutrimouse.sgccda1, blocks = c(1,2), group = nutrimouse$diet)

        # with some ellipse, legend and title
        plotIndiv(nutrimouse.sgccda1, blocks = c(1,2), group = nutrimouse$diet,
        ellipse = TRUE, legend = TRUE, title = 'my sample plot')

    ## End(Not run)

[Package mixOmics version 6.3.2 Index]