Skip to content
SciencealonePublic

Repository files navigation

FPembed - Generalized Molecular Fingerprint Embeddings

PyPI version DOI Documentation

Contents

Introduction

Molecular fingerprints are wide and mostly zeros, and a model pays for every column. FPembed compresses a standard fingerprint into a short dense vector with a fixed, data-independent map, so a QSAR pipeline keeps its fingerprint definition explicit while the model reads a fraction of the inputs. It returns a plain NumPy array, which fits scikit-learn or any model that takes a 2-D float matrix.

Input is SMILES, SELFIES, or RDKit Mol. Fifteen fingerprint types are available, nine of them also in count mode, and embeddings produced by another model can be compressed with the same methods. The full technical reference is in the documentation.

graph LR
    A[SMILES / SELFIES / Mol] --> B[Fingerprint generation] --> C[Binary or count vector]
    C --> D[Compression, fixed map] --> E[float64 / float32 / uint16, L / C values]
    F[Embeddings from another model] --> D
Loading

Why Embedded Fingerprints

A 2048-bit fingerprint hands a model 2048 input columns, and most of them are zero. Compression leaves the fingerprint at full width and shortens what the model reads: at a factor of 16, those 2048 bits become 128 dense values. The saving in columns and stored bytes is exact; the effect on training time, memory, and sample efficiency depends on the model and the data.

Formally, a fingerprint of length L becomes an embedding of length D = L / C, with C the compression factor. 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()

The documentation covers the Quick Start and the API Reference.

Agent Skill

FPembed ships an agent skill at .agents/skills/fpembed/ with SKILL.md, four scripts, reference documents, and a demo fixture. The skill is named fpembed as its machine identifier and uses FPembed as the display name. Agents load it when predicting a molecular property or QSAR from SMILES, SELFIES, or RDKit Mols, when a dataset is large enough that full-length fingerprints are too slow or memory-heavy to model directly, or when compressing external embeddings and exploring chemical space.

The four scripts cover the main workflows:

  • featurize.py turns SMILES, SELFIES, or RDKit Mols into dense embeddings, batch or streaming, with an invalid-row audit.
  • compress.py compresses an external embedding matrix or a raw fingerprint array.
  • qsar_engine.py fits and predicts regression or classification models with scikit-learn.
  • diversity.py picks max-min exemplars, scores outliers, or queries nearest neighbors.

Input can be SMILES or SELFIES from a CSV or .smi file, or RDKit Mols from a .sdf or .mol file. The .sdf and .mol suffixes imply Mol input.

Two dependency tiers apply. Tier 1 needs FPembed and NumPy and covers featurization, compression, and diversity. Tier 2 adds scikit-learn and covers QSAR. Every script offers --doctor to report the installed FPembed version, the minimum of 0.3.0, and the available tier.

Platform Auto-discovered skills directory
OpenCode .opencode/skills/ and .agents/skills/
Claude Code .claude/skills/
Cursor .agents/skills/ and .cursor/skills/
GitHub Copilot .github/skills/, .claude/skills/, and .agents/skills/
Antigravity .agents/skills/
Codex CLI .agents/skills/
Gemini CLI .gemini/skills/ and .agents/skills/

Install the skill with npx skills add Sciencealone/fpembed --skill fpembed, or use gh skill install Sciencealone/fpembed fpembed --agent <agent> --scope user --allow-hidden-dirs or gemini skills install https://github.com/Sciencealone/fpembed --scope workspace as alternatives. If you already have a repository clone, copy .agents/skills/fpembed/ into a discovered skills directory as a fallback. pip install fpembed installs the library only, not the skill.

The agent documentation covers the commands, input formats, discovery paths, and link attribution.

Fingerprint Types at a Glance

Type fp_type Count mode Native width
Extended Connectivity (Morgan) ecfp Yes fp_size
Atom Pair atom_pair Yes fp_size
Topological Torsion topological_torsion Yes fp_size
RDKit rdkit Yes fp_size
Layered layered No fp_size
Pattern pattern No fp_size
Avalon avalon Yes fp_size
SECFP secfp No fp_size
MHFP mhfp Yes fp_size
MAP4 map Yes fp_size
Lingo lingo Yes fp_size
Pharmacophore (folded) pharmacophore Yes fp_size
PubChem pubchem No 881, pad to 1024
Laggner laggner No 307, pad to 512
ERG (bit) erg No 315, pad to 512

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 documentation lists every type parameter, default, count rule, and fixed-width padding cost on its Fingerprint Types page.

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 FPembed source code is licensed under MIT. That licence covers the code and does not include any right to use the FPembed name or logo.

"FPembed" is a trademark of the project author Mikhail Markovskii (@Sciencealone). A trademark application for the name has been filed.

Accurate references to FPembed are permitted: citing the project, stating that a tool uses or is compatible with FPembed, and redistributing an unmodified copy under its name. Uses that suggest the project endorses, sponsors, or operates a product or service need prior written permission from the trademark owner. Permission requests go to contact@fpembed.com.

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.

Releases

Used by

Contributors

Languages