Skip to content

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


Notifications You must be signed in to change notification settings


Repository files navigation


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.


  • 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 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 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.


Set the following environment variables to customize MAGI.

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 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 URL for MAGI annotations server


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.


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.


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.