Metadata-Version: 2.5
Name: seq-lumen
Version: 0.0.1
Summary: A small package for lumen/luminal-structure detection only from centroids. Based on Reyes et al. 2026's method.
Project-URL: Documentation, https://seq-lumen.readthedocs.io/
Project-URL: Homepage, https://github.com/sail-mskcc/seq-lumen
Project-URL: Source, https://github.com/sail-mskcc/seq-lumen
Author: Ilan Gold
Maintainer-email: Ilan Gold <ilan.gold@scverse.org>
License: MIT License
        
        Copyright (c) 2026, Ilan Gold
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: anndata>=0.13
Requires-Dist: geopandas
Requires-Dist: numpy
Requires-Dist: opencv-python
Requires-Dist: pandas
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: session-info2
Requires-Dist: shapely
Requires-Dist: tqdm
Description-Content-Type: text/markdown

# seq-lumen

[![Tests][badge-tests]][tests]
[![Documentation][badge-docs]][documentation]

[badge-tests]: https://img.shields.io/github/actions/workflow/status/sail-mskcc/seq-lumen/test.yaml?branch=main
[badge-docs]: https://app.readthedocs.org/projects/seq-lumen/badge/

A small package for lumen/luminal-structure quantification only from centroids. Based on {cite}`Reyes2026`'s method for quantification, with some small (presumed) fixes.

## Getting started

Please refer to the [documentation][],
in particular, the [API documentation][].

```python
import seq_lumen
from anndata.acc import A

# Set up relevant accessors for each relevant field.
border_acc = A.obs["is_epithelial"]
# Only if needed with multiple samples
sample_acc = A.obs["sample_id"]
# Only if needed - the default check for centroids looks in obsm["spatial"]
# centroids_acc = A.obsm["X_spatial"]
assert seq_lumen.acc.centroids_acc in adata

# Resolve the parameters for quantification for all applicable samples, if present.
# This is much more robust than the defaults, which match Reyes et al.
sl_quantifier = seq_lumen.Quantifier.from_adata(adata, sample_acc=sample_acc)

# Each value of `lumen` is a `(n_lumen_points, 2)` array of luminal centroids and the key is the sample id.
# If no `sample_acc` is passed in, just a single ndarray is returned, calculated over all centroids/borders together.
lumen: dict[str, np.ndarray] = sl_quantifier(adata, border_acc=border_acc, sample_acc=sample_acc)

# Per-cell lumen scores and lumen ids are written to these default accessors (pass `count_acc`/`assignment_acc` to override in the above quantifier call)
assert seq_lumen.acc.count_acc in adata
assert seq_lumen.acc.assignment_acc in adata
```

## Divergences from the Original

There are a combination of fixes/divergences from the original code/paper, some bugs, some things being misreported.
These are indicated within the code and in the docstring of {class}`seq_lumen.Quantifier`.
If you wish to reproduce the {cite}`Reyes2026` paper's results exactly, go to the [paper's repo][].

[paper's repo]: https://github.com/dpeerlab/p53-niche-dynamics

## Installation

You need to have Python 3.12 or newer installed on your system.
If you don't have Python installed, we recommend installing [uv][].

We recommend managing dependencies in project-specific virtual environments to avoid dependency conflicts.
This is most convenient using package managers such as [uv][].
Choose from the options below to install seq-lumen:

<!--
1. Add the latest release of `seq-lumen` from [PyPI][] to your `uv` project:

   ```bash
   uv add seq-lumen
   ```

1. Install the latest release into a [standard virtual environment][venv]:

   ```bash
   (after activating your venv)
   pip install seq-lumen
   ```

-->

1. Install the latest development version:

   ```bash
   pip install seq-lumen  # (or `uv add`)
   ```

## Release notes

See the [changelog][].

## Contact

For questions and help requests, you can reach out in the [scverse discourse][].
If you found a bug, please use the [issue tracker][].

## Citation

Reyes, J., Del Priore, I., Chaikovsky, A. C., Pasnuri, N., Elhossiny, A. M., Park, J., Weiler, P., Krause, T., Moorman, A., Snopkowski, C., Takizawa, M., Burdziak, C., Ratnayeke, N., Masilionis, I., Ho, Y.-J., Chaligné, R., Romesser, P. B., Filliol, A., Nawy, T., … Lowe, S. W. (2026). Oncogenic and tumor-suppressive forces converge on a progenitor niche at the benign-to-malignant transition. Cell, 189(10), 2875–2897.e53. https://doi.org/10.1016/j.cell.2026.03.032

[uv]: https://github.com/astral-sh/uv
[scverse discourse]: https://discourse.scverse.org/
[issue tracker]: https://github.com/sail-mskcc/seq-lumen/issues
[tests]: https://github.com/sail-mskcc/seq-lumen/actions/workflows/test.yaml
[documentation]: https://seq-lumen.readthedocs.io
[changelog]: https://seq-lumen.readthedocs.io/page/changelog.html
[api documentation]: https://seq-lumen.readthedocs.io/page/api.html
[pypi]: https://pypi.org/project/seq-lumen
[venv]: https://docs.python.org/3/tutorial/venv.html
