raphael-group/magi

A web application from the Raphael Lab for mutation annotation and genome interpretation.

MAGI

MAGI is a platform for interactive visualization and collaborative annotation of combinations of genetic aberrations. MAGI allows users to upload their own private datasets and view and annotate them in combination with public datasets.

This repository contains the source code for MAGI. MAGI is written in Node.js with a MongoDB database. MAGI uses D3, jQuery, and GD3 on the front-end. Below, we describe how to get a version of MAGI running on your personal machine.

Dependencies

• Node.js and NPM (included with Node.js).
• MongoDB. Make sure you can run mongod from your terminal. Some basic debugging tips are:
  1. Make sure that you make a directory to store the database. The default is /data/db, so you'll need to make that directory before running mongod.
  2. Make sure that the mongod, mongo, etc. are in your PATH.
• Python. Tested with version 2.7.x.
  • PyMongo to load data into MAGI.
  • Numpy, SciPy, and Scikit-Learn to compute the statistical association of mutations with different sample annotations/categories, or the (dis)similarity of different sample annotations/categories.

MAGI has been tested on both Linux and Mac systems using Chrome, Firefox, and Safari.

MAGI Annotations

Please follow the instructions on setting up MAGI annotations to include protein to include protein-protein interactions and mutation annotations in MAGI.

Setup

Setup consists of five basic steps:

1. Install Node, Python, and MongoDB (as described above).
2. Create an ENVIRONMENT file with your settings, with one export VARIABLE_NAME="..." per line. Make sure to load the environment variables into whatever shell you are running. We provide more information below.
3. Run (possibly a subset of the ) commands in setup.sh to install dependencies, download data, and initialize the database. We provide more information below.
4. Start the server with node server, which serves to http://localhost:8000 by default.

Environment

Set the following environment variables to customize MAGI.

General

Name	Default	Description
NODE_ENV	development	Environment: production for publicly available on the web, or development for local/testing.
PORT	8080	Port from which you are serving MAGI
SITE_URL	localhost	Domain name from which you are serving MAGI
MONGO_DB_NAME	magi	Name of database in MongoDB you want to use for MAGI

Third-party services

To use authentication with MAGI, you will need to obtain Google OAuth2 credentials and set the appropriate environment variables. Similarly, to use the MAGI feedback tool you will need to obtain a WebEngage ID.

Name	Default	Description
GOOGLE_CLIENT_ID	None	Google OAuth2 client ID
GOOGLE_CLIENT_SECRET	None	Google OAuth2 client secret
WEBENGAGE_ID	None	WebEngage ID for Javascript SDK integration

If you want to be a webmaster for your version of MAGI on Google and Bing, you will need MAGI to serve XML files. Google and Bing will provide the XML files and specific paths/names, which you can set with the following variables.

Name	Default	Description
GOOGLE_SEO_ROUTE	None	Local path to Google SEO XML file
GOOGLE_SEO_ROUTE_NAME	None	Name of Google XML file route
BING_SEO_ROUTE	None	Local path to Google SEO XML file

MAGI annotations

MAGI can retrieve protein-protein interactions and mutation annotations from a MAGI annotations Postgres database. To do so, set the following environment variables.

Name	Default	Description
POSTGRES_DJANGO_DBNAME	magipy	Name of Postgres database
POSTGRES_DJANGO_HOST	127.0.0.1	Name of Postgres host
POSTGRES_DJANGO_PORT	5432	Name of Postgres port
POSTGRES_DJANGO_USER	postgres	Name of Postgres user
POSTGRES_DJANGO_PASSWORD	None	Password for Postgres user
DJANGO_ANNOTATIONS_URL	http://annotations.cs.brown.edu	URL for MAGI annotations server

Data

We provide a tarball of data used in MAGI (currently ~100Mb) on the Raphael group website. This includes general datasets -- HG19 gene locations, cancer acronyms and descriptions, known gene sets from KEGG and PINdb -- and also mutation datasets.

Support

MAGI was created and is maintained by the Raphael research group in the Center for Computational Molecular Biology and the Department of Computer Science at Brown University. We offer support for MAGI on the MAGI Google Group, or please visit the group website to contact us.

Citation

If you use MAGI in your work please cite

M.D.M. Leiserson, C.C. Gramazio, J. Hu, H-T. Wu, D.H. Laidlaw, B.J. Raphael. MAGI: visualization and collaborative annotation of genomic aberrations. Nature Methods 12, 483-484 (2015). Publink.

magi's Issues

ambiguous votes on aberration reference annotations

On the main view page (in public MAGI) we can vote on a single reference within an annotation cell. However, that reference may support multiple protein sequence changes; there is currently no way to specify which change is referred. We might need to change how we design the interface for aberration annotation votes at this point to resolve it.

As an example: the tooltip, after voting:

The annotations table.

Refactor log authentication and consent process

Change the current post request used to authenticate whether logging is enabled and whether the user has given consent via on-load variables from Jade.

Save to PDF

Right now we can't save our views to PDF without opening a print dialogue. It would be great if we could do this without using print.

Download views broken

The functionality to download views as SVGs or PNGs is broken. Downloading the aberrations view actually returns the copy number view, and PNGs are blank.

Cannot get OAuth2 to work.

I get a 500 error in Node.js after setting up the OAuth2 environment variables, once I click "Log in" and then accept Google's verification warning.