Metadata-Version: 2.4
Name: aestetik
Version: 0.3.1
Summary: AESTETIK: Convolutional autoencoder for learning spot representations from spatial transcriptomics and morphology data
Author: Kalin Nonchev
License-Expression: MIT
Project-URL: Homepage, https://github.com/ratschlab/aestetik
Project-URL: Repository, https://github.com/ratschlab/aestetik
Project-URL: Bug Tracker, https://github.com/ratschlab/aestetik/issues
Project-URL: Preprint, https://www.medrxiv.org/content/10.1101/2024.06.04.24308256v1
Keywords: spatial-transcriptomics,autoencoder,representation-learning,multimodal,computational-pathology,digital-pathology,histopathology,deep-learning,pytorch,single-cell,bioinformatics,spatial-biology
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: <3.14,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0
Requires-Dist: torchvision>=0.15
Requires-Dist: lightning>=2.0
Requires-Dist: numpy>=1.23; python_version >= "3.10"
Requires-Dist: numpy<2,>=1.23; python_version < "3.10"
Requires-Dist: pandas>=1.5
Requires-Dist: scipy>=1.10
Requires-Dist: anndata>=0.9
Requires-Dist: scanpy>=1.9
Requires-Dist: squidpy>=1.2
Requires-Dist: matplotlib>=3.7
Requires-Dist: scikit-learn>=1.2
Requires-Dist: joblib>=1.2
Requires-Dist: tqdm>=4.64
Provides-Extra: vips
Requires-Dist: pyvips>=2.2; extra == "vips"
Provides-Extra: viz
Requires-Dist: plotnine>=0.10; extra == "viz"
Provides-Extra: graph
Requires-Dist: igraph>=0.10; extra == "graph"
Requires-Dist: leidenalg>=0.9; extra == "graph"
Requires-Dist: louvain>=0.8; extra == "graph"
Requires-Dist: scikit-misc>=0.3; extra == "graph"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Provides-Extra: test-all
Requires-Dist: pytest>=7.0; extra == "test-all"
Requires-Dist: pytest-cov>=4.0; extra == "test-all"
Requires-Dist: igraph>=0.10; extra == "test-all"
Requires-Dist: leidenalg>=0.9; extra == "test-all"
Requires-Dist: louvain>=0.8; extra == "test-all"
Requires-Dist: scikit-misc>=0.3; extra == "test-all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

[![Downloads](https://static.pepy.tech/badge/aestetik)](https://pepy.tech/project/aestetik)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![medRxiv](https://img.shields.io/badge/medRxiv-2024.06.04.24308256-blue)](https://www.medrxiv.org/content/10.1101/2024.06.04.24308256v1)

# AESTETIK: AutoEncoder for Spatial Transcriptomics Expression with Topology and Image Knowledge

This model is part of the paper "Representation learning for multi-modal spatially resolved transcriptomics data".

**Authors**: Kalin Nonchev, Sonali Andani, Joanna Ficek-Pascual, Marta Nowak, Bettina Sobottka, Tumor Profiler Consortium, Viktor Hendrik Koelzer, and Gunnar Rätsch

The preprint is available [here](https://www.medrxiv.org/content/10.1101/2024.06.04.24308256v1).

## News

  - [05.2026] [Representation learning for multi-modal spatially resolved transcriptomics data](https://academic.oup.com/bioinformatics/advance-article/doi/10.1093/bioinformatics/btag316/8692433) has been published in Bioinformatics (Oxford)
  - [03.2026] [Towards Cross-Sample Alignment for Multi-Modal Representation Learning in Spatial Transcriptomics](https://www.biorxiv.org/content/10.64898/2026.03.02.709002v1) will be at ICLR 2026 Learning Meaningful Representations of Life 
  - [09.2026] AESTETIK now supports multi-modal (e.g., H&E images, spatial transcriptomics) and cross-sample integration using Harmony, scVI, etc.
  - [08.2024] AESTETIK secured the 1st place at the Mammoth International Contest On Omics Sciences in Europe 2024 organized by China National GeneBank, BGI Genomics, MGI and CODATA [link](https://micos.cngb.org/europe/index.html).

## Changelog
**NEW version (June 2025)**
  - **UPDATE:** Rewrote AESTETIK using the Lightning framework for improved modularity
  - **Added:** New `fit()/predict()` API
  - **Added:** Support for processing multiple samples at once
  - **Removed:** Multiple old methods and parameters in AESTETIK 

See [full changelog](CHANGELOG.md) for more details.
    
## Do you want to gain a multi-modal understanding of key biological processes through spatial transcriptomics?

We introduce AESTETIK, a convolutional autoencoder model. It jointly integrates transcriptomics and morphology information, on a spot level, and topology, on a neighborhood level, to learn accurate spot representations that capture biological complexity.

![aestetik](/figures/aestetik.png)

**Fig. 1 AESTETIK integrates spatial, transcriptomics, and morphology information to learn accurate spot representations.**
**A**: Spatial transcriptomics enables in-depth molecular characterization of samples on a morphology and RNA level while preserving spatial location. **B**: Workflow of AESTETIK. Initially, the transcriptomics and morphology spot representations are preprocessed. Next, a dimensionality reduction technique (e.g., PCA) is applied. Subsequently, the processed spot representations are clustered separately to acquire labels required for the multi-triplet loss. Afterwards, the modality-specific representations are fused through concatenation and the grid per spot is built. This is used as an input for the autoencoder. Lastly, the spatial-, transcriptomics-, and morphology-informed spot representations are obtained and used for downstream tasks such as clustering, morphology analysis, etc.

## Setup

We can install aestetik directly through pip.

```
pip install aestetik
```

We can also create a conda environment with the required packages.

```
conda env create --file=environment.yaml
```

We can also install aestetik offline.

```
git clone https://github.com/ratschlab/aestetik
cd aestetik
pip install .
```

Optional extras:

```
pip install ".[vips]"   # enables pyvips-based morphology helpers
pip install ".[viz]"    # enables plotnine-based cluster-search plot
pip install ".[test]"   # test dependencies (pytest)
```

##### NB: The morphology spot-extraction helpers require [pyvips](https://github.com/libvips/pyvips). We recommend installing pyvips through conda:
```
conda install conda-forge::pyvips
```

## Getting Started

After installing, confirm the version with `import aestetik;
aestetik.__version__`. AESTETIK follows the scikit-learn ``fit`` /
``transform`` / ``predict`` estimator surface:

```python
from aestetik import AESTETIK

model = AESTETIK(
    n_cluster=adata.obs.ground_truth.unique().size,
    morphology_weight=1.5,
    refine_cluster=True,
    window_size=3,
    clustering_method="kmeans",
)
model.fit(adata)
adata.obsm["AESTETIK"]        = model.transform(adata)
adata.obs["AESTETIK_cluster"] = model.predict(adata)

# Or in one shot:
adata.obs["AESTETIK_cluster"] = model.fit_predict(adata)
```

Please take a look at our [example](example/gettingStartedWithAESTETIK.ipynb) to get started with AESTETIK.

![aestetik](/figures/maynard_human_brain_analysis_151676_Transcriptomics_Morphology_AESTETIK.png)

[Here](example/gettingStartedWithAESTETIKwithSimulatedData.ipynb), another example notebook with [simulated spatial transcriptomics data](https://github.com/ratschlab/simulate_spatial_transcriptomics_tool).

![aestetik](/figures/AESTETIK_clustering.png)


## Papers Citing AESTETIK

<!-- CITATIONS:START -->
1. Ju Dai, Kalin Nonchev, V. Koelzer, and Gunnar Rätsch "Towards Cross-Sample Alignment for Multi-Modal Representation Learning in Spatial Transcriptomics." *bioRxiv* (2026). [DOI](https://doi.org/10.64898/2026.03.02.709002)
2. Kalin Nonchev, Glib Manaiev, V. Koelzer, and Gunnar Rätsch "DeepSpot2Cell: Predicting Virtual Single-Cell Spatial Transcriptomics from H&E images using Spot-Level Supervision." *bioRxiv* (2025). [DOI](https://doi.org/10.1101/2025.09.23.678121)
3. Liping Kang, Qinglong Zhang, F. Qian, Junyao Liang, and Xiaohui Wu "Benchmarking computational methods for detecting spatial domains and domain-specific spatially variable genes from spatial transcriptomics data." *Nucleic Acids Research* (2025). [DOI](https://doi.org/10.1093/nar/gkaf303)
4. Kalin Nonchev, Sebastian Dawo, Karina Silina, H. Moch, S. Andani, Tumor Profiler Consortium, V. H. Koelzer, and Gunnar R¨atsch "DeepSpot: Leveraging Spatial Context for Enhanced Spatial Transcriptomics Prediction from H&E Images." *medRxiv* (2025). [DOI](https://doi.org/10.1101/2025.02.09.25321567)
<!-- CITATIONS:END -->

*This list is automatically updated weekly via [GitHub Actions](.github/workflows/update-citations.yml) using the [Semantic Scholar](https://www.semanticscholar.org/) and [OpenCitations](https://opencitations.net/) APIs.*

## Related Projects

- [DeepSpot](https://github.com/ratschlab/DeepSpot) — Predicts spatial transcriptomics from H&E images at spot-level (Visium) and single-cell (Xenium) resolution. Uses AESTETIK for cross-sample integration.
- [DeepSpot2Cell](https://github.com/ratschlab/DeepSpot2Cell) — Predicts virtual single-cell spatial transcriptomics from H&E images using spot-level supervision.

## Citation

In case you found our work useful, please consider citing us:

```
@article{nonchev2024representation,
  title={Representation learning for multi-modal spatially resolved transcriptomics data},
  author={Nonchev, Kalin and Andani, Sonali and Ficek-Pascual, Joanna and Nowak, Marta and Sobottka, Bettina and Tumor Profiler Consortium and Koelzer, Viktor Hendrik and Raetsch, Gunnar},
  journal={medRxiv},
  pages={2024--06},
  year={2024},
  publisher={Cold Spring Harbor Laboratory Press}
}
```

The code for reproducing the paper results can be found [here](https://github.com/ratschlab/st-rep).

## Contact

In case, you have questions, please get in touch with [Kalin Nonchev](https://bmi.inf.ethz.ch/people/person/kalin-nonchev).
