datavisyn / xsmiles

Visualize atom and non-atom attributions and SMILES strings

Molecular structures and SMILES visualization

XSMILES is a JavaScript tool to visualize atom and non-atom attributions and SMILES strings through interactive coordinated visualizations.

It is also distributed as a plugin to be used within Jupyter Lab notebooks, as a website where users can input molecules using a JSON format, and as a KNIME plugin.

XSMILES uses the RDKit MinimalLib to draw the molecule structures.

To create the JSON file that can be used with the demonstration website, please check the "Jupyter Lab" and "Use Cases" related notebooks cited in section Availability and examples of this repository.

XSMILES was tested with RDKit Canonical SMILES.

Please Cite

If you use XSMILES, the use cases, its code, or the generated explanations, please cite our article:

Preprint here: https://www.researchsquare.com/article/rs-2121152/v1

Heberle, H., Zhao, L., Schmidt, S., Wolf, T., & Heinrich, J. (2022). XSMILES: interactive visualization for molecules, SMILES and XAI scores. Research Square preprint. https://doi.org/10.21203/rs.3.rs-2121152/v1

@article{Heberle2022XSMILES,
author = {Heberle, Henry and Zhao, Linlin and Schmidt, Sebastian and Wolf, Thomas and Heinrich, Julian},
doi = {https://doi.org/10.21203/rs.3.rs-2121152/v1},
journal = {Research Square preprint},
month = {},
number = {},
pages = {},
title = {{XSMILES: interactive visualization for molecules, SMILES and XAI scores}},
volume = {},
year = {2022}
}

Availability and examples

• Demonstration website

• How to use XSMILES (JupyterLab notebook)

• Use cases: from model training to explanations (JupyterLab notebook)

• JupyterLab plugin

• TBD: KNIME pipeline example

Distributions formats

XSMILES (Javascript) is distributed in 3 main formats and they are available in the dist folder. Please go to the Readme from that folder for Details.

Simplest usage of XSMILES

If you just want to use XSMILES, for example, as a Machine Learning expert, you may be interested in the JupyterLab plugin or Demo website.

Using XSMILES as npm package

If you are a web-developer, the npm package may be your option.

Requirement: RDKit MinimalLib needs to be loaded as in window.RDKit = RDKit; before any XSMILES functionality is used. For the Demo Website of this project, you can see how we loaded it on files src/index.tsx and public/index.html. Depending on the project, you may need to load it in different ways. Another example is shown in dist/knime/GenericJavascriptView.js, where we load RDKit directly from an URL. Please refer to https://github.com/rdkit/rdkit-js to learn how to load RDKit. In future versions we want to include the dependency in the npm package, so you won't need to worry about it.

Run npm install xsmiles (unofficial) to install the module package and use XSMILES in another web-based system.

If xsmiles is not in the npm repository, please download the one of the released versions from this repository and run the code below, changing the version accordingly:

npm install xsmiles-0.5.7.tgz

Using XSMILES as Plain javascript

Required: RDKit MinimalLib, as explained in the section above.

You can use XSMILES from our index.js available at dist/plain.

Once your webpage loads it, it will be available through the window global variable:

window.xsmiles.appendSingleView(div, setup);

Please check dist/knime for an example of how it can be used within a Javascript code. In that example, we have XSMILES working in a KNIME's Javascript View. The xsmiles.js is injected in the View through a "table" that is converted to a "variable". For more details, please refer to the KNIME example referred at the top of this page.

Running the Demonstration website locally

npm install
npm start

Development

It builds a module that export functions (defined in src/modules) and a web-system (defined in src/webpage) that provides a GUI to input a .json file and display smiles strings - their XAI scores in the form of coordinated bar charts and molecular structure.

The module functions are exported into dist/modules and the website to be served is exported into dist/web.

Components were created to be exported and used in the xsmiles-jupyterlab project, so that it can be used in Jupyter Lab notebooks.

Run npm install to install all dependencies.

Starting the website in development mode

npm start

Building modules (npm, plain javascript) and website

npm run build

Packing the XSMILES to use with npm install

npm run build

npm pack