Metadata-Version: 2.4
Name: InterSCellar
Version: 0.1.0
Summary: Surface-based Cell Neighbor Detection and Interscellar Volume Computation for 2D & 3D Spatial Omics
Author-email: Eunice Yewon Lee <yl888@duke.edu>
License: MIT
Project-URL: Homepage, https://github.com/euniceyl/InterSCellar
Project-URL: Repository, https://github.com/euniceyl/InterSCellar
Project-URL: Issues, https://github.com/euniceyl/InterSCellar/issues
Keywords: spatial-omics,cell-neighbors,cell-interactions,cell-cell-communication,intercellular,single-cell,transcriptomics,proteomics,metabolomics,bioinformatics,computational-biology,visualization,3d
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: tqdm>=4.62.0
Requires-Dist: opencv-python>=4.5.0
Requires-Dist: dask[array]>=2021.0.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: scikit-image>=0.18.0
Requires-Dist: seaborn>=0.11.0
Requires-Dist: napari>=0.4.0
Requires-Dist: zarr>=2.10.0
Requires-Dist: anndata>=0.8.0
Requires-Dist: duckdb>=0.6.0
Provides-Extra: anndata
Requires-Dist: anndata>=0.8.0; extra == "anndata"
Provides-Extra: duckdb
Requires-Dist: duckdb>=0.6.0; extra == "duckdb"
Provides-Extra: all
Requires-Dist: anndata>=0.8.0; extra == "all"
Requires-Dist: duckdb>=0.6.0; extra == "all"
Dynamic: license-file

# InterSCellar
[![PyPI](https://img.shields.io/pypi/v/interscellar?logo=pypi&logoColor=blue)](https://pypi.org/project/interscellar/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

**InterSCellar** is a Python package for surface-Based cell neighborhood and interaction volume analysis in 3D spatial omics.

![Package workflow](https://raw.githubusercontent.com/euniceyl/InterSCellar/main/docs/images/package_workflow.jpeg)

## Installation

**Install package:**
```sh
pip install interscellar
```

## Usage

**Import:**
```sh
import interscellar
```

### 3D Pipeline:

**(1) Cell Neighbor Detection & Graph Construction**
```sh
neighbors_3d, adata, conn = interscellar.find_cell_neighbors_3d(
    ome_zarr_path="data/segmentation.zarr",
    metadata_csv_path="data/cell_metadata.csv",
    max_distance_um=0.5,
    voxel_size_um=(0.56, 0.28, 0.28),
    n_jobs=4
)
```

**(2) Interscellar Volume Computation**
```sh
# Interscellar volumes
volumes_3d, adata, conn = interscellar.compute_interscellar_volumes_3d(
    ome_zarr_path="data/segmentation.zarr",
    neighbor_pairs_csv="results/neighbors_3d.csv",
    neighbor_db_path="/results/neighbor_graph.db",
    voxel_size_um=(0.56, 0.28, 0.28),
    max_distance_um=3.0,
    intracellular_threshold_um=1.0,
    n_jobs=4
)
```

```sh
# Cell-only volumes
cellonly_3d = interscellar.compute_cell_only_volumes_3d(
    ome_zarr_path="data/segmentation.zarr",
    interscellar_volumes_zarr="results/interscellar_volumes.zarr"
)
```

### 2D Pipeline:

**(1) Cell Neighbor Detection & Graph Construction**
```sh
neighbors_2d, adata, conn = interscellar.find_cell_neighbors_2d(
    polygon_json_path="data/cell_polygons.json",
    metadata_csv_path="data/cell_metadata.csv",
    max_distance_um=1.0,
    pixel_size_um=0.1085,
    n_jobs=4
)
```

### Utilities:

**Volume Visualization**
```sh
# Full dataset (Napari)
visualize-all-3d \
  --cell-only-zarr "results/cell_only_volumes.zarr" \
  --interscellar-zarr "results/interscellar_volumes.zarr" \
  --cell-only-opacity 0.7 \
  --interscellar-opacity 0.9
```

```sh
# Single pair (Napari)
visualize-pair-3d \
  --pair-id 123 \
  --cell-only-zarr "results/cell_only_volumes.zarr" \
  --interscellar-zarr "results/interscellar_volumes.zarr" \
  --pair-opacity 0.6 \
  --cells-opacity 0.7
```
