Mother-ML - A ML framework that takes care.

Mother is a machine-learning framework for predicting properties from mainly chemical molecules. The major features are:

• 🔬 SMILES preprocessing
• 💾 Generating of feature vectors from molecules
• 📈 Grouping and cross-validation, based on chemical similarity
• 💻 Model Training: Standard models like catboost, lasso, or random forest, and custom models (e.g.: TabPFN), and feature selection methods
• 🚴 Training, cross-validation, and hyperparameter optimization of machine-learning models
• 🌀 Handling Gene expression data from transcriptomics experiments including different normalisation techniques
• ✨ Explainability analysis with SHAP (Currently not supported, will be added in a later release)
• 🚙 Generative chemistry (Currently not supported)

Mother provides methods for each of these steps in the form of sklearn transformer objects. By that, all methods are designed to be easily accessible and usable in a modular way. The methods can be combined to ML workflows with sklearn pipelines, column transformers, and feature unions.

All methods can be used as sklearn transformer or estimator. Combination with other methods, or own methods and models (e.g. using mother preprocessing with other model) is therefore straightforward. To be as compatible as possible, every transformer can be constructed using a dictionary containing the required parameters. However, to provide some convenience to the users, a settings class MotherSettings is provided. This class can be used to store all relevant settings for your ML project.

Why Mother?

Mother keeps the parts of a molecular ML workflow connected without requiring you to leave the scikit-learn ecosystem.

• Tune an entire workflow from one place. Mother model wrappers define their own Optuna search spaces, and PipelineWithHyperparameterRooting, ColumnTransformerWithHyperparameterRooting, and FeatureUnionWithHyperparameterRooting collect them across nested steps using familiar step__parameter names. You can therefore tune preprocessing, feature selection, and the final estimator together while retaining scikit-learn composition.
• Exchange compatible transformers and estimators. Preprocessing, molecular feature generation, feature selection, cross-validation grouping, and models follow scikit-learn's estimator and transformer interfaces. Mother components work in Pipeline, ColumnTransformer, and FeatureUnion, and can be combined with your own scikit-learn components.
• Use consistent, analysis-ready outputs. Components preserve pandas-friendly tabular data where appropriate. predict_uncertainty(...) exposes a common prediction and uncertainty schema across model backends, while mother_cv(...) returns fold-level predictions together with evaluation metadata for straightforward comparison and downstream analysis.
• Evaluate chemical models more realistically. Chemistry-aware grouping, including Tanimoto-similarity groups, makes it practical to use group-aware splits that better test generalisation to dissimilar compounds.
• Choose models without rewriting the workflow. The model registry discovers integrated model wrappers and presents a common interface for CatBoost, random forest, lasso, TabPFN when installed, and compatible custom models.
• Make workflows reproducible and configurable. MotherSettings keeps input, preprocessing, feature generation, cross-validation, model, and tuning configuration in one validated object that can be loaded from or written to YAML.

Usage

A basic example can be found in the example regression notebook. Other examples are in the examples folder.

🔬 SMILES preprocessing and mol-object generation

SMILES preprocessing is done with the StandardizerTransformer class. The class is used to preprocess SMILES strings to construct a pipeline from SMILES to rdkit mol-objects with:

import pandas as pd
from sklearn import pipeline as sklearn_pipeline
from mother.preprocessing.core import SmilesToMolTransformer, StandardizerTransformer

structure_data = pd.DataFrame(
    {
        "smiles": [
            "CCO",
            "CCN",
            "c1ccccc1",
            "CC(=O)O",
            "CC(C)O",
            "CCCC",
        ]
    }
)

preprocessor: sklearn_pipeline.Pipeline = sklearn_pipeline.Pipeline(
    [
        (
            "smiles_standardizer",
            StandardizerTransformer(
                flags=["STANDARDIZE", "DESALT", "NEUTRALIZE"],
                smiles_col="smiles",
            ),
        ),
        ("smiles_to_mol", SmilesToMolTransformer(molecule_col="Molecule")),
        # Add other column transformations here if needed
    ],
    memory=None,
).set_output(transform="pandas")

mol_data: pd.DataFrame = preprocessor.fit_transform(structure_data)

Customize by changing the flags attribute.

💾 Feature Generation

Mother provides three types of feature generators: MaccsFingerprints, MorganFingerprints, and ChemicalDescriptors:

from sklearn import pipeline as sklearn_pipeline
from mother.feature_generation.core import (
    ChemicalDescriptors,
    MaccsFingerprints,
    MorganFingerprints,
)

feature_generator = sklearn_pipeline.FeatureUnion(
    transformer_list=[
        ("maccs", MaccsFingerprints()),
        ("morgan", MorganFingerprints()),
        ("desc", ChemicalDescriptors()),
    ],
).set_output(transform="pandas")

features: pd.DataFrame = feature_generator.fit_transform(mol_data["Molecule"])

The FeatureUnion class is used to combine the feature generators. Each feature generator can be configured.

📈 Grouping and Cross-Validation

For cross-validation, or test-set selection based on chemical similarity, mother provides a transformer-class for generating groups (TanimotoGroupingFromMols):

import mother.cv as cv_module

groups_engine = cv_module.TanimotoGroupingFromMols(similarity_threshold=0.3)

groups: pd.DataFrame = groups_engine.set_output(transform="pandas").fit_transform(mol_data["Molecule"])

These groups can be used, e.g. in the GroupKFold class from the sklearn.model_selection module:

from sklearn.model_selection import GroupKFold

cv = GroupKFold(n_splits=3)

💻 Model Training

The standard model setup of Mother consists of a feature selection, and a classification- or regression model. Both are based on Catboost. The standard setup for a regression task would be:

import mother.pipeline_utils as mother_takes_care
from mother import ml

model_settings = {
    "feature_selection_flags": ["DROP_CORRELATED", "DROP_CONSTANT", "DROP_DUPLICATES"],
    "correlation_threshold": 0.9,
    "categorical_features": [],
    "feature_selection_type": "catboost",
    "model_type": "regression",
    "target_type": "single_target",
}
pipeline_settings = {
    "remainder": "drop",
    "verbose_feature_names_out": False,
}

model = ml.PipelineWithHyperparameterRooting(
    [
        (
            "feature_selector",
            mother_takes_care.get_feature_selection_pipeline(
                settings=model_settings,
                pipeline_settings=pipeline_settings,
                data=features,
                cv=cv,
            ).set_output(transform="pandas"),
        ),
        (
            "ml_model",
            ml.CatboostRegressorMother(
                target_type="single_target",
                logging_level="Silent",
                random_seed=42,
                iterations=10,
            ),
        ),
    ]
)

targets = pd.Series([0.2, 0.4, 0.7, 1.1, 1.5, 2.0], name="target")
model.fit(features, targets)

Here, we use the extended sklearn pipeline PipelineWithHyperparameterRooting for some additional methods for hyperparameter tuning.

Without feature selection, this is simplified:

model = ml.CatboostRegressorMother(target_type="single_target", logging_level="Silent")

Any other sklearn model, or own model can be used instead of CatboostRegressorMother. An example, on how a custom preprocessing step is added to the model, can be found in the example notebook on custom preprocessing.

Cross-validation

Having used any sklearn pipeline, or sklearn estimator or transformer classes, we can use the sklearn methods for e.g. cross-validation (cross_validate):

from sklearn.model_selection import cross_validate

cross_validate(model, features, targets, groups=groups.values.ravel(), cv=cv, n_jobs=1)

A more convenient method is provided by mother. Using this methods gives you additional output considering CV and groups.

import mother.pipeline_utils as mother_takes_care

mother_takes_care.mother_cv(
    estimator=model,
    X=features,
    y=targets,
    groups=groups,
    cv=cv,
)

🚴 Hyperparameter Optimization

The Mother object MotherTuner uses optuna to optimize hyperparameters:

import mother.optimization as opt

tuner = opt.MotherTuner(
    scorer="r2",
    n_trials_optuna=2,
    n_threads_optuna=1,
)

model_tuned = tuner.optimize(
    model,
    features,
    targets,
    cv,
    groups=groups.values.ravel(),
)

The function model.get_hyperparameter_space returns the hyperparameter space for the model. For the default catboost model, and the PipelineWithHyperparameterRooting class, this is already implemented.

For examples, on how to customize the hyperparameter optimization, or define hyperparameters for your own models, see the example notebook.

🌀 Handling Gene expression data from transcriptomics experiments including different normalisation techniques

The RNA processing pipeline is implemented in the RNA class, which incorporates various preprocessing steps tailored for RNA sequencing data. All RNA code can be found in the rna.py file.

The pipeline includes normalization, feature selection, and discretization, utilizing the power of the scikit-learn framework. The normalization methods available are "Scanpy," "UQ," "CUF," and "CPM.". You can customise the pipeline to your needs, or try different normalisation methods and bin sizes in hyper-parameter tuning. The pipeline can be fitted and re-applied to avoid data-leakage during the normalisation.

Here’s how to set up and use the RNA processing pipeline:

from mother.ml.rna import RNA
import numpy as np
import pandas as pd

rna_model = RNA(
    n_features=3,  # Number of features (=genes) to keep for the prediction.
    n_bins=20,  # Number of bins to use for the discretisation of the target variable.
    normalisation_method="UQ",  # Which normalisation to use
)

rng = np.random.default_rng(42)
rna_data_train = pd.DataFrame(
    rng.integers(0, 200, size=(20, 8)),
    columns=[f"gene_{i}" for i in range(8)],
)
rna_data_test = pd.DataFrame(
    rng.integers(0, 200, size=(5, 8)),
    columns=rna_data_train.columns,
)
y_train = (rna_data_train["gene_0"] > 100).astype(int).rename("class")

# Fit the pipeline to your RNA sequencing data
transformed_train_data: pd.DataFrame = rna_model.fit_transform(rna_data_train, y_train)
transformed_test_data: pd.DataFrame = rna_model.transform(rna_data_test)

A complete walkthrough of the RNA functionality is found in the example notebook.

Install

uv add mother-ml

Optional Features and Extras

To keep the package size small, some dependencies are added as optional extras. These extras provide additional functionality for specific use cases:

Installation Examples

Using pip:

# Install with report generation support
pip install 'mother-ml[report]'

# Install with PyTorch support (adds ~3GB!)
pip install 'mother-ml[torch]'

# Install multiple extras
pip install 'mother-ml[report,torch,tabpfn]'

Using uv:

# Install with specific extras
uv add mother-ml --extra report --extra torch

Acknowledgements

Thank you to the following contributors:

• Thomas Wolf
• Lukas Hebing
• Kai Sommer

and all the others.