Welcome to synergy-maps’s documentation!¶
Introduction¶
Synergy maps are a novel visualization technique for exploring pairwise combination datasets, developed in the Centre for Molecular Informatics of the Chemistry Department of the University of Cambridge. This is the documentation for an interactive implementation, written by Richard Lewis, whilst a PhD student under the supervision of Andreas Bender.
Software¶
Briefly, the data processing is done on the Python backend, and the visualization is produced by the JavaScript frontend:
There is a demo of the interactive frontend for some example datasets hosted on GitHub.
Paper¶
The accompanying paper has been preliminarily been accepted into the Journal of Chemininformatics as part of the Mixtures and Combination Modelling thematic issue.
Contents¶
Introduction¶
Synergy maps are a novel visualization technique for exploring pairwise combination datasets, developed in the Centre for Molecular Informatics of the Chemistry Department of the University of Cambridge. This is the documentation for an interactive implementation, written by Richard Lewis, whilst a PhD student under the supervision of Andreas Bender.
Software¶
Briefly, the data processing is done on the Python backend, and the visualization is produced by the JavaScript frontend:
There is a demo of the interactive frontend for some example datasets hosted on GitHub.
Paper¶
The accompanying paper has been preliminarily been accepted into the Journal of Chemininformatics as part of the Mixtures and Combination Modelling thematic issue.
Frontend¶
The frontend is written in JavaScript, and runs in modern (HTML5 enabled) web browsers. It is an angularjs app, and was scaffolded using yeoman, using the angular generator. The visualization uses the D3.js library to render the images.
Dependencies¶
The project requires the node runtime to build the app, Grunt to run tasks, and the package managers npm and bower to install development and production dependencies respectively.
Building¶
To build and serve the project (having installed node and npm), change into the frontend directory and run:
$ npm install -g grunt bower // install grunt and bower
$ npm install // install node modules
$ bower install // install bower modules
$ grunt serve // build and run the server
Your default browser should open by default to localhost:9000, where the app is being
served.
Backend¶
The backend is written in Python, and is where data is processed into the JSON representation. The API is detailed in synergy_maps package.
Installation¶
Change into the backend directory and run the setup.py script.
$ python setup.py install
Quickstart¶
A prebuilt script, synergy_map.py for analysing pairwise combination data
in a standard format is provided in the scripts folder. This provides
minimum functionality - the software is designed for extensibility,
so consider writing your own script such as those in the example datasets
inluded in backend/synergy_maps/examples/.
The script can be run using:
$ python synergy_map.py example_compounds.smiles example_combinations.csv > map.json
Data structure¶
Compounds¶
The example script takes compounds as a smiles file. The smiles should be provided as a first column, and the identifier as the second column. The individual activities are supplied as extra columns.
A sample of a (made up) compound dataset would be:
$ head example_compounds.smiles
SMILES name pIC50
CC ethane 1.2
CCC propane 2.1
CN methylamine 4.3
... ... ...
Showing 3 compounds, with pIC50 as activity.
Combinations¶
The example script takes combinations as a csv file. The combination identifier should be given as the first column, and the component compounds ids should be provided as the second and third column. The example combinations should provide their synergy metrics as extra columns.
$ head example_combinations.csv
id RowId ColId pGamma ExcessOverBliss
0 ethane propane 0.001 1.0
1 ethane methylamine 0.2 4.0
2 propane methylamine -0.1 1.2
... ... ... ...
Running the Script¶
The script will use the default representations (Structural and Targets) and reduction methods (TSNE, PCA and MDS) to generate the synergy map data, and print out the JSON to the console. This can be redirected to a file:
$ python synergy_map.py example_compounds.smiles example_combinations.csv > synergy_map.json
Viewing the Map¶
The generated map can then be viewed by putting the json file into the data directory of the Frontend and building the application.
$ mkdir $SYNERGY_BASE/frontend/app/data/new_dataset/
$ mv synergy_map.json > $SYNERGY_BASE/frontend/app/data/new_dataset/data.json
You will also need to add it to the metadata.json file:
$ less $SYNERGY_BASE/frontend/app/data/metadata.json
{"datasets": ["DREAM-Lymphoma", "NCATS-Malaria", "new_dataset"]}
This will now be selectable from the table.
Please consider looking at synergy_maps/examples where there are two example
scripts using the declarative API for generating the datasets.
Documentation¶
The documentation you are reading is included in the docs subdirectory of the project repository. It is build using sphinx and hosted using readthedocs.
Dependencies¶
To get it running locally, install sphinx and the readthedocs theme:
$ pip install sphinx readthedocs
Building¶
Documentation can then be built using the Makefile (or the make.bat for Windows):
$ make html
Live editing¶
For quick editing, we use sphinx-autodoc.
$ pip install sphinx-autodoc
$ make livehtml
Git Structure¶
All code in the project is in one repository. In order to use GitHub Pages,
git subtree was used to put the master frontend/dist directory as the
root of the gh-pages branch, as suggested in this post.
Thus in order to update the gh-pages example, one must perform this subtree merge each time, to get the current master.