Metadata-Version: 2.4
Name: mmcontext
Version: 2.0.1
Summary: Multimodal contrastive learning aligning text and omics embeddings via sentence-transformers.
Author: Jonatan Menger
Maintainer-email: Jonatan Menger <jonatan.menger@gmail.com>
License: MIT License
        
        Copyright (c) 2024, Jonatan Menger
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/mengerj/mmcontext
Project-URL: Issues, https://github.com/mengerj/mmcontext/issues
Project-URL: Source, https://github.com/mengerj/mmcontext
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: accelerate>=1.9
Requires-Dist: anndata>=0.12
Requires-Dist: datasets!=4,>=2.19.1
Requires-Dist: huggingface-hub>=0.34.3
Requires-Dist: numpy>=1.24
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: scanpy>=1.11.3
Requires-Dist: sentence-transformers>=5.4
Requires-Dist: torch>=2.5
Requires-Dist: transformers>=4.57.1
Requires-Dist: zarr>=3.1.6
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: eval
Requires-Dist: scib>=1.1.7; extra == "eval"
Requires-Dist: umap-learn>=0.5; extra == "eval"
Provides-Extra: test
Requires-Dist: coverage; extra == "test"
Requires-Dist: pytest; extra == "test"
Requires-Dist: python-json-logger; extra == "test"
Provides-Extra: train
Requires-Dist: wandb>=0.27; extra == "train"
Dynamic: license-file

# mmcontext

[![Tests][badge-tests]][tests]

Multimodal contrastive learning aligning text and omics embeddings via [sentence-transformers](https://www.sbert.net/).

**mmcontext** enables joint embedding spaces where natural-language descriptions and biological data (single-cell gene expression) can be compared directly. Built on the sentence-transformers v5.4+ multimodal API.

![Conceptual Diagram](figs/concept.png)

## Paper

**mmcontext** is described in detail in our paper:
Jonatan Menger, Sonia Maria Krissmer, Clemens Kreutz, Harald Binder, Maren Hackenberg, mmContext: an open framework for multimodal contrastive learning of omics and text data, Bioinformatics, Volume 42, Issue 6, June 2026, btag338, https://doi.org/10.1093/bioinformatics/btag338
If you use **mmcontext** in your research, please cite our work.

## Installation

```bash
pip install mmcontext
```

Or install from source with development dependencies:

```bash
git clone https://github.com/mengerj/mmcontext.git
cd mmcontext
pip install -e ".[dev,test,eval,train]"
```

## Quick Start

### Using a Pre-trained Model

```python
from sentence_transformers import SentenceTransformer

model = SentenceTransformer("jo-mengr/mmcontext-pubmedbert-gs10k", trust_remote_code=True)

# Encode text queries
text_embeddings = model.encode(["CD4+ T cell", "B cell precursor"])
```

Pre-trained models are available on Hugging Face under the [jo-mengr](https://huggingface.co/jo-mengr) organization.

See the [pretrained inference tutorial](tutorials/pretrained_inference.ipynb) for a complete guide.

### Building a Pipeline

```python
from mmcontext.embed import build_pipeline

pipeline = build_pipeline(
    text_model="microsoft/BiomedNLP-BiomedBERT-base-uncased-abstract",
    omics_dim=512,        # dimension of your omics vectors
    shared_dim=256,       # joint embedding space dimension
)
```

### Evaluation

```python
from mmcontext.eval import get

LabelSimilarity = get("LabelSimilarity")
evaluator = LabelSimilarity(similarity="cosine")
result = evaluator.compute(
    omics_embeddings=omics_emb,
    label_embeddings=label_emb,
    query_labels=labels,
    true_labels=true_labels,
    label_key="cell_type",
)
```

See the [evaluate model 2.0 notebook](tutorials/evaluate_model_2.0.ipynb) for a complete evaluation workflow.

## Architecture

mmcontext 2.0 uses the sentence-transformers module pipeline pattern:

```
Input -> MMContextModule -> AdapterModule -> Pooling -> Normalize
```

The **MMContextModule** handles both text (tokenize -> AutoModel) and omics (VectorStore lookup) modalities. The **AdapterModule** projects omics vectors into the text model's embedding space.

Data is stored in AnnData format (`.h5ad`/zarr), with a memory-efficient VectorStore for runtime omics lookups.

## Multi-Model Benchmarking

For systematic comparisons across multiple models and datasets, see the companion repository: [mmcontext-benchmark](https://github.com/mengerj/mmcontext-benchmark).

## Dataset Preparation

To prepare training datasets from AnnData objects, see [adata-hf-datasets](https://github.com/mengerj/adata_hf_datasets).

## Contributing

Contributions and suggestions are very welcome! Please open an [issue](https://github.com/mengerj/mmcontext/issues) to propose enhancements, report bugs, or ask questions.

## Citation

```bibtex
@article{menger2026mmcontext,
  title={mmContext: an open framework for multimodal contrastive learning of omics and text data},
  author={Menger, Jonatan and Krissmer, Sonia Maria and Kreutz, Clemens and Binder, Harald and Hackenberg, Maren},
  journal={Bioinformatics},
  volume={42},
  number={6},
  pages={btag338},
  year={2026},
  publisher={Oxford University Press}
}
```

---

[badge-tests]: https://img.shields.io/github/actions/workflow/status/mengerj/mmcontext/test.yaml?branch=main
[tests]: https://github.com/mengerj/mmcontext/actions/workflows/test.yaml
