Metadata-Version: 2.5
Name: duetist
Version: 0.1.0
Summary: Kernel smoothing of transcript embeddings and a hierarchical Potts model of niches and domains for image-based spatial transcriptomics.
Project-URL: Repository, https://gitlab.svi.edu.au/biocellgen-public/duetist
Author-email: Patrick Crock <pat.crock@svi.edu.au>
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: Potts model,Xenium,hidden Markov random field,imaging spatial transcriptomics,niches,spatial domains,spatial transcriptomics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.11
Requires-Dist: numpy>=1.24
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scipy>=1.10
Requires-Dist: shapely>=2.0
Requires-Dist: threadpoolctl>=3.1
Provides-Extra: all
Requires-Dist: hdbscan>=0.8.33; extra == 'all'
Requires-Dist: matplotlib>=3.7; extra == 'all'
Requires-Dist: zarr>=3.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: hdbscan>=0.8.33; extra == 'dev'
Requires-Dist: matplotlib>=3.7; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Requires-Dist: zarr>=3.0; extra == 'dev'
Provides-Extra: hdbscan
Requires-Dist: hdbscan>=0.8.33; extra == 'hdbscan'
Provides-Extra: plot
Requires-Dist: matplotlib>=3.7; extra == 'plot'
Provides-Extra: test
Requires-Dist: pytest>=7; extra == 'test'
Provides-Extra: zarr
Requires-Dist: zarr>=3.0; extra == 'zarr'
Description-Content-Type: text/markdown

# 
<!-- PROJECT LOGO -->
<br />
<div align="center">
  <a href="https://gitlab.svi.edu.au/biocellgen-public/duetist">
    <img src="https://gitlab.svi.edu.au/biocellgen-public/duetist/-/raw/main/docs/DuetiST_logo.png" alt="Logo" width="200" height="200">
  </a>

<h3 align="center">DuetiST: Segmentation-free identification of tissue domains in image-based spatial transcriptomics </h3>

</div>

## Overview

Image-based spatial transcriptomics resolves the positions of individual transcripts at sub-cellular scale. However, the (often incorrect) assignment of these transcripts to cells by segmentation presents perennial issues in downstream analysis. Another of our lab's tools, [SpatialRNA](https://pypi.org/project/spatialrna/), effectively distills spatial signal at transcript resolution to produce a latent embedding space encoding the local molecular neigbhourhood of each transcript. Here, you will find **DuetiST**, a tool designed to take the outputs of SpatialRNA and derive two layers of spatial features - fine-grained niches, and coarser, contiguous domains. DuetiST achieves this through a hierarchical Bayesian model. The tool first collapses transcripts into a grid, then uses grid embedding averages and density weights to seed a large number of niches. The local neighbourhood composition of each grid point is then used to seed a smaller number of domains, which are modelled with a Potts-prior Hidden Markov Random Field. The model iterates to learn niches from their overlying domains, and domains from their underlying niches, as well as tuning the smoothing of the Potts model. At predetermined intervals, domains are also merged based on compositional similarity. Finally, an Iterated Conditional Modes step refines each point's identity at both layers of scale. DuetiST is inherently designed for the analysis of many samples at once: smoothing can be run in parallel per-sample, and the model itself learns both shared and unique features across samples.  

## Installation

DuetiST requires Python 3.11 or newer and is available from [PyPI](https://pypi.org/project/duetist/):

```bash
pip install duetist
```

Some features need optional dependencies, installed as extras:

| Extra | Adds | Needed for |
|---|---|---|
| `hdbscan` | `hdbscan` | `init="hdbscan"` seeding |
| `plot` | `matplotlib` | the `duetist.plotting` module and `duetist plot` |
| `zarr` | `zarr` | reading zarr embedding stores (such as SpatialRNA's output) |
| `all` | all of the above | |

```bash
pip install "duetist[all]"
```

To install the development version, with the test and lint tools:

```bash
git clone https://gitlab.svi.edu.au/biocellgen-public/duetist.git
cd duetist
pip install -e ".[dev]"
pytest
```

Check the install with `duetist --version`.

## Examples

Coming soon...

## Project status

DuetiST is still in active development! Expect relatively frequent updates as I further refine the model and backend of the tool. 
