Description Usage Arguments Details Value Examples
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | 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
)
|
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 |
save.breakpoint.plots |
(Path) Path to save plots summarizing (default is |
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 |
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 |
verbose |
(Logical) Report on progress? |
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
.
An URD object with an URD-recovered tree structure stored in @tree
.
1 2 3 4 5 6 7 | # 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)
|
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.