mapscape: MapScape
In mapscape: mapscape

Description Usage Arguments Details Examples

View source: R/mapscape.R

MapScape is a visualization tool for spatial clonal evolution. MapScape displays a cropped anatomical image surrounded by two representations of each tumour sample representing the distribution of clones throughout anatomic space. The first, a cellular aggregate or donut view, displays the prevalence of each clone. The second shows a skeleton of the patient<e2><80><99>s clonal phylogeny while highlighting only those clones present in the sample. Note: the cellular aggregate does not accurately represent the positions of clones within a sample. We therefore provide the alternative donut chart view as a less artistic representation of the tumour sample. See the Interactivity section below for instructions to switch between views.

mapscape(clonal_prev, tree_edges, sample_locations, img_ref,
  clone_colours = "NA", mutations = "NA", sample_ids = c("NA"),
  n_cells = 100, show_low_prev_gtypes = FALSE,
  phylogeny_title = "Clonal Phylogeny", anatomy_title = "Anatomy",
  classification_title = "Phylogenetic Classification",
  show_warnings = TRUE, width = 960, height = 960)

`clonal_prev`	`data.frame` Clonal prevalence. Required columns are: sample_id: `character()` id for the tumour sample. clone_id: `character()` clone id. clonal_prev: `numeric()` clonal prevalence.
`tree_edges`	`data.frame` Tree edges of a rooted tree. Required columns are: source: `character()` source node id. target: `character()` target node id.
`sample_locations`	`data.frame` Anatomic locations for each tumour sample. Required columns are: sample_id: `character()` id for the tumour sample. location_id: `character()` name of anatomic location for this tumour sample. x: `numeric()` x-coordinate (in pixels) for anatomic location on anatomic image. y: `numeric()` y-coordinate (in pixels) for anatomic location on anatomic image.
`img_ref`	`character()` 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.
`clone_colours`	`data.frame` (Optional) Clone ids and their corresponding colours (in hex format). Required columns are: clone_id: `character()` clone id. colour: `character()` the corresponding Hex colour for each clone id.
`mutations`	`data.frame` (Optional) Mutations occurring at each clone. Any additional field will be shown in the mutation table. Required columns are: chrom: `character()` chromosome number. coord: `numeric()` coordinate of mutation on chromosome. clone_id: `character()` clone id. sample_id: `character()` id for the tumour sample. VAF: `numeric()` ariant allele frequency of the mutation in the corresponding sample.
`sample_ids`	`vector` (Optional) Ids of the samples in the order your wish to display them (clockwise from positive x-axis).
`n_cells`	`numeric()` (Optional) The number of cells to plot (for voronoi tessellation).
`show_low_prev_gtypes`	`logical()` (Optional) Whether or not to show low-prevalence (< 0.01) clones in the view. Default is FALSE.
`phylogeny_title`	`character()` (Optional) Legend title for the phylogeny. Default is "Clonal Phylogeny".
`anatomy_title`	`character()` (Optional) Legend title for the anatomy. Default is "Anatomy".
`classification_title`	`character()` (Optional) Legend title for the phylogenetic classification. Default is "Phylogenetic Classification".
`show_warnings`	`logical()` (Optional) Whether or not to show any warnings. Default is TRUE.
`width`	`numeric()` (Optional) Width of the plot. Minimum width is 930.
`height`	`numeric()` (Optional) Height of the plot. Minimum height is 700.

Interactive components in the top toolbar:

Click the download buttons to download the current view as PNG or SVG.
Click the reset button to exit a clone or mutation selection.
Click the view switch button to switch between cellular

Interactive components in main view:

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

Interactive components in legend:

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.
Hover over legend tree branch to view tumour samples expressing all descendant clones.
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).
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:

Search for any chromosome, coordinate, gene, etc.
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.
Sort the table by a column (all columns sortable except the Clone column).

Note: Click on the reset button to exit a selection. Click the download buttons to download a PNG or SVG of the view.

library("mapscape")

# EXAMPLE 1 - Patient A21, Gundem et al., 2015

# clonal prevalences
clonal_prev <- read.csv(system.file("extdata", "A21_clonal_prev.csv", 
    package = "mapscape"))

# mutations
mutations <- read.csv(system.file("extdata", "A21_mutations.csv", 
    package = "mapscape"))

# locations of each tumour sample on user-provided image
sample_locations <- read.csv(system.file("extdata", 
    "A21_sample_locations.csv", package = "mapscape"))

# genotype tree edges
tree_edges <- read.csv(system.file("extdata", "A21_tree.csv", package 
    = "mapscape"))

# image reference
img_ref <- system.file("extdata", "A21_anatomical_image.png", package 
    = "mapscape")

# radial order of samples
sample_ids <- c("H","F","J","D","A","I","C","E","G")

# run mapscape
mapscape(clonal_prev = clonal_prev, tree_edges = tree_edges, 
    sample_locations = sample_locations, mutations = mutations, 
img_ref = img_ref, sample_ids = sample_ids)

# EXAMPLE 2 - Patient 1, McPherson and Roth et al., 2016

# clonal prevalences
clonal_prev <- read.csv(system.file("extdata", "px1_clonal_prev.csv", 
    package = "mapscape"))

# mutations
mutations <- read.csv(system.file("extdata", "px1_mutations.csv", 
    package = "mapscape"))

# locations of each tumour sample on user-provided image
sample_locations <- read.csv(system.file("extdata", 
    "px1_sample_locations.csv", package = "mapscape"))

# genotype tree edges
tree_edges <- read.csv(system.file("extdata", "px1_tree.csv", 
    package = "mapscape"))

# image reference
img_ref <- system.file("extdata", "px1_anatomical_image.png", 
    package = "mapscape")

# colours for each clone
clone_colours <- data.frame( 
    clone_id = c("A","B","C","D","E","F","G","H","I"), 
    colour = c("d0ced0", "2CD0AB", "7FE9D1", "FFD94B", "FD8EE5", 
    "F8766D", "4FD8FF", "B09AF5", "D4C7FC"))

# radial order of samples
sample_ids <- c("LFTB4", "LOvB2", "ApC1", "ROvA4", "ROv4", "ROv3", 
    "ROv2", "ROv1", "RFTA16", "Om1", "SBwl", "SBwlE4")

# run mapscape
mapscape(clonal_prev = clonal_prev, tree_edges = tree_edges, 
    sample_locations = sample_locations, mutations = mutations, 
    img_ref = img_ref, clone_colours = clone_colours, 
    sample_ids = sample_ids)

# EXAMPLE 3 - Patient 7, McPherson and Roth et al., 2016

# clonal prevalences
clonal_prev <- read.csv(system.file("extdata", "px7_clonal_prev.csv", 
    package = "mapscape"))

# mutations
mutations <- read.csv(system.file("extdata", "px7_mutations.csv", 
    package = "mapscape"))

# locations of each tumour sample on user-provided image
sample_locations <- read.csv(system.file("extdata", 
    "px7_sample_locations.csv", package = "mapscape"))

# genotype tree edges
tree_edges <- read.csv(system.file("extdata", "px7_tree.csv", 
    package = "mapscape"))

# image reference
img_ref <- system.file("extdata", "px7_anatomical_image.png", 
    package = "mapscape")

# colours for each clone
clone_colours <- data.frame(clone_id = c("A","B","C","D","E"), 
                            colour = c("d0ced0", "2CD0AB", "FFD94B", 
    "FD8EE5", "F8766D"))

# radial order of samples
sample_ids <- c("BwlA6", "RPvM", "RUtD1", "RUtD2", "RUtD3", "ROvC4", 
    "ROvC5", "ROvC6", "LOv1","LOvA10","LOvA4","BrnM", "BrnMA1")

# run mapscape
mapscape(clonal_prev = clonal_prev, tree_edges = tree_edges, 
    sample_locations = sample_locations, mutations = mutations, 
    img_ref = img_ref, clone_colours = clone_colours, sample_ids = sample_ids)