{"id":22668175,"url":"https://github.com/lanl/minervachem","last_synced_at":"2025-04-12T11:03:47.572Z","repository":{"id":221060376,"uuid":"753324640","full_name":"lanl/minervachem","owner":"lanl","description":"a python library for cheminformatics and machine learning","archived":false,"fork":false,"pushed_at":"2024-12-06T22:20:48.000Z","size":1548,"stargazers_count":11,"open_issues_count":1,"forks_count":4,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-12-06T23:22:14.949Z","etag":null,"topics":["cheminformatics","graphlets","machine-learning"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lanl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-05T22:28:04.000Z","updated_at":"2024-12-06T22:20:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"59d7f0fd-72fb-4b0a-a860-36607893173a","html_url":"https://github.com/lanl/minervachem","commit_stats":null,"previous_names":["lanl/minervachem"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2Fminervachem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2Fminervachem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2Fminervachem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2Fminervachem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lanl","download_url":"https://codeload.github.com/lanl/minervachem/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228911916,"owners_count":17990774,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cheminformatics","graphlets","machine-learning"],"created_at":"2024-12-09T15:14:01.416Z","updated_at":"2024-12-09T15:14:02.126Z","avatar_url":"https://github.com/lanl.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MinervaChem - a python library for cheminformatics and machine learning\n\nMinervachem implements Graphlet Fingerprints and other utilities cheminformatics and chemical machine learning.\n\nThis is an alpha release, so be prepared for breaking changes --\nkeep track of what version you are using if you need to maintain consistency.\n\n## Installation\n\nThere are currently two ways to get `minervachem` up and running: \n1. Build from conda `env.yml` and this git repo\n2. NOT RECOMMENDED install this repo and dependencies via `pip`\n\n### Conda installation\n\nSteps: \n1. Clone this repo and `cd` into it\n2. \n    a. If creating a new conda environment: `conda env create -n minervachem --file env.yml`\n    b. If installing into an existing conda environment: `conda env update -n \u003cYOUR_ENV_NAME\u003e -f env.yml`\n3. `pip install -e .`\n\n### Pip Installation \n\n**This is not recommended**  \n\nSteps: \n1. Clone this repo and `cd` into it.\n2. install the package with `pip install -e .`\n3. If running demos, install your preferred variant of jupyter\n\n### For Developers\nYou'll also want to run `pip install -r requirements_developer.txt`\n\n# Getting started with `minervachem`\n\nWe recommend looking through and running the notebooks in the `demos/` directory for a detailed introduction to `minervachem`'s funcitonality.\n\n## Highlights\n\n### Constructing graphlet fingerprints\n\n`Fingerprinter` classes provide reusable objects for generating molecular fingerprints, including the graphlet fingerprints described in our manuscript.\n\n```python\nfrom rdkit.Chem import MolFromSmiles, AddHs\nfrom minervachem.fingerprinters import GraphletFingerprinter\n\n# Benzene\nmol = AddHs(MolFromSmiles('c1ccccc1'))\n\n# Reusable Fingerprinter object \nfingerprinter = GraphletFingerprinter(max_len=3)\n\n# Fingerprints are a map from fragment IDs to fragment counts.\n# The fragments are identified by their number of atoms and a hash.\nfp, bi = fingerprinter(mol)\nprint(fp)\n\u003e\u003e\u003e {(3, 10387847931347882557): 6,\n\u003e\u003e\u003e  (2, 10630435057451682469): 6,\n\u003e\u003e\u003e  (2, 11665740151475091393): 6,\n\u003e\u003e\u003e  (3, 14577436124092730684): 12,\n\u003e\u003e\u003e  (1, 20784809936286627226): 6,\n\u003e\u003e\u003e  (1, 12794648790135253294): 6}\n\n# We can visualize the above dictiory with a plotting method\nfrom minervachem.plotting import plot_fingerprint\nplot_fingerprint(mol, fingerprinter)\n```\n![A plot of the molecular graphlets of benzene up to size 3 atoms, their counts, and their identifiers](demos/benzene_bits.png)\n\n### scikit-learn transformers\n\nWe can quickly construct feature matrices for machine learning from a set of molecules using `minervachem`'s provided `sklearn`-style transformers:\n\n```python\nfrom minervachem.transformers import FingerprintFeaturizer\n\nmols = [MolFromSmiles(s) for s in [\n    'c1ccccc1',\n    'NCNOCOC',\n    'CN1C=NC2=C1C(=O)N(C(=O)N2C)C',\n    'CNO',\n]]\n\nfeaturizer = FingerprintFeaturizer(\n    fingerprinter, \n    n_jobs=2 # parallelism for large datasets\n)\n\n# FingerprintFeaturizer implements the sklearn transformer API\nfeature_matrix = featurizer.fit_transform(mols)\n# which generates sparse integer matrices by default\nfeature_matrix\n```\n```\n\u003e\u003e\u003e \u003c4x39 sparse matrix of type '\u003cclass 'numpy.int64'\u003e'\n\twith 44 stored elements in Compressed Sparse Row format\u003e\n```\n\n### Building Interpretable Machine Learning Models\n#### Model fitting\n\nAfter constructing a dataset through the methods above, we can use `minervachem` to fit an interpretable ML model. \n\nThe below is a snippet from the demo notebook which fits a hierarchical linear model with ~6,000 coefficients to ~100,000 molecules from QM9. \n\n```python\nimport minervachem\nfrom sklearn.linear_model import Ridge\nfrom minervachem.regressors import HierarchicalResidualModel\nfrom minervachem.plotting import parity_plot_train_test\n\n\n# build a higherarchical residual model\n# using a ridge regressor base model \nbase_model = Ridge(fit_intercept=False, \n                   alpha=1e-5,\n                   solver='sparse_cg')\nhmodel = HierarchicalResidualModel(regressor=base_model,verbose=1)\nhmodel.fit(X_train,y_train,levels=featurizer.bit_sizes_)\n\n# visualize the train and test performance with \n# minervachem's plotting methods\nparity_plot_train_test([X_train, X_test], \n                       [y_train, y_test],\n                       hmodel, \n                       figsize=(12, 4),\n                       xlab='DFT (kcal/mol)', \n                       ylab='Linear Model (kcal/mol)', \n                       title='Hierarchical Model Prediction');   \n```\n![Hierarchical model performance](demos/hmodel_perf.png)\n\n\n#### Model interpretations\nLinear models are interpretable, but 6,000 coefficients is too many to look at all at once. (The most accurate models in our manuscript had \u003e100,000 coefficients.) So, we use `minervachem`'s projection methods to visualize atom- or bond-level contributions to model predictions for a set of molecules. \n\nFirst we construct the Directed-Acyclic-Graph (DAG) between molecular graphlets that defines our projection operation:\n\n```python\nfrom minervachem.graphlet_dags import GraphletDAG, draw_projected_coefs\n\n# Construct the DAG relating larger graphlets to smaller ones\n# for each molecule\ndags = []\nfor mol in mols:\n    dag =  GraphletDAG(mol,\n                       fingerprinter=featurizer.fingerprinter, # the fingerprinter that creates the graphlets\n                       bit_ids=featurizer.bit_ids_, # The bit ids for the features used in the model training\n                       coef=hmodel.coef_ # The model coefficients as an array.\n                     )\n    dags.append(dag)\n\ndraw_projected_coefs(dags,\n                     level=2, # bond-level interpretations (atom-level is 1)\n                    )\n```\n![Hierarhcical model interpretation](demos/hmodel_interp.png)\n\n\n## Citation \nIf you use minervachem in your work, please cite [our paper](https://doi.org/10.26434/chemrxiv-2024-r81c8)\n\n```latex\n@article{tynes2024linear,\n  title={Linear Graphlet Models for Accurate and Interpretable Cheminformatics},\n  author={Tynes, Michael and Taylor, Michael G and Janssen, Jan and Burrill, Daniel J and Perez, Danny and Yang, Ping and Lubbers, Nicholas},\n  journal={ChemRxiv preprint},\n  doi={10.26434/chemrxiv-2024-r81c8},\n  url={dx.doi.org/10.26434/chemrxiv-2024-r81c8},\n  year={2024}\n}\n```\n\n## Copyright and licensing\n\n`minervachem` is released under the BSD-3 License. See LICENSE.txt for the full license.\n\n\nThe copyright to `minervachem` is owned by Triad National Security, LLC\nand is released for open source use as project number O04631.\n\n\n© 2023. Triad National Security, LLC. All rights reserved.\nThis program was produced under U.S. Government contract 89233218CNA000001 for Los Alamos\nNational Laboratory (LANL), which is operated by Triad National Security, LLC for the U.S.\nDepartment of Energy/National Nuclear Security Administration. All rights in the program are.\nreserved by Triad National Security, LLC, and the U.S. Department of Energy/National Nuclear\nSecurity Administration. The Government is granted for itself and others acting on its behalf a\nnonexclusive, paid-up, irrevocable worldwide license in this material to reproduce, prepare.\nderivative works, distribute copies to the public, perform publicly and display publicly, and to permit.\nothers to do so.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flanl%2Fminervachem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flanl%2Fminervachem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flanl%2Fminervachem/lists"}