trackFeatureMap {celltrackR}

Dimensionality Reduction on Track Features

Description

Perform a quick dimensionality reduction visualization of a set of tracks according to a given vector of track measures.

Usage

trackFeatureMap(
  tracks,
  measures,
  scale = TRUE,
  labels = NULL,
  method = "PCA",
  return.mapping = FALSE,
  ...
)

Arguments

tracks

the tracks that are to be clustered.

measures

a function, or a vector of functions (see TrackMeasures). Each function is expected to return a single number given a single track.

scale

logical indicating whether the measures values shall be scaled using the function scale before the mapping is performed.

labels

optional: a vector of labels of the same length as the track object. These are used to color points in the visualization.

method

"PCA" for a scatterplot along principal components, "MDS" for multidimensional scaling, "UMAP" for a UMAP. Note that for "UMAP", the uwot package must be installed.

return.mapping

logical: return the mapping object instead of only the plot? (defaults to FALSE).

...

additional parameters to be passed to the corresponding function: prcomp (for method="PCA"), cmdscale (for method="MDS"), or umap (for method="UMAP").

Details

The measures are applied to each of the tracks in the given tracks object. According to the resulting values, the tracks are mapped to fewer dimensions using the chosen method. If scale is TRUE, the measure values are scaled to mean value 0 and standard deviation 1 (per measure) before the mapping.

The dimensionality reduction methods PCA, MDS, and UMAP each produce a scatterplot of all tracks as points, plotted along the principal component axes generated by the corresponding method.

Value

By default, only returns a plot. If return.clust=TRUE, also returns a clustering object as returned by hclust, kmeans, prcomp (returns $x), cmdscale, or umap (returns $layout). See the documentation of those functions for details on the output object.

See Also

getFeatureMatrix to obtain a feature matrix that can be used for manual clustering and plotting, and clusterTracks to perform hierarchical or k-means clustering on a tracks dataset.

Examples

## Map tracks according to speed, mean turning angle, straightness, and asphericity
## using multidimensional scaling, and store output.

cells <- c(TCells,Neutrophils)
real.celltype <- rep(c("T","N"),c(length(TCells),length(Neutrophils)))
## Prefix each track ID with its cell class to evaluate the clustering visually
names(cells) <- paste0(real.celltype,seq_along(cells))
map <- trackFeatureMap( cells, c(speed,meanTurningAngle,straightness, asphericity),
 method = "MDS",  return.mapping = TRUE  )