Examples
Quick start guide

This example describes a typical pipeline consisting of data processing, generating ChemSpace.js input format and its integration into the web page.

ChemSpace.js does not perform the calculation of 2D coordinates (dimensionality reduction) by itself. It is a visualization library to which data must be supplied in the JSON compliant ChemSpace.js format. This format is readily produced by our Python script chemspace.py. However, the user can use an arbitrary software provided that a valid ChemSpace.js input file is generated.

Step 1 - Data preparation

Data for visualization are typically supplied to chemspace.py as a csv (comma separated values) file. The first row of a csv file can optionally contain header names (recommended). The first column of data file is always taken as an ID column. Below is given an example snippet of data file used in this example. The data file represent the D(2) dopamine receptor ligands (Source: Probes & Drugs portal) with their name, potency and the SMILES representation of their molecular structure.

Whole data file
ID,Name,Smiles,Potency PD008822,SPIPERONE,O=C(CCCN1CCC2(CC1)C(=O)NCN2c1ccccc1)c1ccc(F)cc1,10.02 PD009293,AMPHETAMINE,CC(N)Cc1ccccc1,None PD009418,SNAP-7941,COCC1=C(C(=O)OC)C(c2ccc(F)c(F)c2)N(C(=O)NCCCN2CCC(c3cccc(NC(C)=O)c3)CC2)C(=O)N1,5.55 PD009790,S-15535,c1ccc2c(c1)CC(N1CCN(c3cccc4c3OCCO4)CC1)C2,6.46 PD009836,(+)-butaclamol,CC(C)(C)C1(O)CCN2CC3c4ccccc4CCc4cccc(c43)C2C1,9.11
Step 2 - Data processing

Recommended way of data processing is the use of the chemspace.py script. This script can not only perform dimensionality reduction, but also returns the chemical space as an ChemSpace.js input file. Below given is the command-line for processing of example.csv file. Data file has column headers (-dh option), header name determines the Name (label) field (-lf option) and header Smiles determines the structure field (-csf option). Coordinates are calculated by the t-SNE algorithm applied on the distance matrix of compounds (based on ECFP4 compound fingerprint and Tanimoto distance). To extend compounds' attributes that can be used in the output chemical space, basic physico-chemical properties are calculated and added (-pcp option). The output file example.json contains the chemical space in the ChemSpace.js input format. To decrease the size of the output data (JSON object), the minification of the JSON format is performed (-min option).

Command-line
python chemspace.py ../data/example.csv -drm tsne -dh -lf Name -csf Smiles -arr dm -min -pcp -o ../static/data/example.json
Step 3 - ChemSpace.js deployment

The file example.json describes coordinate system of compounds and it contains all data necessary for chemical space visualization. No other file is needed to render the chemical space. An example below demonstrates how easy it is to integrate ChemSpace.js visualization into your web page.

ChemSpace.js (and its dependencies jquery-3.3.1.min.js and konva-1.7.6.min.js) must be first imported in the <script> tag. ChemSpace.js is initialized immediately when the whole page is loaded (detected by the $(document).ready event), and it contains several attributes defining the appearance of the visualization (all attributes are documented here). Finally, example.json is loaded, and the chemical space is displayed.

Below is an example of a simple HTML web page with ChemSpace.js integration:

<html> <head> <script src="path/to/jquery-3.3.1.min.js"></script> <script src="path/to/konva-1.7.6.min.js"></script> <script src="path/to/chemspace-0.2.0.min.js"></script> <script> $(document).ready(function() { //run when the whole page is loaded window.chemspace = new ChemSpace({ //instantiate ChemSpace target: "chemspace", // the ID of target HTML element }); chemspace.read_data_from_file("path/to/example.json"); //read input json file chemspace.draw(); //draw chemical space }); </script> </head> <body> <div id="chemspace"></div> </body> </html>

You can see the resulted web page here >>