Plot organelle assignment data and results.

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 class '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 addLegendfor 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.

Value

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

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.

Author

Laurent Gatto <lg390@cam.ac.uk>

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
#> [1] "PCA"    "MDS"    "kpca"   "lda"    "t-SNE"  "nipals" "hexbin" "none"  
#> [9] "scree" 
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
#> [1] "blue"  "red"   "green"
getMarkers(dunkley2006)
#> organelleMarkers
#>      ER lumen   ER membrane         Golgi Mitochondrion            PM 
#>            14            45            28            55            46 
#>       Plastid      Ribosome           TGN       unknown       vacuole 
#>            20            19            13           428            21 
plot2D(dunkley2006)
#> Not enough colours: using colours and pch.

## 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)
#>           PC1 (64.36%) PC2 (22.34%)
#> AT1G09210    -4.734261   -0.8204175
#> AT1G21750    -4.615276   -1.1891468
#> AT1G51760    -4.770573   -1.6292717
#> AT1G56340    -5.318056   -0.9972462
#> AT2G32920    -5.135122   -1.5283630
#> AT2G47470    -4.899410   -0.8145343
plot2D(pca, method = "none", methargs  = list(dunkley2006))


## plotting in 3 dimenstions
plot3D(dunkley2006)
#> Loading required package: rgl
#> Warning: RGL: unable to open X11 display
#> Warning: 'rgl.init' failed, running with 'rgl.useNULL = TRUE'.
plot3D(dunkley2006, radius2 = 0.3)
plot3D(dunkley2006, dims = c(2, 4, 6))