plot2D {pRoloc} | R Documentation

## Plot organelle assignment data and results.

### Description

Generate 2 or 3 dimensional feature distribution plots to illustrate localistation clusters. Rows/features containing `NA` values are removed prior to dimension reduction except for the `"nipals"` method. For this method, it is advised to set the method argument 'ncomp' to a low number of dimensions to avoid computing all components when analysing large datasets.

### Usage

    plot2D(object, fcol = "markers", fpch, unknown = "unknown",
      dims = 1:2, score = 1, method = "PCA", methargs,
      axsSwitch = FALSE, mirrorX = FALSE, mirrorY = FALSE, col, pch, cex,
      index = FALSE, idx.cex = 0.75, addLegend, identify = FALSE,
      plot = TRUE, grid = TRUE, ...)

    ## S4 method for signature 'MSnSet'
    plot3D(object, fcol = "markers", dims = c(1, 2, 3),
      radius1 = 0.1, radius2 = radius1 * 2, plot = TRUE, ...)

### Arguments

`object` | An instance of class `MSnSet`.
`fcol` | Feature meta-data label (fData column name) defining the groups to be differentiated using different colours. Default is `markers`. Use `NULL` to suppress any colouring.
`fpch` | Featre meta-data label (fData column name) desining the groups to be differentiated using different point symbols.
`unknown` | A `character` (default is `"unknown"`) defining how proteins of unknown/un-labelled localisation are labelled.
`dims` | A `numeric` of length 2 (or 3 for `plot3D`) defining the dimensions to be plotted. Defaults are `c(1, 2)` and `c(1, 2, 3)`. Always `1:2` for MDS.
`score` | A numeric specifying the minimum organelle assignment score to consider features to be assigned an organelle. (not yet implemented).
`method` | A `character` describe how to transform the data or what to plot. One of `"PCA"` (default), `"MDS"`, `"kpca"`, `"nipals"`, `"t-SNE"` or `"lda"`, defining what dimensionality reduction is applied: principal component analysis (see `prcomp`), classical multidimensional scaling (see `cmdscale`), kernel PCA (see `kpca`), nipals (principal component analysis by NIPALS, non-linear iterative partial least squares which support missing values; see `nipals`) t-SNE (see `Rtsne`) or linear discriminant analysis (see `lda`). The last method uses `fcol` to defined the sub-cellular clusters so that the ration between within ad between cluster variance is maximised. All the other methods are unsupervised and make use `fcol` only to annotate the plot. Prior to t-SNE, duplicated features are removed and a message informs the user if such filtering is needed. `"scree"` can also be used to produce a scree plot. `"hexbin"` applies PCA to the data and uses bivariate binning into hexagonal cells from `hexbin` to emphasise cluster density. If none is used, the data is plotted as is, i.e. without any transformation. In this case, `object` can either be an `MSnSet` or a `matrix` (as invisibly returned by `plot2D`). This enables to re-generate the figure without computing the dimensionality reduction over and over again, which can be time consuming for certain methods. If `object` is a `matrix`, an `MSnSet` containing the feature metadata must be provided in `methargs` (see below for details). Available methods are listed in `plot2Dmethods`.
`methargs` | A `list` of arguments to be passed when `method` is called. If missing, the data will be scaled and centred prior to PCA and t-SNE (i.e. `Rtsne`'s arguments `pca_center` and `pca_scale` are set to `TRUE`). If `method = "none"` and `object` is a `matrix`, then the first and only argument of `methargs` must be an `MSnSet` with matching features with `object`.
`axsSwitch` | A `logical` indicating whether the axes should be switched.
`mirrorX` | A `logical` indicating whether the x axis should be mirrored?
`mirrorY` | A `logical` indicating whether the y axis should be mirrored?
`col` | A `character` of appropriate length defining colours.
`pch` | A `character` of appropriate length defining point character.
`cex` | Character expansion.
`index` | A `logical` (default is `FALSE`, indicating of the feature indices should be plotted on top of the symbols.
`idx.cex` | A `numeric` specifying the character expansion (default is 0.75) for the feature indices. Only relevant when `index` is TRUE.
`addLegend` | A character indicating where to add the legend. See `addLegend`for details. If missing (default), no legend is added.
`identify` | A logical (default is `TRUE`) defining if user interaction will be expected to identify individual data points on the plot. See also `identify`.
`plot` | A `logical` defining if the figure should be plotted. Useful when retrieving data only. Default is `TRUE`.
`grid` | A `logical` indicating whether a grid should be plotted. Default is `TRUE`.
`...` | Additional parameters passed to `plot` and `points`.
`radius1` | A `numeric` specifying the radius of feature of unknown localisation. Default is 0.1, which is specidied on the data scale. See `plot3d` for details.
`radius2` | A `numeric` specifying the radius of marker feature. Default is `radius` * 2.

### Details

`plot3D` relies on the ##' `rgl` package, that will be loaded automatically.

- Note that `plot2D` has been update in version 1.3.6 to support more organelle classes than colours defined in `getStockcol`. In such cases, the default colours are recycled using the default plotting characters defined in `getStockpch`. See the example for an illustration. The `alpha` argument is also depreciated in version 1.3.6. Use `setStockcol` to set colours with transparency instead. See example below.

- Version 1.11.3: to plot data as is, i.e. without any transformation, `method` can be set to "none" (as opposed to passing pre-computed values to `method` as a `matrix`, in previous versions). If `object` is an `MSnSet`, the untransformed values in the assay data will be plotted. If `object` is a `matrix` with coordinates, then a matching `MSnSet` must be passed to `methargs`.

### Value

Used for its side effects of generating a plot. Invisibly returns the 2 or 3 dimensions that are plotted.

### Author(s)

Laurent Gatto <lg390@cam.ac.uk>

### See Also

`addLegend` to add a legend to `plot2D` figures (the legend is added by default on `plot3D`) and `plotDist` for alternative graphical representation of quantitative organelle proteomics data. `plot2Ds` to overlay 2 data sets on the same PCA plot. The `plotEllipse` function can be used to visualise TAGM models on PCA plots with ellipses.

### Examples

    library("pRolocdata")
    data(dunkley2006)
    plot2D(dunkley2006, fcol = NULL)
    plot2D(dunkley2006, fcol = NULL, col = "black")
    plot2D(dunkley2006, fcol = "markers")
    addLegend(dunkley2006,
              fcol = "markers",
              where = "topright",
              cex = 0.5, bty = "n", ncol = 3)
    title(main = "plot2D example")
    ## available methods
    plot2Dmethods
    plot2D(dunkley2006, fcol = NULL, method = "kpca", col = "black")
    plot2D(dunkley2006, fcol = NULL, method = "kpca", col = "black",
           methargs = list(kpar = list(sigma = 1)))
    plot2D(dunkley2006, method = "lda")
    plot2D(dunkley2006, method = "hexbin")
    ## Using transparent colours
    setStockcol(paste0(getStockcol(), "80"))
    plot2D(dunkley2006, fcol = "markers")
    ## New behavious in 1.3.6 when not enough colours
    setStockcol(c("blue", "red", "green"))
    getStockcol() ## only 3 colours to be recycled
    getMarkers(dunkley2006)
    plot2D(dunkley2006)
    ## reset colours
    setStockcol(NULL)
    plot2D(dunkley2006, method = "none") ## plotting along 2 first fractions
    plot2D(dunkley2006, dims = c(3, 5), method = "none") ## plotting along fractions 3 and 5
    ## pre-calculate PC1 and PC2 coordinates
    pca <- plot2D(dunkley2006, plot=FALSE)
    head(pca)
    plot2D(pca, method = "none", methargs  = list(dunkley2006))

    ## plotting in 3 dimenstions
    plot3D(dunkley2006)
    plot3D(dunkley2006, radius2 = 0.3)
    plot3D(dunkley2006, dims = c(2, 4, 6))

[Package pRoloc version 1.30.0 Index]