DOCSEARCHbyAlgolia
Submit Docs

Molfeat: Molecular Featurizers Hub

repository·main·Indexed 42 days ago

https://github.com/datamol-io/molfeat

A centralized hub for molecular featurizers that unifies pre-trained embeddings and hand-crafted descriptors into a high-performance API. Molfeat supports parallelized featurization workflows via MoleculeTransformer, provides access to foundation models and HuggingFace Transformers, and features an extensible plugin system for adding custom calculators and transformers.

Tokens
22.3K
Snippets
59
Records
85
Agent score
53%

What's inside Molfeat

  1. Understand the Molfeat module structure

    main

    Molfeat is organized into three primary modules that represent different levels of the featurization abstraction:

    • molfeat.store: The model store used to load, list, and register all available featurizers.
    • molfeat.calc: Contains calculators, which are callables designed to featurize a single molecule.
    • molfeat.trans: Contains transformers, which are scikit-learn compatible classes that wrap a calculator into a featurization pipeline (supporting batches, parallelism, and caching).

  2. How calculators and featurizers differ in Molfeat

    main

    It is important to distinguish between these two core abstractions:

    • Calculator: Operates on individual molecules. It defines the specific logic for transforming one molecule into a numerical representation.
    • Featurizer: Operates on batches of molecules. Featurizers leverage batch processing (especially for deep learning), parallelism, and caching to optimize computation. A featurizer often uses a calculator internally to process molecules and then aggregates the results.

  3. Extend molfeat with plugins

    main

    Plugins allow you to add new featurizers to the molfeat ecosystem using a plug-and-play architecture. This enables extending the core functionality without modifying the main package.

    Existing community plugins include:

    • molfeat-padel: Adds support for PaDeL descriptors (the official exemplary plugin).
    • molfeat-hype: Investigates performance of embeddings from various LLMs for molecular modeling.

    To create your own plugin, refer to the Extending molfeat guide.

  4. Naming conventions for molfeat plugins

    main

    When creating a plugin, follow these naming conventions to ensure compatibility with PyPI/Conda and Python packaging rules:

    1. Distribution Name (PyPI/Conda): Use molfeat-<myplugin> (with dashes).
    2. Python Package Name: Use molfeat_<myplugin> (with underscores), as Python package names cannot contain dashes.

    Example Structure:

        molfeat-myplugin/           # Distribution folder
       molfeat_myplugin/        # Python package
          __init__.py
    molfeat-myplugin/
   molfeat_myplugin/
      __init__.py

  5. When to create a molfeat plugin

    main

    Deciding whether to implement a new featurizer as a core part of molfeat or as a separate plugin depends on the nature of the featurizer.

    Use a plugin if:

    • The featurizer cannot be loaded by current molfeat classes.
    • It requires additional or difficult-to-install dependencies.
    • You want to introduce a new class of featurizers to the community.
    • You want to extend molfeat for private or internal use.

    Do NOT use a plugin if:

    • The featurizer can already be loaded through existing classes.
    • It requires no additional dependencies.
    • You can demonstrate through benchmarks that the featurizer is performant enough to be part of the core package.

  6. Important behavior changes in Molfeat 1.x

    main

    Users migrating from 0.x should be aware of the following changes in observable behavior:

    • Model Discovery: Creating a ModelStore or a Hugging Face transformer no longer automatically fetches the remote model index. The index is only loaded during the first operation that requires discovery.
    • InChI Decoding: InChI decoding now returns a SMILES string by converting the molecule returned by Datamol.
    • Pharmacophore3D: Pharmacophore3D(..., raw=True) now returns a sorted one-dimensional integer array (previously a zero-dimensional object array containing a Python set).
    • Pooling Masks: Pooling masks (max, mean, sum) now consistently use true values for elements to be included.
    • Scikit-learn: The force_all_finite keyword has been replaced by ensure_all_finite.
    • RDKit Delegation: General RDKit fingerprint folding and conformer alignment now delegate to Datamol. While Molfeat compatibility functions remain available with a deprecation warning, new code should call Datamol directly.

  7. How Molfeat plugins work

    main

    Molfeat uses a plugin system to allow for easy extension without bloating the core package. This allows developers to create and distribute new featurizers independently.

    Key points:

    • Plugins are plug-and-play components.
    • Installation of a plugin is plugin-dependent; you must follow the specific documentation for the plugin you are installing.
    • The core package remains lightweight because most specialized functionality is moved to plugins or optional dependencies.

  8. Quickstart: Featurize molecules with Molfeat

    main

    This example demonstrates the standard workflow: loading data, using a calculator for a single molecule, using a MoleculeTransformer for parallelized batch processing, and saving/loading the transformer state.

    import datamol as dm
from molfeat.calc import FPCalculator
from molfeat.trans import MoleculeTransformer
from molfeat.store.modelstore import ModelStore

# Load some dummy data
data = dm.data.freesolv().sample(100).smiles.values

# Featurize a single molecule using a calculator
calc = FPCalculator("ecfp")
calc(data[0])

# Define a parallelized featurization pipeline using a transformer
mol_transf = MoleculeTransformer(calc, n_jobs=-1)
mol_transf(data)

# Easily save and load featurizers
mol_transf.to_state_yaml_file("state_dict.yml")
mol_transf = MoleculeTransformer.from_state_yaml_yaml_file("state_dict.yml")
mol_transf(data)

# List all available featurizers via the ModelStore
store = ModelStore()
print(store.available_models)

# Find a specific featurizer and view its usage instructions
model_card = store.search(name="ChemBERTa-77M-MLM")[0]
model_card.usage()
    import datamol as dm
from molfeat.calc import FPCalculator
from molfeat.trans import MoleculeTransformer
from molfeat.store.modelstore import ModelStore

# Load some dummy data
data = dm.data.freesolv().sample(100).smiles.values

# Featurize a single molecule
calc = FPCalculator("ecfp")
calc(data[0])

# Define a parallelized featurization pipeline
mol_transf = MoleculeTransformer(calc, n_jobs=-1)
mol_transf(data)

# Easily save and load featurizers
mol_transf.to_state_yaml_file("state_dict.yml")
mol_transf = MoleculeTransformer.from_state_yaml_file("state_dict.yml")
mol_transf(data)

# List all available featurizers
store = ModelStore()
store.available_models

# Find a featurizer and learn how to use it
model_card = store.search(name="ChemBERTa-77M-MLM")[0]
model_card.usage()

  9. Explore molfeat community tutorials

    main

    The community provides several step-by-step tutorials to help you get started with molfeat and related workflows:

    • Practical cheminformatics: Demonstrates how to train a QSAR model using only 8 lines of code, utilizing the datamol.io ecosystem.
    • PyG GNN on Graphcore IPUs: Adapts PyTorch Geometric (PyG) GNN training to leverage Graphcore IPUs.
    • Transformer on Graphcore IPUs: Adapts pre-trained transformer fine-tuning to leverage Graphcore IPUs.

  10. Install Molfeat

    main

    You can install Molfeat using uv, pip, or conda.

    Requirements:

    • Python 3.11 or newer
    • RDKit 2024.09 or newer
    • PyTorch 2.5 or newer (Note: macOS Intel users will use the 2.2.x series).

    Installation commands:

    # Using uv
uv add molfeat

# Using pip
python -m pip install molfeat

# Using conda-forge
mamba install -c conda-forge molfeat
    uv add molfeat

  11. Use HuggingFace Transformers pretrained models with molfeat

    main
    The molfeat.trans.pretrained.hf_transformers module provides access to pretrained transformer models from the HuggingFace ecosystem for molecular featurization. This allows users to leverage state-of-the-art transformer architectures (like ChemBERTa or others available on the HuggingFace Hub) to generate molecular embeddings or features.

  12. Recommended folder structure for molfeat plugins

    main

    While the overall structure is flexible, following these conventions helps organize your plugin components:

    • tests/: Directory for your test suite.
    • molfeat_<myplugin/: The top-level Python package.
      • calc/: Contains SerializableCalculator implementations.
      • trans/: Contains MoleculeTransformer implementations.
      • data/: Contains custom data formats (e.g., MyData).
    • pyproject.toml: Metadata, installation requirements, and entry points.
    • LICENSE, README.md, MANIFEST.in: Standard project files.
    molfeat-myplugin/
   tests/
   molfeat_myplugin/
      __init__.py
      calc/
         __init__.py
         myplugin.py      # contains my plugin SerializableCalculator
      trans/
         __init__.py
         myplugin.py      # contains my plugin MoleculeTransformer
      data/
         __init__.py    # contains code-specific MyData data format
   setup.py             # optional
   LICENSE
   MANIFEST.in
   README.md
   pyproject.toml       # plugin metadata, requirements, entry points
...