- Introduction
- Why Embedded Fingerprints
- Install
- Quick Start
- Agent Skill
- Fingerprint Types at a Glance
- Quickstart Notebook
- Original Concept (eMFP)
- License
- Legal & Trademark Notice
- Commercial & Research Services
- AI Disclosure
- Support
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
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.
git clone https://github.com/Sciencealone/fpembed.git
cd fpembed
python -m pip install -e .python -m pip install fpembedCount 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 create -n fpembed python=3.12
conda activate fpembed
python -m pip install fpembedFPembed requires Python 3.10 or newer, below 3.14. Runtime dependencies are NumPy, RDKit, scikit-fingerprints, and SELFIES.
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 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,)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.
A JSON manifest describes every configuration.
manifest = gen.representation_manifest()The documentation covers the Quick Start and the API Reference.
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.pyturns SMILES, SELFIES, or RDKit Mols into dense embeddings, batch or streaming, with an invalid-row audit.compress.pycompresses an external embedding matrix or a raw fingerprint array.qsar_engine.pyfits and predicts regression or classification models with scikit-learn.diversity.pypicks 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.
| 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.
The quickstart notebook is at examples/quickstart.ipynb.
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
This project is licensed under the terms of the MIT open source license. See LICENSE for the full terms.
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.
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 usage during project development is declared in aidecl.yaml following the AI Declaration Format.
The Maintainer ships FPembed as-is and may update it over time. Open an issue if you have questions.