cloneMap: Construct clone maps

In amf71/cloneMap: A Package to Construct Visual Representations of the Spatial Distribution of Somatic Clones in a Tissue / Sample

Construct clone maps

Description

Function to represent somatic clones present in a tissue accounting for clone size, ie the Cancer Cell Fraction (CCF), and for phylogenetic relationships between clones

Usage

cloneMap(
  tree.mat = NA,
  CCF.data = NA,
  clone_map = NA,
  output.Clone.map.obj = FALSE,
  plot.data = TRUE,
  high_qualty_mode = FALSE,
  track = NA,
  brewer.palette = "Paired",
  clone.cols = NA,
  border.colour = "grey20",
  border.thickness = 1.5,
  resolution.index = 100,
  smoothing.par = 10,
  repeat.limit = 4,
  space_fraction = NA,
  tissue_border = FALSE
)

Arguments

tree.mat	A phylogenetic tree matrix with two columns and one row per phylogenetic relationship (column1 = parent, column2 = child). All clones must be contained in the tree or they will not be plotted (see example data).
CCF.data	A table indicating CCFs for each clone in the tree (column names are "clones" and "CCF", see example data).
clone_map	Instead of providing a tree and CCF table you may provide a 'clone_map' object which has previously been outputted by setting 'output.Clone.map.obj' as TRUE. This contains data specifying tree structure and the positions of clones. When inputting a tree and a CCF table, clone positions are semi-randomly generated but when inputting a 'clone_map' postions will be the identical each time as the postions are recorded in the input and once the 'clone_map' has been generated the plotting is far quicker.
output.Clone.map.obj	If TRUE output a clone_map object containing informtion on the positions of clones. This object can be saved and repeatly provided back to the 'clone_map' argument of this function to reproduce precisely the same plot and once the 'clone_map' has been generated the plotting is far quicker.
plot.data	Plot the cloneMap visualisation now. This may not be desirable if 'output.Clone.map.obj' is set to TRUE.
high_qualty_mode	This activates several mechanisms to ensure high quality plots at the expense of longer running times, particularly so for some input data. These mechanisms attempt to aviod plots where the same clone seperates into several islands, and hence is not continuous with itself, as well as interweaving of clones. If TRUE Track will also be TRUE unless Track is explicited set to FALSE.
track	Provide extra feedback on progress of function. Default is FALSE in normal mode but TRUE in high quialty mode.
brewer.palette	A qualitative colour pallette from the 'RColourBrewer' package to use for the clones.
clone.cols	A named vector specifying hexidecimal colours for all clones in your input (see example). This allows you to keep consistent colours for the same clone accross several plots with different inputs, for instance if you wish to plot cloneMaps for each of several samples from the same tumour.
border.colour	The colour of the clone borders.
border.thickness	The thickness of the clone borders.
resolution.index	This indicates the resolution of the model representing clonal growth. More precisely it is the diameter of the rasterised matrix in which each point represents a position where a clone can reside. A higher resolution index will allow more precise positioning of clones but also increase running time.
smoothing.par	Smoothing parameter for the clones. Edges of the clones are smoothed for visual appeal. The higher this parameter the more smoothing will occur.
repeat.limit	When 'high_qualty_mode' is TRUE the function will test each clone for continuity (i.e. that there are not multiple islands or patches of the same clone) and if so it will plot this clone and all its sisters again to attempt to avoid this as clone positions are semi-randomly generated. The 'repeat.limit' indicates the maximum number of allowed repeats before the function will output a warning and continue with the plot. These repeats increase run time significantly when high_quality_mode' is TRUE. After two repeats the function will use various mechanisms to decrease the probability of non-continuous clones even further but at the expense of even longer run times.
space_fraction	When an unrooted tree is provided how much much of the plot should be white space. White space indicates non-mutated tissue and hence the density of the clones. Default is NA in which case the amount of white space will be determined by the CCFs provided i.e. if all the root clone CCFs add up to 60 space fraction is specified the CCFs for an unrooted tree become relative to amount of non-white space which is available.
tissue_border	When a tree is unrooted, should a border be draw to make clear the edge of the tissue. Default is FALSE.

Value

A 'clone_map' object will be returned if 'output.Clone.map.obj' is TRUE containing information on clonal positions and tree structure. This output can be inputted using the 'clone_map' argument to repeat the same plot many times.

Author(s)

Alexander M Frankell, Francis Crick institute, University College London, [e-mail]

Examples

# example objects provided in env after loading package #

cloneMap( tree_example, CCFs_example_1 )
cloneMap( tree_example, CCFs_example_2 ) 


# Use a clone_map object to  plot cloneMap reproducibility #

clone_map_eg <- cloneMap( tree_example, CCFs_example_2, 
                          output.Clone.map.obj = TRUE, plot.data = FALSE )
cloneMap( clone_map = clone_map_eg )


# specify colours #
# plot two samples from the same tumour so the clone colours match #

cloneMap( tree_example, CCFs_example_1, clone.cols = clone_colours_example )
cloneMap( tree_example, CCFs_example_2, clone.cols = clone_colours_example )

# Can also be used with tree containing unrelated clones i.e. unrooted trees #
# such as is common is data derived from normal tissues: #

cloneMap( tree.mat = tree_example_poly, 
CCF.data = CCF_example_poly )

cloneMap( tree.mat = tree_example_poly, 
CCF.data = CCF_example_poly,
tissue_border = TRUE)

# Here space_fraction indicates that 70% of the plot area should be white space #
# indicating that only 70% of cells are wild type.

cloneMap( tree.mat = tree_example_poly, 
CCF.data = CCF_example_poly,
tissue_border = TRUE,
space_fraction = 0.7 )

amf71/cloneMap documentation built on Jan. 11, 2024, 5:28 a.m.