Assign cells from Xenium bundle to cells segmented from any other image segmentation pipeline using polygon parquet file. It can be used for datasets which are aligned with global affine transformation if transformation matrix is provided.
The repository performs one-to-one matching between Xenium cells and external segmentation results based on transformed polygon centroids, simply by finding the closest cells and assigning them with upper limit that can be set.
Clone the repository
git clone https://github.com/<username>/cell-assignment.git
cd cell-assignmentCreate a Conda environment
conda env create -f environment.yml
conda activate cell_assignmentThe program requires
- Xenium output bundle
- H&E segmentation polygons (Parquet)
- H&E OME-TIFF image
- Maximum allowed distance between each assigned cell pair
- Affine transformation matrix (optional). Has to be simply csv with matrix 3x3
Basic usage
python bin/assign_cells.py \
--xenium_bundle_path <xenium_bundle> \
--image_path <he_image.ome.tif> \
--polygons_parquet_path <he_polygons.parquet> \
--output_matches_csv matches.csvTwo example workflows are included.
Demonstrates matching Xenium cells to StarDist segmentation after affine registration. Please nto that depending on direction of reigstration you may use True or False values for invert_matrix. Exam
Demonstrates matching Xenium cells to an alternative segmentation saved (probably with XeniumRanger) in Xenium bundle format. Idea here that one can use parquet file "cell_boundaries.parquet" and image "morphology.ome.tif" directly from second xenium bundle directory
Both example can be found in folder "examples"
The program generates
- matched cell table (.csv)
- unmatched Xenium cell IDs (.txt, optional)
- unmatched H&E cell IDs (.txt, optional)
The matching table contains
| Column | Description |
|---|---|
| cell_id_xenium | Xenium cell identifier |
| cell_id_he | External segmentation cell identifier |
| distance_um | Centroid distance after matching |
- Read Xenium polygons.
- Read external segmentation polygons.
- Compute polygon centroids.
- Apply the affine transformation (if supplied).
- Convert coordinates into H&E full-resolution pixels.
- Build a KD-tree for efficient neighbour search.
- Perform greedy one-to-one centroid matching within a defined maximum distance.
This project is distributed under the MIT License. See the LICENSE file for details.