Metadata-Version: 2.4
Name: densr
Version: 0.1.3
Summary: Density-Aware Spatial Randomization (DenSR) generates realistic null models for object-based colocalization analysis.
Author: Sudharsan Kannan
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=1.5
Requires-Dist: scipy>=1.9
Requires-Dist: trimesh>=3.20
Requires-Dist: rtree>=1.0
Requires-Dist: libigl>=2.5
Requires-Dist: plotly>=5.0
Requires-Dist: kaleido>=0.2.1

# DenSR

DenSR provides density-aware spatial randomization using KDE-weighted sampling within a 3D cell mesh, plus object-based colocalization analysis for observed RNA spot coordinates, UniSR, and DenSR.

## Cite this package

```
Kannan, S., Voelker, T. L., Snyder, B. S., & Robertson, G. A. (2026). Density-Aware Spatial Randomization (DenSR) generates realistic null models for object-based colocalization analysis. Molecular Biology of the Cell, 37(6), mr6.
```

## Install

```bash
pip install densr
```

## Usage

```python
from densr import densr

spots1 = "path/to/folder/C1_1a_xyz.txt"
spots2 = "path/to/folder/C1_1b_xyz.txt"
object = "path/to/folder/C1_volume.obj"
colocalization_threshold = 1

results = densr(
    spots1=spots1,
    spots2=spots2,
    object=object,
    colocalization_threshold=colocalization_threshold,
)
```

The RNA spot files are read as tab-separated text files, and the first three columns are used as x, y, and z coordinates.
The `densr(...)` call displays the results table and spot plot automatically.

## Built-in sample data

```python
from densr import densr, sample_data

sample = sample_data()

results = densr(
    spots1=sample.spots1,
    spots2=sample.spots2,
    object=sample.object,
    colocalization_threshold=0.25,
)
```

## Command line

```bash
densr C1_volume.obj C1_1a_xyz.txt C1_1b_xyz.txt --colocalization-threshold 1
```

## functions
- `densr(spots1, spots2, object, colocalization_threshold=1)`: one-line DenSR analysis using RNA spot files and a 3D cell mesh file.
- `sample_data()`: return file paths for the built-in DenSR sample data.
