# COZIpy - Neighbor preference analysis with a conditional z-score
![License](https://img.shields.io/badge/license-MIT-green)

COZI is a python package for neighbor preference (NEP) analysis of cell type labelled spatial data. As described in [Schiller *et al.* bioRxiv 2025](https://doi.org/10.1101/2025.03.31.646289), 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:
```bash
# 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:
```bash
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](https://doi.org/10.1101/2025.03.31.646289).

### Tutorial

Check the [Tutorial](https://github.com/SchapiroLabor/COZIpy/blob/main/tutorial/cozipy_tutorial.ipynb) 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](https://github.com/schapirolabor/COZIpy/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](https://github.com/BodenmillerGroup/imcRtools) or [Squidpy](https://github.com/scverse/squidpy/pull/1023) 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
