scloop 0.1.2__tar.gz → 0.1.4__tar.gz

{scloop-0.1.2/src/scloop.egg-info → scloop-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scloop
-Version: 0.1.2
+Version: 0.1.4
 Summary: single-cell loop analysis
 Author-email: "Zhiyuan(Stan) Yu" <zyyu@umich.edu>, Idse Heemskerk <idse.heemskerk@gmail.com>
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -9,6 +9,7 @@ Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: cython>=3.0.12
+Requires-Dist: igraph>=0.11
 Requires-Dist: numba>=0.62.1
 Requires-Dist: numpy<2
 Requires-Dist: pandas
@@ -75,10 +76,14 @@ src/scloop/
 │   └── __init__.py
 ├── benchmarking
 │   └── __init__.py
+├── computing
+│   ├── homology.py
+│   └── __init__.py
 ├── data
 │   ├── analysis_containers.py
 │   ├── containers.py
 │   ├── __init__.py
+│   ├── loop_reconstruction.py
 │   ├── metadata.py
 │   ├── ripser.cpp
 │   ├── ripser.hpp
@@ -105,7 +110,8 @@ src/scloop/
 │   └── prepare.py
 ├── py.typed
 ├── tools
-│   └── __init__.py
+│   ├── __init__.py
+│   └── _loops.py
 └── utils
     ├── distance_metrics
     │   ├── discrete-frechet-distance

{scloop-0.1.2 → scloop-0.1.4}/README.md

@@ -46,10 +46,14 @@ src/scloop/
 │   └── __init__.py
 ├── benchmarking
 │   └── __init__.py
+├── computing
+│   ├── homology.py
+│   └── __init__.py
 ├── data
 │   ├── analysis_containers.py
 │   ├── containers.py
 │   ├── __init__.py
+│   ├── loop_reconstruction.py
 │   ├── metadata.py
 │   ├── ripser.cpp
 │   ├── ripser.hpp
@@ -76,7 +80,8 @@ src/scloop/
 │   └── prepare.py
 ├── py.typed
 ├── tools
-│   └── __init__.py
+│   ├── __init__.py
+│   └── _loops.py
 └── utils
     ├── distance_metrics
     │   ├── discrete-frechet-distance

{scloop-0.1.2 → scloop-0.1.4}/pyproject.toml

@@ -19,7 +19,7 @@ requires = [ "cython>=3.0.12", "setuptools>=74.1" ]
 
 [project]
 name = "scloop"
-version = "0.1.2"
+version = "0.1.4"
 description = "single-cell loop analysis"
 readme = "README.md"
 authors = [
@@ -34,6 +34,7 @@ classifiers = [
 ]
 dependencies = [
   "cython>=3.0.12",
+  "igraph>=0.11",
   "numba>=0.62.1",
   "numpy<2",
   "pandas",
@@ -75,6 +76,8 @@ explicit = true
 [tool.ruff]
 format.indent-style = "space"
 format.quote-style = "double"
+lint.extend-select = [ "I" ]
+lint.fixable = [ "ALL" ]
 
 [tool.pyproject-fmt]
 column_width = 120

{scloop-0.1.2 → scloop-0.1.4}/setup.py

@@ -1,7 +1,8 @@
-from setuptools import setup, Extension
-from Cython.Build import cythonize
 import os
 
+from Cython.Build import cythonize
+from setuptools import Extension, setup
+
 project_root = os.path.dirname(os.path.abspath(__file__))
 m4ri_dir = os.path.join(project_root, "src/scloop/utils/linear_algebra_gf2")
 

{scloop-0.1.2 → scloop-0.1.4}/src/scloop/__init__.py

@@ -3,6 +3,6 @@ import warnings
 warnings.filterwarnings("ignore", category=FutureWarning, module="scanpy")
 warnings.filterwarnings("ignore", category=FutureWarning, module="anndata")
 
-from . import data
-from . import utils
+from . import data, utils
 from . import preprocessing as pp
+from . import tools as tl

scloop-0.1.4/src/scloop/computing/__init__.py

@@ -0,0 +1,8 @@
+"""Lightweight compute helpers used by the public API layer."""
+# Copyright 2025 Zhiyuan Yu (Heemskerk's lab, University of Michigan)
+
+from .homology import (
+    compute_boundary_matrix_data,
+    compute_persistence_diagram_and_cocycles,
+    compute_sparse_pairwise_distance,
+)

scloop-0.1.4/src/scloop/computing/homology.py

@@ -0,0 +1,92 @@
+# Copyright 2025 Zhiyuan Yu (Heemskerk's lab, University of Michigan)
+from __future__ import annotations
+
+import numpy as np
+from anndata import AnnData
+from scipy.sparse import csr_matrix
+from sklearn.neighbors import radius_neighbors_graph
+
+from ..data.metadata import ScloopMeta
+from ..data.ripser_lib import get_boundary_matrix, ripser
+from ..data.types import Diameter_t, IndexListDistMatrix
+from ..data.utils import encode_triangles_and_edges
+
+
+def compute_sparse_pairwise_distance(
+    adata: AnnData,
+    meta: ScloopMeta,
+    bootstrap: bool = False,
+    noise_scale: float = 1e-3,
+    thresh: Diameter_t | None = None,
+    **nei_kwargs,
+) -> tuple[csr_matrix, IndexListDistMatrix | None]:
+    assert meta.preprocess is not None
+    assert meta.preprocess.embedding_method is not None
+    emb = adata.obsm[f"X_{meta.preprocess.embedding_method}"]
+    selected_indices = (
+        meta.preprocess.indices_downsample
+        if meta.preprocess.indices_downsample is not None
+        else list(range(emb.shape[0]))
+    )
+    X = emb[selected_indices]
+    boot_idx = None
+    if bootstrap:
+        sample_idx = np.random.choice(
+            len(selected_indices), size=len(selected_indices), replace=True
+        ).tolist()
+        boot_idx = [selected_indices[i] for i in sample_idx]
+        X = X[sample_idx] + np.random.normal(scale=noise_scale, size=X.shape)
+    else:
+        boot_idx = selected_indices
+    return (
+        radius_neighbors_graph(
+            X=X,
+            radius=thresh,
+            **nei_kwargs,
+        ),
+        boot_idx,
+    )
+
+
+def compute_persistence_diagram_and_cocycles(
+    adata: AnnData,
+    meta: ScloopMeta,
+    thresh: Diameter_t | None = None,
+    bootstrap: bool = False,
+    **nei_kwargs,
+) -> tuple[list[np.ndarray], list, IndexListDistMatrix | None, csr_matrix]:
+    sparse_pairwise_distance_matrix, boot_idx = compute_sparse_pairwise_distance(
+        adata=adata, meta=meta, bootstrap=bootstrap, thresh=thresh, **nei_kwargs
+    )
+    result = ripser(
+        distance_matrix=sparse_pairwise_distance_matrix.tocoo(copy=False),
+        modulus=2,
+        dim_max=1,
+        threshold=thresh,
+        do_cocycles=True,
+    )
+    return (
+        result.births_and_deaths_by_dim,
+        result.cocycles_by_dim,
+        boot_idx,
+        sparse_pairwise_distance_matrix,
+    )
+
+
+def compute_boundary_matrix_data(
+    adata: AnnData, meta: ScloopMeta, thresh: Diameter_t | None = None, **nei_kwargs
+) -> tuple:
+    assert meta.preprocess is not None
+    assert meta.preprocess.num_vertices is not None
+    sparse_pairwise_distance_matrix, vertex_indices = compute_sparse_pairwise_distance(
+        adata=adata, meta=meta, bootstrap=False, thresh=thresh, **nei_kwargs
+    )
+    result = get_boundary_matrix(sparse_pairwise_distance_matrix.tocoo(), thresh)
+    triangles = np.asarray(result.triangle_vertices, dtype=np.int64)
+    if len(triangles) == 0:
+        edge_ids, trig_ids = [], []
+    else:
+        edge_ids, trig_ids = encode_triangles_and_edges(
+            triangles, meta.preprocess.num_vertices
+        )
+    return result, edge_ids, trig_ids, sparse_pairwise_distance_matrix, vertex_indices

scloop-0.1.4/src/scloop/data/__init__.py

@@ -0,0 +1,2 @@
+from .containers import HomologyData
+from .ripser_lib import RipserResults, get_boundary_matrix, ripser

{scloop-0.1.2 → scloop-0.1.4}/src/scloop/data/analysis_containers.py

@@ -3,8 +3,8 @@ from __future__ import annotations
 
 import numpy as np
 import pandas as pd
+from pydantic import ConfigDict, Field
 from pydantic.dataclasses import dataclass
-from pydantic import Field, ConfigDict
 
 
 @dataclass(config=ConfigDict(arbitrary_types_allowed=True))

scloop-0.1.4/src/scloop/data/containers.py

@@ -0,0 +1,221 @@
+# Copyright 2025 Zhiyuan Yu (Heemskerk's lab, University of Michigan)
+from abc import abstractmethod
+
+import numpy as np
+from anndata import AnnData
+from pydantic import BaseModel, ConfigDict, ValidationInfo, field_validator
+from pydantic.dataclasses import dataclass
+from scipy.sparse import csr_matrix
+
+from ..computing.homology import (
+    compute_boundary_matrix_data,
+    compute_persistence_diagram_and_cocycles,
+    compute_sparse_pairwise_distance,
+)
+from .analysis_containers import BootstrapAnalysis, HodgeAnalysis
+from .loop_reconstruction import reconstruct_n_loop_representatives
+from .metadata import ScloopMeta
+from .types import Diameter_t, Index_t, IndexListDistMatrix, Size_t
+from .utils import decode_edges, decode_triangles
+
+
+class BoundaryMatrix(BaseModel):
+    num_vertices: Size_t
+    data: tuple[list, list]  # in coo format (row indices, col indices) of ones
+    shape: tuple[Size_t, Size_t]
+    row_simplex_ids: list[Index_t]
+    col_simplex_ids: list[Index_t]
+    row_simplex_diams: list[Diameter_t]
+    col_simplex_diams: list[Diameter_t]
+
+    @field_validator(
+        "row_simplex_ids", "col_simplex_ids", "col_simplex_diams", mode="before"
+    )
+    @classmethod
+    def validate_fields(cls, v: list[Index_t], info: ValidationInfo):
+        shape = info.data.get("shape")
+        assert shape
+        if info.field_name == "row_simplex_ids":
+            if len(v) != shape[0]:
+                raise ValueError(
+                    "Length of row ids does not match the number of rows of the matrix"
+                )
+        elif info.field_name in ["col_simplex_ids", "col_simplex_diams"]:
+            if len(v) != shape[1]:
+                raise ValueError(
+                    f"Length of {info.field_name} does not match the number of columns of the matrix"
+                )
+        return v
+
+    @abstractmethod
+    def row_simplex_decode(self) -> list:
+        """
+        From simplex id (row) to vertex ids
+        """
+        pass
+
+    @abstractmethod
+    def col_simplex_decode(self) -> list:
+        """
+        From simplex id (column) to vertex ids
+        """
+        pass
+
+
+class BoundaryMatrixD1(BoundaryMatrix):
+    data: tuple[list[list[Index_t]], list[list[Index_t]]]
+
+    def row_simplex_decode(self) -> list[tuple[Index_t, Index_t]]:
+        return decode_edges(np.array(self.row_simplex_ids), self.num_vertices)
+
+    def col_simplex_decode(self) -> list[tuple[Index_t, Index_t, Index_t]]:
+        return decode_triangles(np.array(self.col_simplex_ids), self.num_vertices)
+
+
+@dataclass(config=ConfigDict(arbitrary_types_allowed=True))
+class HomologyData:
+    """
+    store core homology data and associated analysis data
+    """
+
+    meta: ScloopMeta
+    persistence_diagram: list[np.ndarray] | None = None
+    loop_representatives: list[list[list[int]]] | None = None
+    cocycles: list | None = None
+    pairwise_distance_matrix: csr_matrix | None = None
+    selected_vertex_indices: list[int] | None = None
+    boundary_matrix_d1: BoundaryMatrixD1 | None = None
+    bootstrap_data: BootstrapAnalysis | None = None
+    hodge_data: HodgeAnalysis | None = None
+
+    def _compute_sparse_pairwise_distance(
+        self,
+        adata: AnnData,
+        bootstrap: bool = False,
+        thresh: Diameter_t | None = None,
+        **nei_kwargs,
+    ) -> tuple[csr_matrix, IndexListDistMatrix | None]:
+        return compute_sparse_pairwise_distance(
+            adata=adata,
+            meta=self.meta,
+            bootstrap=bootstrap,
+            thresh=thresh,
+            **nei_kwargs,
+        )
+
+    def _compute_homology(
+        self,
+        adata: AnnData,
+        thresh: Diameter_t | None = None,
+        bootstrap: bool = False,
+        **nei_kwargs,
+    ) -> None:
+        (
+            persistence_diagram,
+            cocycles,
+            vertex_indices,
+            sparse_pairwise_distance_matrix,
+        ) = compute_persistence_diagram_and_cocycles(
+            adata=adata,
+            meta=self.meta,
+            thresh=thresh,
+            bootstrap=bootstrap,
+            **nei_kwargs,
+        )
+        self.persistence_diagram = persistence_diagram
+        self.cocycles = cocycles
+        self.pairwise_distance_matrix = sparse_pairwise_distance_matrix
+        self.selected_vertex_indices = vertex_indices
+
+    def _compute_boundary_matrix(
+        self, adata: AnnData, thresh: Diameter_t | None = None, **nei_kwargs
+    ) -> None:
+        assert self.meta.preprocess
+        assert self.meta.preprocess.num_vertices
+        (
+            result,
+            edge_ids,
+            trig_ids,
+            sparse_pairwise_distance_matrix,
+            vertex_indices,
+        ) = compute_boundary_matrix_data(
+            adata=adata, meta=self.meta, thresh=thresh, **nei_kwargs
+        )
+        self.pairwise_distance_matrix = sparse_pairwise_distance_matrix
+        self.selected_vertex_indices = vertex_indices
+        edge_ids_1d = np.array(edge_ids).flatten()
+        # reindex edges (also keep as colllection of triplets, easier to subset later)
+        edge_ids_reindex = np.searchsorted(edge_ids_1d, edge_ids)
+        edge_diameters = decode_edges(edge_ids_1d, self.meta.preprocess.num_vertices)
+        edge_diameters = [
+            sparse_pairwise_distance_matrix[i, j] for i, j in edge_diameters
+        ]
+        self.boundary_matrix_d1 = BoundaryMatrixD1(
+            num_vertices=self.meta.preprocess.num_vertices,
+            data=(
+                edge_ids_reindex.tolist(),
+                np.repeat(
+                    np.expand_dims(np.arange(edge_ids_reindex.shape[0]), 1), 3, axis=1
+                ).tolist(),
+            ),
+            shape=(len(edge_ids_1d), len(trig_ids)),
+            row_simplex_ids=edge_ids_1d.tolist(),
+            col_simplex_ids=trig_ids,
+            row_simplex_diams=edge_diameters,
+            col_simplex_diams=result.triangle_diameters,
+        )
+
+    def _compute_loop_representatives(
+        self,
+        loop_idx: int,
+        n: int = 8,
+        life_pct: float = 0.1,
+        n_force_deviate: int = 4,
+        n_reps_per_loop: int = 8,
+        loop_lower_pct: float = 5,
+        loop_upper_pct: float = 95,
+        n_max_cocycles: int = 10,
+    ):
+        assert self.persistence_diagram is not None
+        assert self.cocycles is not None
+        assert self.pairwise_distance_matrix is not None
+
+        births, deaths = self.persistence_diagram[1]
+        loop_birth = float(births[loop_idx])
+        loop_death = float(deaths[loop_idx])
+
+        dm = self.pairwise_distance_matrix.tocoo()
+        edge_weights: dict[tuple[int, int], float] = {}
+        for i, j, w in zip(dm.row.tolist(), dm.col.tolist(), dm.data.tolist()):
+            if i == j:
+                continue
+            key = (i, j) if i < j else (j, i)
+            if key not in edge_weights or w < edge_weights[key]:
+                edge_weights[key] = float(w)
+        if not edge_weights:
+            return [], []
+
+        edges = list(edge_weights.keys())
+        edge_births = np.array([edge_weights[e] for e in edges], dtype=float)
+
+        loops, dists = reconstruct_n_loop_representatives(
+            cocycles_dim1=self.cocycles[1][loop_idx],
+            edges=edges,
+            edge_births=edge_births,
+            loop_birth=loop_birth,
+            loop_death=loop_death,
+            n=n,
+            life_pct=life_pct,
+            n_force_deviate=n_force_deviate,
+            n_reps_per_loop=n_reps_per_loop,
+            loop_lower_pct=loop_lower_pct,
+            loop_upper_pct=loop_upper_pct,
+            n_max_cocycles=n_max_cocycles,
+        )
+
+        if self.loop_representatives is None:
+            self.loop_representatives = []
+        while len(self.loop_representatives) <= loop_idx:
+            self.loop_representatives.append([])
+        self.loop_representatives[loop_idx] = loops
+        return loops, dists

scloop-0.1.4/src/scloop/data/loop_reconstruction.py

@@ -0,0 +1,150 @@
+# Copyright 2025 Zhiyuan Yu (Heemskerk's lab, University of Michigan)
+from __future__ import annotations
+
+import math
+from typing import Iterable, List, Sequence, Tuple
+
+import igraph as ig
+import numpy as np
+
+
+def reconstruct_n_loop_representatives(
+    cocycles_dim1: List,
+    edges: List[Tuple[int, int]],
+    edge_births: np.ndarray,
+    loop_birth: float,
+    loop_death: float,
+    n: int,
+    life_pct: float = 0.1,
+    n_force_deviate: int = 4,
+    n_reps_per_loop: int = 8,
+    loop_lower_pct: float = 5,
+    loop_upper_pct: float = 95,
+    n_max_cocycles: int = 10,
+) -> Tuple[List[List[int]], List[float]]:
+    """
+    Reconstruct diverse loop representatives using Yen-style deviation rounds.
+    """
+    if n <= 0 or len(edges) == 0:
+        return [], []
+
+    filt_t = loop_birth + (loop_death - loop_birth) * life_pct
+
+    # Parse cocycle edges (each entry is [[i, j], coeff])
+    cocycle_edges: list[tuple[int, int]] = []
+    for simplex in cocycles_dim1:
+        try:
+            verts, coeff = simplex
+        except ValueError:
+            continue
+        if coeff == 0 or len(verts) != 2:
+            continue
+        cocycle_edges.append((int(verts[0]), int(verts[1])))
+        if len(cocycle_edges) == n_max_cocycles:
+            break
+
+    edge_births = np.asarray(edge_births)
+    mask = edge_births <= filt_t
+    if not np.any(mask):
+        return [], []
+    edges_filt = [e for e, keep in zip(edges, mask) if keep]
+    weights_filt = edge_births[mask].tolist()
+
+    sources = [e[0] for e in edges_filt] + [e[0] for e in cocycle_edges]
+    destinations = [e[1] for e in edges_filt] + [e[1] for e in cocycle_edges]
+    weights = weights_filt + [math.inf] * len(cocycle_edges)
+    if len(sources) == 0:
+        return [], []
+
+    n_vertices = max(max(sources), max(destinations)) + 1
+    g = ig.Graph(n=n_vertices, edges=list(zip(sources, destinations)), directed=False)
+    g.es["weight"] = weights
+
+    cycles_pool: list[list[int]] = []
+    cycles_dist: list[float] = []
+
+    for _ in range(n_force_deviate):
+        paths_this_round: list[list[int]] = []
+        for i, j in cocycle_edges:
+            paths = _k_shortest_paths(g, i, j, n_reps_per_loop)
+            if not paths:
+                continue
+            for path in paths:
+                dist = _path_weight(g, path)
+                cycles_pool.append(path)
+                paths_this_round.append(path)
+                cycles_dist.append(dist)
+
+        # Force deviation
+        for path in paths_this_round:
+            for u, v in zip(path[:-1], path[1:]):
+                try:
+                    eid = g.get_eid(u, v, directed=False)
+                except ig._igraph.InternalError:
+                    continue
+                g.es[eid]["weight"] = math.inf
+
+    return _select_diverse_loops(
+        cycles=cycles_pool,
+        distances=cycles_dist,
+        n=n,
+        lower_pct=loop_lower_pct,
+        upper_pct=loop_upper_pct,
+    )
+
+
+def _k_shortest_paths(g: ig.Graph, source: int, target: int, k: int) -> list[list[int]]:
+    if source == target:
+        return []
+    try:
+        return g.get_k_shortest_paths(
+            source, target, k=k, weights=g.es["weight"], mode="ALL"
+        )
+    except ig._igraph.InternalError:
+        return []
+
+
+def _path_weight(g: ig.Graph, path: Sequence[int]) -> float:
+    if len(path) < 2:
+        return math.inf
+    weight = 0.0
+    for u, v in zip(path[:-1], path[1:]):
+        try:
+            eid = g.get_eid(u, v, directed=False)
+        except ig._igraph.InternalError:
+            return math.inf
+        w = g.es[eid]["weight"]
+        weight += float(w)
+    return weight
+
+
+def _select_diverse_loops(
+    cycles: Iterable[Sequence[int]],
+    distances: Iterable[float],
+    n: int,
+    lower_pct: float,
+    upper_pct: float,
+) -> Tuple[List[List[int]], List[float]]:
+    pairs = sorted(
+        [(float(d), list(c)) for d, c in zip(distances, cycles) if math.isfinite(d)],
+        key=lambda x: x[0],
+    )
+    if not pairs:
+        return [], []
+
+    n_total = len(pairs)
+    n_return = min(n_total, n)
+    if n_return == 1:
+        idxs = [n_total // 2]
+    else:
+        step = (upper_pct - lower_pct) / (n_return - 1)
+        idxs = []
+        for i in range(n_return):
+            pct = (lower_pct + step * i) / 100
+            idx = min(int(math.floor(n_total * pct)), n_total - 1)
+            idxs.append(idx)
+
+    selected = [pairs[i] for i in idxs]
+    dists = [p[0] for p in selected]
+    loops = [p[1] for p in selected]
+    return loops, dists

{scloop-0.1.2 → scloop-0.1.4}/src/scloop/data/metadata.py

@@ -1,7 +1,13 @@
 # Copyright 2025 Zhiyuan Yu (Heemskerk's lab, University of Michigan)
 from pydantic import BaseModel
 
-from .types import FeatureSelectionMethod, EmbeddingMethod, EmbeddingNeighbors
+from .types import (
+    EmbeddingMethod,
+    EmbeddingNeighbors,
+    FeatureSelectionMethod,
+    IndexListDownSample,
+    Size_t,
+)
 
 
 class PreprocessMeta(BaseModel):
@@ -17,6 +23,8 @@ class PreprocessMeta(BaseModel):
     n_neighbors: int
     n_diffusion_comps: int | None = None
     scvi_key: str | None = None
+    indices_downsample: IndexListDownSample | None = None
+    num_vertices: Size_t | None = None
 
 
 class ScloopMeta(BaseModel):

scloop-0.1.4/src/scloop/data/types.py

@@ -0,0 +1,33 @@
+# Copyright 2025 Zhiyuan Yu (Heemskerk's lab, University of Michigan)
+from typing import Annotated, Literal, TypeAlias
+
+from pydantic import Field
+
+FeatureSelectionMethod = Literal["hvg", "delve", "none"]
+EmbeddingMethod = Literal["pca", "diffmap", "scvi"]
+EmbeddingNeighbors = Literal["pca", "scvi"]
+
+Index_t = Annotated[int, Field(ge=0)]
+Size_t = Annotated[int, Field(ge=0)]
+Diameter_t = Annotated[float, Field(ge=0)]
+SizeDownSample = Annotated[
+    int, Field(ge=2, description="Sample to this number of cells")
+]
+# need at least 2 points to compute PH. Maybe also set an upper bound later as it is not feasible to compute PH on a lot of points
+IndexListDownSample: TypeAlias = Annotated[
+    list[Index_t],
+    Field(min_length=2, description="Downsampled indices for PH computation"),
+]
+IndexListDistMatrix: TypeAlias = Annotated[
+    list[Index_t],
+    Field(
+        min_length=2,
+        description="Corresponding vertex index for each column of a distance matrix",
+    ),
+]
+IndexListSimplex: TypeAlias = Annotated[
+    list[Index_t],
+    Field(min_length=0, description="Unique indicies for simplicies"),
+]
+
+# TODO: make a type for boundary matrix. Restrict matrix size for efficient computation