Metadata-Version: 2.4
Name: aignostics-tme-studio
Version: 0.1.2
Summary: 🎨 A toolkit to explore the Aignostics OpenTME dataset.
Project-URL: Homepage, https://github.com/aignostics/tme-studio
Project-URL: Documentation, https://github.com/aignostics/tme-studio#readme
Project-URL: Source, https://github.com/aignostics/tme-studio
Project-URL: Changelog, https://github.com/aignostics/tme-studio/releases
Project-URL: Issues, https://github.com/aignostics/tme-studio/issues
Author-email: Maaike Galama <maaike@aignostics.com>
License: MIT License
        
        Copyright (c) [2026] [Aignostics GmbH (support@aignostics.com)]
        
        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.
License-File: LICENSE
Keywords: act,aignostics-tme-studio,codecov,copier,cyclonedx,detect-secrets,foundry,foundry-python,jupyter,nox,pip-audit,pip-licenses,pre-commit,pypi,pytest,python,ruff,sonarcloud,sonarqube,uv
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: <3.13,>=3.11
Requires-Dist: datasets>=4.8.4
Requires-Dist: elements>=3.21.0
Requires-Dist: huggingface-hub>=1.7.2
Requires-Dist: jinja2>=3.1.6
Requires-Dist: kaplanmeier>=0.2.0
Requires-Dist: marimo>=0.20.4
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: munch>=4.0.0
Requires-Dist: pandas>=3.0.1
Requires-Dist: plotly>=6.6.0
Requires-Dist: pyasn1>=0.6.3
Requires-Dist: scikit-learn>=1.8.0
Requires-Dist: scipy>=1.17.1
Requires-Dist: statsmodels>=0.14.6
Requires-Dist: tabulate>=0.10.0
Description-Content-Type: text/markdown

[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/aignostics/tme-studio/blob/main/LICENSE)
[![CI](https://github.com/aignostics/tme-studio/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/aignostics/tme-studio/actions/workflows/ci-cd.yml)
[![Dependabot](https://img.shields.io/badge/dependabot-active-brightgreen?style=flat-square&logo=dependabot)](https://github.com/aignostics/tme-studio/security/dependabot)
[![Renovate enabled](https://img.shields.io/badge/renovate-enabled-brightgreen.svg)](https://github.com/aignostics/tme-studio/issues?q=is%3Aissue%20state%3Aopen%20Dependency%20Dashboard)
[![codecov](https://codecov.io/gh/aignostics/tme-studio/graph/badge.svg)](https://codecov.io/gh/aignostics/tme-studio)
[![Ruff](https://img.shields.io/badge/style-Ruff-blue?color=D6FF65)](https://github.com/aignostics/tme-studio/blob/main/noxfile.py)
[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-orange.json)](https://github.com/aignostics/foundry-python)

# 🎨 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).

Already familiar and just want to get started? Move on to the [Setup instructions](#setup-instructions).

## 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](http://aignostics.com) 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](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/
|-- 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](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 (including private registry packages), then sets up pre-commit hooks.

### 🤗 Hugging Face access
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 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. 

2. Download the [Hugging Face CLI](https://huggingface.co/docs/huggingface_hub/en/guides/cli)
3. Log into hugging face by calling
```
hf auth login
```
Enter your access token created on https://huggingface.co/settings/tokens.

> Note: If you have an invalid token, you can force logging in 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](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
