clacell 0.1.0__py3-none-any.whl

clacell/__init__.py

@@ -0,0 +1,4 @@
+from .classifier import BloodCellClassifier
+from .marker_annotator import MarkerAnnotator
+
+__all__ = ["BloodCellClassifier", "MarkerAnnotator"]

clacell/_marker_based_annotation/__init__.py

@@ -0,0 +1,10 @@
+from .clustering import cluster_scanpy
+from .markers import calculate_auc, compute_cluster_auc
+from .model_selection import select_cluster_model
+
+__all__ = [
+    "calculate_auc",
+    "cluster_scanpy",
+    "compute_cluster_auc",
+    "select_cluster_model",
+]

clacell/_marker_based_annotation/cli.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+import pandas as pd
+
+from .io import read_count_matrix, read_markers
+from .model_selection import select_cluster_model
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(description="Marker-based annotation pipeline")
+    p.add_argument(
+        "--matrix", required=True, help="Gene x cell count matrix CSV (index=gene)"
+    )
+    p.add_argument("--markers", required=True, help="Markers as JSON or CSV/TSV")
+    p.add_argument("--outdir", required=True, help="Output directory")
+    p.add_argument("--species", default="human", choices=["human", "mouse"])
+    p.add_argument("--min-cluster", type=int, default=3)
+    p.add_argument("--max-cluster", type=int, default=20)
+    p.add_argument("--seed", type=int, default=0)
+    return p
+
+
+def main() -> None:
+    args = _build_parser().parse_args()
+
+    matrix = read_count_matrix(args.matrix)
+    markers = read_markers(args.markers)
+
+    result = select_cluster_model(
+        matrix,
+        markers,
+        min_cluster=args.min_cluster,
+        max_cluster=args.max_cluster,
+        species=args.species,
+        random_state=args.seed,
+    )
+
+    outdir = Path(args.outdir)
+    outdir.mkdir(parents=True, exist_ok=True)
+
+    params_file = outdir / "best_params.json"
+    with params_file.open("w", encoding="utf-8") as f:
+        json.dump(result.params_final, f, indent=2)
+
+    auc_file = outdir / "final_auc.json"
+    with auc_file.open("w", encoding="utf-8") as f:
+        json.dump(result.auc_final, f, indent=2)
+
+    clusters = result.model_final.clusters.rename("cluster")
+    cluster_labels = pd.DataFrame({"cell": clusters.index, "cluster": clusters.values})
+    cluster_labels.to_csv(outdir / "clusters.csv", index=False)
+
+    labels = pd.DataFrame(
+        {
+            "cell": result.label_final.index,
+            "cell_type_label": result.label_final.values,
+        }
+    )
+    labels.to_csv(outdir / "cell_type_labels.csv", index=False)
+
+    result.auc_table.to_csv(outdir / "model_grid_auc.csv", index=False)
+    result.silhouette_table.to_csv(outdir / "model_grid_silhouette.csv", index=False)
+    result.cluster_table.to_csv(outdir / "model_grid_cluster_counts.csv", index=False)
+
+    print(f"Done. Results written to: {outdir}")
+
+
+if __name__ == "__main__":
+    main()

clacell/_marker_based_annotation/clustering.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import anndata as ad
+import numpy as np
+import pandas as pd
+import scanpy as sc
+
+from .types import ClusterResult
+
+
+def _to_anndata(umi_count: pd.DataFrame) -> ad.AnnData:
+    if not isinstance(umi_count, pd.DataFrame):
+        raise TypeError(
+            "umi_count must be a pandas DataFrame with genes as index and cells as columns"
+        )
+    adata = ad.AnnData(X=umi_count.T.copy())
+    adata.var_names = umi_count.index.astype(str)
+    adata.obs_names = umi_count.columns.astype(str)
+    return adata
+
+
+def cluster_scanpy(
+    umi_count: pd.DataFrame,
+    number_neighbor: int = 30,
+    variable_gene: bool = False,
+    resolution: float = 1.0,
+    num_pc: int = 50,
+    species: str = "human",
+    normalize: bool = True,
+    min_cells: int = 3,
+    min_genes: int = 1,
+    random_state: int = 0,
+) -> ClusterResult:
+    adata = _to_anndata(umi_count)
+
+    sc.pp.filter_cells(adata, min_genes=min_genes)
+    sc.pp.filter_genes(adata, min_cells=min_cells)
+
+    if species == "human":
+        adata.var["mito"] = adata.var_names.str.startswith("MT-")
+    elif species == "mouse":
+        adata.var["mito"] = adata.var_names.str.startswith("mt-")
+    else:
+        raise ValueError("species must be 'human' or 'mouse'")
+
+    sc.pp.calculate_qc_metrics(
+        adata, qc_vars=["mito"], percent_top=None, log1p=False, inplace=True
+    )
+
+    if normalize:
+        sc.pp.normalize_total(adata, target_sum=10000)
+        sc.pp.log1p(adata)
+    else:
+        adata.X = np.log1p(adata.X)
+
+    if variable_gene:
+        sc.pp.highly_variable_genes(adata, min_mean=0.0125, max_mean=3, min_disp=0.5)
+        hvg_mask = adata.var["highly_variable"].to_numpy()
+        if int(hvg_mask.sum()) == 0:
+            adata_use = adata.copy()
+        else:
+            adata_use = adata[:, hvg_mask].copy()
+    else:
+        if species == "human":
+            mt_rb = adata.var_names.str.contains(
+                r"^MT-|^RPL|^RPS|^MRPS|^MRPL", regex=True
+            )
+        else:
+            mt_rb = adata.var_names.str.contains(
+                r"^mt-|^Rpl|^Rps|^Mrps|^Mrpl", regex=True
+            )
+        adata_use = adata[:, ~mt_rb].copy()
+
+    if adata_use.n_vars == 0:
+        adata_use = adata.copy()
+
+    sc.pp.scale(adata_use)
+
+    n_pc_eff = min(num_pc, adata_use.n_vars - 1, adata_use.n_obs - 1)
+    n_pc_eff = max(n_pc_eff, 2)
+
+    sc.tl.pca(
+        adata_use,
+        n_comps=n_pc_eff,
+        random_state=random_state,
+        mask_var=None,
+    )
+    sc.pp.neighbors(
+        adata_use,
+        n_neighbors=number_neighbor,
+        n_pcs=n_pc_eff,
+        random_state=random_state,
+    )
+    sc.tl.leiden(
+        adata_use,
+        resolution=resolution,
+        random_state=random_state,
+        key_added="cluster",
+        flavor="igraph",
+        n_iterations=2,
+        directed=False,
+    )
+    sc.tl.tsne(adata_use, n_pcs=n_pc_eff, random_state=random_state)
+
+    adata.obsm["X_pca"] = adata_use.obsm["X_pca"]
+    adata.obsm["X_tsne"] = adata_use.obsm["X_tsne"]
+    adata.obs["cluster"] = adata_use.obs["cluster"].astype(str)
+
+    params = {
+        "number_neighbor": number_neighbor,
+        "variable_gene": variable_gene,
+        "resolution": resolution,
+        "num_pc": num_pc,
+        "normalize": normalize,
+        "min_cells": min_cells,
+        "min_genes": min_genes,
+        "species": species,
+    }
+    return ClusterResult(
+        adata=adata, clusters=adata.obs["cluster"].copy(), params=params
+    )

clacell/_marker_based_annotation/human_pbmc_marker.json

@@ -0,0 +1 @@
+{"CD4+ T cell":["CD3D+","CD3E+","CD3G+","TRAC+","CD4+","TCF7+","CD27+","IL7R+","CD8A-","CD8B-","GNLY-","NKG7-","CST7-"],"Cytotoxic T cell":["CD3D+","CD3E+","CD3G+","TRAC+","CD8A+","CD8B+","GZMK+","CCL5+","NKG7+","CD4-","FCER1G-"],"B cell":["CD19+","MS4A1+","CD79A+","CD79B+","MZB1+","IGHD+","IGHM+"],"Natural killer cell":["NCAM1+","NKG7+","KLRB1+","KLRD1+","KLRF1+","KLRC1+","KLRC2+","KLRC3+","KLRC4+","CD3D-","CD3E-","CD3G-","CD14-","FCGR3A+","FCGR3B+","ITGAL+","ITGAM+","FCER1G+","TRAC-"],"CD14+ monocyte":["VCAN+","FCN1+","S100A8+","S100A9+","CD14+","ITGAL+","ITGAM+","CSF3R+","CSF1R+","CX3CR1+","FCGR3A-","FCGR3B-","TYROBP+","LYZ+","S100A12+","CD3D-","CD3E-","CD3G-","TRAC-","NKG7-","KLRB1-","KLRD1-"],"CD16+ monocyte":["FCN1+","FCGR3A+","FCGR3B+","ITGAL+","ITGAM+","CSF3R+","CSF1R+","CX3CR1+","CDKN1C+","MS4A7+","S100A8-","S100A9-","S100A12-","CD14-","CD3D-","CD3E-","CD3G-","TRAC-","NKG7-","KLRB1-","KLRD1-"],"Dendritic cell":["HLA-DPB1+","HLA-DPA1+","HLA-DQA1+","ITGAX+","CD3D-","CD3E-","CD3G-","NCAM1-","CD19-","CD14-","CD1C+","CD1E+","FCER1A+","CLEC10A+","FCGR2B+","MS4A1-","CD79A-","CD79B-"],"Plasmacytoid dendritic cell":["IL3RA+","GZMB+","JCHAIN+","IRF7+","TCF4+","LILRA4+","CLEC4C+","ITGAX-","CD3D-","CD3E-","CD3G-","NCAM1-","CD19-","CD14-","MS4A1-","CD79A-","CD79B-"],"Plasma cell":["CD38+","XBP1+","CD27+","SLAMF7+","CD19-","MS4A1-","CD3D-","CD3E-","CD3G-","IGHA1+","IGHA2+","IGHG1+","IGHG2+","IGHG3+","IGHG4+"],"Megakaryocyte":["PF4+","PPBP+","GP5+","ITGA2B+","NRGN+","TUBB1+","SPARC+","RGS18+","MYL9+","GNG11+"]}

clacell/_marker_based_annotation/io.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pandas as pd
+
+from .types import MarkerDict
+
+
+def read_count_matrix(path: str | Path) -> pd.DataFrame:
+    matrix = pd.read_csv(path, index_col=0)
+    return matrix
+
+
+def read_markers(path: str | Path) -> MarkerDict:
+    p = Path(path)
+    if p.suffix.lower() == ".json":
+        with p.open("r", encoding="utf-8") as f:
+            obj = json.load(f)
+        return {str(k): [str(x) for x in v] for k, v in obj.items()}
+
+    if p.suffix.lower() in {".csv", ".tsv"}:
+        sep = "\t" if p.suffix.lower() == ".tsv" else ","
+        df = pd.read_csv(p, sep=sep)
+        required = {"cell_type", "marker"}
+        if not required.issubset(set(df.columns)):
+            raise ValueError("Marker table must contain columns: cell_type, marker")
+        out: MarkerDict = {}
+        for ct, grp in df.groupby("cell_type"):
+            out[str(ct)] = [str(x) for x in grp["marker"].tolist()]
+        return out
+
+    raise ValueError("Unsupported marker format. Use .json, .csv, or .tsv")

clacell/_marker_based_annotation/markers.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+from sklearn.metrics import roc_auc_score
+
+from .types import MarkerDict
+
+
+@dataclass(slots=True)
+class ClusterAucResult:
+    auc_assign: pd.Series
+    cell_type_assign: pd.Series
+    auc_table: pd.DataFrame
+    cell_type_score: pd.DataFrame
+
+
+@dataclass(slots=True)
+class AucLabelResult:
+    auc: pd.Series
+    label: pd.Series
+
+
+def split_marker(marker: MarkerDict) -> dict[str, tuple[list[str], list[str]]]:
+    out: dict[str, tuple[list[str], list[str]]] = {}
+    for cell_type, genes in marker.items():
+        pos: list[str] = []
+        neg: list[str] = []
+        for token in genes:
+            if not token:
+                continue
+            if token.endswith("-"):
+                neg.append(token[:-1])
+            elif token.endswith("+"):
+                pos.append(token[:-1])
+            else:
+                pos.append(token)
+        neg_set = set(neg)
+        pos = [g for g in pos if g not in neg_set]
+        out[cell_type] = (pos, neg)
+    return out
+
+
+def compute_marker_score(
+    x: pd.DataFrame, marker_list: tuple[list[str], list[str]]
+) -> pd.Series:
+    total = x.sum(axis=0).replace(0, np.nan)
+
+    gene_pos = [g for g in marker_list[0] if g in x.index]
+    gene_neg = [g for g in marker_list[1] if g in x.index]
+
+    if gene_pos and gene_neg:
+        out = x.loc[gene_pos].sum(axis=0) - x.loc[gene_neg].sum(axis=0)
+    elif gene_pos:
+        out = x.loc[gene_pos].sum(axis=0)
+    elif gene_neg:
+        neg_sum = x.loc[gene_neg].sum(axis=0)
+        out = neg_sum.max() - neg_sum
+    else:
+        out = pd.Series(0.0, index=x.columns)
+
+    res = out / total * 10000.0
+    res = res.fillna(0.0)
+    res[res < 0] = 0.0
+    return np.log1p(res)
+
+
+def score_auc(score: pd.Series, label: pd.Series) -> float:
+    if label.nunique() != 2:
+        return 0.5
+    try:
+        return float(roc_auc_score(label.astype(int), score))
+    except ValueError:
+        return 0.5
+
+
+def assign_cluster(auc_table: pd.DataFrame) -> tuple[pd.Series, pd.Series]:
+    auc_assign = pd.Series(index=auc_table.columns, dtype=float)
+    cell_type_assign = pd.Series(index=auc_table.columns, dtype=object)
+    for cluster in auc_table.columns:
+        col = auc_table[cluster]
+        best_type = str(col.idxmax())
+        auc_assign.loc[cluster] = float(col.loc[best_type])
+        cell_type_assign.loc[cluster] = best_type
+    return auc_assign, cell_type_assign
+
+
+def _cluster_to_celltype_map(auc_table: pd.DataFrame) -> dict[str, str]:
+    return {
+        str(cluster): str(auc_table[cluster].idxmax()) for cluster in auc_table.columns
+    }
+
+
+def _merge_detector(
+    x: pd.DataFrame,
+    cluster_name: str,
+    cell_type: str,
+    cluster_all: pd.Series,
+    cluster_to_type: dict[str, str],
+) -> float:
+    if cluster_to_type[cluster_name] == cell_type:
+        return 0.5
+
+    cluster_rm = [k for k, v in cluster_to_type.items() if v == cell_type]
+    keep = cluster_all.isin([cluster_name] + cluster_rm)
+    cluster_keep = cluster_all[keep]
+    score = x.loc[keep, cluster_to_type[cluster_name]]
+    return score_auc(score, cluster_keep == cluster_name)
+
+
+def _reassign_cluster(
+    x: pd.DataFrame,
+    cluster: pd.Series,
+    auc_table: pd.DataFrame,
+) -> tuple[pd.Series, pd.Series, pd.DataFrame]:
+    cluster_names = list(auc_table.columns.astype(str))
+    cluster_to_type = _cluster_to_celltype_map(auc_table)
+    cell_type_candidates = sorted(set(cluster_to_type.values()))
+    auc_table_update = auc_table.loc[cell_type_candidates, :].copy()
+
+    for cl in cluster_names:
+        if float(auc_table_update[cl].max()) > 0.9:
+            continue
+
+        scores: dict[str, float] = {}
+        for ct in cell_type_candidates:
+            auc_one = _merge_detector(x, cl, ct, cluster, cluster_to_type)
+
+            current_type = cluster_to_type[cl]
+            if (
+                sum(v == current_type for v in cluster_to_type.values()) == 1
+                and auc_one > 0.55
+            ):
+                continue
+
+            cluster_rm = [k for k, v in cluster_to_type.items() if v == ct and k != cl]
+            keep_mask = ~cluster.isin(cluster_rm)
+            cluster_keep = cluster[keep_mask]
+            cluster_score = x.loc[keep_mask, ct]
+            scores[ct] = score_auc(cluster_score, cluster_keep == cl)
+
+        for ct, val in scores.items():
+            auc_table_update.loc[ct, cl] = val
+
+    auc_assign, cell_type_assign = assign_cluster(auc_table_update)
+    return auc_assign, cell_type_assign, auc_table_update
+
+
+def compute_merge_cluster_auc(
+    x: pd.DataFrame,
+    cluster: pd.Series,
+    auc: pd.Series,
+    auc_table: pd.DataFrame,
+    merge: bool = True,
+    unassigned_threshold: float = 0.65,
+) -> AucLabelResult:
+    auc_curr = auc.copy()
+    auc_table_curr = auc_table.copy()
+    _, cell_type_curr = assign_cluster(auc_table_curr)
+
+    if merge:
+        auc_update, cell_type_update, auc_table_update = _reassign_cluster(
+            x, cluster, auc_table_curr
+        )
+        num_iter = 1
+        while not cell_type_curr.equals(cell_type_update) and num_iter <= 5:
+            num_iter += 1
+            auc_curr = auc_update
+            cell_type_curr = cell_type_update
+            auc_table_curr = auc_table_update
+            auc_update, cell_type_update, auc_table_update = _reassign_cluster(
+                x, cluster, auc_table_curr
+            )
+        auc_curr = auc_update
+        cell_type_curr = cell_type_update
+        auc_table_curr = auc_table_update
+
+    cluster_names = list(auc_table_curr.columns.astype(str))
+    cluster_to_type = _cluster_to_celltype_map(auc_table_curr)
+
+    unassigned_clusters = [
+        c
+        for c in cluster_names
+        if float(auc_table_curr[c].max()) < unassigned_threshold
+    ]
+    for c in unassigned_clusters:
+        cluster_to_type[c] = "Unassigned"
+
+    merged_auc: dict[str, float] = {}
+    for ct in sorted(set(cluster_to_type.values())):
+        if ct == "Unassigned":
+            continue
+        merge_clusters = [c for c, v in cluster_to_type.items() if v == ct]
+        merged_auc[ct] = score_auc(x[ct], cluster.isin(merge_clusters))
+
+    if unassigned_clusters:
+        vals = [
+            float(auc_curr.loc[c]) for c in unassigned_clusters if c in auc_curr.index
+        ]
+        if vals:
+            merged_auc["Unassigned"] = float(np.mean(vals))
+
+    label = cluster.astype(str).map(cluster_to_type)
+    return AucLabelResult(auc=pd.Series(merged_auc, dtype=float), label=label)
+
+
+def compute_cluster_auc(
+    x: pd.DataFrame, cluster: pd.Series, marker: MarkerDict
+) -> ClusterAucResult:
+    marker_split = split_marker(marker)
+    cell_type_score = pd.DataFrame(
+        {
+            cell_type: compute_marker_score(x=x, marker_list=marker_set)
+            for cell_type, marker_set in marker_split.items()
+        }
+    )
+
+    uniq_cluster = pd.Index(cluster.astype(str).unique())
+    auc_table = pd.DataFrame(
+        index=list(marker_split.keys()), columns=uniq_cluster, dtype=float
+    )
+    for cell_type in marker_split.keys():
+        for cl in uniq_cluster:
+            auc_table.loc[cell_type, cl] = score_auc(
+                cell_type_score[cell_type], cluster.astype(str) == cl
+            )
+
+    auc_assign, cell_type_assign = assign_cluster(auc_table)
+    return ClusterAucResult(
+        auc_assign=auc_assign,
+        cell_type_assign=cell_type_assign,
+        auc_table=auc_table,
+        cell_type_score=cell_type_score,
+    )
+
+
+def calculate_auc(
+    umi_count: pd.DataFrame,
+    cluster: pd.Series,
+    marker: MarkerDict,
+    merge: bool = True,
+    unassigned_threshold: float = 0.65,
+) -> AucLabelResult:
+    res = compute_cluster_auc(umi_count, cluster.astype(str), marker)
+    return compute_merge_cluster_auc(
+        res.cell_type_score,
+        cluster.astype(str),
+        res.auc_assign,
+        res.auc_table,
+        merge=merge,
+        unassigned_threshold=unassigned_threshold,
+    )
+
+
+def average_auc(auc: pd.Series) -> float:
+    counts = Counter(auc.index.tolist())
+    if len(auc) >= len(counts) * 2:
+        return 0.0
+    score = [float(auc.loc[ct]) - 0.7 for ct in counts.keys()]
+    return float(np.sum(score))