parkerici/panorama

R package for interactive visualization and analysis of single-cell data

Installation

1. Install the devtools package if you have not already

install.packages("devtools")

2. install panorama with the following command

devtools::install_github("ParkerICI/panorama")

This will install the panorama R package together with all the required dependencies. If evertyhing was successful you should be able to start the GUI with the following commands

library(panorama)
panorama()

to stop the GUI simply hit the ESC key in your R session.

Usage

When you launch the GUI you will be prompted to select a file. You can select any file in what you want to be your working directory and this will set the working directory for the remainder of the session.

The working directory must contain all the graphml files you want to visualize, plus a sub-folder named clusters_data containing the single-cell data for each cluster. If the graphml files represent Scaffold maps, a sub-folder called landmarks_data must also be present.

If the graphml files were generated using the scgraphs package these directories were generated for you as long as the process.clusters.data option was set to TRUE in scgraphs::run_scaffold_analysis or scgraphs::get_unsupervised_graph_from_files (please refer to the documentation of the scgraphs packages for details)

Once the working directory has been selected two browser windows will be opened: a main window containing the graph visualization, and a separate plotting window. Please note the following, depending on your browser settings:

• If your browser is configured to block pop-ups you need to allow pop-ups coming from the address 127.0.0.1:8072 (8072 is the default panorama port, you will have to enable pop-ups coming from a different port if you change this default)
• If your browser is configured to open new windows in a new tab, the last tab shown in the browser will be the plotting window, which is initially empty. The main panorama interface will be in a different tab

Description of the GUI functionality

• Choose a graph: select the graphml file you want to visualize from a list of files contained in your working directory

You can interact with the graph using the mouse as follows:

• Scrolling: zoom in/out.
• Left click + drag: panning
• Click on a node + Shift key: add the node to the current selection, or create a new selection if none existed (selected nodes are displayed in red)
• Left click + drag + Alt key: select all nodes inside a rectangle. To clear the current selection use this key combination to create a selection on an empty area of the graph

The appearence of the graph can be modified with the following controls:

• Active sample: whether to display data for All the samples (i.e. the pooled data) or a specific sample (this control is only available if the graph represents multiple samples, i.e. it was generated from pooled clustering). Selecting a different sample changes the size and color of the nodes, to reflect statistics calculated using only data from the current active sample.
• Display edges: select which edges to display:
  • All: displays all the edges
  • Highest scoring: for each node, display the highest scoring connection to a landmark (i.e. this is the most similar landmark)
  • Inter cluster: only display edges between clusters
  • To landmark: only display edges between clusters and landmarks
• Nodes color: use this dropdown to color the nodes according to the expression of a specific marker, or with "Default" colors (clusters in Blue, landmarks in red)
• Stats type: only available if the graph represents mulitple samples:
  • Absolute: the node colors represent the absolute value of the selected marker in the active sample
  • Ratio: the node colors represent the ratio between the value of the selected marker in the active sample and the value of the selected marker in the sample selected from the Stats relative to dropdown. The ratio is calculated on the asinh transformed values
  • Difference: the node colors represent the difference between the value of the selected marker in the active sample and the value of the selected marker in the sample selected from the Stats relative to dropdown. The difference is calculated on the asinh transformed values
• Stats relative to: only available if the graph represents multiple samples and Stats type is different from Absolute. The sample with respect to which stats are calculated (see Stats type)
• Number of colors: number of colors to use in the color scale
• Under: the color to use for values that are below the minimum of the scale
• Over: the color to use for value that are above the maximum of the scale
• Min: the color corresponding to the minimum of the scale
• Mid: the color corresponding to the midpoint of the scale (only available if the number of colors is 3)
• Max: the color corresponding to the maximum of the scale
• Color scale midpoint: the value corresponding to the midpoint of the color scale (only available if the number of colors is 3)
• Color scale limits: the numerical values that correspond to the domain of the color scale
• Color scale min: the minimum value available in the Color scale limits slider
• Color scale max: the maximum value available in the Color scale limits slider
• Nodes size: select whether you want the size of the nodes to be constant (Default) or Proportional to the number of cells in each cluster.
• Minimum / Maximum / Landmark node size: the minimum and maximum size for the cluster and the size of the landmark (red) nodes
• Reset graph position: this button will reset the graph to its initial position, which is intended to display most of the nodes in a single image
• Toggle landmark labels: toggle the display of the landmark labels on/off
• Toggle cluster labels: toggle the display of the cluster labels on/off. If any nodes are selected, this only applies to the selected nodes
• Export selected clusters: click this button to export the events in the selected clusters in a separate FCS file. For this to work, the original RData files corresponding to the clustered files in use must be located in the working directory. A new FCS file will be created in the working directory, with a name starting with scaffold_export, and ending with a random string of alpha-numeric characters, to prevent naming conflicts.

One of the most useful ways to inspect a cluster is to plot the expression values for the cells that comprise the cluster. The controls below allow you to control the appeareance of the plot. Only data for the clusters that have been selected will be plotted. If the graph represents a Scaffold map, the plot will also include the data for the landmarks that are connected to the selected clusters

• Plot type: the type of plot to display. Either Boxplot, Density plot, Scatteplot (biaxial), or Communities (the latter is only available if the graph contains a vertex property called community_id). The Communities plot displays a heatmap representing the median marker expression in each community of node (i.e. groups of similar nodes, as calculated by a community detection algorithm, see the documentation for vite::get_unsupervised_graph)
• Facet by: only availabe if the graph represents data from multiple samples. Whether the plot should be faceted by Sample, Variable or Cluster, i.e. wether each Sample, Variable or Cluster should be its separate plot in the panel. If the plot type is Scatterplot only the Sample and Variable options will be available, otherwise only Sample and Cluster. Please note that, if the graph was derived from multiple independent clustering runs, the name of the clusters will not match across sample (e.g. cluster X in sample A, will not have anything in common with cluster X in sample B). Keep this in mind when interpreting certain combination of plots (e.g. boxplots of multiple clusters, faceted by sample). panorama will not allow plots that would require pooling data across multiple samples, in cases where such pooling does not make sense
• Pool clusters data: whether to pool all the data from the selected clusters for plotting. If the option is not selected, each cluster will be plotted individually as a separate boxplot, or density plot. Selecting this option will pool all the clusters data together for plotting.
• Pool samples data: only available if the graph represents data from multiple samples and Pool clusters data is not selected. Whether to pool the data from multiple samples for plotting.
• Markers to plot: Select which markers you want to display in the plot.
• Samples to plot: only available if the graph represents data from multiple samples. If this is left empty, the pooled data is plotted, otherwise only the data from the specified samples
• Plot clusters: plot the selected clusters. A spinner animation will appear in this button while the plot is loading. The plots appear in the separate plotting window

panorama's Issues

panorama. subscript out of bounds

Hi

I can't find where my mistake is. I have repeated every step of the flow-analysis-tutorial with no problem until I try to run panorama::panorama() on either my ubuntu terminal or RStudio.

In RStudio I get this message:

Warning: Error in [[: subscript out of bounds
48: getSliderType
47: updateSliderInput
46: [/home/juan/R/x86_64-pc-linux-gnu-library/3.4/panorama/shinyGUI/server/tab_graph.R#315]
3:
1: panorama::panorama

Any clue is much appreciate.

Cheers
Juan

Question about application

Hi, I'm new to this package, and got it from one paper about brain cancer, using this package to visualize cytometry data. It's powerful and very useful for flow data analysis.

And my question is is it possible to analyze single cell RNA-seq data by this package?

Since data format, preprocessing pipeline could be some different between flow data and scRNAseq data, I wonder the accessibility to use it in scRNA-seq analysis.

Cant make scatter/boxplots

Hi,

I have been trying to make scatter/boxplots in panorama, and i cant make it work. I feel i have tried any conceivable combination of things ticked or markers chosen. I want to look at a functional marker p38 in my three groups: baseline/4h/24h. i have these three samples from 6 patients, a total of 18 files. What am i doing wrong? And how do i get the heatmap?

Cannot visualize in Scaffold Analysis on Panorama

Hello,

I have samples from four organs (bone marrow, spleen, blood, and liver) and would like to generate Scaffold maps of the 4 organs on one reference map. I pooled and clustered the data using the cluster_fcs_files_groups. I then used Vite to load landmarks and generated a Scaffold Result folder of .graphml files. I open the Panorama GUI and set the folder to where the .graphml files are located. When I try to choose one of the .graphml files, I encounter the following error. I appreciate any insights on how to troubleshoot this.

R version 4.1.1

Warning: non-unique value when setting 'row.names': ‘0’
No traceback available
Warning: Error in .rowNamesDF<-: duplicate 'row.names' are not allowed
53: stop
52: .rowNamesDF<-
51: row.names<-.data.frame
49: rownames<-
48: igraph::get.data.frame
47: panorama:::get_vertex_attributes
46: [C:/Users/liusuy/Dropbox/My PC (PATH-577183-DT)/Documents/R/win-library/4.1/panorama/shinyGUI/server/tab_graph.R#191]
3:
1: panorama::panorama
Warning: non-unique value when setting 'row.names': ‘0’
No traceback available
Warning: Error in .rowNamesDF<-: duplicate 'row.names' are not allowed
105: stop
104: .rowNamesDF<-
103: row.names<-.data.frame
101: rownames<-
100: igraph::get.data.frame
99: panorama:::graph_to_json
98: reactive:output$graphui_mainnet [C:/Users/liusuy/Dropbox/My PC (PATH-577183-DT)/Documents/R/win-library/4.1/panorama/shinyGUI/server/tab_graph.R#218]
82: output$graphui_mainnet
3:
1: panorama::panoram

panorama: save plots

Dear Pier,
I started to use Scaffold not long time ago. I have an issue to save/export created plot in package panorama(). Is it any smart way to do when I run analysis using GUI version? Or shall I run the script from R environment?
Thank you in advance for your reply!

difficulty de-selecting nodes in panorama

last one, i promise...
when using Shift+click or Alt+click to select or deselect nodes in panorama, I have noticed that sometimes the node will refuse to be de-selected, and other times the program has developed a "memory", and will ignore my de-selection command when making heat maps or box plots. any ideas on how to fix? This is in a MacOS environment, High Sierra 10.13. I can post more details if necessary.

error in panorama - cannot create clusters_data directory

HI Federico, I was using panorama and got this error.

Warning: Error in panorama:::plot_clusters: clusters_data directory is missing, data cannot be plotted

Where precisely does the clusters_data directory belong? in parallel with the clustered directory, or within it? Or somewhere else?
I was using the GUI for grappolo, vite, and panorama, in MacOS.

"Error: Arguments imply differing number of rows: 0, 2"

I'm unable to load the .graphml file output from Vite in Panorama. I get the above error (details below), and I have tinkered with my inputs in Premessa and Grappolo in a number of ways. I have also tried with and without metadata, as well as another set of FCS files to determine if a file is corrupt (neither seem to resolve the issue).

I've noticed that while Grappolo allows me to select parameters I want used to cluster, Vite does not allow me to select parameters for the analysis and runs only when no markers are selected.

Could this be a problem with the Vite package? I have existing .graphml files that can be visualized using Panorama so perhaps this is an issue with the Vite package.

Listening on http://127.0.0.1:8072
12: execCallbacks(timeoutSecs, all)
11: run_now(timeoutMs/1000, all = FALSE)
10: service(timeout)
9: serviceApp()
8: ..stacktracefloor..(serviceApp())
7: withCallingHandlers(expr, error = doCaptureStack)
6: globals$domain$wrapSync(expr)
5: promises::with_promise_domain(createStackTracePromiseDomain(),
expr)
4: captureStackTraces({
while (!.globals$stopped) {
..stacktracefloor..(serviceApp())
Sys.sleep(0.001)
}
})
3: ..stacktraceoff..(captureStackTraces({
while (!.globals$stopped) {
..stacktracefloor..(serviceApp())
Sys.sleep(0.001)
}
}))
2: shiny::runApp(appDir = file.path(system.file(package = "vite"),
"shinyGUI"), ...)
1: vite::vite_GUI()
Warning: Error in data.frame: arguments imply differing number of rows: 0, 2
103: stop
102: data.frame
101: cbind
100: cbind
99: panorama:::graph_to_json
98: reactive:output$graphui_mainnet [/Library/Frameworks/R.framework/Versions/3.5/Resources/library/panorama/shinyGUI/server/tab_graph.R#218]
82: output$graphui_mainnet
3:
1: panorama

graphics adjustments in heatmaps

Hi,
when generating the heatmap of communities in the second window, in panorama, I noticed that the lower edge (where the marker names are written) gets cut off and one cannot scroll down any farther to see them. Is there a way to adjust this in the code? This might be another PC-> Mac complication.
Thanks!
Will post a photo of bug shortly...