python-chebifier

An AI ensemble model for predicting chemical classes in the ChEBI ontology. It integrates deep learning models, rule-based models and generative AI-based models.

A web application for Chebifier is available at https://chebifier.hastingslab.org/.

Installation

You can get the package from PyPI:

pip install chebifier

or get the latest development version from GitHub:

# Clone the repository
git clone https://github.com/yourusername/python-chebifier.git
cd python-chebifier

# Install the package
pip install -e .

By default, the models of the ensemble are not installed. You can install them with the [models] extra:

pip install chebifier[models]

The Graph Neural Networks depend on torch_geometric and torch_scatter which you need to install separately (depending on your CUDA version). E.g.

pip install torch==2.12.0 torch_scatter torch_geometric -f https://data.pyg.org/whl/torch-2.12.0+cpu.html

Usage

Command Line Interface

The package provides a command-line interface (CLI) for making predictions using an ensemble model.

The ensemble configuration is given by a configuration file (by default, this is chebifier/ensemble.yml). If you want to change which models are included in the ensemble or how they are weighted, you can create your own configuration file.

Trained deep learning models are automatically downloaded from Hugging Face. To access a model from Hugging face, add the load_model key in your configuration file. For example:

my_electra:
  type: electra
  load_model: "electra_chebi50-3star_v244"

Available model weights:

• resgated-aug_chebi50-3star_v244
• gat-aug_chebi50_v244
• electra_chebi50-3star_v244
• gat_chebi50_v244
• electra_chebi50_v241
• resgated_chebi50_v241
• c3p_with_weights

You can also supply your own model checkpoints (see configs/example_config.yml for an example).

# Make predictions
python -m chebifier predict --smiles "CC(=O)OC1=CC=CC=C1C(=O)O" --smiles "C1=CC=C(C=C1)C(=O)O"

# Make predictions using SMILES from a file
python -m chebifier predict --smiles-file smiles.txt

# Make predictions using a configuration file
python -m chebifier predict --ensemble-config configs/my_config.yml --smiles-file smiles.txt

# Get all available options
python -m chebifier predict --help

Python API

You can use the package programmatically as well:

from chebifier import BaseEnsemble

# Instantiate ensemble model. Optionally, you can pass
# a path to a configuration, like 'configs/example_config.yml'
ensemble = BaseEnsemble()

# Make predictions
smiles_list = ["CC(=O)OC1=CC=CC=C1C(=O)O", "C1=CC=C(C=C1)C(=O)O"]
predictions = ensemble.predict_smiles_list(smiles_list)

# Print results
for smiles, prediction in zip(smiles_list, predictions):
    print(f"SMILES: {smiles}")
    if prediction:
        print(f"Predicted classes: {prediction}")
    else:
        print("No predictions")

The models

Currently, the following models are supported:

In addition, Chebifier also includes a ChEBI lookup that automatically retrieves the ChEBI superclasses for a class matched by a SMILES string. This is not activated by default, but can be included by adding

chebi_lookup:
    type: chebi_lookup
    model_weight: 10 # optional

to your configuration file.

The ensemble

For an extended description of the ensemble, see Flügel, Simon, et al., 2025: Chebifier 2: An Ensemble for Chemistry.

Given a sample (i.e., a SMILES string) and models $m_1, m_2, \ldots, m_n$, the ensemble works as follows:

1. Get predictions from each model $m_i$ for the sample.
2. For each class $c$, aggregate predictions $p_c^{m_i}$ from all models that made a prediction for that class. The aggregation happens separately for all positive predictions (i.e., $p_c^{m_i} \geq 0.5$) and all negative predictions ($p_c^{m_i} < 0.5$). If the aggregated value is larger for the positive predictions than for the negative predictions, the ensemble makes a positive prediction for class $c$:

Here, confidence is the model's (self-reported) confidence in its prediction, calculated as $ \text{confidence}_c^{m_i} = 2|p_c^{m_i} - 0.5| $ For example, if a model makes a positive prediction with $p_c^{m_i} = 0.55$, the confidence is $2|0.55 - 0.5| = 0.1$. One could say that the model is not very confident in its prediction and very close to switching to a negative prediction. If another model is very sure about its negative prediction with $p_c^{m_j} = 0.1$, the confidence is $2|0.1 - 0.5| = 0.8$. Therefore, if in doubt, we are more confident in the negative prediction.

Confidence can be disabled by the use_confidence parameter of the predict method (default: True).

Themodel_weight can be set for each model in the configuration file (default: 1). This is used to favor a certain model independently of a given class. Trust is based on the model's performance on a validation set. After training, we evaluate the Machine Learning models on a validation set for each class. If the ensemble_type is set to wmv-f1, the trust is calculated as F1-score $^{6.25}$. If the ensemble_type is set to mv (the default), the trust is set to 1 for all models.

Inconsistency resolution

After a decision has been made for each class independently, the consistency of the predictions with regard to the ChEBI hierarchy and disjointness axioms is checked. This is done in 3 steps:

• (1) First, the hierarchy is corrected. For each pair of classes $A$ and $B$ where $A$ is a subclass of $B$ (following the is-a relation in ChEBI), we set the ensemble prediction of $A$ to $0$ if the absolute value of $B$'s score is large than that of $A$. For example, if $A$ has a net score of $3$ and $B$ has a net score of $-4$, the ensemble will set $A$ to $0$ (i.e., predict neither $A$ nor $B$).
• (2) Next, we check for disjointness. This is not specified directly in ChEBI, but in an additional ChEBI module (chebi-disjoints.owl). We have extracted these disjointness axioms into a CSV file and added some more disjointness axioms ourselves (see data>disjoint_chebi.csv and data>disjoint_additional.csv). If two classes $A$ and $B$ are disjoint and we predict both, we select one with the higher class score and set the other to 0.
• (3) Since the second step might have introduced new inconsistencies into the hierarchy, we repeat the first step, but with a small change. For a pair of classes $A \subseteq B$ with predictions $1$ and $0$, instead of setting $B$ to $1$, we now set $A$ to $0$. This has the advantage that we cannot introduce new disjointness-inconsistencies and don't have to repeat step 2.