fpembed 0.1.7__tar.gz → 0.1.8__tar.gz

{fpembed-0.1.7 → fpembed-0.1.8}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: fpembed
-Version: 0.1.7
+Version: 0.1.8
 Summary: Generalized fingerprint embedding library
 License-Expression: MIT
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: scikit-fingerprints==2.0.0
+Requires-Dist: scikit-fingerprints==2.1.0
 Requires-Dist: selfies>=2.2.0
 Provides-Extra: app
 Requires-Dist: nicegui>=3.8.0; extra == "app"
@@ -24,10 +24,40 @@ Dynamic: license-file
 [![DOI](https://img.shields.io/badge/DOI-10.5281/zenodo.21447996-blue)](https://doi.org/10.5281/zenodo.21447996)
 
 
-A lightweight Python package for generating compressed molecular fingerprint embeddings, backed by [scikit-fingerprints](https://github.com/scikit-fingerprints/scikit-fingerprints). Supports ten binary fingerprint types through a single unified class.
+## Contents
+
+- [Installation](#installation)
+  - [Conda Environment](#conda-environment)
+- [Quick Start](#quick-start)
+- [Why Use Embedded Fingerprints?](#why-use-embedded-fingerprints)
+  - [Storage Size](#storage-size)
+  - [ML Training and Inference Speed](#ml-training-and-inference-speed)
+  - [Memory During ML Training](#memory-during-ml-training)
+  - [Compression Overhead](#compression-overhead)
+  - [Sample Efficiency](#sample-efficiency)
+  - [Summary of Advantages](#summary-of-advantages)
+- [Supported Fingerprint Types](#supported-fingerprint-types)
+- [Compression Methods](#compression-methods)
+  - [Method Reference](#method-reference)
+  - [The `method` Parameter](#the-method-parameter)
+  - [Method-Specific Parameters (`method_params`)](#method-specific-parameters-method_params)
+  - [Code Examples](#code-examples)
+  - [Choosing a Method](#choosing-a-method)
+  - [Performance Characteristics](#performance-characteristics)
+- [Project Structure](#project-structure)
+- [Running the Demo App](#running-the-demo-app)
+- [Datasets](#datasets)
+- [License](#license)
+- [Legal & Trademark Notice](#legal--trademark-notice)
+- [AI disclosure](#ai-disclosure)
+- [Support](#support)
+
+A Python package for generating compressed molecular fingerprint embeddings, backed by [scikit-fingerprints](https://github.com/scikit-fingerprints/scikit-fingerprints). Supports ten binary fingerprint types through a single unified class.
 
 FPembed compresses standard molecular fingerprints using weighted binary masking, producing compact float vectors suitable for machine-learning models. The package accepts SMILES, SELFIES, and RDKit Mol objects as input.
 
+At a glance: roughly 16x smaller feature vectors, comparable accuracy to raw fingerprints, and a drop-in fit for any scikit-learn model. If you just want to try it, jump to [Quick Start](#quick-start); if you want the reasoning first, read [Why Use Embedded Fingerprints?](#why-use-embedded-fingerprints) below.
+
 The concept of compressing molecular fingerprints via weighted binary masking was originally introduced for Morgan fingerprints in the eMFP paper:
 
 > Nuñez-Andrade, E. A., Vidal-Daza, I., Gomez-Bombarelli, R., Ryan, J. W., & Martin-Martinez, F. J. (2025).
@@ -47,108 +77,133 @@ The concept of compressing molecular fingerprints via weighted binary masking wa
 
 Original concept repository: [MMLabCodes/eMFP](https://github.com/MMLabCodes/eMFP)
 
-## Supported Fingerprint Types
+## Installation
 
-| Type | `fp_type` | Type-specific params |
-|------|-----------|---------------------|
-| Extended Connectivity (ECFP) | `ecfp` | `radius` (default 2) |
-| Atom Pair | `atom_pair` | `min_distance` (1), `max_distance` (30) |
-| Topological Torsion | `topological_torsion` | `torsion_atom_count` (4) |
-| RDKit | `rdkit` | `min_path` (1), `max_path` (7) |
-| Layered | `layered` | `min_path` (1), `max_path` (7) |
-| Pattern | `pattern` | (none) |
-| Avalon | `avalon` | (none) |
-| SECFP | `secfp` | `radius` (default 3) |
-| MHFP | `mhfp` | `radius` (default 3) |
-| MAP4 | `map` | `radius` (default 2) |
+Install the core package (rdkit, numpy, selfies, scikit-fingerprints):
 
-## Compression Methods
+```bash
+pip install fpembed
+```
 
-FPembed supports six compression methods, selectable via the `method` parameter on `EmbeddedFingerprintGenerator`. The default is `geometric`.
+Install with demo app dependencies (nicegui, optuna, pandas, scikit-learn, etc.):
 
-### Method Reference
+```bash
+pip install fpembed[app]
+```
 
-| Method (`method` value) | Category | `method_params` | Dynamic Range / Distance Preservation | Complexity |
-|-------------------------|----------|-----------------|---------------------------------------|------------|
-| `geometric` | block-wise | `interleave` (bool) | 65,536:1 dynamic range | O(L)       |
-| `linear` | block-wise | `interleave` (bool) | S:1 dynamic range | O(L)       |
-| `log` | block-wise | `interleave` (bool) | ~4.1:1 dynamic range | O(L)       |
-| `uniform` | block-wise | `interleave` (bool) | 1:1 (mean pooling) | O(L)       |
-| `hadamard` | global | `seed` (int) | orthogonal projection | O(L log L) |
-| `random_projection` | global | `seed` (int) + `sparse` (bool) | JL distance preservation | O(L D)     |
+For development (editable install):
 
-### The `method` Parameter
+```bash
+pip install -e .
+```
 
-Pass `method` to the Generator constructor to select a compression strategy.
+### Conda Environment
 
-### Method-Specific Parameters (`method_params`)
+A full conda environment is provided for reproducibility:
 
-- **Block-wise methods** (`geometric`, `linear`, `log`, `uniform`): accept `interleave` (bool, default `False`). When `True`, bits are assigned to blocks by stride (`bit[i] -> block[i % n_blocks]`) instead of contiguous partitioning, breaking hash clustering artifacts.
-- **`hadamard`**: accepts `seed` (int, default `42`). Controls the random sign flips applied before the Fast Walsh-Hadamard Transform.
-- **`random_projection`**: accepts `seed` (int, default `42`) and `sparse` (bool, default `False`). The `sparse` option uses the Achlioptas variant with approximately 2/3 zero entries for faster computation at comparable quality.
+```bash
+conda env create -f environment.yml
+conda activate fpembed
+```
 
-Seed-based methods (`hadamard`, `random_projection`) are fully deterministic given the same seed and NumPy version. The default seed is `42`.
+This installs all dependencies and the `fpembed` package in editable mode.
 
-### Code Examples
+## Quick Start
+
+### Single Molecule (SMILES)
 
 ```python
 from fpembed import EmbeddedFingerprintGenerator
 
-# Geometric (default)
-gen = EmbeddedFingerprintGenerator(fp_type="ecfp", fp_size=2048, compression=16, fp_params={"radius": 2})
+gen = EmbeddedFingerprintGenerator(
+    fp_type="ecfp", fp_size=2048, compression=16, fp_params={"radius": 2}
+)
 
-# Linear weights
-gen = EmbeddedFingerprintGenerator(fp_type="ecfp", fp_size=2048, compression=16, fp_params={"radius": 2}, method="linear")
+# Generate compressed fingerprint from SMILES
+emb = gen.GetFingerprintFromSmiles("CCO")
+print(emb.shape)  # (128,)
+```
 
-# Logarithmic weights
-gen = EmbeddedFingerprintGenerator(fp_type="ecfp", fp_size=2048, compression=16, fp_params={"radius": 2}, method="log")
+### Different Fingerprint Types
 
-# Uniform weights (mean pooling)
-gen = EmbeddedFingerprintGenerator(fp_type="ecfp", fp_size=2048, compression=16, fp_params={"radius": 2}, method="uniform")
+```python
+# Atom Pair fingerprint
+gen_ap = EmbeddedFingerprintGenerator(
+    fp_type="atom_pair", fp_size=2048, compression=16,
+    fp_params={"min_distance": 1, "max_distance": 30}
+)
 
-# Hadamard (SRHT)
-gen = EmbeddedFingerprintGenerator(fp_type="ecfp", fp_size=2048, compression=16, fp_params={"radius": 2}, method="hadamard")
+# Topological Torsion fingerprint
+gen_tt = EmbeddedFingerprintGenerator(
+    fp_type="topological_torsion", fp_size=2048, compression=16,
+    fp_params={"torsion_atom_count": 4}
+)
+```
 
-# Random projection
-gen = EmbeddedFingerprintGenerator(fp_type="ecfp", fp_size=2048, compression=16, fp_params={"radius": 2}, method="random_projection")
+### Single Molecule (SELFIES)
+
+```python
+emb = gen.GetFingerprintFromSelfies("[C][C][O]")
+print(emb.shape)  # (128,)
 ```
 
-Bit-interleaving with a block-wise method:
+### Batch Processing
 
 ```python
-gen = EmbeddedFingerprintGenerator(
-    fp_type="ecfp", fp_size=2048, compression=16,
-    fp_params={"radius": 2}, method="linear",
-    method_params={"interleave": True}
+smiles_list = ["CCO", "c1ccccc1", "CC(=O)O", "invalid_smiles"]
+
+embeddings, invalid_indices = gen.GetFingerprintsFromSmiles(smiles_list)
+print(embeddings.shape)    # (3, 128) - 3 valid molecules
+print(invalid_indices)      # [3] - index of invalid SMILES
+```
+
+### Raw Fingerprint (No Compression)
+
+```python
+gen_raw = EmbeddedFingerprintGenerator(
+    fp_type="ecfp", fp_size=2048, compression=None, fp_params={"radius": 2}
 )
+fp = gen_raw.GetFingerprintFromSmiles("CCO")
+print(fp.shape)  # (2048,)
 ```
 
-Standalone `compress_fingerprint` with a non-default method:
+### Standalone Compression Function
 
 ```python
-from fpembed import compress_fingerprint
 import numpy as np
+from fpembed import compress_fingerprint
 
 fp = np.random.randint(0, 2, size=2048).astype(np.float64)
-emb = compress_fingerprint(fp, size=16, method="hadamard", method_params={"seed": 42})
+emb = compress_fingerprint(fp, size=16)
 print(emb.shape)  # (1, 128)
 ```
 
-### Choosing a Method
+### Parameter Hashing
 
-Block-wise methods (`geometric`, `linear`, `log`, `uniform`) are fast (O(L)) and simple - use them when speed matters or compression ratios are modest. Among these, `geometric` preserves the most dynamic range while `uniform` treats all bits equally (mean pooling). Global projection methods (`hadamard`, `random_projection`) mix information across all input bits, which helps retain more information at high compression ratios. `hadamard` is efficient (O(L log L)) and requires power-of-2 fingerprint sizes; `random_projection` offers the strongest theoretical distance-preservation guarantees (Johnson-Lindenstrauss lemma) at the cost of O(L D) complexity.
+```python
+from fpembed import fp_params_hash
 
-### Performance Characteristics
+h = fp_params_hash("ecfp", {"radius": 2})
+print(h)  # 16-char hex string, stable across sessions
+```
 
-All methods produce the same output dimensionality (D = L / compression) but differ in speed and memory:
+### Caching for Repeated Lookups
 
-| Method | Speed                                                                              | Precomputed Memory                   | Best For |
-|--------|------------------------------------------------------------------------------------|--------------------------------------|----------|
-| Block-wise (all four) | Fastest - single vectorized einsum, O(L)                                           | Negligible (C-length weight vector)  | Default choice; large batches |
-| Hadamard (SRHT) | Fast - vectorized FWHT (NumPy reshape/broadcast, no Python-level loop), O(L log L) | L-length sign vector (~16 KB)        | Large batches at high compression ratios |
-| Random projection | Fast - BLAS matmul, O(L D)                                                         | DxL matrix (~2 MB for L=2048, D=128) | Best theoretical guarantees (JL lemma) |
+```python
+gen = EmbeddedFingerprintGenerator(
+    fp_type="ecfp", fp_size=2048, compression=16,
+    fp_params={"radius": 2}, cache_size=1024
+)
 
-Block-wise methods remain the fastest choice for large batches. Hadamard's FWHT is vectorized across the whole batch and works much faster now. Random projection's memory cost grows quadratically with fingerprint size.
+# First call computes and caches
+emb = gen.GetFingerprintFromSmiles("CCO")
+
+# Second call returns cached result
+emb2 = gen.GetFingerprintFromSmiles("CCO")
+
+print(gen.cache_info())  # CacheInfo(hits=1, misses=1, maxsize=1024, currsize=1)
+gen.clear_cache()
+```
 
 ## Why Use Embedded Fingerprints?
 
@@ -207,154 +262,129 @@ High-dimensional spaces (2048 binary features) suffer from the curse of dimensio
 
 The choice between raw and embedded fingerprints is a classic accuracy-vs-efficiency tradeoff. Embedded fingerprints sacrifice a small amount of information for dramatic improvements in storage, speed, and memory - making them the practical default for most molecular ML workflows.
 
-## Project Structure
-
-```
-fpembed/
-├── src/fpembed/                # pip-distributable package
-│   ├── __init__.py
-│   ├── generator.py            # EmbeddedFingerprintGenerator
-│   ├── compression.py          # compress_fingerprint (orchestrator)
-│   ├── compression_blockwise.py # block-wise weight schemes
-│   ├── compression_projection.py # Hadamard SRHT + random projection
-│   ├── smiles_utils.py         # parse_smiles, canonicalize_smiles
-│   ├── hashing.py              # fp_params_hash
-│   └── py.typed                # PEP 561 marker
-├── examples/
-│   ├── quickstart.ipynb        # usage notebook
-│   ├── datasets/               # molecular datasets (RedDB, NFA, QM9)
-│   └── nicegui_app/            # NiceGUI demo application
-├── pyproject.toml
-├── environment.yml
-└── README.md
-```
-
-## Installation
-
-Install the core package (rdkit, numpy, selfies, scikit-fingerprints):
+## Supported Fingerprint Types
 
-```bash
-pip install fpembed
-```
+| Type | `fp_type` | Type-specific params |
+|------|-----------|---------------------|
+| Extended Connectivity (ECFP) | `ecfp` | `radius` (default 2) |
+| Atom Pair | `atom_pair` | `min_distance` (1), `max_distance` (30) |
+| Topological Torsion | `topological_torsion` | `torsion_atom_count` (4) |
+| RDKit | `rdkit` | `min_path` (1), `max_path` (7) |
+| Layered | `layered` | `min_path` (1), `max_path` (7) |
+| Pattern | `pattern` | (none) |
+| Avalon | `avalon` | (none) |
+| SECFP | `secfp` | `radius` (default 3) |
+| MHFP | `mhfp` | `radius` (default 3) |
+| MAP4 | `map` | `radius` (default 2) |
 
-Install with demo app dependencies (nicegui, optuna, pandas, scikit-learn, etc.):
+## Compression Methods
 
-```bash
-pip install fpembed[app]
-```
+FPembed supports six compression methods, selectable via the `method` parameter on `EmbeddedFingerprintGenerator`. The default is `geometric`.
 
-For development (editable install):
+### Method Reference
 
-```bash
-pip install -e .
-```
+| Method (`method` value) | Category | `method_params` | Dynamic Range / Distance Preservation | Complexity |
+|-------------------------|----------|-----------------|---------------------------------------|------------|
+| `geometric` | block-wise | `interleave` (bool) | 65,536:1 dynamic range | O(L)       |
+| `linear` | block-wise | `interleave` (bool) | S:1 dynamic range | O(L)       |
+| `log` | block-wise | `interleave` (bool) | ~4.1:1 dynamic range | O(L)       |
+| `uniform` | block-wise | `interleave` (bool) | 1:1 (mean pooling) | O(L)       |
+| `hadamard` | global | `seed` (int) | orthogonal projection | O(L log L) |
+| `random_projection` | global | `seed` (int) + `sparse` (bool) | JL distance preservation | O(L D)     |
 
-### Conda Environment
+### The `method` Parameter
 
-A full conda environment is provided for reproducibility:
+Pass `method` to the Generator constructor to select a compression strategy.
 
-```bash
-conda env create -f environment.yml
-conda activate fpembed
-```
+### Method-Specific Parameters (`method_params`)
 
-This installs all dependencies and the `fpembed` package in editable mode.
+- **Block-wise methods** (`geometric`, `linear`, `log`, `uniform`): accept `interleave` (bool, default `False`). When `True`, bits are assigned to blocks by stride (`bit[i] -> block[i % n_blocks]`) instead of contiguous partitioning, breaking hash clustering artifacts.
+- **`hadamard`**: accepts `seed` (int, default `42`). Controls the random sign flips applied before the Fast Walsh-Hadamard Transform.
+- **`random_projection`**: accepts `seed` (int, default `42`) and `sparse` (bool, default `False`). The `sparse` option uses the Achlioptas variant with approximately 2/3 zero entries for faster computation at comparable quality.
 
-## Quick Start
+Seed-based methods (`hadamard`, `random_projection`) are fully deterministic given the same seed and NumPy version. The default seed is `42`.
 
-### Single Molecule (SMILES)
+### Code Examples
 
 ```python
 from fpembed import EmbeddedFingerprintGenerator
 
-gen = EmbeddedFingerprintGenerator(
-    fp_type="ecfp", fp_size=2048, compression=16, fp_params={"radius": 2}
-)
-
-# Generate compressed fingerprint from SMILES
-emb = gen.GetFingerprintFromSmiles("CCO")
-print(emb.shape)  # (128,)
-```
-
-### Different Fingerprint Types
-
-```python
-# Atom Pair fingerprint
-gen_ap = EmbeddedFingerprintGenerator(
-    fp_type="atom_pair", fp_size=2048, compression=16,
-    fp_params={"min_distance": 1, "max_distance": 30}
-)
-
-# Topological Torsion fingerprint
-gen_tt = EmbeddedFingerprintGenerator(
-    fp_type="topological_torsion", fp_size=2048, compression=16,
-    fp_params={"torsion_atom_count": 4}
-)
-```
+# Geometric (default)
+gen = EmbeddedFingerprintGenerator(fp_type="ecfp", fp_size=2048, compression=16, fp_params={"radius": 2})
 
-### Single Molecule (SELFIES)
+# Linear weights
+gen = EmbeddedFingerprintGenerator(fp_type="ecfp", fp_size=2048, compression=16, fp_params={"radius": 2}, method="linear")
 
-```python
-emb = gen.GetFingerprintFromSelfies("[C][C][O]")
-print(emb.shape)  # (128,)
-```
+# Logarithmic weights
+gen = EmbeddedFingerprintGenerator(fp_type="ecfp", fp_size=2048, compression=16, fp_params={"radius": 2}, method="log")
 
-### Batch Processing
+# Uniform weights (mean pooling)
+gen = EmbeddedFingerprintGenerator(fp_type="ecfp", fp_size=2048, compression=16, fp_params={"radius": 2}, method="uniform")
 
-```python
-smiles_list = ["CCO", "c1ccccc1", "CC(=O)O", "invalid_smiles"]
+# Hadamard (SRHT)
+gen = EmbeddedFingerprintGenerator(fp_type="ecfp", fp_size=2048, compression=16, fp_params={"radius": 2}, method="hadamard")
 
-embeddings, invalid_indices = gen.GetFingerprintsFromSmiles(smiles_list)
-print(embeddings.shape)    # (3, 128) - 3 valid molecules
-print(invalid_indices)      # [3] - index of invalid SMILES
+# Random projection
+gen = EmbeddedFingerprintGenerator(fp_type="ecfp", fp_size=2048, compression=16, fp_params={"radius": 2}, method="random_projection")
 ```
 
-### Raw Fingerprint (No Compression)
+Bit-interleaving with a block-wise method:
 
 ```python
-gen_raw = EmbeddedFingerprintGenerator(
-    fp_type="ecfp", fp_size=2048, compression=None, fp_params={"radius": 2}
+gen = EmbeddedFingerprintGenerator(
+    fp_type="ecfp", fp_size=2048, compression=16,
+    fp_params={"radius": 2}, method="linear",
+    method_params={"interleave": True}
 )
-fp = gen_raw.GetFingerprintFromSmiles("CCO")
-print(fp.shape)  # (2048,)
 ```
 
-### Standalone Compression Function
+Standalone `compress_fingerprint` with a non-default method:
 
 ```python
-import numpy as np
 from fpembed import compress_fingerprint
+import numpy as np
 
 fp = np.random.randint(0, 2, size=2048).astype(np.float64)
-emb = compress_fingerprint(fp, size=16)
+emb = compress_fingerprint(fp, size=16, method="hadamard", method_params={"seed": 42})
 print(emb.shape)  # (1, 128)
 ```
 
-### Parameter Hashing
+### Choosing a Method
 
-```python
-from fpembed import fp_params_hash
+Block-wise methods (`geometric`, `linear`, `log`, `uniform`) are fast (O(L)) and simple - use them when speed matters or compression ratios are modest. Among these, `geometric` preserves the most dynamic range while `uniform` treats all bits equally (mean pooling). Global projection methods (`hadamard`, `random_projection`) mix information across all input bits, which helps retain more information at high compression ratios. `hadamard` is efficient (O(L log L)) and requires power-of-2 fingerprint sizes; `random_projection` offers the strongest theoretical distance-preservation guarantees (Johnson-Lindenstrauss lemma) at the cost of O(L D) complexity.
 
-h = fp_params_hash("ecfp", {"radius": 2})
-print(h)  # 16-char hex string, stable across sessions
-```
+### Performance Characteristics
 
-### Caching for Repeated Lookups
+All methods produce the same output dimensionality (D = L / compression) but differ in speed and memory:
 
-```python
-gen = EmbeddedFingerprintGenerator(
-    fp_type="ecfp", fp_size=2048, compression=16,
-    fp_params={"radius": 2}, cache_size=1024
-)
+| Method | Speed                                                                              | Precomputed Memory                   | Best For |
+|--------|------------------------------------------------------------------------------------|--------------------------------------|----------|
+| Block-wise (all four) | Fastest - single vectorized einsum, O(L)                                           | Negligible (C-length weight vector)  | Default choice; large batches |
+| Hadamard (SRHT) | Fast - vectorized FWHT (NumPy reshape/broadcast, no Python-level loop), O(L log L) | L-length sign vector (~16 KB)        | Large batches at high compression ratios |
+| Random projection | Fast - BLAS matmul, O(L D)                                                         | DxL matrix (~2 MB for L=2048, D=128) | Best theoretical guarantees (JL lemma) |
 
-# First call computes and caches
-emb = gen.GetFingerprintFromSmiles("CCO")
+Block-wise methods remain the fastest choice for large batches. Hadamard's FWHT is vectorized across the whole batch and works much faster now. Random projection's memory cost grows quadratically with fingerprint size.
 
-# Second call returns cached result
-emb2 = gen.GetFingerprintFromSmiles("CCO")
+## Project Structure
 
-print(gen.cache_info())  # CacheInfo(hits=1, misses=1, maxsize=1024, currsize=1)
-gen.clear_cache()
+```
+fpembed/
+├── src/fpembed/                # pip-distributable package
+│   ├── __init__.py
+│   ├── generator.py            # EmbeddedFingerprintGenerator
+│   ├── compression.py          # compress_fingerprint (orchestrator)
+│   ├── compression_blockwise.py # block-wise weight schemes
+│   ├── compression_projection.py # Hadamard SRHT + random projection
+│   ├── smiles_utils.py         # parse_smiles, canonicalize_smiles
+│   ├── hashing.py              # fp_params_hash
+│   └── py.typed                # PEP 561 marker
+├── examples/
+│   ├── quickstart.ipynb        # usage notebook
+│   ├── datasets/               # molecular datasets (RedDB, NFA, QM9)
+│   └── nicegui_app/            # NiceGUI demo application
+├── pyproject.toml
+├── environment.yml
+└── README.md
 ```
 
 ## Running the Demo App