FPembed - Generalized Molecular Fingerprint Embeddings

Contents

• Introduction
• Why Embedded Fingerprints
• Install
• Quick Start
• Fingerprint Types at a Glance
• Quickstart Notebook
• Original Concept (eMFP)
• License
• Legal & Trademark Notice
• Commercial & Research Services
• AI Disclosure
• Support

Introduction

FPembed turns standard molecular fingerprints into compact, dense vectors for machine learning. It accepts SMILES, SELFIES, and RDKit Mol input, supports fifteen fingerprint types, nine of which also support count mode, and keeps the fingerprint, compression method, and output dtype explicit. It returns a plain NumPy array, which fits a scikit-learn pipeline or any model that accepts a 2-D float matrix.

The full technical reference is in USER_MANUAL.md.

graph LR
    A[SMILES / SELFIES / Mol] --> B[EmbeddedFingerprintGenerator] --> C[Binary or count vector]
    C --> D[Compression] --> E[float64 / float32 / uint16 embedding]
    F[External embeddings] --> G[PrecomputedEmbeddingCompressor] --> D

Why Embedded Fingerprints

Compression reduces a fingerprint of length L to an embedding of length D = L / C, where C is the compression factor. At C=16, a 2048-bit fingerprint becomes 128 features, so downstream models see about 16 times fewer inputs.

The guaranteed saving is the feature count and the stored byte count. Training speed, inference speed, memory use, and sample efficiency often improve as a result. The size of that effect depends on the model, hardware, and dataset.

FPembed makes the choice of fingerprint and compression method explicit. It offers six methods: four block-wise schemes and two global projections. The default is geometric for binary input and uniform for count input.

Three entry points cover the common paths: EmbeddedFingerprintGenerator for molecules, PrecomputedEmbeddingCompressor for embeddings from another model, and compress_fingerprint() for arrays you compress yourself.

Install

From source

git clone https://github.com/Sciencealone/fpembed.git
cd fpembed
python -m pip install -e .

From PyPI

python -m pip install fpembed

Count fingerprints, fixed-width fingerprint types, and precomputed embeddings require FPembed 0.3.0 or newer. Use the source install if the PyPI release is older.

Conda

conda create -n fpembed python=3.12
conda activate fpembed
python -m pip install fpembed

Requirements

FPembed requires Python 3.10 or newer, below 3.14. Runtime dependencies are NumPy, RDKit, scikit-fingerprints, and SELFIES.

Quick Start

Binary fingerprint

from fpembed import EmbeddedFingerprintGenerator

gen = EmbeddedFingerprintGenerator(
    fp_type="ecfp",        # ECFP (Morgan) fingerprint
    fp_size=2048,          # fingerprint length
    compression=16,        # 2048 / 16 = 128 output features
    fp_params={"radius": 2},
)
embedding = gen.GetFingerprintFromSmiles("CCO")
print(embedding.shape)  # (128,)

Count fingerprint

# Count fingerprints use the same generator.
count_gen = EmbeddedFingerprintGenerator(
    fp_type="ecfp", fp_size=2048, compression=16,
    fp_params={"radius": 2},
    count=True, count_transform="log1p",
)
counts = count_gen.GetFingerprintFromSmiles("CCO")
print(counts.shape)  # (128,)

Batch input and label alignment

X, invalid = gen.GetFingerprintsFromSmiles(smiles)
y = [label for i, label in enumerate(labels) if i not in set(invalid)]
model.fit(X, y)

X is a 2-D float array, and the generator drops invalid SMILES, so filter labels with the same indices. The iterator methods stream one molecule at a time, for inputs that do not fit in memory.

Representation manifest

A JSON manifest describes every configuration.

manifest = gen.representation_manifest()

See the manual's Quick Start and API Reference.

Fingerprint Types at a Glance

Most types produce exactly fp_size values. PubChem and Laggner have a fixed native width and require a padded fp_size that is a power of two and at least the native width. ERG's native width depends on max_path and is padded the same way.

The manual lists every type parameter, default, count rule, and fixed-width padding cost in Fingerprint Types.

Quickstart Notebook

The quickstart notebook is at examples/quickstart.ipynb.

Original Concept (eMFP)

The weighted binary masking approach was introduced for Morgan fingerprints in the eMFP paper:

Nuñez-Andrade, E. A., Vidal-Daza, I., Gomez-Bombarelli, R., Ryan, J. W., and Martin-Martinez, F. J. (2025). Embedded Morgan Fingerprints for more efficient molecular property predictions with machine learning. ChemRxiv preprint. https://doi.org/10.26434/chemrxiv-2025-6hfp8

Original concept repository: MMLabCodes/eMFP

License

This project is licensed under the terms of the MIT open source license. See LICENSE for the full terms.

Legal & Trademark Notice

The name "FPembed", its branding, and identifiers are the intellectual property of the project author (@Sciencealone).

• Commercial Branding: The unauthorized use of the name "FPembed" to brand, market, or promote commercial software, corporate AI engines, or proprietary services within the fields of bioinformatics, chemoinformatics, and AI drug discovery is strictly prohibited.
• Community Protection: This notice prevents public confusion and protects the open-source community from misleading corporate misrepresentations. For licensing queries regarding the project name, open an issue or contact the author directly.

Commercial & Research Services

The project Maintainer provides project onboarding, corporate deployments, compute scaling on HPC, Databricks, and Ray, and custom model fine-tuning for pharma R&D and research grants (Horizon Europe / Art. 60 LOSU / AEI). The Maintainer also provides technical support and handles related contract work.

View Full Service Offerings & Contact Details

AI Disclosure

AI usage during project development is declared in aidecl.yaml following the AI Declaration Format.

Support

The Maintainer ships FPembed as-is and may update it over time. Open an issue if you have questions.