CosMxScope

CosMxScope is a lightweight Python utility module for working with image and coordinate outputs exported from the NanoString CosMx / AtoMx spatial transcriptomics platform.

The code focuses on three practical tasks commonly needed during downstream analysis:

1. Stitch CosMx field‑of‑view (FOV) images into a reconstructed slide image
2. Convert spatial coordinates into GeoJSON annotation files compatible with QuPath
3. Generate spatial visualizations of cells, transcripts, and gene expression

The module is implemented as a collection of Python functions in cosmxscope.py (previously cosmx_util.py). It does not currently provide a command‑line interface; functions are intended to be imported and executed from Python scripts or notebooks.

Main Capabilities

FOV stitching The function stitch_fov() reconstructs a large image by stitching individual CosMx FOV images exported from AtoMx. The function also produces:

- A stitched TIFF image
- A CSV file containing FOV positions after stitching
- A downsampled thumbnail image

GeoJSON export for QuPath Two functions convert spatial coordinates into GeoJSON annotation objects:

- `plg2gson()` converts cell segmentation polygons into QuPath annotations
- `tx2gson()` converts transcript coordinates for selected genes into
  MultiPoint GeoJSON annotations

Spatial visualization Several plotting utilities generate spatial visualizations on stitched or thumbnail images:

- `draw_fov()` – draw FOV boundaries
- `sp_celltype()` – visualize cells colored by cell type
- `sp_tx()` – plot transcript locations for selected genes
- `sp_goiExp_cell()` – plot expression of a gene at the cell level
- `sp_goiExp_fov()` – plot mean gene expression per FOV
- `sp_goiExp_fov_arc()` – color FOVs by transcript count

Input Files

The functions expect files exported from AtoMx/CosMx workflows, including for example:

• sample metadata table such as sample_metadata_file.csv.gz
• FOV coordinate table such as sample_fov_positions_file.csv.gz
• polygon coordinate tables such as sample-polygons.csv.gz
• transcript tables such as sample_tx_file.csv.gz
• directories containing FOV images (for example CellOverlay images)

Some functions expect specific column names such as:

• fov
• cell_id
• CenterX_local_px
• CenterY_local_px
• target (gene name)

Dependencies

The code imports the following Python packages:

numpy pandas polars matplotlib seaborn opencv-python tifffile geojson iteration_utilities [1] joblib

[1] iteration_utilities: compatible with python 3.12 or lower.

Install example dependencies with:

pip install numpy pandas polars matplotlib seaborn opencv-python tifffile geojson iteration_utilities joblib

Repository Structure

cosmxscope/ cosmxscope.py docs/ examples/ README.txt LICENSE CITATION.cff

License

See the LICENSE file included in the repository.