reportEdges: Report MST edge coordinates
In TSCAN: Tools for Single-Cell Analysis

Description Usage Arguments Details Value Author(s) References See Also Examples

Provides the coordinates of the start and end of every edge in the MST, possibly on a different coordinate space from that used to construct the MST. This is mostly useful for plotting purposes in segments or the equivalent ggplot2 functionality.

reportEdges(x, ...)

## S4 method for signature 'ANY'
reportEdges(x, mst, clusters, combined = TRUE, columns = NULL)

## S4 method for signature 'SummarizedExperiment'
reportEdges(x, ..., assay.type = "logcounts")

## S4 method for signature 'SingleCellExperiment'
reportEdges(
  x,
  clusters = colLabels(x, onAbsence = "error"),
  ...,
  use.dimred = NULL
)

`x`	A numeric matrix of coordinates where each row represents a cell/sample and each column represents a dimension (usually a PC or another low-dimensional embedding, but features or genes can also be used). Alternatively, a SummarizedExperiment or SingleCellExperiment object containing such a matrix in its `assays`, as specified by `assay.type`. This will be transposed prior to use. Alternatively, for SingleCellExperiments, this matrix may be extracted from its `reducedDims`, based on the `use.dimred` specification. In this case, no transposition is performed. Alternatively, if `clusters=NULL`, a numeric matrix of coordinates for cluster centroids, where each row represents a cluster and each column represents a dimension Each row should be named with the cluster name. This mode can also be used with assays/matrices extracted from SummarizedExperiments and SingleCellExperiments.
`...`	For the generic, further arguments to pass to the specific methods. For the SummarizedExperiment method, further arguments to pass to the ANY method. For the SingleCellExperiment method, further arguments to pass to the SummarizedExperiment method (if `use.dimred` is specified) or the ANY method (otherwise).
`mst`	A graph object containing a MST, typically the output of `createClusterMST`. This need not be constructed from the same coordinates as those in `x`.
`clusters`	A factor-like object of the same length as `nrow(x)`, specifying the cluster identity for each cell in `x`. If `NULL`, `x` is assumed to already contain coordinates for the cluster centroids.
`combined`	Logical scalar indicating whether a single data.frame of edge coordinates should be returned.
`columns`	A character, logical or integer vector specifying the columns of `x` to use. If `NULL`, all provided columns are used by default.
`assay.type`	An integer or string specifying the assay to use from a SummarizedExperiment `x`.
`use.dimred`	An integer or string specifying the reduced dimensions to use from a SingleCellExperiment `x`.

It is entirely possibly to supply, say, t-SNE coordinates in x along with a MST constructed from the PCA coordinates. This allows us to visualize the edges of the MST on other low-dimensional embeddings. The coordinates in x can be per-cell or, if clusters=NULL, they are assumed to already be per-cluster means. x may also be NULL, in which case the center coordinates are obtained from the coordinates vertex attribute of mst.

A data.frame containing the start and end coordinates of segments representing all the edges in mst. If combined=FALSE, a list of two data.frames is returned where corresponding rows represent the start and end coordinates of the same edge.

Aaron Lun

Ji Z and Ji H (2016). TSCAN: Pseudo-time reconstruction and evaluation in single-cell RNA-seq analysis. Nucleic Acids Res. 44, e117

createClusterMST, to generate mst.

quickPseudotime, a wrapper to quickly perform these calculations.

# Re-using the example from ?createClusterMST.
example(createClusterMST, ask=FALSE) 

# Plotting the MST on top of existing visualizations:
edges <- reportEdges(x=NULL, mst, combined=FALSE)
plot(cells[,1], cells[,2], col=clusters)
segments(edges$start$dim1, edges$start$dim2, edges$end$dim1, 
     edges$end$dim2, lwd=5)

# Use with coordinates other than those used to make the MST:
shifted.cells <- cells + 10

shift.edges <- reportEdges(shifted.cells, mst, 
    clusters=clusters, combined=FALSE)
plot(shifted.cells[,1], shifted.cells[,2], col=clusters)
segments(shift.edges$start$dim1, shift.edges$start$dim2, 
    shift.edges$end$dim1, shift.edges$end$dim2, lwd=5)

# Also works for ggplot2:
df <- data.frame(shifted.cells, cluster=factor(clusters))
shift.edges2 <- reportEdges(shifted.cells, mst, clusters=clusters)

library(ggplot2)
ggplot(df) +
   geom_point(aes(x=X1, y=X2, color=cluster)) + 
   geom_line(data=shift.edges2, mapping=aes(x=dim1, y=dim2, group=edge))