bblean 0.6.0b1__cp312-cp312-macosx_10_13_universal2.whl

bblean-0.6.0b1.dist-info/METADATA

@@ -0,0 +1,283 @@
+Metadata-Version: 2.4
+Name: bblean
+Version: 0.6.0b1
+Summary: BitBirch-Lean Python package
+Author: The Miranda-Quintana Lab and other BitBirch developers
+Author-email: Ramon Alain Miranda Quintana <quintana@chem.ufl.edu>, Krisztina Zsigmond <kzsigmond@ufl.edu>, Ignacio Pickering <ipickering@ufl.edu>, Kenneth Lopez Perez <klopezperez@chem.ufl.edu>, Miroslav Lzicar <miroslav.lzicar@deepmedchem.com>
+License-Expression: GPL-3.0-only
+Project-URL: homepage, https://github.com/mqcomplab/bblean.git
+Project-URL: repository, https://github.com/mqcomplab/bblean.git
+Project-URL: documentation, https://github.com/mqcomplab/bblean.git
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Topic :: Software Development
+Classifier: Topic :: Scientific/Engineering
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scipy
+Requires-Dist: rdkit
+Requires-Dist: numpy>=2.0
+Requires-Dist: pandas
+Requires-Dist: psutil
+Requires-Dist: matplotlib
+Requires-Dist: colorcet
+Requires-Dist: seaborn
+Requires-Dist: scikit-learn
+Requires-Dist: rich
+Requires-Dist: typer
+Requires-Dist: opentsne
+Requires-Dist: umap-learn
+Requires-Dist: pynndescent
+Dynamic: license-file
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mqcomplab/bblean/main/docs/src/_static/logo-dark-bw.svg">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/mqcomplab/bblean/main/docs/src/_static/logo-light-bw.svg">
+  <img alt="BitBIRCH-Lean logo" src="https://raw.githubusercontent.com/mqcomplab/bblean/main/docs/src/_static/logo-light-bw.svg">
+</picture>
+<br>
+<br>
+
+[![DOI](https://zenodo.org/badge/1051268662.svg)](https://doi.org/10.5281/zenodo.17139445)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![CI](https://github.com/mqcomplab/bblean/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/mqcomplab/bblean/actions/workflows/ci.yaml)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+![Code coverage](https://img.shields.io/endpoint?url=https%3A%2F%2Fmqcomplab.github.io%2Fbblean%2Fcoverage%2Fcoverage-badge.json) 
+
+## Overview
+
+BitBIRCH-Lean is a high-throughput implementation of the BitBIRCH clustering
+algorithm designed for very large molecular libraries.
+
+If you find this software useful please cite the following articles:
+
+- *BitBIRCH: efficient clustering of large molecular libraries*:
+    https://doi.org/10.1039/D5DD00030K
+- *BitBIRCH Clustering Refinement Strategies*:
+    https://doi.org/10.1021/acs.jcim.5c00627
+- *BitBIRCH-Lean*:
+    (preprint) https://www.biorxiv.org/content/10.1101/2025.10.22.684015v1
+
+**NOTE**: BitBirch-Lean is currently beta software, expect minor breaking changes until
+we hit version 1.0
+
+The [documentation](https://mqcomplab.github.io/bblean/devdocs) of the developer version is a work in progress. Please let us know if you find any issues.
+
+⚠️  **Important**: The default `threshold` is 0.3 and the default fingerprint kind to
+*ecfp4*. We recommend setting `threshold` to 0.5-0.65 for *rdkit* fingerprints and
+0.3-0.4 for *ecfp4* or *ecfp6* fingerprints (although you may need further tuning for
+your specific library / fingerprint set). For more information on tuning these
+parameters see [the best
+practices](https://mqcomplab.github.io/bblean/devdocs/user-guide/notebooks/bitbirch_best_practices.html)
+and [parameter
+tuning](https://mqcomplab.github.io/bblean/devdocs/user-guide/parameters.html) guides.
+
+## Installation
+
+BitBIRCH-Lean requires Python 3.11 or higher, and can be installed in Linux or macOS.
+Via pip, which automatically includes C++ extensions:
+
+```bash
+pip install bblean
+```
+We recommend installing `bblean` in a conda environment or a `venv`.
+
+### From source
+
+To build from source instead (editable mode):
+
+```bash
+git clone git@github.com:mqcomplab/bblean,
+cd bblean
+
+conda env create --file ./environment.yaml
+conda activate bblean
+
+BITBIRCH_BUILD_CPP=1 pip install -e .
+
+# If you want to build without the C++ extensions run this instead:
+pip install -e .
+
+bb --help
+```
+
+If the extensions install successfully, they will be automatically used each time
+BitBirch-Lean or its classes are used. No need to do anything else.
+
+If you run into any issues when installing the extensions, please open a GitHub issue
+and tag it with `C++`.
+
+## CLI Quickstart
+
+<div align="center">
+<img src="bblean-demo-v2.gif" width="600" />
+</div>
+
+BitBIRCH-Lean provides a convenient CLI interface, `bb`. The CLI can be used to convert
+SMILES files into compact fingerprint arrays, and cluster them in parallel or serial
+mode with a single command, making it straightforward to triage collections with
+millions of molecules. The CLI prints a run banner with the parameters used, memory
+usage (when available), and elapsed timings so you can track each job at a glance.
+
+The most important commands you need are:
+
+- `bb fps-from-smiles`: Generate fingerprints from a `*.smi` file.
+- `bb run` or `bb multiround`: Cluster the fingerprints
+- `bb plot-summary` or `bb plot-tsne`: Analyze the clusters
+
+An example usual workflow is as follows:
+
+1. **Generate fingerprints from SMILES**: The repository ships with a ChEMBL
+   sample that you can use right away for testing:
+
+   ```bash
+   bb fps-from-smiles examples/chembl-33-natural-products-sample.smi
+   ```
+
+   This writes a packed fingerprint array to the current working directory (use
+   `--out-dir <dir>` for a different location). The naming convention is
+   `packed-fps-uint8-508e53ef.npy`, where `508e53ef` is a unique identifier (use `--name
+   <name>` if you prefer a different name). The packed `uint8` format is required for
+   maximum memory-efficient, so keep the default
+   `--pack` and `--dtype` values unless you have a very good reason to change them.
+   You can optionally split over multiple files for parallel parallel processing with `--num-parts <num>`.
+
+3. **Cluster the fingerprints**: To cluster in serial mode, point `bb run` at the
+   generated array (or a directory with multiple `*.npy` files):
+
+   ```bash
+   bb run ./packed-fps-uint8-508e53ef.npy
+   ```
+
+   The outputs are stored in directory such as `bb_run_outputs/504e40ef/`, where
+   `504e40ef` is a unique identifier (use `--out-dir <dir>` for a different location).
+   Additional flags can be set to control the BitBIRCH `--branching`, `--threshold`,
+   and merge criterion. Optionally, cluster refinement can be performed with `--refine-num 1`.
+   `bb run --help ` for details.
+
+   To cluster in parallel mode, use `bb multiround ./file-or-dir` instead. If pointed to
+   a directory with multiple `*.npy` files, files will be clustered in parallel and
+   sub-trees will be merged iteratively in intermediate rounds. For more information:
+   `bb multiround --help`. Outputs are written by default to
+   `bb_multiround_outputs/<unique-id>/`.
+
+4. **Visualize the results**: You can plot a summary of the largest clusters with
+   `bb plot-summary <output-path> --top 20` (largest 20 clusters). Passing the optional `--smiles <path-to-file.smi>` argument
+   additionally generates Murcko scaffold analysis. For a t-SNE
+   visualization try `bb plot-tsne <output-path> -- top 20`.
+   t-SNE plots use [openTSNE](https://opentsne.readthedocs.io/en/latest/) as a backend,
+   which is a parallel, extremely fast implementation. We recommend you consult the corresponding
+   documentation for info on the available parameters.
+   Still, expect t-SNE plots to be slow for very large datasets (more than 1M molecules).
+
+### Manually exploring clustering results
+
+Every run directory contains a raw `clusters.pkl` file with the molecule indices for each
+cluster, plus metadata in `*.json` files that captures the exact settings and
+performance characteristics. A quick Python session is all you need to get started:
+
+```python
+import pickle
+
+clusters = pickle.load(open("bb_run_outputs/504e40ef/clusters.pkl", "rb"))
+clusters[:2]
+# [[321, 323, 326, 328, 337, ..., 9988, 9989],
+#  [5914, 5915, 5916, 5917, 5918, ..., 9990, 9991, 9992, 9993]]
+```
+
+The indices refer to the position of each molecule in the order they were read from the
+fingerprint files, making it easy to link back to your original SMILES records.
+
+## Python Quickstart and Examples
+
+For an example of how to use the main `bblean` classes and functions consult
+`examples/bitbirch_quickstart.ipynb`. The `examples/dataset_splitting.ipynb` notebook
+contains an adapted notebook by Pat Walters ([Some Thoughts on Splitting Chemical
+Datasets](https://practicalcheminformatics.blogspot.com/2024/11/some-thoughts-on-splitting-chemical.html)).
+More examples will be added soon!
+
+A quick summary:
+
+```python
+import pickle
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+import bblean
+import bblean.plotting as plotting
+import bblean.analysis as analysis
+
+# Create the fingerprints and pack them into a numpy array, starting from a *.smi file
+smiles = bblean.load_smiles("./examples/chembl-33-natural-products-sample.smi")
+fps = bblean.fps_from_smiles(smiles, pack=True, n_features=2048, kind="rdkit")
+
+# Fit the figerprints (by default all bblean functions take *packed* fingerprints)
+# A threhsold of 0.5-0.65 is good for rdkit fingerprints, a threshold of 0.3-0.4
+# is better for ECFPs
+tree = bblean.BitBirch(branching_factor=50, threshold=0.65, merge_criterion="diameter")
+tree.fit(fps)
+
+# Refine the tree (if needed)
+tree.set_merge(merge_criterion="tolerance-diameter", tolerance=0.0)
+tree.refine_inplace(fps)
+
+# Visualize the results
+clusters = tree.get_cluster_mol_ids()
+ca = analysis.cluster_analysis(clusters, fps, smiles)
+plotting.summary_plot(ca, title="ChEMBL Sample")
+plt.show()
+
+# Save the resulting clusters, metrics, and fps
+with open("./clusters.pkl", "wb") as f:
+    pickle.dump(clusters, f)
+ca.dump_metrics("./metrics.csv")
+np.save("./fps-packed-2048.npy", fps)
+```
+
+## Public Python API and Documentation
+
+By default all functions take *packed* fingerprints of dtype `uint8`. Many functions
+support an `input_is_packed: bool` flag, which you can toggle to `False` in case for
+some reason you want to pass unpacked fingerprints (not recommended).
+
+- Functions and classes that *end in an underscore* are considered private (such as
+  `_private_function(...)`) and should not be used, since they can be removed or
+  modified without warning.
+- All functions and classes that are in *modules that end with an underscore* are also
+  considered private (such as `bblean._private_module.private_function(...)`) and should
+  not be used, since they can be removed or modified without warning.
+- All other functions and classes are part of the stable public API and can be used.
+    However, expect minor breaking changes before we hit version 1.0
+
+## Contributing
+
+If you find a bug in BitBIRCH-Lean or have an issue with the usage
+or documentation please open an issue in the GitHub issue tracker.
+
+If you want to contribute to BitBIRCH-Lean with a bug fix, improving the documentation,
+with usability, maintainability, or performance, please open an issue with your
+idea/request (or directly open a PR from a fork if you prefer).
+
+Currently we don't directly accept PRs with new features that have not been extensively
+validated, but if you have an idea to improve the BitBIRCH algorithm you may want to
+contact the Miranda-Quintana Lab, we are open to collaborations.
+
+To contribute, first create a
+[fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo),
+then clone your fork (`git clone git@github.com:<user>/bblean`. We recommend you install
+`pre-commit` (`pre-commit install --hook-type pre-push`), which will run some checks
+before you push to your branch. After you have finished work on your branch, [open a
+pull
+request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).

bblean-0.6.0b1.dist-info/RECORD

@@ -0,0 +1,31 @@
+bblean-0.6.0b1.dist-info/RECORD,,
+bblean-0.6.0b1.dist-info/WHEEL,sha256=3DzZhK-rNIkkEIppB3qbu6syT4kayeV5HkusnWIqMIg,142
+bblean-0.6.0b1.dist-info/entry_points.txt,sha256=a0jb2L5JFKioMD6CqbvJiI2unaArGzi-AMZsyY-uyGg,38
+bblean-0.6.0b1.dist-info/top_level.txt,sha256=ybxTonvTC9zR25yR5B27aEDLl6CiwID093ZyS_--Cq4,7
+bblean-0.6.0b1.dist-info/METADATA,sha256=KZDkJKONgnTbqwaXEK6a023k1hqcdjQBSXGemqAzx4Y,12558
+bblean-0.6.0b1.dist-info/licenses/LICENSE,sha256=-LLlY16Y8cwDvYq3OsbnPMiG1LZnISvS1vWpKf0tFMk,2550
+bblean/_console.py,sha256=vT217TqL_SPBGk23GnW8F8sKKDY5Uq-8LdsxutqxClE,7834
+bblean/metrics.py,sha256=j5_ho52zBddTINpkKqBmJ7oJ_XzeH4UyTI73scNLGlI,7081
+bblean/_timer.py,sha256=ozAtbXcCw5btCxTYgsBWSiVcZdJVzOpAD03wd4VQfwg,1360
+bblean/analysis.py,sha256=JHoUZZfR8NpvjU-UXr8MlXIczQrIMhVHUqIdLbGt2N0,7860
+bblean/_merges.py,sha256=tQLnviVkjnHa5sgN-steyi6Tb7ZbNpfWkDQpiPVEriA,6220
+bblean/similarity.py,sha256=ZieFoeV5sFkNGOBn1VfO3sg1B3QrxuW7Q3W-mUSANs0,9899
+bblean/_version.py,sha256=qOyKFSwx2M995XMIWlR9oHifiOE8nDtfvsOvfcxYC1E,712
+bblean/bitbirch.py,sha256=6C14DKJhepqsKV_Lii9yfg5JivJ55TbEXZqYNN5eDUc,57355
+bblean/_cpp_similarity.cpython-312-darwin.so,sha256=q5DU8xMweZMA585-IP1Kn4liysjBGDA4DoeI9YypW1s,534968
+bblean/plotting.py,sha256=dAOGqo4r_FtQJEKibU_tadM7bs9-uVJg0TMYAiESVjE,15197
+bblean/_py_similarity.py,sha256=TWc3MVM1Qyf2uNcXr0aRZez4D42FJeAOL4_OhUGuXTg,9581
+bblean/__init__.py,sha256=PI-W0P_HskNz_15jySNAOsHCAwWJgO9daUr2-furDzc,664
+bblean/multiround.py,sha256=_-pr5LG_GLSBNZ60uLcy8XZ-qo7lr0Y048Kp041_ug8,19980
+bblean/cli.py,sha256=2LDzZBXPC1P51LFYZOVOKzZ2OA13t3CdFdRSSfZpOB0,60788
+bblean/utils.py,sha256=34Az3-hQoY5IVd1-28xkrQOyjETpyvi3LaoG8-W6EHU,3706
+bblean/smiles.py,sha256=O-uZ0xyWThGT06rYzxYTMlH4Wkld8fnuXMxk1QByg7o,1794
+bblean/_memory.py,sha256=433F0G86SVMK62OrC0YEkUwM0asnS_tiaLdp_HJwFK8,6694
+bblean/_config.py,sha256=Fe5drpl4zvaDpp0V9n9bguh8bh-akQXXM7NkNeOOk1Y,1752
+bblean/fingerprints.py,sha256=QoHda68n5qb9Q6CCDkyhJnOLZImi8c5P8trkOhQdjCA,14891
+bblean/sklearn.py,sha256=baHX1hBS7e-Dnw1lSTsnqNkiYd1RkCv3KHZN41OAeGo,7309
+bblean/csrc/README.md,sha256=Gat24x1okyEdRI-FvQFK-WV_dm7IMcBZNvVA-05ZZeQ,58
+bblean/csrc/similarity.cpp,sha256=dDvnpRtKZTnQS6ttzW2bnbeslebohpViF0cLFhT2mrQ,20717
+bblean/_legacy/bb_int64.py,sha256=r6tIS-9jZGRLpvNA3AFfUTKkqTs_NUkf81wFnJy4bWs,44518
+bblean/_legacy/bb_uint8.py,sha256=a0RTc6OFzQ-4E43sKjJfs79D_zwrgSp1iEFFcYA0Nsw,40429
+bblean/_legacy/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0

bblean-0.6.0b1.dist-info/WHEEL

@@ -0,0 +1,6 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: false
+Tag: cp312-cp312-macosx_10_13_universal2
+Generator: delocate 0.13.0
+

bblean-0.6.0b1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bb = bblean.cli:app

bblean-0.6.0b1.dist-info/licenses/LICENSE

@@ -0,0 +1,48 @@
+BitBIRCH-Lean Python Package: An open-source clustering module based on iSIM.
+
+If you find this software useful please cite the following articles:
+- BitBIRCH: efficient clustering of large molecular libraries:
+    https://doi.org/10.1039/D5DD00030K
+- BitBIRCH Clustering Refinement Strategies:
+    https://doi.org/10.1021/acs.jcim.5c00627
+- BitBIRCH-Lean:
+    (preprint) https://www.biorxiv.org/content/10.1101/2025.10.22.684015v1
+
+Copyright (C) 2025  The Miranda-Quintana Lab and other BitBirch developers, comprised
+exclusively by:
+- Ramon Alain Miranda Quintana <ramirandaq@gmail.com>, <quintana@chem.ufl.edu>
+- Krisztina Zsigmond <kzsigmond@ufl.edu>
+- Ignacio Pickering <ipickering@chem.ufl.edu>
+- Kenneth Lopez Perez <klopezperez@chem.ufl.edu>
+- Miroslav Lzicar <miroslav.lzicar@deepmedchem.com>
+
+Authors of ./bblean/multiround.py are:
+- Ramon Alain Miranda Quintana <ramirandaq@gmail.com>, <quintana@chem.ufl.edu>
+- Ignacio Pickering <ipickering@chem.ufl.edu>
+
+This program is free software: you can redistribute it and/or modify it under the
+terms of the GNU General Public License as published by the Free Software Foundation,
+version 3 (SPDX-License-Identifier: GPL-3.0-only).
+
+Portions of the file ./bblean/bitbirch.py are licensed under the BSD 3-Clause License
+Copyright (c) 2007-2024 The scikit-learn developers. All rights reserved.
+(SPDX-License-Identifier: BSD-3-Clause). Copies or reproductions of code in the
+./bblean/bitbirch.py file must in addition adhere to the BSD-3-Clause license terms. A
+copy of the BSD-3-Clause license can be located at the root of this repository, under
+./LICENSES/BSD-3-Clause.txt.
+
+Portions of the file ./bblean/bitbirch.py were previously licensed under the LGPL 3.0
+license (SPDX-License-Identifier: LGPL-3.0-only), they are relicensed in this program
+as GPL-3.0, with permission of all original copyright holders:
+- Ramon Alain Miranda Quintana <ramirandaq@gmail.com>, <quintana@chem.ufl.edu>
+- Vicky (Vic) Jung <jungvicky@ufl.edu>
+- Kenneth Lopez Perez <klopezperez@chem.ufl.edu>
+- Kate Huddleston <kdavis2@chem.ufl.edu>
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with this
+program. This copy can be located at the root of this repository, under
+./LICENSES/GPL-3.0-only.txt.  If not, see <http://www.gnu.org/licenses/gpl-3.0.html>.

bblean-0.6.0b1.dist-info/top_level.txt

@@ -0,0 +1 @@
+bblean