COZIpy - Neighbor preference analysis with a conditional z-score

COZI is a python package for neighbor preference (NEP) analysis of cell type labelled spatial data. As described in Schiller et al. bioRxiv 2025, COZI is one optimized flavor of neighbor preference analysis and infers directional neighbor preferences based on label permutations.

Installation

Option 1. Clone the repository

If you plan to develop or modify COZIpy, install it in editable mode:

# Clone the repository
git clone https://github.com/SchapiroLabor/COZIpy
cd COZIpy

# (Optional) create the conda environment
conda env create -f env.yml
conda activate cozi-env

# Install in editable/development mode
pip install -e .

Option 2. Install from PyPI

Directly install with pip:

pip install cozipy

How to run COZIpy

Description

COZI requires x and y-coordinates and cell type label information as input. The function allows the definition of three different neighborhoods, namely k-nearest neighbor, radius and delaunay. COZI outputs z-scores generated by comparing the observed against the expected neighbor counts between cell types. The counts themselves are normalized by the number of cells of type A with at least one neighbor of type B (termed conditional normalization). It also outputs the conditional cell ratio, so the ratio of cells of type A that actually neighbor cells of type B. For more methodological details, please refer to Schiller et al. bioRxiv 2025.

Tutorial

Check the Tutorial for a code example.

Contributing

Contributions, issues, and feature requests are welcome!
Feel free to open a pull request or submit an issue on GitHub Issues.

Before submitting a PR:

• Run tests
• Follow existing code style and documentation patterns

Citing

If you use COZIpy or any other COZI implementation in IMCRtools or Squidpy in your work, please cite:

Schiller, C. Comparison and Optimization of Cellular Neighbor Preference Methods for Quantitative Tissue Analysis., https://doi.org/10.1101/2025.03.31.646289, bioRxiv, 2025