Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/dcjones/proseg

Probabilistic cell segmentation for in situ spatial transcriptomics
https://github.com/dcjones/proseg

Last synced: 18 days ago
JSON representation

Probabilistic cell segmentation for in situ spatial transcriptomics

Awesome Lists containing this project

README 

        

# Proseg



Proseg (**pro**babilistic **seg**mentation) is a cell segmentation method for in

situ spatial transcriptomics. Xenium, CosMx, and MERSCOPE platforms are

currently supported.



![](https://github.com/dcjones/proseg/blob/main/figure.png)



# Installing



Proseg can be built and installed with cargo. Clone this repository, then run



```shell

cargo install proseg

```



# General usage



Proseg is run on a table of transcript positions which in some form must include

preliminary assignments of transcripts to nuclei. Xenium, CosMx, and MERSCOPE

all provide this out of the box in some form.



Proseg is invoked, at minimum like:



```shell

proseg /path/to/transcripts.csv.gz

```



There are command line arguments to tell it which columns in the csv file to use,

but typically one of the presets `--xenium`, `--cosmx`, or `--merfish` are used.



Proseg is a sampling method, and in its current form in non-deterministic. From

run to run, results will vary slightly.



## General options



By default proseg will use all available CPU cores. To change this use `--nthreads N`.



## Output options



Output is in the form of a number of tables, which can be either gzipped csv files

or parquet files, and [GeoJSON](https://geojson.org/) files giving cell boundaries.



  * `--output-expected-counts expected-counts.csv.gz`: Cell-by-gene count matrix. Proseg is a sampling method, so these are posterior expectations that will generally not be integers but fractional counts.

  * `--output-cell-metadata cell-metadata.csv.gz`: Cell centroids, volume, and other information.

  * `--output-transcript-metadata transcript-metadata.csv.gz`: Transcript ids, genes, revised positions, assignment probability, etc.

  * `--output-gene-metadata`: Per-gene summary statistics

  * `--output-rates rates.csv.gz`: Cell-by-gene Poisson rate parameters. These are essentially expected relative expression values, but may be too overly-smoothed for use in downstream analysis.



Cell boundaries can be output a number of ways:



  * `--output-cell-polygons cell-polygons.geojson.gz`: 2D polygons for each cell in GeoJSON format. These are flattened from 3D, so will overlap.

  * `--output-cell-polygon-layers cell-polygons-layers.geojson.gz`: Output a separate, non-overlapping cell polygon for each z-layer, preserving 3D segmentation.

  * `--output-cell-hulls cell-hulls.geojson.gz`: Instead of inferred cell polygons, output convex hulls around assigned transcripts.

  * `--output-cell-voxels cell-voxels.csv.gz`: Output a (very large) table giving the coordinates and cell assignment of every assigned voxel.



## Modeling assumptions



A number of options can alter assumptions made by the model, which generally should

not need



  * `--ncomponents 5`: Cell gene expression is a modeled as a mixture of negative binomial distributions. This parameter controls the number of mixture components. More components will tend to nudge the cells into more distinct types, but setting it too high risks manifesting cell types that are not real.

  * `--no-diffusion`: By default Proseg models cells as leaky, under the assumption that some amount of RNA leaks from cells and diffuses elsewhere. This seems to be the case in much of the Xenium data we've seen, but could be a harmfully incorrect assumption in some data. This argument disables that part of the model.

  * `--diffusion-probability`: Prior probability of a transcript is diffused and should be repositioned.

  * `--diffusion-sigma-far`: Prior standard deviation on transcript repositioning distance.

  * `--voxel-layers 4`: Number of layers of voxels on the z-axis to use. Essentially how 3D the segmentation should be.

  * `--initial-voxel-size 4`: Initial side length of voxels on the xy-axis.

  * `--schedule 150,150,300`: A comma separated list of numbers giving the sampling schedule. The sampler runs for a given number of iterations, halves the voxel size, then runs for the next number of iterations.

  * `--nuclear-reassignment_prob 0.2`: Prior probability that the initial nuclear assignment (if any) is incorrect.

  * `--perimeter-bound 1.3`: Larger numbers allow less spherical cells.



# Running on Xenium datasets



Xenium data should be run with the `--xenium` argument.



## Using Xenium Explorer with `proseg-to-baysor`



It is possible to use proseg segmentation with Xenium Explorer, but requires a

little work.



The [xeniumranger](https://www.10xgenomics.com/support/software/xenium-ranger) tool has a

command to import segmentation from [Baysor](https://github.com/kharchenkolab/Baysor). To use this,

we must first convert Proseg output to Baysor-compatible formatting.



For this we need transcript metadata and cell polygons from Proseg, then run the provided `proseg-to-baysor`

command like



```shell

proseg-to-baysor \

    transcript-metadata.csv.gz \

    cell-polygons.geojson.gz \

    --output-transcript-metadata baysor-transcript-metadata.csv \

    --output-cell-polygons baysor-cell-polygons.geojson

```



[Xenium

Ranger](https://www.10xgenomics.com/support/software/xenium-ranger/latest) can

then be run to import these into a format useable with Xenium Explorer:



```shell

xeniumranger import-segmentation \

    --id project-id \

    --xeinum-bundle /path/to/original/xenium/output \

    --viz-polygons baysor-cell-polygons.geojson \

    --transcript-assignment baysor-transcript-metadata.csv \

    --units microns

```



This will output a new Xenium bundle under the `project-id` directory



~~Xenium Explorer currently has issues displaying Proseg polygons. It appears to

perform some sort of naive polygon simplification that results in profoundly

distorted polygons. There's not any known workaround for this issue for now.~~



Issues displaying proseg polygons in Xenium Explorer are resolved with more

recent versions of Xenium Ranger (starting with 2.0).



# Running on CosMx datasets



Earlier versions of CosMx did not automatically provide a single table of global

transcript positions. To work around this, we provide a Julia program in

`extra/stitch-cosmx.jl` to construct a table from the flat files downloaded from

AtoMx.



To run this, some dependencies are required, which can be installed with

```shell

julia -e 'import Pkg; Pkg.add(["Glob", "CSV", "DataFrames", "CodecZlib", "ArgParse"])'

```



Then the program can be run with like

```shell

julia stitch-cosmx.jl /path/to/cosmx-flatfiles transcripts.csv.gz

```

to output a complete transcripts table to `transcripts.csv.gz`.



From here proseg can be run with

```shell

proseg --cosmx-micron transcripts.csv.gz

```



Alternatively, the `--cosmx` can be used with CosMx data that is in pixel coordinates.

It will automatically scale the data to micrometers.



# Running on MERSCOPE datasets



No special considerations are needed for MERSCOPE data. Simply use the

`--merscope` argument with the `detected_transcripts.csv.gz` file.