search

iVis-at-Bilkent / pathway-mapper

PathwayMapper: An interactive and collaborative graphical curation tool for cancer pathways
https://www.pathwaymapper.org/
GNU Affero General Public License v3.0
55 stars 27 forks source link
bioinformatics cancer-genomics cancer-pathways graphviz network-visualization pathway-analysis pathways systems-biology tcga

readme

PathwayMapper

PathwayMapper is a web based pathway curation tool for interactive creation, editing, and sharing of cancer pathways. The tool supports remote users to collaborate and concurrently modify pathways using ShareDB with built-in conflict resolution implemented as a ReactJS component.

How to Cite Usage

Bahceci et al. (2017) "PathwayMapper: a collaborative visual web editor for cancer pathways and genomic data", Bioinformatics.

Here is a screenshot from the PathwayMapper editor:

Click on the video tutorial below to see the basics of the PathwayMapper editor:

A special, viewer edition of PathwayMapper was built for use in cBioPortal (tutorial). PathwayMapper is used in Results view (example):

as well as in Patient view (example):

Feedback

Send any feedback and error reports to at pathwaymapper@gmail.com.

Software

PathwayMapper is distributed under GNU Affero General Public License.

A sample deployment can be found here.

Running a Local Instance

In order to deploy and run a local instance of the tool, please follow the steps below:

Firstly, clone PathwayMapper to your local machine, and navigate to the local repository:

Please note that the app runs on port 3000 by default. To change the port, set the port environment variable before running npm start:

export PORT=3000
yarn start

Windows users need to change the associated variable in server.js file:

const DEFAULT_PORT = 3000;

Running an instance on Heroku (free)

Deploy

Running Tool in Development Mode

Running the tool in development mode does not require any changes.

Just make sure that after you made your changes, execute the below command to start build process:

yarn build

Then, it can be run using yarn start.

Please note that the app runs on the port 3000 by default. To change the port follow the same steps in previous section.

Sample TCGA Pathways

A number of pathways from the manuscripts of The Cancer Genome Atlas (TCGA) studies and those resulting from TCGA PanCanAtlas Project are available under Network > TCGA menu items sorted alphabetically by cancer type or pathway name. For instance, following is the PI3K pathway in Glioblastoma:

The same pathway can be opened up in PathwayMapper with URL http://pathwaymapper.org/?pathwayName=GBM-2013-RTK-RAS-PI(3)K-pathway, where pathwayName is the title of the sample pathway in PathwayMapper.

Adding Genes and Interactions

PathwayMapper allows creation of following node types:

and following interaction types:

To create a node, drag and drop it from the Node Palette. Similarly, to create an interaction, first select an interaction type from the Interaction Palette. Then, click on the green circle on top of the source node and drag it to the target node.

To add a node inside a compound node, you may directly drag it from the palette onto the parent compound node. Alternatively, you may select the node(s) and then right click on the compound to which you'd like to add the node and choose Add Selected Into This.

Below is a screenshot showing a sample pathway constructed with PathwayMapper:

Validating Gene Symbols

Gene symbols may be checked for validity using cBioPortal's web service. Below is a screenshot showing genes with invalid labels in red borders:

Inspecting Gene Properties

Assuming a gene symbol is valid, you may inspect its properties from MyCancerGenome by simply double-clicking on that gene and pressing the button "MyCancerGenome". This will display the associated gene page in a new browser tab:

Associating PubMed IDs with Interactions

One can associate any number of PubMed IDs with an interaction by simply double-clicking on that interaction and entering the PubMed IDs. These IDs have hyperlinks to the associated PubMed web page:

Editing Pathways

Editing and Aligning Nodes

Node locations may be adjusted manually by clicking on / selecting and dragging them. Multiple nodes may be selected by either using Shift + click or by Shift and box selection.

Nodes may be resized manually using the resize handles that appear on the edge of the node borders upon selection. Alternatively, the visual cue that appear toward the lower right corner of a node may be clicked to resize it to content (label and experiment data). All nodes may be simulatenously resized to their content via Edit > Resize Nodes to Content.

Alignment guidelines help us align nodes manually in a vertical or horizontal manner. Alternatively, one may select two or more nodes and align using View > Align Selected menu item. Alignment is performed with respect to the firstly selected node.

Before vertical center alignment of four nodes with respect to the firstly selected gene KRAS (left) and after alignment (right):

      

Editing and Reconnecting Interactions

Interactions may be routed through additional anchor (bend or control) points. To introduce a new anchor point, first select the interaction by clicking on it, and then right click and select Add Bend Point or Add Control Point. After the anchor point is created, drag it around to bend the edge. If an edge already has one type of anchor point (bend or control) additional anchor points of the same type can be created by dragging on the edge when it is selected, without needing to right click and add. In order to remove an anchor point, either move it to a location where it becomes almost unnecessary (it falls onto a straight line) or right click on the anchor point and select the Remove Bend/Control Point option. Given that there are multiple anchor points on an edge, all anchor points can be removed at once by right clicking on the edge or one of the anchors and selecting Remove All Bend/Control Points.

Below is an example map where edges used such anchor points:

One may also reconnect an interaction through its reconnection handles that appear when the edge is selected. Simply click on the reconnection handle close to the source / target that you'd like to change and drag it onto the new source / target.

Performing Automatic Layout

At any point, the user may want to rearrange the layout of the pathway. By default, automatic layout is performed incrementally, starting with the current positions of nodes. If you'd rather perform a static layout from scratch, you may uncheck the Incremental option under Layout > Layout Properties.

A pathway randomly laid out and the same pathway after automatic layout:

    

Hide and Show

Certain parts of a pathway may be temporarily removed by selecting and choosing View > Hide Selected Nodes. Nodes hidden in this way may be collectively brought back into the view using View > Show All Nodes.

Highlight

Nodes and interactions may be highlighted to draw attention to certain paths or sub-pathways by simply selecting them and applying Highlight > Highlight Selected.

One may use Highlight > Identify Invalid Genes to highlight all genes with symbols that are not valid.

All such highlights can be removed at once by issuing Highlight > Remove All Highlights.

Undo / Redo

All editing operations explained earlier may be undone and redone if needed using Edit > Undo or Redo. Undo, however, is not available in Collaborative mode (see below).

Export and Import

Exporting To / Importing From A Text File

The user may persist the current pathway onto the disk and import it back later on. Pathway content is organized as follows in a tab-delimited text file:

PTEN and the PI3-Kinase Pathway

This pathway ...

--NODE_NAME NODE_ID NODE_TYPE   PARENT_ID   POSX    POSY--
PTEN    PTEN    GENE    -1  444 46  
PIK3CA  PIK3CA  GENE    -1  360 139 
...

--EDGE_ID   SOURCE  TARGET  EDGE_TYPE
PTEN-PIK3CA PTEN    PIK3CA  INHIBITS
...

Here the first line contains the pathway title followed by a single empty line. Then comes a description of the pathway, again followed by a single empty line. After that comes nodes with properties name, ID, type, parent ID, x, and y positions, where parent ID and location information are optional. This is succeeded with a single empty line, followed by edges with properties ID, source ID, target ID, and type.

Exporting As Image

The user may export the current pathway as a static image (JPG and PNG) or in scalable vector graphics (SVG).

Viewing Experiment Data

At any point during pathway editing, the user may upload and overlay an associated experimental data set from a text file.

The tab-delimited experiment data files are organized as follows, where after the gene name one or more data sets follow:

gene    lung    ovarian breast
PTEN    -7  -20 10
PIK3CA  18  40  -50
...

Here, by default, a positive value signifies an activation percentage and is shown with a white-red color scale, whereas negative values signify inactivation shown with a white-blue color scale. The experiment file may contain an arbitrary number of data sets, and its view can be customized through Alteration % > Data Sets dialog.

Below is a screenshot showing sample experiment data overlaid on our sample data (left), the same map after the user unchecks the experiment data for "lung" through Alteration % > Data Sets (right):

    

Due to the limited space within a node's graphical representation, up to six data sets can be shown simultaneously. The user may also fetch alteration frequencies available on cBioPortal database through Alteration % > Load From cBioPortal... dialog. The dialog will let the user select a cancer study followed by data type(s) available for that studey in the database, and overlay the related data set(s) on the pathway in addition to any currently available data set.

The default color scheme may be changed and particular value ranges could be mapped to specified colors through the Alteration % > Color Scheme dialog. Value-color mapping is performed using a log-scale (i.e. if 40 is mapped to yellow and 80 is mapped to red, 60 will be a lot closer to red than yellow).

Collaborative Editing

Should you choose "Collaborative" on the welcome page, your editing session will be given a unique ID and you will have the option of sharing the URL containing this ID with desired person(s) and construct / edit a pathways in real time with support for concurrent modifications and built-in conflict resolution.

Any changes made by any person working on the pathway with the same URL will be shared / reflected to other people currently viweing / editing the same pathway. Below is a short video illustrating collaborative usage:

Credits

PathwayMapper uses many third party libraries mainly including Cytoscape.js and many of its extensions, React, Node.js, and cBioPortal API licensed under BSD-2-Clause, BSD-3-Clause, ISC, Apache-2.0 or MIT. For a complete list, please refer to this file.

Icons made by Freepik, Daniel Bruce, TutsPlus, Robin Kylander, Catalin Fertu, Yannick, Icon Works, Flaticon and licensed with Creative Commons BY 3.0

Team

Alumni