aignostics-tme-studio 0.2.1

🎨 A toolkit to explore the Aignostics OpenTME dataset.

🎨 TME Studio

Welcome to TME Studio! This readme explains the content of TME Studio, and the dataset it is built on: OpenTME.

Already familiar and just want to get started? Move on to the Setup instructions.

Want to view an interactive demo first? Open the molab demo app!

Content

• What is OpenTME?
• What is TME Studio?
• Setup instructions

What is OpenTME?

OpenTME is an open-source project by Aignostics that provides academic researchers with pre-computed quantitative TME (Tumor Micro-Environment) features across H&E-stained 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, 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. 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/
|-- aignostics_tme_studio/
    |-- src/
        |-- notebooks/
            |-- demo/
            |-- examples/
            |-- tutorials/

• Tutorials: 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.

• Examples: Concise notebooks demonstrating specific analysis types, such as immune desert classification and Kaplan–Meier survival plots. The examples showcase what types of analyses might be possible with OpenTME. Note that these are examples, and are not statistically rigorous, but may be used as a starting point for your own analysis.

• Demo: contains a demo notebook showcasing all features in OpenTME and some example analyses.

If you are unfamiliar with the OpenTME dataset, we suggest beginning at src/aignostics_tme_studio/notebooks/tutorials/1_getting_started.py. To get a feeling for all the different features you can find in OpenTME, have a look at the demo notebook src/aignostics_tme_studio/notebooks/demo/demo.py.

Setup instructions

To run the TME Studio notebooks, follow these installation instructions:

Prerequisites

Tool	Version	Purpose
mise	latest	Task runner & tool version manager
Git	latest	Version control

Installing mise

mise manages tool versions (Python, uv, trivy, etc.) and runs all project tasks. Install it first:

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:

echo 'eval "$(mise activate --shims zsh)"' >> ~/.zshrc
source ~/.zshrc

For other shells, see mise installation docs.

Verify the installation:

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:

gh auth login

gh repo clone aignostics/tme-studio

cd tme-studio
mise trust
gh auth setup-git

Installation

# 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 (including private registry packages), then sets up pre-commit hooks.

🤗 Hugging Face access

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.
2. Get access to the dataset by going to https://huggingface.co/datasets/Aignostics/OpenTME and clicking "Access"

Note: You will eceive 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. You will have to repeat this action each time you open a notebook.

2. Log in via the Hugging Face CLI (recommended). 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
   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

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.

Further Reading

• Security policy - Documentation of security checks, tools, and principles
• Release notes - Complete log of improvements and changes
• Attributions - Open source projects this project builds upon