Metadata-Version: 2.3
Name: mother-ml
Version: 1.0.5
Summary: A ML framework that takes care
Author: Thomas Wolf, Florian Huber, Nicolas Peschke, Niklas Toetsch, Satya Kanuri, Alex Calabrese, Samantha Martinez, Hamza Ibrahim, Agata Zieba, Yunhee Jeong, Nesma Mousa, Lukas Hebing, Kai Sommer, Nicolas Arning
License: BSD 3-Clause License
         
         Copyright (c) 2026, Bayer
         
         Redistribution and use in source and binary forms, with or without
         modification, are permitted provided that the following conditions are met:
         
         1. Redistributions of source code must retain the above copyright notice, this
            list of conditions and the following disclaimer.
         
         2. Redistributions in binary form must reproduce the above copyright notice,
            this list of conditions and the following disclaimer in the documentation
            and/or other materials provided with the distribution.
         
         3. Neither the name of the copyright holder nor the names of its
            contributors may be used to endorse or promote products derived from
            this software without specific prior written permission.
         
         THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
         AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
         IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
         DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
         FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
         DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
         SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
         CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
         OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
         OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Requires-Dist: catboost>=1.2.9,<=1.2.10
Requires-Dist: feature-engine>=1.8.0,<2
Requires-Dist: numpy>=2.2,<2.3
Requires-Dist: optuna>=4.2.0,<5
Requires-Dist: pandas>=2.2,<3.0
Requires-Dist: pydantic-settings>=2.4.0,<3
Requires-Dist: rdkit>=2024.9.1
Requires-Dist: scikit-learn>=1.9.0,<1.10
Requires-Dist: colorama>=0.4.6,<0.5
Requires-Dist: boruta>=0.4.3,<0.5
Requires-Dist: quantile-forest>=1.4.2,<2
Requires-Dist: kmedoids>=0.5.3.1,<0.6 ; extra == 'clustering'
Requires-Dist: matplotlib>3.7.0 ; extra == 'report'
Requires-Dist: seaborn>=0.13.2,<0.14 ; extra == 'report'
Requires-Dist: umap-learn>=0.5.12,<0.6 ; extra == 'report'
Requires-Dist: plotly>=6.0.1,<7 ; extra == 'report'
Requires-Dist: ipywidgets>=8.1.5,<9 ; extra == 'report'
Requires-Dist: igraph>=0.11.8,<0.12 ; extra == 'report'
Requires-Dist: leidenalg>=0.10.2,<0.11 ; extra == 'report'
Requires-Dist: anndata ; extra == 'rna'
Requires-Dist: scanpy ; extra == 'rna'
Requires-Dist: tabpfn==8.0.8 ; extra == 'tabpfn'
Requires-Dist: torch>=2.3.0,<3 ; extra == 'tabpfn'
Requires-Dist: torch>=2.3.0,<3 ; extra == 'torch'
Requires-Python: >=3.11, <3.15
Project-URL: Homepage, https://github.com/Bayer-Group/MotherML
Project-URL: Documentation, https://bayer-group.github.io/MotherML/
Project-URL: Repository, https://github.com/Bayer-Group/MotherML
Project-URL: Issues, https://github.com/Bayer-Group/MotherML/issues
Project-URL: Changelog, https://bayer-group.github.io/MotherML/Changelog/
Provides-Extra: clustering
Provides-Extra: report
Provides-Extra: rna
Provides-Extra: tabpfn
Provides-Extra: torch
Description-Content-Type: text/markdown

# Mother-ML

A ML framework that takes care.

Mother is a machine-learning framework for predicting properties from 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 catboost models, 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](https://scikit-learn.org/dev/modules/compose.html).

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](https://github.com/Bayer-Group/MotherML/blob/main/src/mother/settings.py). This class can be used to store all relevant settings for your ML project.

## Usage

A basic example can be found in the [example regression notebook](https://github.com/Bayer-Group/MotherML/blob/main/examples/notebooks/02_regression/01_basic_regression.ipynb). Other
examples are in the [examples folder](https://github.com/Bayer-Group/MotherML/tree/main/examples/notebooks).

### 🔬 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:

```python
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`:

```python
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`):

```python
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:

```python
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:

```python
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:

```python
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](https://github.com/Bayer-Group/MotherML/blob/main/examples/notebooks/01_basics/03_custom_preprocessing.ipynb).

### 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`):

```python
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.

```python
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:

```python
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](https://github.com/Bayer-Group/MotherML/blob/main/examples/notebooks/05_advanced/01_custom_hyperparameter_optimization.ipynb).

### 🌀 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:

```python
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](https://github.com/Bayer-Group/MotherML/blob/main/examples/notebooks/04_feature_engineering/03_rna_preprocessing.ipynb).

## 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:

| Extra | Description | Key Packages | Notes |
|-------|-------------|--------------|-------|
| `all` | All optional features | All packages below | Installs everything |
| `report` | Visualization and reporting tools | plotly, kaleido | For generating plots and reports |
| `rna` | RNA sequence analysis | rnalib | RNA-specific preprocessing |
| `torch` | PyTorch neural network support | torch, pytorch-tabular | **Adds ~3GB to environment size!** |
| `tabpfn` | TabPFN model support | tabpfn | Prior-fitted networks for tabular data |
| `clustering` | Chemical compound clustering | mol2vec, cluster-my-molecules | For molecular clustering analysis |

#### Installation Examples

**Using pip:**

```bash
# 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:**

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

> [!CAUTION]
> There is also a different `mother` package on PyPI. Be sure to install `mother-ml`.

## Acknowledgements

Thank you to the following contributors:

- Thomas Wolf
- Lukas Hebing
- Kai Sommer

and all the others.
