API Reference¶

molfp is organized by activity type in a typical cheminformatics workflow. All functions are importable directly from molfp.

import molfp

Workflow¶

A cheminformatics project typically starts with computing molecular fingerprints, then moves through understanding what the bits mean, validating data quality, analyzing structure-activity relationships, and finally preparing features for machine learning. The diagram below shows how molfp's modules connect across these stages.

Each module handles one step — from Fingerprints through Explain & Annotate, Collisions, Bioactivity, Isomers, Fusion, and Graph representations, all the way to sklearn transformers ready for pipelines. Standardize supports the workflow at any stage. For visualization, see molviewer.

graph TD
    FP["<b>Fingerprints</b>"]
    EA["<b>Explain & Annotate</b>"]
    CO["<b>Collisions</b>"]
    SC["<b>Scaffold</b>"]
    IN["<b>Interpret</b>"]
    SD["<b>Similarity & Distance</b>"]
    BA["<b>Bioactivity</b>"]
    AC["<b>Activity Cliffs</b>"]
    IS["<b>Isomers</b>"]
    FU["<b>Fusion</b>"]
    GR["<b>Graph</b>"]
    FS["<b>Feature Selection</b>"]
    SK["<b>sklearn</b>"]

    FP --> EA & CO & SC
    EA --> IN
    CO --> SD
    IN --> BA
    SD --> AC
    FP --> IS
    BA & AC --> FU
    FU & SC --> GR & FS & SK

    style FP fill:#2563eb,color:#fff,stroke:#1d4ed8
    style EA fill:#3b82f6,color:#fff,stroke:#2563eb
    style CO fill:#3b82f6,color:#fff,stroke:#2563eb
    style SC fill:#3b82f6,color:#fff,stroke:#2563eb
    style IN fill:#3b82f6,color:#fff,stroke:#2563eb
    style SD fill:#3b82f6,color:#fff,stroke:#2563eb
    style BA fill:#0d9488,color:#fff,stroke:#0f766e
    style AC fill:#0d9488,color:#fff,stroke:#0f766e
    style IS fill:#0d9488,color:#fff,stroke:#0f766e
    style FU fill:#0d9488,color:#fff,stroke:#0f766e
    style GR fill:#0d9488,color:#fff,stroke:#0f766e
    style FS fill:#0d9488,color:#fff,stroke:#0f766e
    style SK fill:#0d9488,color:#fff,stroke:#0f766e

Browse the modules below for function details and examples.

Compute¶

Fingerprints ¶

Compute 35 molecular fingerprint types (18 2D + 9 3D + 8 graph). Every function accepts a single SMILES, a list, a pandas Series, or a DataFrame column.

fp = molfp.maccs("CCO")
fps = molfp.ecfp4(["CCO", "c1ccccc1"], collision_free=True)

Understand¶

Explain & Annotate ¶

Bit-level explainability — which atoms set which bits, and what each bit means chemically.

molfp.explain("CCO", "ecfp4")        # atom → bit mapping
molfp.annotate("maccs", 162)          # {"name": "Aromatic ring", ...}

Interpret ¶

SHAP-based feature importance with chemical meaning. Trains a classifier, computes SHAP values, and maps top bits back to substructures.

result = molfp.interpret(smiles, activities, fp_type="ecfp4", collision_aware=True)

Validate¶

Collisions ¶

Detect, remove, or avoid hash collisions in hashed fingerprints. Collision-free mode uses multi-hash Bloom filters.

molfp.detect_collisions("c1ccccc1", "ecfp4", n_bits=1024)
fps = molfp.ecfp4(smiles, collision_free=True)

Similarity & Distance ¶

Five vectorized pairwise metrics (Tanimoto, Dice, Cosine, Sokal-Michener, Russel-Rao) and similarity profiling.

molfp.tanimoto(fp_a, fp_b)
dist_matrix = molfp.pairwise(fps, metric="tanimoto")

Analyze¶

Bioactivity ¶

Classify molecules by activity threshold and identify enriched/depleted bits that distinguish active from inactive.

result = molfp.classify(smiles, activities, "ecfp4", threshold=6.0)
molfp.enriched_bits(smiles, activities, "maccs")

Activity Cliffs ¶

Find structurally similar molecule pairs with large activity differences — the hard cases for QSAR.

cliffs = molfp.activity_cliffs(smiles, activities, "ecfp4", sim_threshold=0.8)

Isomers ¶

Test whether fingerprints can distinguish structural isomers. Find identical fingerprint vectors across different molecules.

molfp.discriminative_power(smiles)
molfp.find_identical_fps(smiles, "ecfp4")

Combine¶

Fusion ¶

Build consensus fingerprints from multiple FP types. Selects the most informative bits across fingerprint families.

result = molfp.fuse(smiles, activities, fp_types=["maccs", "ecfp4", "pubchem"])

Scaffold ¶

Extract Murcko/generic scaffolds with chemical names from ~130 common ring systems. Scaffold-aware splitting prevents data leakage.

molfp.scaffold("CC(=O)Oc1ccccc1C(=O)O")  # {"name": "Benzene", ...}
result = molfp.scaffold_split(smiles, test_size=0.2)

Represent¶

Graph ¶

Convert molecules to atom/bond feature matrices for GNNs. Four graph types (standard, distance, line, fragment) with optional enriched features. Includes PyG and DGL converters.

g = molfp.mol_graph("c1ccccc1", type="standard", enriched=True)
X = molfp.graph_vectors(smiles, type="standard")

Feature Selection ¶

Remove constant features and select top-k by mutual information — works with any fingerprint or graph vector output.

result = molfp.select_features(X, y, k=500)
result = molfp.remove_low_variance(X, threshold=0.01)

Model¶

sklearn ¶

22 pipeline-ready transformers (one per FP type) plus GraphTransformer. Drop into any scikit-learn pipeline.

from sklearn.pipeline import make_pipeline
from sklearn.ensemble import RandomForestClassifier
pipe = make_pipeline(molfp.ECFPTransformer(), RandomForestClassifier())

Utilities¶

Standardize ¶

SMILES cleaning pipeline — desalt, neutralize, canonicalize tautomers, deduplicate.

clean = molfp.preprocess(smiles)  # full pipeline
molfp.standardize_smiles("CC(=O)Oc1ccccc1C(=O)[O-].[Na+]")