# SegmentaTion AwaRe cLusterING (STARLING)
![build](https://github.com/camlab-bioml/starling/actions/workflows/main.yml/badge.svg)
![](https://img.shields.io/badge/Python-3.9-blue)
![](https://img.shields.io/badge/Python-3.10-blue)
![](https://img.shields.io/badge/Python-3.11-blue)
![](https://img.shields.io/badge/Python-3.12-blue)
STARLING is a probabilistic model for clustering cells measured with spatial expression assays (e.g. IMC, MIBI, etc...) while accounting for segmentation errors.
It outputs:
1. Clusters that account for segmentation errors in the data (i.e. should no longer show implausible marker co-expression)
2. Assignments for every cell in the dataset to those clusters
3. A segmentation error probability for each cell
A **preprint** describing the method and introducing a novel benchmarking workflow is available: [Lee et al. (2024) _Segmentation error aware clustering for highly multiplexed imaging_](https://www.biorxiv.org/content/10.1101/2024.02.29.582827v1)
A **tutorial** outlining basic usage is available [here][tutorial].
![Model](https://github.com/camlab-bioml/starling/raw/main/starling-schematic600x.png)
## Requirements
Python 3.9 or 3.10 are required to run starling. If your current version of python is not one of these, we recommend using [pyenv](https://github.com/pyenv/pyenv) to install a compatible version alongside your current one. Alternately, you could use the Docker configuration described below.
## Installation
### Install with pip
`pip install biostarling` and then import the module `from starling import starling`
### Building from source
Starling can be cloned and installed locally (typically <10 minutes) via the Github repository,
```
git clone https://github.com/camlab-bioml/starling.git && cd starling
```
After cloning the repository, the next step is to install the required dependencies. There are three recommended methods:
### 1. Use `requirements.txt` and your own virtual environment:
We use virtualenvwrapper (4.8.4) to create and activated a standalone virtual environment for _starling_:
```
pip install virtualenvwrapper==4.8.4
mkvirtualenv starling
```
For convenience, one can install packages in the tested environment:
```
pip install -r requirements.txt
```
The virtual environment can be activated and deactivated subsequently:
```
workon starling
deactivate
```
### 2. Use Poetry and `pyproject.toml`.
[Poetry](https://python-poetry.org/) is a packaging and dependency management tool can simplify code development and deployment. If you do not have Poetry installed, you can find instructions [here](https://python-poetry.org/docs/).
Once poetry is installed, navigate to the `starling` directory and run `poetry install`. This will download the required packages into a virtual environment and install Starling in development mode. The location and state of the virtual environment may depend on your system. For more details, see [the documentation](https://python-poetry.org/docs/managing-environments/).
### 3. Use Docker
If you have Docker installed on your system, you can run `docker build -t starling .` from the project root in order to build the image locally. You can then open a shell within the image with a command like `docker run --rm -it starling bash`.
## Getting started
With starling installed, please proceed to the [online documentation][docs] or launch the [interactive notebook tutorial][tutorial] to learn more about the package's features.
## Authors
This software is authored by: Jett (Yuju) Lee, Conor Klamann, Kieran R Campbell
Lunenfeld-Tanenbaum Research Institute & University of Toronto
<!-- github-only -->
[tutorial]: https://colab.research.google.com/github/camlab-bioml/starling/blob/main/docs/source/tutorial/getting-started.ipynb
[license]: https://github.com/camlab-bioml/starling/blob/main/LICENSE
[docs]: https://camlab-bioml.github.io/starling/
Raw data
{
"_id": null,
"home_page": "https://github.com/camlab-bioml/starling",
"name": "biostarling",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.9",
"maintainer_email": null,
"keywords": "imaging cytometry classifier single-cell",
"author": "Jett (Yuju) Lee",
"author_email": "yulee@lunenfeld.ca",
"download_url": "https://files.pythonhosted.org/packages/7d/8c/5ed2b20988807ded51d1a3873111895b45340278bd1985d332e38a39c6ba/biostarling-0.1.4.tar.gz",
"platform": null,
"description": "# SegmentaTion AwaRe cLusterING (STARLING)\n\n![build](https://github.com/camlab-bioml/starling/actions/workflows/main.yml/badge.svg)\n![](https://img.shields.io/badge/Python-3.9-blue)\n![](https://img.shields.io/badge/Python-3.10-blue)\n![](https://img.shields.io/badge/Python-3.11-blue)\n![](https://img.shields.io/badge/Python-3.12-blue)\n\n\nSTARLING is a probabilistic model for clustering cells measured with spatial expression assays (e.g. IMC, MIBI, etc...) while accounting for segmentation errors.\n\nIt outputs:\n1. Clusters that account for segmentation errors in the data (i.e. should no longer show implausible marker co-expression)\n2. Assignments for every cell in the dataset to those clusters\n3. A segmentation error probability for each cell\n\nA **preprint** describing the method and introducing a novel benchmarking workflow is available: [Lee et al. (2024) _Segmentation error aware clustering for highly multiplexed imaging_](https://www.biorxiv.org/content/10.1101/2024.02.29.582827v1)\n\nA **tutorial** outlining basic usage is available [here][tutorial].\n\n![Model](https://github.com/camlab-bioml/starling/raw/main/starling-schematic600x.png)\n\n## Requirements\n\nPython 3.9 or 3.10 are required to run starling. If your current version of python is not one of these, we recommend using [pyenv](https://github.com/pyenv/pyenv) to install a compatible version alongside your current one. Alternately, you could use the Docker configuration described below.\n\n## Installation\n\n### Install with pip\n\n`pip install biostarling` and then import the module `from starling import starling`\n\n### Building from source\n\nStarling can be cloned and installed locally (typically <10 minutes) via the Github repository,\n\n```\ngit clone https://github.com/camlab-bioml/starling.git && cd starling\n```\n\nAfter cloning the repository, the next step is to install the required dependencies. There are three recommended methods:\n\n### 1. Use `requirements.txt` and your own virtual environment:\n\nWe use virtualenvwrapper (4.8.4) to create and activated a standalone virtual environment for _starling_:\n\n```\npip install virtualenvwrapper==4.8.4\nmkvirtualenv starling\n```\n\nFor convenience, one can install packages in the tested environment:\n\n```\npip install -r requirements.txt\n```\n\nThe virtual environment can be activated and deactivated subsequently:\n\n```\nworkon starling\ndeactivate\n```\n\n### 2. Use Poetry and `pyproject.toml`.\n\n[Poetry](https://python-poetry.org/) is a packaging and dependency management tool can simplify code development and deployment. If you do not have Poetry installed, you can find instructions [here](https://python-poetry.org/docs/).\n\nOnce poetry is installed, navigate to the `starling` directory and run `poetry install`. This will download the required packages into a virtual environment and install Starling in development mode. The location and state of the virtual environment may depend on your system. For more details, see [the documentation](https://python-poetry.org/docs/managing-environments/).\n\n\n### 3. Use Docker\n\nIf you have Docker installed on your system, you can run `docker build -t starling .` from the project root in order to build the image locally. You can then open a shell within the image with a command like `docker run --rm -it starling bash`.\n\n## Getting started\n\nWith starling installed, please proceed to the [online documentation][docs] or launch the [interactive notebook tutorial][tutorial] to learn more about the package's features.\n\n## Authors\n\nThis software is authored by: Jett (Yuju) Lee, Conor Klamann, Kieran R Campbell\n\nLunenfeld-Tanenbaum Research Institute & University of Toronto\n\n<!-- github-only -->\n\n[tutorial]: https://colab.research.google.com/github/camlab-bioml/starling/blob/main/docs/source/tutorial/getting-started.ipynb\n[license]: https://github.com/camlab-bioml/starling/blob/main/LICENSE\n[docs]: https://camlab-bioml.github.io/starling/\n\n",
"bugtrack_url": null,
"license": "See License.txt",
"summary": "Segmentation error aware clustering single-cell spatial expression data",
"version": "0.1.4",
"project_urls": {
"Homepage": "https://github.com/camlab-bioml/starling",
"Repository": "https://github.com/camlab-bioml/starling"
},
"split_keywords": [
"imaging",
"cytometry",
"classifier",
"single-cell"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d8247304844bbdf0e6cb171233bad79ea30acc1074199359d9c35596829b77de",
"md5": "c5e2390b5f82d0493812591fa3f52f89",
"sha256": "58999c8ecae495a318dd3c781d0ba44a373bd90cf400ac9e789beeb2a54e6b59"
},
"downloads": -1,
"filename": "biostarling-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c5e2390b5f82d0493812591fa3f52f89",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.9",
"size": 15525,
"upload_time": "2024-08-16T14:34:23",
"upload_time_iso_8601": "2024-08-16T14:34:23.534525Z",
"url": "https://files.pythonhosted.org/packages/d8/24/7304844bbdf0e6cb171233bad79ea30acc1074199359d9c35596829b77de/biostarling-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7d8c5ed2b20988807ded51d1a3873111895b45340278bd1985d332e38a39c6ba",
"md5": "5a89b67e7e6d287082024f3dda10304a",
"sha256": "7e22cc1689215d0c7f2c2c8456ce0260cab77dc498200fee5b1f920830dcc607"
},
"downloads": -1,
"filename": "biostarling-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "5a89b67e7e6d287082024f3dda10304a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.9",
"size": 16140,
"upload_time": "2024-08-16T14:34:25",
"upload_time_iso_8601": "2024-08-16T14:34:25.071646Z",
"url": "https://files.pythonhosted.org/packages/7d/8c/5ed2b20988807ded51d1a3873111895b45340278bd1985d332e38a39c6ba/biostarling-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-16 14:34:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "camlab-bioml",
"github_project": "starling",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "aiohappyeyeballs",
"specs": [
[
"==",
"2.3.5"
]
]
},
{
"name": "aiohttp",
"specs": [
[
"==",
"3.10.3"
]
]
},
{
"name": "aiosignal",
"specs": [
[
"==",
"1.3.1"
]
]
},
{
"name": "anndata",
"specs": [
[
"==",
"0.10.8"
]
]
},
{
"name": "array-api-compat",
"specs": [
[
"==",
"1.8"
]
]
},
{
"name": "async-timeout",
"specs": [
[
"==",
"4.0.3"
]
]
},
{
"name": "attrs",
"specs": [
[
"==",
"24.2.0"
]
]
},
{
"name": "colorama",
"specs": [
[
"==",
"0.4.6"
]
]
},
{
"name": "contourpy",
"specs": [
[
"==",
"1.2.1"
]
]
},
{
"name": "cycler",
"specs": [
[
"==",
"0.12.1"
]
]
},
{
"name": "decorator",
"specs": [
[
"==",
"5.1.1"
]
]
},
{
"name": "exceptiongroup",
"specs": [
[
"==",
"1.2.2"
]
]
},
{
"name": "fcsparser",
"specs": [
[
"==",
"0.2.8"
]
]
},
{
"name": "filelock",
"specs": [
[
"==",
"3.15.4"
]
]
},
{
"name": "flowcytometrytools",
"specs": [
[
"==",
"0.5.1"
]
]
},
{
"name": "flowsom",
"specs": [
[
"==",
"0.1.1"
]
]
},
{
"name": "fonttools",
"specs": [
[
"==",
"4.53.1"
]
]
},
{
"name": "frozenlist",
"specs": [
[
"==",
"1.4.1"
]
]
},
{
"name": "fsspec",
"specs": [
[
"==",
"2024.6.1"
]
]
},
{
"name": "fsspec",
"specs": [
[
"==",
"2024.6.1"
]
]
},
{
"name": "get-annotations",
"specs": [
[
"==",
"0.1.2"
]
]
},
{
"name": "h5py",
"specs": [
[
"==",
"3.11.0"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.7"
]
]
},
{
"name": "igraph",
"specs": [
[
"==",
"0.11.6"
]
]
},
{
"name": "importlib-resources",
"specs": [
[
"==",
"6.4.0"
]
]
},
{
"name": "jinja2",
"specs": [
[
"==",
"3.1.4"
]
]
},
{
"name": "joblib",
"specs": [
[
"==",
"1.4.2"
]
]
},
{
"name": "kiwisolver",
"specs": [
[
"==",
"1.4.5"
]
]
},
{
"name": "legacy-api-wrap",
"specs": [
[
"==",
"1.4"
]
]
},
{
"name": "leidenalg",
"specs": [
[
"==",
"0.10.2"
]
]
},
{
"name": "lightning-utilities",
"specs": [
[
"==",
"0.11.6"
]
]
},
{
"name": "llvmlite",
"specs": [
[
"==",
"0.43.0"
]
]
},
{
"name": "markupsafe",
"specs": [
[
"==",
"2.1.5"
]
]
},
{
"name": "matplotlib",
"specs": [
[
"==",
"3.9.1.post1"
]
]
},
{
"name": "minisom",
"specs": [
[
"==",
"2.3.2"
]
]
},
{
"name": "mpmath",
"specs": [
[
"==",
"1.3.0"
]
]
},
{
"name": "multidict",
"specs": [
[
"==",
"6.0.5"
]
]
},
{
"name": "natsort",
"specs": [
[
"==",
"8.4.0"
]
]
},
{
"name": "networkx",
"specs": [
[
"==",
"3.2.1"
]
]
},
{
"name": "numba",
"specs": [
[
"==",
"0.60.0"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"1.26.4"
]
]
},
{
"name": "nvidia-cublas-cu12",
"specs": [
[
"==",
"12.1.3.1"
]
]
},
{
"name": "nvidia-cuda-cupti-cu12",
"specs": [
[
"==",
"12.1.105"
]
]
},
{
"name": "nvidia-cuda-nvrtc-cu12",
"specs": [
[
"==",
"12.1.105"
]
]
},
{
"name": "nvidia-cuda-runtime-cu12",
"specs": [
[
"==",
"12.1.105"
]
]
},
{
"name": "nvidia-cudnn-cu12",
"specs": [
[
"==",
"9.1.0.70"
]
]
},
{
"name": "nvidia-cufft-cu12",
"specs": [
[
"==",
"11.0.2.54"
]
]
},
{
"name": "nvidia-curand-cu12",
"specs": [
[
"==",
"10.3.2.106"
]
]
},
{
"name": "nvidia-cusolver-cu12",
"specs": [
[
"==",
"11.4.5.107"
]
]
},
{
"name": "nvidia-cusparse-cu12",
"specs": [
[
"==",
"12.1.0.106"
]
]
},
{
"name": "nvidia-nccl-cu12",
"specs": [
[
"==",
"2.20.5"
]
]
},
{
"name": "nvidia-nvjitlink-cu12",
"specs": [
[
"==",
"12.6.20"
]
]
},
{
"name": "nvidia-nvtx-cu12",
"specs": [
[
"==",
"12.1.105"
]
]
},
{
"name": "packaging",
"specs": [
[
"==",
"24.1"
]
]
},
{
"name": "pandas",
"specs": [
[
"==",
"2.2.2"
]
]
},
{
"name": "patsy",
"specs": [
[
"==",
"0.5.6"
]
]
},
{
"name": "phenograph",
"specs": [
[
"==",
"1.5.7"
]
]
},
{
"name": "pillow",
"specs": [
[
"==",
"10.4.0"
]
]
},
{
"name": "psutil",
"specs": [
[
"==",
"6.0.0"
]
]
},
{
"name": "pynndescent",
"specs": [
[
"==",
"0.5.13"
]
]
},
{
"name": "pyparsing",
"specs": [
[
"==",
"3.1.2"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
"==",
"2.9.0.post0"
]
]
},
{
"name": "pytorch-lightning",
"specs": [
[
"==",
"2.4.0"
]
]
},
{
"name": "pytz",
"specs": [
[
"==",
"2024.1"
]
]
},
{
"name": "pyyaml",
"specs": [
[
"==",
"6.0.2"
]
]
},
{
"name": "scanpy",
"specs": [
[
"==",
"1.10.2"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
"==",
"1.5.1"
]
]
},
{
"name": "scipy",
"specs": [
[
"==",
"1.13.1"
]
]
},
{
"name": "seaborn",
"specs": [
[
"==",
"0.13.2"
]
]
},
{
"name": "session-info",
"specs": [
[
"==",
"1.0.0"
]
]
},
{
"name": "setuptools",
"specs": [
[
"==",
"72.1.0"
]
]
},
{
"name": "six",
"specs": [
[
"==",
"1.16.0"
]
]
},
{
"name": "statsmodels",
"specs": [
[
"==",
"0.14.2"
]
]
},
{
"name": "stdlib-list",
"specs": [
[
"==",
"0.10.0"
]
]
},
{
"name": "sympy",
"specs": [
[
"==",
"1.13.2"
]
]
},
{
"name": "texttable",
"specs": [
[
"==",
"1.7.0"
]
]
},
{
"name": "threadpoolctl",
"specs": [
[
"==",
"3.5.0"
]
]
},
{
"name": "torch",
"specs": [
[
"==",
"2.4.0"
]
]
},
{
"name": "torchmetrics",
"specs": [
[
"==",
"1.4.1"
]
]
},
{
"name": "tqdm",
"specs": [
[
"==",
"4.66.5"
]
]
},
{
"name": "triton",
"specs": [
[
"==",
"3.0.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
"==",
"4.12.2"
]
]
},
{
"name": "tzdata",
"specs": [
[
"==",
"2024.1"
]
]
},
{
"name": "umap-learn",
"specs": [
[
"==",
"0.5.6"
]
]
},
{
"name": "yarl",
"specs": [
[
"==",
"1.9.4"
]
]
},
{
"name": "zipp",
"specs": [
[
"==",
"3.20.0"
]
]
}
],
"lcname": "biostarling"
}