Metadata-Version: 2.4
Name: sopa
Version: 2.1.6
Summary: Spatial-omics pipeline and analysis
Project-URL: Homepage, https://gustaveroussy.github.io/sopa
Project-URL: Repository, https://github.com/gustaveroussy/sopa
Project-URL: Documentation, https://gustaveroussy.github.io/sopa
Author-email: Quentin Blampey <quentin.blampey@gmail.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: anndata>=0.11.0
Requires-Dist: dask[distributed]>=2024.4.1
Requires-Dist: igraph>=0.11.0
Requires-Dist: scanpy>=1.10.4
Requires-Dist: spatialdata-io>=0.3.0
Requires-Dist: spatialdata-plot>=0.2.10
Requires-Dist: spatialdata>=0.4.0
Requires-Dist: typer>=0.9.0
Provides-Extra: baysor
Requires-Dist: loompy>=3.0.7; extra == 'baysor'
Requires-Dist: toml>=0.10.2; extra == 'baysor'
Provides-Extra: cellpose
Requires-Dist: cellpose>=3.0.5; extra == 'cellpose'
Requires-Dist: opencv-python>=4.8.0; extra == 'cellpose'
Requires-Dist: torch>=2.1.1; extra == 'cellpose'
Provides-Extra: stardist
Requires-Dist: multiscale-spatial-image<2.0.3; extra == 'stardist'
Requires-Dist: numpy<2.0.0; extra == 'stardist'
Requires-Dist: spatial-image<1.2.2; extra == 'stardist'
Requires-Dist: spatialdata<0.5.0; extra == 'stardist'
Requires-Dist: stardist>=0.9.1; extra == 'stardist'
Requires-Dist: tensorflow>=2.18.0; extra == 'stardist'
Provides-Extra: wsi
Requires-Dist: tiffslide>=2.3.1; extra == 'wsi'
Requires-Dist: torch>=2.1.1; extra == 'wsi'
Requires-Dist: torchvision>=0.20.0; extra == 'wsi'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/gustaveroussy/sopa/main/docs/assets/sopa.png" alt="sopa_logo" width="250"/>
</p>
<p align="center"><b><i>
	Spatial omics pipeline and analysis
</b></i></p>

<div align="center">

[![PyPI](https://img.shields.io/pypi/v/sopa.svg)](https://pypi.org/project/sopa)
[![Downloads](https://static.pepy.tech/badge/sopa)](https://pepy.tech/project/sopa)
[![Docs](https://img.shields.io/badge/docs-mkdocs-blue)](https://gustaveroussy.github.io/sopa)
![Build](https://github.com/gustaveroussy/sopa/workflows/ci/badge.svg)
[![License](https://img.shields.io/pypi/l/sopa.svg)](https://github.com/gustaveroussy/sopa/blob/main/LICENSE)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

</div>

Built on top of [SpatialData](https://github.com/scverse/spatialdata), Sopa enables processing and analyses of spatial omics data with single-cell resolution (spatial transcriptomics or multiplex imaging data) using a standard data structure and output. We currently support the following technologies: Xenium, Visium HD, MERSCOPE, CosMx, PhenoCycler, MACSima, Molecular Cartography, and others. Sopa was designed for generability and low memory consumption on large images (scales to `1TB+` images).

## Documentation

Check [Sopa's documentation](https://gustaveroussy.github.io/sopa) to get started. It contains installation explanations, CLI/API details, and tutorials.

## Overview

The following illustration describes the main steps of `sopa`:

<p align="center">
  <img src="https://raw.githubusercontent.com/gustaveroussy/sopa/main/docs/assets/overview_white.png" alt="sopa_overview" width="100%"/>
</p>

## Installation

Sopa can be installed from `PyPI` on all OS, for any Python version from `3.10` to `3.13` (included). On a new environment, run the following command:
```sh
pip install sopa
```

> [!NOTE]
> See this [installation section](https://gustaveroussy.github.io/sopa/getting_started/) for more details about extras and other installations modes.

## Features
Sopa comes in four different flavours, each corresponding to a different use case:
- `API`: use directly `sopa` as a Python package for complete flexibility and customization
- `Snakemake pipeline`: choose a config, and run our pipeline on your spatial data in a couple of minutes
- `nf-core/sopa`: run Sopa with Nextflow (see [this repo](https://github.com/nf-core/sopa) and the corresponding [usage guide](https://nf-co.re/sopa/usage))
- `CLI`: use our command-line-interface for prototyping quickly your own pipeline

### API

Below is a minimal example of API usage. For a complete API description, please refer to the [documentation](https://gustaveroussy.github.io/sopa/tutorials/api_usage/).

```python
import sopa

sdata = sopa.io.xenium("path/to/data") # reading Xenium data

sopa.make_image_patches(sdata) # creating overlapping patches
sopa.segmentation.cellpose(sdata, "DAPI", diameter=30) # running cellpose segmentation
sopa.aggregate(sdata) # counting the transcripts inside the cells
```

### Snakemake pipeline

Clone our repository, choose a config [here](https://github.com/gustaveroussy/sopa/tree/main/workflow/config) (or create your own), and execute our pipeline locally or on a high-performance cluster:
```bash
git clone https://github.com/gustaveroussy/sopa.git
cd sopa/workflow
snakemake --configfile=/path/to/yaml_config --config data_path=/path/to/data_directory --cores 1 --use-conda
```

For more details on `snakemake` configuration and how to properly setup your environments, please refer to the [documentation](https://gustaveroussy.github.io/sopa/tutorials/snakemake/).

### CLI

Below are examples of commands that can be run with the `sopa` CLI. For a complete description of the CLI, please refer to the [documentation](https://gustaveroussy.github.io/sopa/tutorials/cli_usage/).

```bash
> sopa --help # show command names and arguments
> sopa convert merscope_directory --technology merscope # read some data
> sopa patchify image merscope_directory.zarr # make patches for low-memory segmentation
> sopa segmentation cellpose merscope_directory.zarr --diameter 60 --channels DAPI # segmentation
> sopa resolve cellpose merscope_directory.zarr # resolve segmentation conflicts at boundaries
> sopa aggregate merscope_directory.zarr --average-intensities # transcripts/channels aggregation
> sopa explorer write merscope_directory.zarr # convert for interactive vizualisation
```

## Cite us
Our article is published in [Nature Communications](https://www.nature.com/articles/s41467-024-48981-z). You can cite Sopa as below:

```txt
@article{blampey_sopa_2024,
	title = {Sopa: a technology-invariant pipeline for analyses of image-based spatial omics},
	volume = {15},
	url = {https://www.nature.com/articles/s41467-024-48981-z},
	doi = {10.1038/s41467-024-48981-z},
	journal = {Nature Communications},
	author = {Blampey, Quentin and Mulder, Kevin and Gardet, Margaux and Christodoulidis, Stergios and Dutertre, Charles-Antoine and André, Fabrice and Ginhoux, Florent and Cournède, Paul-Henry},
	year = {2024},
	note = {Publisher: Nature Publishing Group},
	pages = {4981},
}
```
