plottingFunctions {clusterExperiment} | R Documentation

## Convert clusterLegend into useful formats

### Description

Function for converting the information stored in the clusterLegend slot into other useful formats.

Most of these functions are called internally by plotting functions, but are exported in case the user finds them useful.

### Usage

    makeBlankData(
      data,
      groupsOfFeatures = NULL,
      groupsOfSamples = NULL,
      nBlankFeatures = 1,
      nBlankSamples = 1
    )

    ## S4 method for signature 'ClusterExperiment'
    convertClusterLegend(
      object,
      output = c("plotAndLegend", "aheatmapFormat", "matrixNames", "matrixColors"),
      whichClusters = ifelse(output == "plotAndLegend", "primary", "all")
    )

    showPalette(colPalette = bigPalette, which = NULL, cex = 1)

    bigPalette

    massivePalette

    setBreaks(data, breaks = NA, makeSymmetric = FALSE, returnBreaks = TRUE)

    showHeatmapPalettes()

    seqPal5

    seqPal2

    seqPal3

    seqPal4

    seqPal1

    ## S4 method for signature 'ClusterExperiment'
    plotClusterLegend(
      object,
      whichCluster = "primary",
      clusterNames,
      title,
      add = FALSE,
      location = if (add) "topright" else "center",
      ...
    )

### Arguments

`data` | matrix with samples on columns and features on rows.
`groupsOfFeatures` | list, with each element of the list containing a vector of numeric indices of features (rows).
`groupsOfSamples` | list, with each element of the list containing a vector of numeric indices of samples (columns).
`nBlankFeatures` | the number of blank lines to add in the data matrix to separate the groups of feature indices (will govern the amount of white space if data is then fed to heatmap.)
`nBlankSamples` | the number of blank lines to add in the data matrix to separate the groups of sample indices (will govern the amount of white space if data is then fed to heatmap.)
`object` | a `ClusterExperiment` object.
`output` | character value, indicating desired type of conversion.
`whichClusters` | argument that can be either numeric or character vector indicating the clusterings to be used. See details of `getClusterIndex`.
`colPalette` | a vector of character colors. By default, the palette `bigPalette` is used
`which` | numeric. Which colors to plot. Must be a numeric vector with values between 1 and length of `colPalette`. If missing, all colors plotted.
`cex` | numeric value giving the cex for the text of the plot.
`breaks` | either vector of breaks, or number of breaks (integer) or a number between 0 and 1 indicating a quantile, between which evenly spaced breaks should be calculated. If missing or NA, will determine evenly spaced breaks in the range of the data.
`makeSymmetric` | whether to make the range of the breaks symmetric around zero (only used if not all of the data is non-positive and not all of the data is non-negative)
`returnBreaks` | logical as to whether to return the vector of breaks. See details.
`whichCluster` | argument that can be a single numeric or character value indicating the single clustering to be used. Giving values that result in more than one clustering will result in an error. See details of `getClusterIndex`.
`clusterNames` | vector of names for the clusters; vector should have names that correspond to the clusterIds in the ClusterExperiment object. If this argument is missing, will use the names in the "name" column of the clusterLegend slot of the object.
`title` | title for the clusterLegend plot
`add` | logical. Whether legend should be added to the existing plot.
`location` | character passed to `x` argument of legend indicating where to place legend.
`...` | arguments passed to legend

### Format

An object of class `character` of length 56.

An object of class `character` of length 484.

An object of class `character` of length 16.

An object of class `character` of length 14.

An object of class `character` of length 11.

An object of class `character` of length 13.

An object of class `character` of length 11.

### Details

`makeBlankData` pulls the data corresponding to the row indices in `groupsOfFeatures` adds lines of NA values into data between these groups. When given to heatmap, will create white space between these groups of features.

convertClusterLegend pulls out information stored in the `clusterLegend` slot of the object and returns it in useful format.

`bigPalette` is a long palette of colors (length 58) used by `plotClusters` and accompanying functions. `showPalette` creates plot that gives index of each color in a vector of colors. `massivePalette` is a combination of `bigPalette` and the non-grey colors of `colors()` (length 487). `massivePalette` is mainly useful for when doing `plotClusters` of a very large number of clusterings, each with many clusters, so that the code doesn't run out of colors. However, many of the colors will be very similar to each other.

`showPalette` will plot the `colPalette` colors with their labels and index.

if returnBreaks if FALSE, instead of returning the vector of breaks, the function will just return the second smallest and second largest value of the breaks. This is useful for alternatively just setting values of the data matrix larger than these values to this value if breaks was a percentile. This argument is only used if `breaks<1`, indicating truncating the breaks for large values of data.

`setBreaks` gives a set of breaks (of length 52) equally spaced between the boundaries of the data. If breaks is between 0 and 1, then the evenly spaced breaks are between these quantiles of the data.

`seqPal1`-`seqPal4` are palettes for the heatmap. `showHeatmapPalettes` will show you these palettes.

### Value

`makeBlankData` returns a list with items

- "dataWBlanks" The data with the rows of NAs separating the given indices.

- "rowNamesWBlanks" A vector of characters giving the rownames for the data, including blanks for the NA rows. These are not given as rownames to the returned data because they are not necessarily unique. However, they can be given to the `labRow` argument of `aheatmap` or `plotHeatmap`.

- "colNamesWBlanks" A vector of characters giving the colnames for the data, including blanks for the NA rows. They can be given to the `labCol` argument of `aheatmap` or `plotHeatmap`.

- "featureGroupNamesWBlanks" A vector of characters of the same length as the number of rows of the new data (i.e. with blanks) giving the group name for the data, indicating which group (i.e. which element of `groupsOfFeatures` list) the feature came from. If `groupsOfFeatures` has unique names, these names will be used, other wise "Feature Group1", "Feature Group2", etc. The NA rows are given NA values.

- "sampleGroupNamesWBlanks" A vector of characters of the same length as the number of columns of the new data (i.e. with blanks) giving the group name for the data, indicating which group (i.e. which element of `groupsOfFeatures` list) the feature came from. If `groupsOfFeatures` has unique names, these names will be used, other wise "SampleGroup1", "Group2", etc. The NA rows are given NA values.

If `output="plotAndLegend"`, `"convertClusterLegend"` will return a list that provides the necessary information to color samples according to cluster and create a legend for it:

- "colorVector" A vector the same length as the number of samples, assigning a color to each cluster of the primaryCluster of the object.

- "legendNames" A vector the length of the number of clusters of primaryCluster of the object giving the name of the cluster.

- "legendColors" A vector the length of the number of clusters of primaryCluster of the object giving the color of the cluster.

If `output="aheatmap"` a conversion of the clusterLegend to be in the format requested by `aheatmap`. The column 'name' is used for the names and the column 'color' for the color of the clusters.

If `output="matrixNames"` or `"matrixColors"` a matrix the same dimension of `clusterMatrix(object)`, but with the cluster color or cluster name instead of the clusterIds, respectively.

### See Also

`plotHeatmap`

### Examples

    data(simData)

    x <- makeBlankData(simData[,1:10], groupsOfFeatures=list(c(5, 2, 3), c(20,
    34, 25)))
    plotHeatmap(x$dataWBlanks,clusterFeatures=FALSE)
    showPalette()
    showPalette(massivePalette,cex=0.6)
    setBreaks(data=simData,breaks=.9)

    #show the palette colors
    showHeatmapPalettes()

    #compare the palettes on heatmap
    cl <- clusterSingle(simData, subsample=FALSE,
    sequential=FALSE,
    mainClusterArgs=list(clusterFunction="pam", clusterArgs=list(k=8)))

    ## Not run:
    par(mfrow=c(2,3))
    plotHeatmap(cl, colorScale=seqPal1, main="seqPal1")
    plotHeatmap(cl, colorScale=seqPal2, main="seqPal2")
    plotHeatmap(cl, colorScale=seqPal3, main="seqPal3")
    plotHeatmap(cl, colorScale=seqPal4, main="seqPal4")
    plotHeatmap(cl, colorScale=seqPal5, main="seqPal5")
    par(mfrow=c(1,1))

    ## End(Not run)

[Package clusterExperiment version 2.12.0 Index]