buildTree: Build Tree

In farrellja/URD: URD

Description

This function recovers the branching dendrogram structure from the developmental trajectories found by the random walks. IMPORTANT: CURRENTLY THIS FUNCTION IS DESTRUCTIVE. Output the results to a new URD object (i.e. object2 <- buildTree(object1, ...) or save your object (using saveRDS) before running.

Usage

buildTree(
  object,
  pseudotime,
  tips.use = NULL,
  divergence.method = c("ks", "preference"),
  weighted.fusion = T,
  use.only.original.tips = T,
  cells.per.pseudotime.bin = 80,
  bins.per.pseudotime.window = 5,
  minimum.visits = 10,
  visit.threshold = 0.7,
  save.breakpoint.plots = NULL,
  save.all.breakpoint.info = F,
  p.thresh = 0.01,
  min.cells.per.segment = 1,
  min.pseudotime.per.segment = 0.01,
  dendro.node.size = 100,
  dendro.cell.jitter = 0.15,
  dendro.cell.dist.to.tree = 0.05,
  verbose = T
)

Arguments

object	An URD object
pseudotime	(Character) Pseudotime to use for building tree
tips.use	(Character vector) Name of tips to use in the final tree (Default is NULL, which uses all tips.) Currently, these should all be numeric – the tree building function will fail otherwise.
divergence.method	(Character: "ks" or "preference") Test to use to determine whether visitation has diverged for each pseudotime window.
cells.per.pseudotime.bin	(Numeric) Approximate number of cells to assign to each pseudotime bin for branchpoint finding.
bins.per.pseudotime.window	(Numeric) Width of moving window in pseudotime used for branchpoint finding, in terms of bins.
minimum.visits	(Numeric) Minimum number of random walk visits to a cell to consider it for the tree
visit.threshold	(Numeric) Cells are considered potential members for segments/tips from which random walks visited them at least this fraction of their maximum visitation from a single tip (i.e. if visit.treshold=0.7 and a cell was visited most heavily from tip X with 10,000 visits, then all tips that visited that cell at least 7,000 times will include it when determining branchpoints.)
save.breakpoint.plots	(Path) Path to save plots summarizing (default is NULL, which does not save plots as they are somewhat slow)
save.all.breakpoint.info	(Logical) Should all information about breakpoints be stored in the object for use in diagnostic plots? (Can add several hundred MB to object size, but enables branchpointDetails plots.)
p.thresh	(Numeric) p-value threshold to use in determining whether visitation is significantly different from pairs of tips
min.cells.per.segment	(Numeric) Segments with fewer assigned cells will be collapsed during tree construction
min.pseudotime.per.segment	(Numeric) Segments shorter than this in pseudotime will be collapsed during tree construction
dendro.node.size	(Numeric) Number of cells to assign per node (used for averaging expression for tree dendrogram branch coloring)
dendro.cell.jitter	(Numeric) For the dendrogram tree layout, how much jitter to apply to cells. This can be revised after building the tree by re-generating the cell layout using treeLayoutCells with a different parameter.
dendro.cell.dist.to.tree	(Numeric) For the dendrogram tree layout, how far to push cells away from the dendrogram branches. This can be revised after building the tree by re-generating the cell layout using treeLayoutCells with a different parameter.
verbose	(Logical) Report on progress?

Details

This function starts from each tip and agglomeratively joins trajectories that visited the same cells (which indicates a common progenitor type). It works by first comparing all tips in a pair-wise fashion. For each pair, the cells visited by either tip are divided up by a moving window through pseudotime. Then, a test is used to determine whether the cells in each window were visited significantly differently by walks from the two tips. A putative branchpoint is chosen when the test starts being significant. After comparing all tips, the latest branchpoint is chosen, and the two segments are combined upstream of the branchpoint into a new segment. This process is repeated iteratively until only one trajectory remains. Then, the branching tree is refined to remove overly short segments, thereby allowing for multi-furcating branchpoints. Finally, the dendrogram layouts are generated.

There are several parameters that can be modified that affect the resultant tree structure slightly. (1) The test used for determining whether visitation of cells is different from two tips (divergence.method), the p-value threshold used (p.thresh), and the number of cells in each pseudotime window (cells.per.pseudotime.bin and bins.per.pseudotime.window). In general, adjusting the p-value threshold will make all branchpoints slightly earlier or later. Adjusting the number of cells in each window may be important to make sure that the procedure is buffered from noise (too small windows can cause bizarre fusion results), but if it is too large, cell populations that split near the end of your timecourse may immediately fuse.

A number of plots can help shed light on the tree-building process. If save.breakpoint.plots points to a path, then a plot is saved every time two branches fuse showing the pseudotime of the putative branchpoint between every pair of segments. The plots are named by the number of remaining segments (so the largest number is the first fusion event). Within a plot, each bar represents the comparison between a pair of segments with pseudotime along the x-axis, red represents pseudotime windows that are not significantly different and blue represents pseudotime windows that are significantly different, and the orange dotted line represents the putative pseudotime of the breakpoint. Additionally, branchpoint detail plots can be very useful if save.all.breakpoint.info=T – see branchpointDetailsVisitTsne, branchpointDetailsVisitDist, and branchpointDetailsPreferenceDist.

Value

An URD object with an URD-recovered tree structure stored in @tree.

Examples

# Load the cells used for each tip into the URD object
axial.tree <- loadTipCells(axial, "tip.clusters")

# Build the tree
axial.tree <- buildTree(axial.tree, pseudotime = "pseudotime", tips.use=1:2, divergence.method = "preference", cells.per.pseudotime.bin = 25, bins.per.pseudotime.window = 8, save.all.breakpoint.info = T, p.thresh=0.001)

object.built <- buildTree(object = object, pseudotime="pseudotime", divergence.method = "ks", tips.use=tips.to.use, weighted.fusion = T, use.only.original.tips = T, cells.per.pseudotime.bin=80, bins.per.pseudotime.window = 5, minimum.visits = 1, visit.threshold = 0.7, p.thresh = 0.025, save.breakpoint.plots = NULL, dendro.node.size = 100, min.cells.per.segment = 10, min.pseudotime.per.segment = .01, verbose = F)

farrellja/URD documentation built on June 17, 2020, 4:48 a.m.