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

    plotIndiv(object, ...)

    ## S3 method for class 'mint.pls'
    plotIndiv(
      object,
      comp = NULL,
      study = "global",
      rep.space = c("X-variate", "XY-variate", "Y-variate", "multi"),
      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 'mint.spls'
    plotIndiv(
      object,
      comp = NULL,
      study = "global",
      rep.space = c("X-variate", "XY-variate", "Y-variate", "multi"),
      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 'mint.plsda'
    plotIndiv(
      object,
      comp = NULL,
      study = "global",
      rep.space = c("X-variate", "XY-variate", "Y-variate", "multi"),
      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 'mint.splsda'
    plotIndiv(
      object,
      comp = NULL,
      study = "global",
      rep.space = c("X-variate", "XY-variate", "Y-variate", "multi"),
      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 'pca'
    plotIndiv(
      object,
      comp = NULL,
      ind.names = TRUE,
      group,
      col.per.group,
      style = "ggplot2",
      ellipse = FALSE,
      ellipse.level = 0.95,
      centroid = FALSE,
      star = FALSE,
      title = NULL,
      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,
      ...
    )

    ## S3 method for class 'mixo_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 '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,
      ...
    )

    ## S3 method for class 'rgcca'
    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 inherited from any mixOmics: `PLS, sPLS, PLS-DA, SPLS-DA, rCC, PCA, sPCA, IPCA, sIPCA, rGCCA, sGCCA, sGCCDA`
`...` | Optional arguments or type par can be added with `style = 'graphics'`
`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.
`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".
`rep.space` | For objects of class `"pca", "plsda", "plsda"` default is `"X-variate"`. For the objects of class `"pls", "rcc"` default is a panel plot representing each data subspace. For objects of class `"rgcca"` and `"sgcca"`, numerical value(s) indicating the block data set to represent needs to be specified.
`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 as 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` | Logical indicating if ellipse 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` | Logical 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` | Logical 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` | Logical. Whether the legend should be added. Default is FALSE.
`X.label` | x axis titles.
`Y.label` | y axis titles.
`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.
`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.position` | position of the legend, one of "bottom", "left", "top" and "right".
`point.lwd` | `lwd` of the points, used when `ind.names = FALSE`
`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).
`Z.label` | z axis titles (when style = '3d').
`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.
`legend.title.pch` | title of the second legend created by `pch`, if any.
`background` | color the background by the predicted class, see `background.predict`
`blocks` | integer value or name(s) of block(s) to be plotted using the GCCA module. "average" and "weighted.average" will create average and weighted average plots, respectively. See details and examples.

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

The argument `block = 'average'` averages the components from all blocks to produce a consensus plot. The argument `block='weighted.average'` is a weighted average of the components according to their correlation with the outcome Y.

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

Note: the ellipse options were borrowed from the ellipse.

### Value

none

### Author(s)

Ignacio González, Benoit Gautier, Francois Bartolo, Florian Rohart, Kim-Anh Lê Cao, Al J Abadi

### 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, panel plot for X and Y subspaces
    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')

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

    # 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,
    legend = TRUE)

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

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

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

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

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

    ## variable representation for objects of class 'sgcca' (or 'rgcca')
    # ----------------------------------------------------

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

    ## variable representation for objects of class 'sgccda'
    # ----------------------------------------------------

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

    # include the average plot (average the components across datasets)
    plotIndiv(nutrimouse.sgccda1, blocks = "average", group = nutrimouse$diet)

    # include the weighted average plot (average of components weighted by
    # correlation of each dataset with Y)
    plotIndiv(
        nutrimouse.sgccda1,
        blocks = c("average", "weighted.average"),
        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.14.1 Index]