Package: exmol
Explaining why that moleculeExplaining why that moleculeInstallQuickstartCounterfactual GenerationDescriptor AttributionUsageFurther ExamplesChemical SpaceSVGDisable Progress BarsAPI and DocsDevelopingCitationexmolis a package to explain black-box predictions of molecules. The package uses model agnostic explanations to help users understand why a molecule is predicted to have a property.InstallpipinstallexmolQuickstartSeethe tutorialto give an overview of the basic usage of exmol.Counterfactual GenerationOur package implements the Model Agnostic Counterfactual Compounds with STONED to generate counterfactuals.
A counterfactual can explain a prediction by showing what would have to change in the molecule to change its predicted class. Here is an example of a counterfactual:This package is not popular. If the package had a logo, it would be popular.In addition to having a changed prediction, a molecular counterfactual must be similar to its base molecule as much as possible. Here is an example of a molecular counterfactual:The counterfactual shows that if the carboxylic acid were an ester, the molecule would be active. It is up to the user to translate this set of structures into a meaningful sentence.Descriptor AttributionThis package also implements Model Agnostic Descriptor Attribution for molecules using LIME.
Descriptor attributions can explain a prediction by computing QSARs for molecular structure properties independent of features used for model predictions. Here is an example of descriptor attribution:The descriptor t-statistics show which chemical properties or substructures influence properety prediction for the pictured molecule. LIME is a perturbation based method and the descriptor attributions depend on the perturbed chemical space created around the molecule of interest.UsageLet's assume you have a deep learning modelmy_model(s)that takes in one SMILES string and outputs a predicted binary class. We first expand chemical space around the prediction of interestimportexmol# mol of interestbase='Cc1onc(-c2ccccc2Cl)c1C(=O)NC1C(=O)N2C1SC(C)(C)C2C(=O)O'samples=exmol.sample_space(base,my_model,batched=False)We usesbatched=Falseto indicatemy_modelcannot handle a batch of SMILES, just one at a time.  If your model takes SELFIES, just passuse_selfies=Truetosample_space. Now we select counterfactuals from that space and plot them.cfs=exmol.cf_explain(samples)exmol.plot_cf(cfs)We can also plot the space around the counterfactual. This is computed via PCA of the affinity matrix -- the similarity (Tanimoto of ECFP4) with the base molecule.
Due to how similarity is calculated, the base is going to be the farthest from all other molecules. Thus your base should fall on the left (or right) extreme of your plot.cfs=exmol.cf_explain(samples)exmol.plot_space(samples,cfs)Each counterfactual is a Pythondataclasswith information allowing it to be used in your own analysis:print(cfs[1]){
'smiles': 'Cc1onc(-c2ccccc2Cl)c1C(=O)NC1C(=O)N2C1SC(C)(C)C2C',
'selfies': '[C][C][O][N][=C][Branch1_1][Branch2_3][C][=C][C][=C][C][=C][Ring1][Branch1_2][Cl][C]
            [Expl=Ring1][N][C][Branch1_2][C][=O][N][C][C][Branch1_2][C][=O][N][C][Ring1][Branch1_1][S][C]
            [Branch1_1][C][C][Branch1_1][C][C][C][Ring1][Branch1_3][C]',
'similarity': 0.8,
'yhat': 1,
'index': 1813,
'position': array([-7.8032394 ,  0.51781263]),
'is_origin': False,
'cluster': -1,
'label': 'Counterfactual 1'
}We can use the same chemical space to get descriptor attributions for the molecule. Along withsamples, we also need to specify thedescriptor_typeto get attributions. You can select fromClassicRdkit descriptors,MACCSfingerprint descriptors,ECFPsubstructure descriptors. The defaultdescriptor_typeisMACCS. If you'd like to use regression coefficients for analysis, specifyreturn_beta=True. The descriptor t-statistics are stored indescriptors.tstatsattribute for the base molecule and can be accessed usingspace_tstats = space[0].descriptors.tstats.plot_descriptorssaves a plot as shown below in theoutput_file.beta=exmol.lime_explain(samples,descriptor_type='ECFP',return_beta=True)exmol.plot_descriptors(samples,output_file='ecfp.svg')You can use a more typical atom attribution plot as well, although note that some information is lost in this representation.exmol.plot_utils.similarity_map_using_tstats(samples[0])You can also plot the chemical space colored by fit to see how well the regression fits the original model. To plot by fit, regression coefficientsbetaneed to be passed in as an argument.exmol.plot_utils.plot_space_by_fit(samples,[samples[0]],beta=beta,mol_size=(300,250),figure_kwargs={'figsize':(7,5)},)It is also possible to get global attributions for multiple base molecules. For this, the user should create a space around each instance of interest and concatenate these spaces. Then use this joint space to do lime explanations:beta=exmol.lime_explain(joint_space,descriptor_type='ECFP',return_beta=True,multiple_bases=True)lime_explain()uses a linear surrogate model for descriptor explanations. You can also use a custom surrogate model instead of a linear model. To do so, just add desired descriptors to the chemical space using theadd_descriptors()function and then use a custom model on samples to get explanations. For example, add ECFP descriptors usingexmol.add_descriptors(samples, descriptor_type='ECFP').Further ExamplesYou can find more examples by looking at the exact code used to generate all figures from our paperin the docs webpage.Chemical SpaceWhen callingexmol.sample_spaceyou can passpreset=<preset>, which can be
one of the following:'narrow': Only one change to molecular structure, reduced set of possible bonds/elements'medium': Default. One or two changes to molecular structure, reduced set of possible bonds/elements'wide': One through five changes to molecular structure, large set of possible bonds/elements'chemed': A restricted set where only pubchem molecules are considered.'custom': A restricted set where only molecules provided by the "data" key are considered.'synspace': Chemical space is generated by running retro and forward synthesis reactions, so all generaterd molecules are synthetically feasible. Usessynspacepackage.You can also passnum_samplesas a "request" for number of samples. You will typically end up with less due to
degenerate molecules. See API for complete description.SVGMolecules are by default drawn as PNGs. If you would like to have them drawn as SVGs, callinsert_svgafter callingplot_spaceorplot_cfimportskunkexmol.plot_cf(exps)svg=exmol.insert_svg(exps,mol_fontsize=16)# for Jupyter Notebookskunk.display(svg)# To save to filewithopen('myplot.svg','w')asf:f.write(svg)This is done with theskunk🦨 library.Disable Progress BarsIfexmolis being too loud, addquiet = Truetosample_spacearguments.API and DocsRead API here. You should also read the paper (see below) for a more exact
description of the methods and implementation.DevelopingThis repo uses pre-commit, so after cloning runpip install -r requirements.txtandpre-commit installprior to committing.CitationFor the counterfactual work, please citeWellawatte et al.@Article{wellawatte_seshadri_white_2021,author="Wellawatte, Geemi P. and Seshadri, Aditi and White, Andrew D.",title="Model agnostic generation of counterfactual explanations for molecules",journal="Chem. Sci.",year="2022",pages="-",publisher="The Royal Society of Chemistry",doi="10.1039/D1SC05259D",url="http://dx.doi.org/10.1039/D1SC05259D",}For the descriptor explanations, please citeGandhi et. al.@Article{gandhi_white_2022,place="Cambridge",title="Explaining structure-activity relationships using locally faithful surrogate models",DOI="10.26434/chemrxiv-2022-v5p6m",url="https://doi.org/10.26434/chemrxiv-2022-v5p6m"journal="ChemRxiv",publisher="CambridgeOpenEngage",author="Gandhi,HetaA.andWhite,AndrewD.",year="2022"}