cellstate-c2s 0.1.0__py3-none-any.whl

cellstate_c2s/__init__.py

@@ -0,0 +1,7 @@
+"""Deviation-from-reference gene ordering for Cell2Sentence cell-state prediction."""
+
+from .builder import DeviationSentenceBuilder
+from .c2s_adapter import replace_sentences
+
+__all__ = ["DeviationSentenceBuilder", "replace_sentences"]
+__version__ = "0.1.0"

cellstate_c2s/builder.py

@@ -0,0 +1,154 @@
+"""Deviation-from-reference cell sentences."""
+
+import warnings
+
+import numpy as np
+import pandas as pd
+from scipy import sparse
+
+
+class DeviationSentenceBuilder:
+    """
+    Build cell sentences by ranking genes on signed deviation from a reference mean.
+
+    For each cell, (deviation = expression - reference_mean). Genes are sorted
+    by deviation (highest first, stable on ties) and the first (top_k) are
+    kept. With (mask_unexpressed=True), genes whose value in that cell is
+    exactly 0 are dropped, so sentences can be shorter than (top_k).
+
+    Parameters
+    ----------
+    top_k : int
+        Maximum number of genes per sentence.
+    mask_unexpressed : bool
+        Drop genes with zero expression in the cell.
+    chunk_size : int
+        Number of cells densified at a time in ``transform``.
+
+    Notes
+    -----
+    adata.X must hold normalized expression, on the same scale for every
+    dataset you convert. The reference mean is taken over every cell passed to
+    fit (or the subset selected by mask).
+    """
+
+    def __init__(self, top_k=200, mask_unexpressed=True, chunk_size=2048):
+        if top_k < 1:
+            raise ValueError("top_k must be at least 1.")
+        if chunk_size < 1:
+            raise ValueError("chunk_size must be at least 1.")
+        self.top_k = top_k
+        self.mask_unexpressed = mask_unexpressed
+        self.chunk_size = chunk_size
+        self.reference_mean_ = None
+        self.gene_names_ = None
+        self.n_reference_cells_ = None
+
+    def fit(self, adata, mask=None):
+        """
+        Compute the reference mean.
+
+        Parameters
+        ----------
+        adata : anndata.AnnData
+            Cells x genes, normalized.
+        mask : array-like of bool, optional
+            Selects the cells that define the reference (for example AT2 cells
+            only). Defaults to all cells.
+        """
+        _check_unique_var_names(adata)
+        X = adata.X
+        if mask is not None:
+            mask = np.asarray(mask, dtype=bool)
+            if mask.shape != (adata.n_obs,):
+                raise ValueError(f"mask must have shape ({adata.n_obs},), got {mask.shape}.")
+            if not mask.any():
+                raise ValueError("mask selects no cells.")
+            X = X[mask]
+        if X.shape[0] == 0:
+            raise ValueError("Cannot fit a reference on zero cells.")
+        self.reference_mean_ = np.asarray(X.mean(axis=0)).ravel().astype(np.float64)
+        self.gene_names_ = np.asarray(adata.var_names).astype(str)
+        self.n_reference_cells_ = int(X.shape[0])
+        return self
+
+    def transform(self, adata):
+        """
+        Return (cell_names, sentences) for every cell in adata.
+
+        Only genes present in both the reference and adata are used. A
+        warning lists how many reference genes are missing.
+        """
+        self._check_fitted()
+        _check_unique_var_names(adata)
+        idx = pd.Index(adata.var_names).get_indexer(self.gene_names_)
+        keep = idx >= 0
+        if not keep.any():
+            raise ValueError("No genes shared between the reference and this AnnData.")
+        if not keep.all():
+            warnings.warn(
+                f"{int((~keep).sum())} of {len(keep)} reference genes are missing from "
+                "this AnnData and will be ignored.",
+                stacklevel=2,
+            )
+        col_idx = idx[keep]
+        genes = self.gene_names_[keep]
+        ref = self.reference_mean_[keep]
+        k = min(self.top_k, len(genes))
+
+        X = adata.X
+        sentences = []
+        for start in range(0, X.shape[0], self.chunk_size):
+            chunk = X[start:start + self.chunk_size][:, col_idx]
+            chunk = chunk.toarray() if sparse.issparse(chunk) else np.asarray(chunk)
+            chunk = chunk.astype(np.float64, copy=False)
+            dev = chunk - ref
+            if self.mask_unexpressed:
+                dev = np.where(chunk > 0, dev, -np.inf)
+            order = np.argsort(-dev, axis=1, kind="stable")[:, :k]
+            for row in range(order.shape[0]):
+                o = order[row]
+                if self.mask_unexpressed:
+                    o = o[np.isfinite(dev[row, o])]
+                sentences.append(" ".join(genes[o]))
+        return [str(n) for n in adata.obs_names], sentences
+
+    def fit_transform(self, adata, mask=None):
+        """Fit the reference on ``adata`` and transform the same cells."""
+        return self.fit(adata, mask=mask).transform(adata)
+
+    def save(self, path):
+        """Save the reference and settings to a ``.npz`` file."""
+        self._check_fitted()
+        np.savez(
+            path,
+            reference_mean=self.reference_mean_,
+            gene_names=self.gene_names_,
+            n_reference_cells=self.n_reference_cells_,
+            top_k=self.top_k,
+            mask_unexpressed=self.mask_unexpressed,
+            chunk_size=self.chunk_size,
+        )
+
+    @classmethod
+    def load(cls, path):
+        """Load a builder saved with :meth:save."""
+        with np.load(path, allow_pickle=False) as d:
+            obj = cls(
+                top_k=int(d["top_k"]),
+                mask_unexpressed=bool(d["mask_unexpressed"]),
+                chunk_size=int(d["chunk_size"]),
+            )
+            obj.reference_mean_ = d["reference_mean"]
+            obj.gene_names_ = d["gene_names"].astype(str)
+            obj.n_reference_cells_ = int(d["n_reference_cells"])
+        return obj
+
+    def _check_fitted(self):
+        if self.reference_mean_ is None:
+            raise RuntimeError("Call fit() first.")
+
+
+def _check_unique_var_names(adata):
+    if not adata.var_names.is_unique:
+        raise ValueError("var_names must be unique; call adata.var_names_make_unique().")

cellstate_c2s/c2s_adapter.py

@@ -0,0 +1,43 @@
+"""
+Glue for Cell2Sentence arrow datasets.
+
+Works on Hugging Face datasets.Dataset, such as the one returned by
+cell2sentence.CSData.adata_to_arrow. This module does not import
+cell2sentence itself.
+"""
+
+
+def replace_sentences(arrow_ds, cell_names, sentences,
+                      field="cell_sentence", name_field="cell_name"):
+    """Swap the sentence column of an arrow dataset, matching rows by cell name.
+
+    Parameters
+    ----------
+    arrow_ds : datasets.Dataset
+        Dataset with (field) and (name_field) columns.
+    cell_names, sentences : sequence of str
+        Output of (DeviationSentenceBuilder.transform).
+    field : str
+        Column holding the cell sentence.
+    name_field : str
+        Column holding the cell name, matching (adata.obs_names).
+
+    Returns
+    -------
+    datasets.Dataset
+        A new dataset; the input is not modified.
+    """
+    if len(cell_names) != len(sentences):
+        raise ValueError("cell_names and sentences must have the same length.")
+    lookup = dict(zip(cell_names, sentences))
+    if len(lookup) != len(cell_names):
+        raise ValueError("cell_names contains duplicates.")
+    for col in (field, name_field):
+        if col not in arrow_ds.column_names:
+            raise KeyError(f"Column {col!r} not in dataset; columns are {arrow_ds.column_names}.")
+    missing = [n for n in arrow_ds[name_field] if n not in lookup]
+    if missing:
+        raise KeyError(
+            f"{len(missing)} cells in the arrow dataset have no sentence, e.g. {missing[:3]}"
+        )
+    return arrow_ds.map(lambda ex: {field: lookup[ex[name_field]]})

cellstate_c2s-0.1.0.dist-info/METADATA

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: cellstate_c2s
+Version: 0.1.0
+Summary: Deviation-from-reference gene ordering for Cell2Sentence cell-state prediction
+Author-email: impatient_hedgehog <impatienthedgehog@duck.com>
+License-Expression: MIT
+Keywords: single-cell,cell2sentence,llm,scRNA-seq,xenium
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: pandas
+Requires-Dist: anndata
+Provides-Extra: c2s
+Requires-Dist: cell2sentence; extra == "c2s"
+Requires-Dist: datasets; extra == "c2s"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: datasets; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# cellstate_c2s
+
+Custom cell sentences for [Cell2Sentence](https://github.com/vandijklab/cell2sentence) fine-tuning and prediction.
+
+Cell2Sentence normally writes each cell as its genes ordered by expression. This package replaces that with genes ordered by **deviation from a reference mean** (for example, the mean AT2 profile), so the sentence describes how a cell differs from the reference state rather than which genes are simply most abundant. You build the arrow dataset with Cell2Sentence as usual, then swap in the new sentences before creating `CSData`.
+
+## Install
+
+```bash
+pip install cellstate_c2s            # core: numpy, scipy, pandas, anndata
+pip install "cellstate_c2s[c2s]"     # plus cell2sentence and datasets
+```
+
+From a local clone:
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Usage
+
+```python
+import cell2sentence as cs
+from cellstate_c2s import DeviationSentenceBuilder, replace_sentences
+
+# 1. Build the arrow dataset with Cell2Sentence as usual
+arrow_ds, vocabulary = cs.CSData.adata_to_arrow(
+    adata=adata_train, random_state=SEED, sentence_delimiter=" ",
+    label_col_names=["annotation_cell_states", "organism", "tissue"],
+)
+
+# 2. Fit the reference and build deviation sentences
+builder = DeviationSentenceBuilder(top_k=200)
+builder.fit(adata_train, mask=adata_train.obs["cell_type"] == "AT2")  # optional mask
+names, sentences = builder.transform(adata_train)
+builder.save("reference.npz")
+
+# 3. Swap the sentences in, matched by cell name, then continue with Cell2Sentence
+arrow_ds = replace_sentences(arrow_ds, names, sentences)
+csdata = cs.CSData.csdata_from_arrow(
+    arrow_dataset=arrow_ds, vocabulary=vocabulary,
+    save_dir=save_dir, save_name=save_name, dataset_backend="arrow",
+)
+```
+
+**Held-out test data (same platform):** reuse the reference fitted on training data. Do not fit on the test set.
+
+```python
+builder = DeviationSentenceBuilder.load("reference.npz")
+names, sentences = builder.transform(adata_test)
+```
+
+**Another platform (e.g. Xenium):** fit a separate reference on that dataset, then do the Cell2Sentence vocabulary swap yourself.
+
+```python
+names_x, sents_x = DeviationSentenceBuilder(top_k=200).fit_transform(adata_xenium)
+arrow_ds_xenium = replace_sentences(arrow_ds_xenium, names_x, sents_x)
+```
+
+## How sentences are built
+
+For each cell, `deviation = expression - reference_mean`. Genes are sorted by deviation, highest first, and the first `top_k` are kept. Ties keep the order of `var_names` (stable sort), so the same input always gives the same sentence.
+
+| Option | Default | Effect |
+|---|---|---|
+| `top_k` | 200 | Maximum genes per sentence. Capped at the number of shared genes. |
+| `mask_unexpressed` | `True` | Drops genes whose value in that cell is exactly 0, so sentences can be shorter than `top_k`. Set `False` for a pure ranking of all genes. |
+| `chunk_size` | 2048 | Cells densified at a time. Lower it if memory is tight. |
+| `fit(..., mask=)` | all cells | Boolean array selecting the cells that define the reference. |
+
+`transform` uses only the genes shared by the reference and the AnnData passed in, warns about missing reference genes, and ignores extra genes.
+
+## Before you use this
+
+The code cannot check most of these, so they are on you. The first four are the most likely to cause silent errors.
+
+1. **`adata.X` is normalized, the same way in every dataset.** Deviation is in expression units, so raw counts in one dataset and log-normalized values in another give meaningless ranks. The package never reads `layers` or `.raw`.
+2. **Zero means "not expressed."** With `mask_unexpressed=True`, any gene with a value of exactly 0 in a cell is dropped.
+3. **The cells passed to `fit` define the reference.** Pass only the cells you want (e.g. AT2), or use `mask=`.
+4. **Fit on training data only for evaluation.** `fit_transform` on a test set computes the reference from test cells.
+5. **Gene names are unique and use one naming system** (symbols or Ensembl IDs, not a mix). Duplicates raise an error; mismatched naming just shrinks the shared gene set.
+6. **Cell names (`obs_names`) are unique and match the arrow dataset's `cell_name` column.** Field names are parameters of `replace_sentences` if your Cell2Sentence version differs.
+7. **The datasets are already subset to the genes you want.** The package does not select genes.
+
+## What is checked
+
+| Checked in code | Not checked |
+|---|---|
+| `fit` called before `transform` | Normalization |
+| Unique gene names | Gene naming system |
+| Shared genes exist; warns on missing ones | Whether the reference cells are the right ones |
+| Every arrow row has a sentence; no duplicate cell names | Train/test separation |
+| Required arrow columns exist | Meaning of zeros |
+
+## License
+
+MIT

cellstate_c2s-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+cellstate_c2s/__init__.py,sha256=hCwNcO2njGiLis8Zhbb_FKWn6Qo6aExAYzWtNutVe4E,259
+cellstate_c2s/builder.py,sha256=q7MUO8h3brUP2RBBHpBpF1xhz0JJjEyQ4XnvM_dt-1A,5723
+cellstate_c2s/c2s_adapter.py,sha256=kfHe6GiYga3f90WGlDcyYnF0-NW-SztJT9ar5vfI87Y,1604
+cellstate_c2s-0.1.0.dist-info/licenses/LICENSE,sha256=ZPVnK694kpNR2D_ji4dqIcHxv4gZoS6glCJO26Yi_9w,1075
+cellstate_c2s-0.1.0.dist-info/METADATA,sha256=TUyIVQpVpm0X9LAncsOqgtgKinVUkMZ17ellKqaYRoI,5665
+cellstate_c2s-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+cellstate_c2s-0.1.0.dist-info/top_level.txt,sha256=MoF-soUO4Bt7jNeMwTzMPwFA1Gkeya9fbDU3HzPfrk0,14
+cellstate_c2s-0.1.0.dist-info/RECORD,,

cellstate_c2s-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cellstate_c2s-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 impatient_hedgehog
+
+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.

cellstate_c2s-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cellstate_c2s