https://github.com/aignostics/tme-studio
🎨 A toolkit to explore the OpenTME dataset.
https://github.com/aignostics/tme-studio
Last synced: 2 months ago
JSON representation
🎨 A toolkit to explore the OpenTME dataset.
- Host: GitHub
- URL: https://github.com/aignostics/tme-studio
- Owner: aignostics
- License: mit
- Created: 2026-04-08T14:26:52.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-10T08:57:16.000Z (3 months ago)
- Last Synced: 2026-04-10T10:18:35.896Z (3 months ago)
- Language: Python
- Size: 7.3 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Agents: .github/AGENTS.md
Awesome Lists containing this project
README
[](https://github.com/aignostics/tme-studio/blob/main/LICENSE)
[](https://github.com/aignostics/tme-studio/actions/workflows/ci-cd.yml)
[](https://github.com/aignostics/tme-studio/security/dependabot)
[](https://github.com/aignostics/tme-studio/issues?q=is%3Aissue%20state%3Aopen%20Dependency%20Dashboard)
[](https://codecov.io/gh/aignostics/tme-studio)
[](https://github.com/aignostics/tme-studio/blob/main/noxfile.py)
[](https://github.com/aignostics/foundry-python)
[](https://molab.marimo.io/notebooks/nb_6P1wbPYcPEN5GfXbUjVnpg/app)
# 🎨 TME Studio
Welcome to TME Studio! This readme explains the content of TME Studio, and the dataset it is built on: [OpenTME](https://huggingface.co/datasets/Aignostics/OpenTME).
New to TME Studio? Want to try out the notebooks right away without any set up required? [Try out our interactive demo via molab](https://molab.marimo.io/notebooks/nb_6P1wbPYcPEN5GfXbUjVnpg/app).
Make sure you have [access to OpenTME on Hugging Face](#hugging-face-access), then open the link and start exploring.
Already familiar with TME Studio? You want to edit the notebooks and adapt them to your needs?
You can choose to either
* follow the setup instructions to [fork the notebooks into your molab workspace](#edit-notebooks-in-molab) OR
* follow the setup instructions to [run the notebooks locally](#edit-notebooks-locally) .
## Content
- [What is OpenTME?](#what-is-opentme)
- [What is TME Studio?](#what-is-tme-studio)
- [Setup instructions](#setup-instructions)
## What is OpenTME?
OpenTME is an open-source project by [Aignostics](https://aignostics.com) that provides academic researchers with pre-computed quantitative TME (Tumor Micro-Environment) features across H&E-stained Whole-Slide Images (WSIs) from The Cancer Genome Atlas (TCGA). It provides comprehensive spatial outputs characterizing key cellular and tissue components of the TME, including cancer cells, immune cells, and stromal features, as well as their relationships within the tissue architecture.
All outputs were generated using [Atlas H&E-TME](https://www.aignostics.com/products/he-tme-profiling-product), Aignostics' AI-powered computational pathology application for the automated identification and quantification of TME features in FFPE H&E-stained tissue samples.
## What is TME Studio?
TME Studio contains a set of tutorials and example notebooks to help you explore [OpenTME](https://huggingface.co/datasets/Aignostics/OpenTME). TME Studio is provided as an entry point into OpenTME, and intended to accelerate research output from the OpenTME data.
### Content
The structure of the notebooks in this repo looks as follows:
```
tme_studio/
|-- src/
|-- aignostics_tme_studio/
|-- notebooks/
|-- demo/
|-- examples/
|-- tutorials/
```
*Each folder is described below. Follow the links and click the "Fork" button to run the notebooks in molab (make sure
you have [access to OpenTME on Hugging Face](#hugging-face-access), and a [molab](https://molab.marimo.io/) account).*
* **Tutorials:** Step-by-step notebooks to help users get started, covering foundational tasks such as loading and exploring the dataset, and providing a guide through the OpenTME features.
1. [Getting started](https://molab.marimo.io/github.com/aignostics/tme-studio/blob/main/src/aignostics_tme_studio/notebooks/tutorials/1_getting_started.py)
2. [Description of the OpenTME features](https://molab.marimo.io/github.com/aignostics/tme-studio/blob/main/src/aignostics_tme_studio/notebooks/tutorials/2_description_opentme_features.py)
3. [Including TCGA metadata](https://molab.marimo.io/github.com/aignostics/tme-studio/blob/main/src/aignostics_tme_studio/notebooks/tutorials/3_including_TCGA_metadata.py)
* **Examples:** Concise notebooks demonstrating specific types of analysis, such as tumor immune phenotype classification and Kaplan–Meier survival plots. Note that these are examples that may be used as a starting point for your own analysis.
1. [Clustering](https://molab.marimo.io/github.com/aignostics/tme-studio/blob/main/src/aignostics_tme_studio/notebooks/examples/clustering.py)
2. [Outlier detection](https://molab.marimo.io/github.com/aignostics/tme-studio/blob/main/src/aignostics_tme_studio/notebooks/examples/outlier_detection.py)
3. [Survival analysis](https://molab.marimo.io/github.com/aignostics/tme-studio/blob/main/src/aignostics_tme_studio/notebooks/examples/survival_analysis.py)
4. [Tumor immune phenotyping](https://molab.marimo.io/github.com/aignostics/tme-studio/blob/main/src/aignostics_tme_studio/notebooks/examples/tumor_immune_phenotyping.py)
* **Demo:** contains a demo notebook showcasing all features in OpenTME and some example analyses.
1. [Demo](https://molab.marimo.io/notebooks/nb_6P1wbPYcPEN5GfXbUjVnpg/app)
If you are unfamiliar with the OpenTME dataset, we suggest beginning at the [getting started](https://molab.marimo.io/github.com/aignostics/tme-studio/blob/main/src/aignostics_tme_studio/notebooks/tutorials/1_getting_started.py) notebook. To get a feeling for all the different features you can find in OpenTME, have a look at the [demo](https://molab.marimo.io/notebooks/nb_6P1wbPYcPEN5GfXbUjVnpg/app).
# Setup instructions
## Hugging Face access
Regardless of how you decide to run the notebooks, you will need to get access to OpenTME on Hugging Face 🤗.
### Creating an access token
1. Make sure you have a Hugging Face account. If you don't have one, you can create one for free at [hf.co/join](https://hf.co/join).
2. Get access to the dataset by going to https://huggingface.co/datasets/Aignostics/OpenTME and clicking "Access"
> Note: You will receive an email from Hugging Face as soon as your access request has been reviewed. This may take a few working days.
> Note: No need to download the dataset! The tutorials will show you how to access the dataset via the Hugging Face API.
3. Create an access token by going to https://huggingface.co/settings/tokens
### Authenticating with your token
You can now use your token in two ways:
1. Enter it in the designated box for it inside each notebook. This is how you authenticate when you are running a notebook in molab. You will have to repeat this action each time you open a notebook.
2. Log in via the Hugging Face CLI (only when running notebooks locally). In this case your token will be stored and you won't have to enter your token each time you open a notebook.
1. Download the [Hugging Face CLI](https://huggingface.co/docs/huggingface_hub/en/guides/cli)
2. Log into hugging face by calling
```
hf auth login
```
and log in with your access token.
> Note: If you invalidated your token, you can force logging in with a new token by calling `hf auth login \--force`
## Edit notebooks in molab
To edit your own copy of the TME Studio notebooks in molab, do the following:
1. Open the notebook of choice via the link in the [content overview](#content) above. E.g. our
[Demo](https://molab.marimo.io/notebooks/nb_6P1wbPYcPEN5GfXbUjVnpg/app) notebook.
2. Create a molab account, via the "Sign In" button in the upper right corner.
3. Click the "Fork" button.
4. Run the notebook via the play button.
5. Install "missing packages" via the pop-up menu on the left tab bar.
You can start exploring now.
## Edit notebooks locally
To run the TME Studio notebooks on your local machine, follow these installation instructions:
### Prerequisites
| Tool | Version | Purpose |
|------|---------|---------|
| [mise](https://mise.jdx.dev/) | latest | Task runner & tool version manager |
| Git | latest | Version control |
### Installing mise
[mise](https://mise.jdx.dev/) manages tool versions (Python, uv, trivy, etc.) and runs all project tasks. Install it first:
```shell
curl https://mise.run | sh
# activate mise in the current shell and add to shell config for future sessions
echo 'eval "$(mise activate --shims bash)"' >> ~/.bashrc
source ~/.bashrc
```
For .zsh users:
```shell
echo 'eval "$(mise activate --shims zsh)"' >> ~/.zshrc
source ~/.zshrc
```
For other shells, see [mise installation docs](https://mise.jdx.dev/installing-mise.html).
Verify the installation:
```shell
mise --version
# Check path - mise shims should be first in the PATH to ensure the correct tool versions are used
echo $PATH
which uv # Path should contain the `mise/shims/uv` shim, not a system-wide uv installation; please do not install uv in the same directory as `mise` to avoid conflicts
```
### Cloning the repository
Authenticate with GitHub using the Github CLI to clone the repository:
```shell
gh auth login
gh repo clone aignostics/tme-studio
cd tme-studio
mise trust
gh auth setup-git
```
### Installation
```shell
# Install all dev dependencies, pre-commit hooks, and keyring tooling
mise run install
# Verify everything works
mise run lint
# List all existing mise tasks
mise tasks
```
This runs `uv sync --all-extras` to install all dependencies, then sets up pre-commit hooks.
### Starting Marimo
You are now ready to explore the notebooks! 🎨
Start marimo by calling the following command and opening the URL in your browser:
```
uv run marimo edit
```
Use the marimo UI opened in your browser to navigate to the notebooks.
Alternatively, you can run
```
uv run marimo edit path/to/notebook.py
```
to open a specific notebook directly.
## Citation
If you use OpenTME or TME Studio in your research, please cite:
```
@article{galama2026opentme,
title={{OpenTME}: An Open Dataset of {AI}-Powered {H\&E} Tumor
Microenvironment Profiles from {TCGA}},
author={Galama, Maaike and Kozar-Gillan, Nina and Embacher, Christina
and Dembo, Todd and B{\"o}hm, Cornelius and Ramberger, Evelyn
and Ribbat-Idel, Julika and Krupar, Rosemarie and Aumiller, Verena
and H{\"a}gele, Miriam and Standvoss, Kai and Erdmann, Gerrit
and Pablos, Blanca and Angelo, Ari and Schallenberg, Simon
and Norgan, Andrew and Matyas, Viktor and M{\"u}ller, Klaus-Robert
and Alber, Maximilian and Ruff, Lukas and Klauschen, Frederick},
journal={arXiv preprint arXiv:2604.12075},
year={2026},
url={https://arxiv.org/abs/2604.12075},
}
```
## Further reading
- [OpenTME](https://arxiv.org/abs/2604.12075) - Paper on arxiv describing OpenTME and TME Studio
- [Security policy](SECURITY.md) - Documentation of security checks, tools, and principles
- [Release notes](https://github.com/aignostics/tme-studio/releases) - Complete log of improvements and changes
- [Attributions](ATTRIBUTIONS.md) - Open source projects this project builds upon