Installation

To install MapScape, type the following commands in R:

# try http:// if https:// URLs are not supported
if (!requireNamespace("BiocManager", quietly=TRUE))
    install.packages("BiocManager")
BiocManager::install("mapscape")

Examples

Run the examples by:

example("mapscape")

Three visualizations will appear in your browser (optimized for Chrome).

For instance, the first visualization is of metastatic prostate cancer data published in Gundem et al. (2015):

Required parameters

The required parameters for MapScape are as follows:

clonal_prev is a data frame consisting of clonal prevalences for each clone at each time point. The columns in this data frame are:

1. character() sample_id - id for the tumour sample
2. character() clone_id - clone id
3. numeric() clonal_prev - clonal prevalence.

tree_edges is a data frame describing the edges of a rooted clonal phylogeny. The columns in this data frame are:

1. character() source - source node id
2. character() target - target node id.

sample_locations is a data frame describing the anatomical locations for each tumour sample. The columns in this data frame are:

1. character() sample_id - id for the tumour sample
2. character() location_id - name of anatomic location for this tumour sample
3. numeric() (Optional) x - x-coordinate (in pixels) for anatomic location on anatomic image
4. numeric() (Optional) y - y-coordinate (in pixels) for anatomic location on anatomic image

img_ref is a reference for the custom anatomical image to use, in PNG format, either a URL to an image hosted online or a path to the image in local file system.

Optional parameters

Cellular Aggregate vs Donut Chart views

Each sample can be represented as either

• a cellular aggregate

Screen capture of cellular aggregate.

• or a donut chart

Screen capture of donut chart.

Obtaining the data

E-scape takes as input a clonal phylogeny and clonal prevalences per clone per sample. At the time of submission many methods have been proposed for obtaining these values, and accurate estimation of these quantities is the focus of ongoing research. We describe a method for estimating clonal phylogenies and clonal prevalence using PyClone (Roth et al., 2014; source code available at https://bitbucket.org/aroth85/pyclone/wiki/Home) and citup (Malikic et al., 2016; source code available at https://github.com/sfu-compbio/citup). In brief, PyClone inputs are prepared by processing fastq files resulting from a targeted deep sequencing experiment. Using samtools mpileup (http://samtools.sourceforge.net/mpileup.shtml), the number of nucleotides matching the reference and non-reference are counted for each targeted SNV. Copy number is also required for each SNV. We recommend inferring copy number from whole genome or whole exome sequencing of samples taken from the same anatomic location / timepoint as the samples to which targeted deep sequencing was applied. Copy number can be inferred using Titan (Ha et al., 2014; source code available at https://github.com/gavinha/TitanCNA). Sample specific SNV information is compiled into a set of TSV files, one per sample. The tables includes mutation id, reference and variant read counts, normal copy number, and major and minor tumour copy number (see PyClone readme). PyClone is run on these files using the PyClone run_analysis_pipeline subcommand, and produces the tables/cluster.tsv in the working directory. Citup can be used to infer a clonal phylogeny and clone prevalences from the cellular prevalences produced by PyClone. The tables/cluster.tsv file contains per sample, per SNV cluster estimates of cellular prevalence. The table is reshaped into a TSV file of cellular prevalences with rows as clusters and columns as samples, and the mean of each cluster taken from tables/cluster.tsv for the values of the table. The iterative version of citup is run on the table of cellular frequencies, producing an hdf5 output results file. Within the hdf5 results, the /results/optimal can be used to identify the id of the optimal tree solution. The clonal phylogeny as an adjacency list is then the /trees/{tree_solution}/adjacency_list entry and the clone frequencies are the /trees/{tree_solution}/clone_freq entry in the hdf5 file. The adjacency list can be written as a TSV with the column names source, target to be input into E-scape, and the clone frequencies should be reshaped such that each row represents a clonal frequency in a specific sample for a specific clone, with the columns representing the time or space ID, the clone ID, and the clonal prevalence.

Interactivity

Interactive components in the top toolbar:

1. Click the download buttons to download the current view as PNG or SVG.
2. Click the reset button to exit a clone or mutation selection.
3. Click the view switch button to switch between cellular aggregate and donut views of each sample.

Interactive components in main view:

1. Reorder samples by grabbing the sample name or cellular aggregate / donut and dragging it radially.
2. Hover over anatomic location of interest to view the anatomic location name and the patient data associated with that location.
3. Hover over a tree node of a particular sample to view cellular prevalence of that clone in that particular sample.

Interactive components in legend:

1. Hover over legend tree node to view the clone ID as well as the clone’s prevalence at each tumour sample. Any anatomic locations expressing that clone will be highlighted.
2. Hover over legend tree branch to view tumour samples expressing all descendant clones.
3. Click on legend tree node(s) to view (a) updated mutations table showing novel mutations at that clone(s), and (b) tumour samples expressing the novel mutations at that clone(s).
4. Hover over a mixture class (e.g. “pure”, “polyphyletic”, “monophyletic”) to view corresponding tumour samples, and the participating phylogeny in each tumour sample.

Interactive components in mutation table:

1. Search for any chromosome, coordinate, gene, etc.
2. Click on a row in the table, and the view will update to show the tumour samples with that mutation, and the variant allele frequency for that mutation in each tumour sample.
3. Sort the table by a column (all columns sortable except the Clone column).

Documentation

To view the documentation for MapScape, type the following command in R:

?mapscape

or:

browseVignettes("mapscape") 

References

MapScape was developed at the Shah Lab for Computational Cancer Biology at the BC Cancer Research Centre.

References:

Gundem, Gunes, et al. “The evolutionary history of lethal metastatic prostate cancer.” Nature 520.7547 (2015): 353-357.

Ha, Gavin, et al. “TITAN: inference of copy number architectures in clonal cell populations from tumor whole-genome sequence data.” Genome research 24.11 (2014): 1881-1893.

Malikic, Salem, et al. “Clonality inference in multiple tumor samples using phylogeny.” Bioinformatics 31.9 (2015): 1349-1356.

McPherson, Andrew, et al. “Divergent modes of clonal spread and intraperitoneal mixing in high-grade serous ovarian cancer.” Nature genetics (2016).

Roth, Andrew, et al. “PyClone: statistical inference of clonal population structure in cancer.” Nature methods 11.4 (2014): 396-398.