chemap 0.1.0__tar.gz

chemap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 matchms
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chemap-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: chemap
+Version: 0.1.0
+Summary: Library for computing molecular fingerprint based similarities as well as dimensionality reduction based chemical space visualizations. 
+License-Expression: MIT
+License-File: LICENSE
+Author: Florian Huber
+Author-email: florian.huber@hs-duesseldorf.de
+Requires-Python: >=3.11,<3.14
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Dist: map4 (>=1.1.3)
+Requires-Dist: matplotlib (>=3.10.1)
+Requires-Dist: numba (>=0.61.2)
+Requires-Dist: numpy (>=2.1.0)
+Requires-Dist: pandas (>=2.2.1)
+Requires-Dist: pooch (>=1.8.2)
+Requires-Dist: rdkit (>=2024.9.6)
+Requires-Dist: scikit-fingerprints (>=1.15.0)
+Requires-Dist: scipy (>=1.14.2)
+Requires-Dist: tqdm (>=4.67.1)
+Description-Content-Type: text/markdown
+
+
+<img src="./materials/chemap_logo_green_pink.svg" width="400">
+
+![GitHub License](https://img.shields.io/github/license/matchms/chemap?color=#00B050)
+[![PyPI](https://img.shields.io/pypi/v/chemap?color=#00B050)](https://pypi.org/project/chemap/)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/matchms/chemap/CI_build_and_matrix_tests.yml?color=#00B050)
+[![Powered by RDKit](https://img.shields.io/badge/Powered%20by-RDKit-3838ff.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQBAMAAADt3eJSAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAAAFVBMVEXc3NwUFP8UPP9kZP+MjP+0tP////9ZXZotAAAAAXRSTlMAQObYZgAAAAFiS0dEBmFmuH0AAAAHdElNRQfmAwsPGi+MyC9RAAAAQElEQVQI12NgQABGQUEBMENISUkRLKBsbGwEEhIyBgJFsICLC0iIUdnExcUZwnANQWfApKCK4doRBsKtQFgKAQC5Ww1JEHSEkAAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAyMi0wMy0xMVQxNToyNjo0NyswMDowMDzr2J4AAAAldEVYdGRhdGU6bW9kaWZ5ADIwMjItMDMtMTFUMTU6MjY6NDcrMDA6MDBNtmAiAAAAAElFTkSuQmCC)](https://www.rdkit.org/)
+    
+# chemap - Chemical Mapping
+Library for computing molecular fingerprint based similarities as well as dimensionality reduction based chemical space visualizations.
+
+
+## Fingerprint computations
+Fingerprints can be computed using generators from `RDKit` or `scikit-fingerprints`. Here a code example:
+
+```python
+import numpy as np
+import scipy.sparse as sp
+from rdkit.Chem import rdFingerprintGenerator
+from skfp.fingerprints import MAPFingerprint, AtomPairFingerprint
+
+from chemap import compute_fingerprints, DatasetLoader, FingerprintConfig
+
+
+ds_loader = DatasetLoader()
+smiles = ds_loader.load("tests/data/smiles.csv")
+
+# ----------------------------
+# RDKit: Morgan (folded, dense)
+# ----------------------------
+morgan = rdFingerprintGenerator.GetMorganGenerator(radius=3, fpSize=4096)
+X_morgan = compute_fingerprints(
+    smiles,
+    morgan,
+    config=FingerprintConfig(
+        count=False,
+        folded=True,
+        return_csr=False,   # dense numpy
+        invalid_policy="raise",
+    ),
+)
+print("RDKit Morgan:", X_morgan.shape, X_morgan.dtype)
+
+# -----------------------------------
+# RDKit: RDKitFP (folded, CSR sparse)
+# -----------------------------------
+rdkitfp = rdFingerprintGenerator.GetRDKitFPGenerator(fpSize=4096)
+X_rdkitfp_csr = compute_fingerprints(
+    smiles,
+    rdkitfp,
+    config=FingerprintConfig(
+        count=False,
+        folded=True,
+        return_csr=True,    # SciPy CSR
+        invalid_policy="raise",
+    ),
+)
+assert sp.issparse(X_rdkitfp_csr)
+print("RDKit RDKitFP (CSR):", X_rdkitfp_csr.shape, X_rdkitfp_csr.dtype, "nnz=", X_rdkitfp_csr.nnz)
+
+# --------------------------------------------------
+# scikit-fingerprints: MAPFingerprint (folded, dense)
+# --------------------------------------------------
+# MAPFingerprint is a MinHash-like fingerprint (different from MAP4 lib).
+map_fp = MAPFingerprint(fp_size=4096, count=False, sparse=False)
+X_map = compute_fingerprints(
+    smiles,
+    map_fp,
+    config=FingerprintConfig(
+        count=False,
+        folded=True,
+        return_csr=False,
+        invalid_policy="raise",
+    ),
+)
+print("skfp MAPFingerprint:", X_map.shape, X_map.dtype)
+
+# ----------------------------------------------------
+# scikit-fingerprints: AtomPairFingerprint (folded, CSR)
+# ----------------------------------------------------
+atom_pair = AtomPairFingerprint(fp_size=4096, count=False, sparse=False, use_3D=False)
+X_ap_csr = compute_fingerprints(
+    smiles,
+    atom_pair,
+    config=FingerprintConfig(
+        count=False,
+        folded=True,
+        return_csr=True,
+        invalid_policy="raise",
+    ),
+)
+assert sp.issparse(X_ap_csr)
+print("skfp AtomPair (CSR):", X_ap_csr.shape, X_ap_csr.dtype, "nnz=", X_ap_csr.nnz)
+
+# (Optional) convert CSR -> dense if you need a NumPy array downstream:
+X_ap = X_ap_csr.toarray().astype(np.float32, copy=False)
+
+
+```
+

chemap-0.1.0/README.md

@@ -0,0 +1,99 @@
+
+<img src="./materials/chemap_logo_green_pink.svg" width="400">
+
+![GitHub License](https://img.shields.io/github/license/matchms/chemap?color=#00B050)
+[![PyPI](https://img.shields.io/pypi/v/chemap?color=#00B050)](https://pypi.org/project/chemap/)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/matchms/chemap/CI_build_and_matrix_tests.yml?color=#00B050)
+[![Powered by RDKit](https://img.shields.io/badge/Powered%20by-RDKit-3838ff.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQBAMAAADt3eJSAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAAAFVBMVEXc3NwUFP8UPP9kZP+MjP+0tP////9ZXZotAAAAAXRSTlMAQObYZgAAAAFiS0dEBmFmuH0AAAAHdElNRQfmAwsPGi+MyC9RAAAAQElEQVQI12NgQABGQUEBMENISUkRLKBsbGwEEhIyBgJFsICLC0iIUdnExcUZwnANQWfApKCK4doRBsKtQFgKAQC5Ww1JEHSEkAAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAyMi0wMy0xMVQxNToyNjo0NyswMDowMDzr2J4AAAAldEVYdGRhdGU6bW9kaWZ5ADIwMjItMDMtMTFUMTU6MjY6NDcrMDA6MDBNtmAiAAAAAElFTkSuQmCC)](https://www.rdkit.org/)
+    
+# chemap - Chemical Mapping
+Library for computing molecular fingerprint based similarities as well as dimensionality reduction based chemical space visualizations.
+
+
+## Fingerprint computations
+Fingerprints can be computed using generators from `RDKit` or `scikit-fingerprints`. Here a code example:
+
+```python
+import numpy as np
+import scipy.sparse as sp
+from rdkit.Chem import rdFingerprintGenerator
+from skfp.fingerprints import MAPFingerprint, AtomPairFingerprint
+
+from chemap import compute_fingerprints, DatasetLoader, FingerprintConfig
+
+
+ds_loader = DatasetLoader()
+smiles = ds_loader.load("tests/data/smiles.csv")
+
+# ----------------------------
+# RDKit: Morgan (folded, dense)
+# ----------------------------
+morgan = rdFingerprintGenerator.GetMorganGenerator(radius=3, fpSize=4096)
+X_morgan = compute_fingerprints(
+    smiles,
+    morgan,
+    config=FingerprintConfig(
+        count=False,
+        folded=True,
+        return_csr=False,   # dense numpy
+        invalid_policy="raise",
+    ),
+)
+print("RDKit Morgan:", X_morgan.shape, X_morgan.dtype)
+
+# -----------------------------------
+# RDKit: RDKitFP (folded, CSR sparse)
+# -----------------------------------
+rdkitfp = rdFingerprintGenerator.GetRDKitFPGenerator(fpSize=4096)
+X_rdkitfp_csr = compute_fingerprints(
+    smiles,
+    rdkitfp,
+    config=FingerprintConfig(
+        count=False,
+        folded=True,
+        return_csr=True,    # SciPy CSR
+        invalid_policy="raise",
+    ),
+)
+assert sp.issparse(X_rdkitfp_csr)
+print("RDKit RDKitFP (CSR):", X_rdkitfp_csr.shape, X_rdkitfp_csr.dtype, "nnz=", X_rdkitfp_csr.nnz)
+
+# --------------------------------------------------
+# scikit-fingerprints: MAPFingerprint (folded, dense)
+# --------------------------------------------------
+# MAPFingerprint is a MinHash-like fingerprint (different from MAP4 lib).
+map_fp = MAPFingerprint(fp_size=4096, count=False, sparse=False)
+X_map = compute_fingerprints(
+    smiles,
+    map_fp,
+    config=FingerprintConfig(
+        count=False,
+        folded=True,
+        return_csr=False,
+        invalid_policy="raise",
+    ),
+)
+print("skfp MAPFingerprint:", X_map.shape, X_map.dtype)
+
+# ----------------------------------------------------
+# scikit-fingerprints: AtomPairFingerprint (folded, CSR)
+# ----------------------------------------------------
+atom_pair = AtomPairFingerprint(fp_size=4096, count=False, sparse=False, use_3D=False)
+X_ap_csr = compute_fingerprints(
+    smiles,
+    atom_pair,
+    config=FingerprintConfig(
+        count=False,
+        folded=True,
+        return_csr=True,
+        invalid_policy="raise",
+    ),
+)
+assert sp.issparse(X_ap_csr)
+print("skfp AtomPair (CSR):", X_ap_csr.shape, X_ap_csr.dtype, "nnz=", X_ap_csr.nnz)
+
+# (Optional) convert CSR -> dense if you need a NumPy array downstream:
+X_ap = X_ap_csr.toarray().astype(np.float32, copy=False)
+
+
+```

chemap-0.1.0/chemap/__init__.py

@@ -0,0 +1,9 @@
+from .data_loader import DatasetLoader
+from .fingerprint_computation import FingerprintConfig, compute_fingerprints
+
+
+__all__ = [
+    "FingerprintConfig",
+    "compute_fingerprints",
+    "DatasetLoader",
+]

chemap-0.1.0/chemap/approx_nn.py

@@ -0,0 +1,162 @@
+"""
+Module: approx_nn
+-----------------
+
+This module defines a function for computing approximate nearest neighbors
+from a list of SMILES strings. It uses two different fingerprints:
+  - A dense (1024-bit) fingerprint for dimensionality reduction via PCA.
+  - A sparse (4096-bit) fingerprint for a refined nearest neighbor search
+    based on a Ruzicka similarity.
+
+The general steps are:
+    1. Compute fingerprints from SMILES using RDKit's Morgan generator.
+    2. Scale and reduce the dense fingerprints with PCA.
+    3. Build an approximate NN graph on the PCA vectors.
+    4. Refine the neighbor search using a Ruzicka-based candidate search.
+"""
+
+import time
+from typing import Any, List, Tuple
+import numba
+import numpy as np
+from fingerprint_computation import compute_fingerprints_from_smiles
+from metrics import ruzicka_similarity_sparse_numba
+from numba import prange
+from pynndescent import NNDescent
+from rdkit.Chem import rdFingerprintGenerator
+from sklearn.decomposition import PCA
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import StandardScaler
+
+
+def compound_nearest_neighbors(
+    smiles: List[str], k_pca: int = 500, k_morgan: int = 100
+) -> Tuple[Any, Any]:
+    """
+    Compute approximate nearest neighbors for a list of SMILES strings.
+
+    This function computes two sets of molecular fingerprints using RDKit’s Morgan
+    generator (one dense and one sparse), reduces the dimensionality of the dense
+    fingerprints via PCA, builds an approximate nearest neighbor graph using NNDescent,
+    and finally refines the search with a Ruzicka-based candidate search.
+
+    Parameters:
+        smiles (List[str]): List of SMILES strings representing molecules.
+        k_pca (int): Number of neighbors used for the initial approximate NN search
+                     (using PCA vectors). Must be larger than k_morgan. Default: 500.
+        k_morgan (int): Number of neighbors used for the refined Ruzicka-based search.
+                        Default: 100.
+
+    Returns:
+        Tuple[Any, Any]: A tuple (order, scores) where:
+            - order: An array-like structure of neighbor indices.
+            - scores: An array-like structure of similarity scores corresponding to the neighbors.
+    """
+    # Validate input: ensure that the PCA search uses more neighbors than the refined search.
+    assert k_pca > k_morgan, "Expected k_pca to be larger than k_morgan"
+
+    t_start = time.time()
+    print(">" * 20, "Compute fingerprints")
+    # Compute dense fingerprints (1024 bits) for PCA.
+    fpgen = rdFingerprintGenerator.GetMorganGenerator(radius=3, fpSize=1024)
+    fingerprints_morgan3_count_1024 = compute_fingerprints_from_smiles(
+        smiles, fpgen, count=True, sparse=False, progress_bar=True,
+    )
+
+    # Compute sparse fingerprints for refined neighbor search.
+    fpgen = rdFingerprintGenerator.GetMorganGenerator(radius=3, fpSize=4096)
+    fingerprints_morgan3_count_sparse = compute_fingerprints_from_smiles(
+        smiles, fpgen, count=True, sparse=True, progress_bar=True,
+    )
+    print(f"Took: {(time.time() - t_start):.4f} s.")
+
+    order, scores = compute_approx_nearest_neighbors(
+        fingerprints_morgan3_count_1024, fingerprints_morgan3_count_sparse, k_pca, k_morgan
+        )
+    return order, scores
+
+
+def compute_approx_nearest_neighbors(
+    fingerprints_coarse, fingerprints_fine, k_pca: int = 500, k_morgan: int = 100
+) -> Tuple[Any, Any]:
+
+    t_start = time.time()
+    print(">" * 20, "Compute PCA vectors")
+    pca = PCA(n_components=100)
+    scaler = StandardScaler()
+    pipe = Pipeline(steps=[("scaler", scaler), ("pca", pca)])
+    pca_vectors = pipe.fit_transform(fingerprints_coarse)
+    print(f"Took: {(time.time() - t_start):.4f} s.")
+
+    t_start = time.time()
+    print(">" * 20, f"Build NN-graph ({k_pca} neighbors)")
+    ann_graph = NNDescent(pca_vectors, metric="cosine", n_neighbors=k_pca)
+    print(f"Took: {(time.time() - t_start):.4f} s.")
+
+    t_start = time.time()
+    print(">" * 20, f"Build Ruzicka based NN-graph ({k_morgan} neighbors)")
+    order, scores = ruzicka_candidate_search(
+        fingerprints_fine, fingerprints_fine,
+        ann_graph.neighbor_graph[0],
+        k_morgan,
+    )
+    print(f"Took: {(time.time() - t_start):.4f} s.")
+
+    return order, scores
+
+
+@numba.jit(nopython=True)
+def ruzicka_candidate_search(
+        references: list, queries: list,
+        knn_indices_approx: list,
+        k
+        ) -> np.ndarray:
+    """Search all candidates...
+
+    Parameters
+    ----------
+    references:
+        List of sparse fingerprints (tuple of two arrays: keys and counts).
+    queries
+        List of sparse fingerprints (tuple of two arrays: keys and counts).
+    """
+    size = len(queries)
+    candidate_idx = np.zeros((size, k))#, dtyoe=np.int32)
+    candidate_scores = np.zeros((size, k), dtype=np.float64)
+    for i, knn_indices in enumerate(knn_indices_approx):
+        
+        order, scores = ruzicka_similarity_query_search(
+            [references[i] for i in knn_indices],
+            queries[i], k
+        )
+        candidate_idx[i, :] = knn_indices[order]
+        candidate_scores[i, :] = scores
+    return candidate_idx, candidate_scores
+
+
+@numba.jit(nopython=True, fastmath=True, parallel=True)
+def ruzicka_similarity_query_search(
+    candidates: list, query, k) -> np.ndarray:
+    """Returns matrix of Ruzicka similarity between all-vs-all vectors of references and queries.
+
+    Parameters
+    ----------
+    references:
+        List of sparse fingerprints (tuple of two arrays: keys and counts).
+    queries
+        Sparse fingerprint (tuple of two arrays: keys and counts).
+
+    Returns
+    -------
+    scores:
+        Matrix of all-vs-all similarity scores. scores[i, j] will contain the score
+        between the vectors references[i, :] and queries[j, :].
+    """
+    size1 = len(candidates)
+    distances = np.zeros(size1)
+    for i in prange(size1):
+        distances[i] = 1 - ruzicka_similarity_sparse_numba(
+            candidates[i][0], candidates[i][1],
+            query[0], query[1])
+    order = np.argsort(distances)[:k]
+    return order, distances[order]

chemap-0.1.0/chemap/data_loader.py

@@ -0,0 +1,95 @@
+import os
+import pathlib
+import pandas as pd
+import pooch
+
+
+class DatasetLoader:
+    def __init__(self, cache_dir="./data_cache"):
+        self.cache_dir = cache_dir
+
+    def load(self, source: str, **kwargs) -> list:
+        """
+        Loads a dataset from local file or web.
+
+        Parameters
+        -------------
+        source:
+            Either load a local file or a hyperlink pointing to a remote file.
+            Supported filetypes: .csv, .json, .parquet, .xls, .xlsx, .xlsx.
+
+        Returns
+        -------------
+        list of smiles strings.
+
+        Raises
+        -------------
+        ValueError if neither local file nor http/ftp/sftp.
+        """
+        if os.path.exists(source):
+            return self._from_local_file(source, **kwargs)
+        elif source.startswith(("http", "ftp", "sftp")):
+            return self._from_web(source, **kwargs)
+        else:
+            raise ValueError(f"Source {source} unknown.")
+
+    def _from_local_file(self, path, smiles_column: str = "smiles") -> list:
+        """
+        Loads a dataset from local file.
+
+        Parameters
+        -------------
+        path:
+            string of local file path.
+
+        smiles_column:
+            Name of column containing smiles. Defaults to smiles
+
+        Returns
+        -------------
+        list of smiles strings.
+
+        Raises
+        -------------
+        ValueError if file type unsupported.
+        ValueError if smiles column not present.
+        """
+        suffix = pathlib.Path(path).suffix.lower()
+
+        if suffix == ".csv":
+            df = pd.read_csv(path)
+        elif suffix == ".json":
+            df = pd.read_json(path)
+        elif suffix in [".parquet", ".pq"]:
+            df = pd.read_parquet(path)
+        elif suffix in [".xlsx", ".xls"]:
+            df = pd.read_excel(path)
+        else:
+            raise ValueError(f"Fileformat {suffix} not supported.")
+
+        if smiles_column not in df.columns:
+            raise ValueError(f"Smiles column {smiles_column} not in dataframe.")
+
+        return df[smiles_column].tolist()
+
+    def _from_web(self, url: str, **kwargs) -> list:
+        """
+        Loads a dataset from web.
+
+        Parameters
+        -------------
+        url:
+            string of url.
+
+        Returns
+        -------------
+        list of smiles strings.
+        """
+        file_path = pooch.retrieve(
+            url=url,
+            known_hash=kwargs.get("hash", None),
+            path=self.cache_dir,
+            progressbar=True,
+        )
+
+        return self._from_local_file(file_path, **kwargs)