Metadata-Version: 2.3
Name: cellpax
Version: 0.0.1
Summary: Cell feature universe analysis for connectomics
Author: Casey Schneider-Mizell
Author-email: Casey Schneider-Mizell <caseysm@gmail.com>
Classifier: License :: OSI Approved :: MIT License
Requires-Dist: crepes>=0.9
Requires-Dist: datafolio>=2.3
Requires-Dist: diptest>=0.8
Requires-Dist: igraph>=1.0.0
Requires-Dist: joblib>=1.5
Requires-Dist: leidenalg>=0.11.0
Requires-Dist: numpy>=1.26
Requires-Dist: polars>=1.0.0
Requires-Dist: scipy>=1.14
Requires-Dist: scikit-learn>=1.6
Requires-Dist: anndata>=0.10 ; extra == 'anndata'
Requires-Dist: fastapi>=0.115 ; extra == 'app'
Requires-Dist: uvicorn>=0.32 ; extra == 'app'
Requires-Dist: mapie>=1.5 ; extra == 'conditional'
Requires-Dist: cvxpy>=1.7 ; extra == 'conditional'
Requires-Dist: umap-learn>=0.5 ; extra == 'embeddings'
Requires-Dist: pacmap>=0.8 ; extra == 'embeddings'
Requires-Dist: pacmap>=0.8 ; extra == 'pacmap'
Requires-Dist: umap-learn>=0.5 ; extra == 'umap'
Requires-Python: >=3.11
Provides-Extra: anndata
Provides-Extra: app
Provides-Extra: conditional
Provides-Extra: embeddings
Provides-Extra: pacmap
Provides-Extra: umap
Description-Content-Type: text/markdown

# cellpax

Flexible, polars-native cell feature clustering for connectomics. You hold one
`FeatureTable`, mask subsets, preprocess heavy-tailed features, run consensus
clustering, turn cuts into clear named labels, compare approaches, and save the
whole analysis to a DataFolio.

## Setup

This project uses `uv` for dependency management and `poe` for task running.

```bash
# During DataFolio development, uv uses the editable sibling checkout ../datafolio.
uv sync
poe lab        # Jupyter Lab
poe test       # pytest with coverage
```

## Quick start

```python
import polars as pl
from cellpax import FeatureTable, compare

ft = FeatureTable(cells_df, features=[...], feature_metadata=meta)
ft.define_features("axon", family="axon")
ft.add_mask("l23", pl.col("layer") == "L2/3")
ft.preprocess()                                   # ihs heavy-tail transform

ft.cluster("l23", columns="axon", n_neighbors=(30,), name="run")
labels = ft.label("run", mask="l23", distance_threshold=0.6, name="subclass")
labels.rename({0: "L2a", 1: "L2b"})
ft.attach(labels)

L = labels.to_enum("Subclass")                    # IntEnum: filter with autocomplete
ft.dataframe("l23").filter(pl.col("subclass_id") == L.L2a)

ft.save(folio, "l23it")                            # many analyses per folio
```

## What's here

- **`FeatureTable`** — polars container with hierarchical masks, composable
  feature collections, and `dataframe(mask, scaled=…)` raw/normalized views.
- **`preprocess`** — heavy-tail (`ihs`) skew screening, fit per mask.
- **clustering** — fauxnograph kNN/Leiden consensus + `SimilarityMatrix`, with a
  hierarchy toolkit (`merge_support`, nested labels, per-cell stability) for
  choosing cuts, and deterministic-by-default seeds derived from the table.
- **`LabelSet`** — clear, relabelable clusters with `IntEnum` bindings.
- **`compare`** — ARI/NMI/FMI/Jaccard, contingency, alluvial across labelings.
- **persistence** — first-class DataFolio `save`/`load`, namespaced, many per folio.

See the [documentation](https://ceesem.github.io/cellpax/) (`poe doc-preview`),
`DESIGN_PROPOSAL.md` for the architecture and rationale, and the tutorial to build
an analysis end to end.
