In bicbioeng/ctgPHYL: Package for Single-cell Data Visualization and Analysis

knitr::opts_chunk$set(echo = TRUE)

Introduction

There are a number of R packages that exist for visualization of phylogenetic data. Each of these packages have unique inputs, outputs, and visualization schemes, which makes cross-comparison between methods time-consuming. ctgPHYL is an R package that streamlines the building of phylogenetic trees across multiple existing tools, using a unified output for improved comparability and reproducibility. Results are stored in the SIF file format for use in downstream analysis workflows or as input into Cytoscape. Currently supports tools from r Biocpkg("cellscape"),r Biocpkg("timescape"), and r Biocpkg("mapscape").

Installing ctgPHYL

Installing htmlwidgets (Optional)

To optionally save cellscape, timescape, and mapscape plots as self-contained files, the htmlwidgets package must also be installed.

install.packages("htmlwidgets")

Installing Bioconductor and the ctgPHYL package

ctgPHYL requires the most recent version of Bioconductor. For more information on Bioconductor, please see their website at https://bioconductor.org. To install Bioconductor and ctgPHYL, run the following commands:

# For R version >= 4.0
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("ctgPHYL")

After installing, attach the ctgPHYL package with the following command:

library(ctgPHYL)

Preparing a ctgPHYLset object

The ctgPHYL workflow is based around a single data class. Details for loading the data for and constructing an example ctgPHYLset object suitable for this vignette can be found in the following section.

Loading the Data

A ctgPHYLset object that will support all of the tree types in the ctgPHYL requires a variety of data types, as each tree type has specific requirements. For this vignette, we will construct a toy object using examples provided in the vignettes for each tree package. This will include single-cell copy-number variation and targeted mutation data. Note that these data do not necessarily correlate to one another in any way and are strictly for example purposes.

# load data for cellscape
cs_tree_edges <-
  read.csv(system.file("extdata", "cnv_tree_edges.csv",
                        package = "cellscape"))
cs_cnv_data <- read.csv(system.file("extdata", "cnv_data.csv",
                                    package = "cellscape"))
cs_sc_annot <- read.csv(system.file("extdata", "cnv_annots.tsv",
                                    package = "cellscape"),
                        sep = "\t")
cs_clone_colours <- data.frame(clone_id = c("1", "2", "3"),
                               colour = c("7fc97f", "beaed4", "fdc086"))
# load data for timescape
ts_tree_edges <-
  read.csv(system.file("extdata", "AML_tree_edges.csv",
                       package = "timescape"))
ts_clonal_prev <-
  read.csv(system.file("extdata", "AML_clonal_prev.csv",
                       package = "timescape"))
ts_mutations <- read.csv(system.file("extdata", "AML_mutations.csv",
                                     package = "timescape"))
ts_perturbations <- data.frame(pert_name = c("Chemotherapy"),
                               prev_tp = c("Diagnosis"))

# load data for mapscape
ms_clonal_prev <-
  read.csv(system.file("extdata", "A21_clonal_prev.csv",
                       package = "mapscape"))
ms_mutations <- read.csv(system.file("extdata", "A21_mutations.csv",
                                     package = "mapscape"))
ms_sample_locations <- read.csv(system.file("extdata",
                                            "A21_sample_locations.csv",
                                            package = "mapscape"))
ms_tree_edges <- read.csv(system.file("extdata", "A21_tree.csv",
                                      package = "mapscape"))

ms_img_ref <- system.file("extdata", "A21_anatomical_image.png",
                          package = "mapscape")

ms_sample_ids <- c("H", "F", "J", "D", "A", "I", "C", "E", "G")

Constructing a ctgPHYLset object

To construct the ctgPHYLset for this vignette, we will create an empty ctgPHYLset and then add in the data loaded in the previous step.

toyPHYLset <- ctgPHYLset()

Adding Data: cellscape, timescape, and mapscape

The cellscape, timescape, and mapscape tree methods require properly formatted data. We can add the example data loaded earlier to our ctgPHYLset. Because each piece of these data corresponds to a parameter used by one of the packages, when it is added to a ctgPHYLset, the parameter name must be supplied. Additional details concerning these parameters can be found in the respective package's documentation. Note: Although these some of these data share the same parameter name, these example data are not interchangable.

# store cellscape data
cellscapeData(toyPHYLset, "clone_colours") <- cs_clone_colours
cellscapeData(toyPHYLset, "tree_edges") <- cs_tree_edges 
cellscapeData(toyPHYLset, "cnv_data") <- cs_cnv_data
cellscapeData(toyPHYLset, "sc_annot") <- cs_sc_annot

# store timescape data
timescapeData(toyPHYLset, "tree_edges") <- ts_tree_edges
timescapeData(toyPHYLset, "clonal_prev") <- ts_clonal_prev
timescapeData(toyPHYLset, "mutations") <- ts_mutations
timescapeData(toyPHYLset, "perturbations") <- ts_perturbations

# store mapscape data
mapscapeData(toyPHYLset, "clonal_prev") <- ms_clonal_prev
mapscapeData(toyPHYLset, "mutations") <- ms_mutations
mapscapeData(toyPHYLset, "sample_locations") <- ms_sample_locations
mapscapeData(toyPHYLset, "tree_edges") <- ms_tree_edges
mapscapeData(toyPHYLset, "img_ref") <- ms_img_ref
mapscapeData(toyPHYLset, "sample_ids") <- ms_sample_ids

Using ctgPHYL

To use ctgPHYL, call the generate_tree function with the desired tree method and ctgPHYLset object. The user can specify the desired output directory using the 'outputDir' parameter or use the default, which is the current working directory returned by getwd().

Using cellscape:

To use our example ctgPHYLset and the cellscape method, we would type the following:

toyPHYLset <- generate_tree(dataSet = toyPHYLset, treeType = "cellscape")

This stores the final tree in the originalTrees slot of the ctgPHYLset object, a simplified r CRANpkg("igraph") version of the tree in the treeList within the ctgPHYLset object, and if necessary creates a new folder, called "CTG-Output", that contains a folder called "SIFs" containing the .SIF text file for the final tree, and a folder called "Plots" containing an .html file with the final product. The .html version is interactive, but a static version is displayed here.

knitr::include_graphics(file.path("figures", "cellscape.png"))

Using timescape:

To use our example ctgPHYLset and the timescape method, we would type the following:

toyPHYLset <- generate_tree(dataSet = toyPHYLset, treeType = "timescape")

This stores the final tree in the originalTrees slot of the ctgPHYLset object, a simplified r CRANpkg("igraph") version of the tree in the treeList within the ctgPHYLset object, and if necessary creates a new folder, called "CTG-Output", that contains a folder called "SIFs" containing the .SIF text file for the final tree, and a folder called "Plots" containing an .html file with the final product. The .html version is interactive, but a static version is displayed here.

knitr::include_graphics(file.path("figures", "timescape.png"))

Using mapscape:

To use our example ctgPHYLset and the mapscape method, we would type the following:

toyPHYLset <- generate_tree(dataSet = toyPHYLset, treeType = "mapscape")

This stores the final tree in the originalTrees slot of the ctgPHYLset object, a simplified r CRANpkg("igraph") version of the tree in the treeList within the ctgPHYLset object, and if necessary creates a new folder, called "CTG-Output", that contains a folder called "SIFs" containing the .SIF text file for the final tree, and a folder called "Plots" containing an .html file with the final product. The .html version is interactive, but a static version is displayed here.

knitr::include_graphics(file.path("figures", "mapscape.png"))

Replotting Trees

If at some point we wish to view the plot of a tree generated after it's been created, but don't want to have to regenerate it and all its files, ctgPHYL has a function, plotOriginalTree(), that will reproduce a plot stored in a ctgPHYLset object. To use this function, we must know the name of the tree we wish to plot. We can view the names of the trees in our toyPHYLset using the names() function.

names(originalTrees(toyPHYLset))

n <- c("cellscape", "timescape", "mapscape")
print(n)

Once we have the names, we can choose a tree to plot. Let's plot the "cellscape" tree again.

plotOriginalTree(toyPHYLset, "cellscape")

knitr::include_graphics(file.path("figures", "cellscape.png"))

Using this function eliminates the need to regenerate the tree to view a plot that was already created, thereby saving time for trees that require extensive computations to generate.

To store your analysis session result for later use, you can use the .Rda format.

save(toyPHYLset, file = "toyPHYLset.Rda")

Session Information

sessionInfo()

References

cellscape

Maia Smith (2017). cellscape: Explores single cell copy number profiles in the context of a single cell tree. R package version 1.0.0.

cellscape package URL: https://bioconductor.org/packages/cellscape

timescape

Maia Smith (2017). timescape: Patient Clonal Timescapes. R package version 1.0.0.

timescape package URL: https://bioconductor.org/packages/timescape

mapscape

Maia Smith (2017). mapscape: mapscape. R package version 1.0.0.

mapscape package URL: https://bioconductor.org/packages/mapscape

bicbioeng/ctgPHYL documentation built on April 13, 2020, 12:38 a.m.