Identifying DRVI factors with LLM tools

LLM-based annotators take a factor’s top marker genes and return a cell-type or biological-process label in natural language without requiring a reference atlas. In practice, they can label factors the annotation- and enrichment-based tools leave empty — which makes them useful when neither of the previous steps identifies a factor. This notebook covers:

1. Direct LLM annotation — a single, well-structured prompt you control, runnable against any backend (Ollama, Claude API, Claude Code (no API key), OpenAI, or Gemini). You own the prompt and can inspect exactly what the model was asked.

2. CASSIA — a multi-agent annotator (chain-of-thought → validation loop → structured output) with a quality score.

3. gs2txt — free-text process summaries that run pathway enrichment first, then one LLM call.

This is one of four companion notebooks. See cell types from annotations, biological processes via enrichment, and factor curation. All share embed.h5ad; the curation notebook picks up the results stored here.

Note: LLM output is fluent but produced without an uncertainty signal and can be confidently wrong, so always cross-check it against the SMI and enrichment tools and against the literature.

Install the backends and tools via the install cell below (all bundled in the drvi-py tutorials-llm extra).

Prerequisites

Assumes a trained DRVI model with interpretability scores (see the general pipeline).

Adapting to your own model — change io_dir (Section 0), pick LLM_BACKEND, set that backend’s model and credentials, and set llm_tissue_context / llm_species.

Contact

Questions: scverse discourse. Bugs: issue tracker.

Install

Every optional tool this notebook can use is bundled in the tutorials-llm extra of drvi-py. To install all of them at once:

pip install "drvi-py[tutorials-llm]"

That pulls in every backend SDK (openai, anthropic, claude-agent-sdk, google-genai), plus nest-asyncio, cassia (Section 2), and gs2txt[enrichment] (Section 3). If you only need a single backend, install just what it requires instead:

• Ollama or OpenAI: pip install openai

• Claude API: pip install anthropic

• Claude Code (no API key — uses your Claude Code login): pip install claude-agent-sdk; also needs the claude CLI installed and logged in (claude login), and in Jupyter pip install nest-asyncio.

• Gemini: pip install google-genai

• CASSIA (Section 2): pip install cassia

• gs2txt (Section 3): pip install "gs2txt[enrichment]"

import sys
import subprocess

# Everything at once (all backends + CASSIA + gs2txt):
# subprocess.check_call([sys.executable, "-m", "pip", "install", "drvi-py[tutorials-llm]"])

# ...or uncomment only the line(s) for the backend/tools you want to use:
# subprocess.check_call([sys.executable, "-m", "pip", "install", "openai"])            # Ollama / OpenAI
# subprocess.check_call([sys.executable, "-m", "pip", "install", "anthropic"])         # Claude API
# subprocess.check_call([sys.executable, "-m", "pip", "install", "claude-agent-sdk", "nest-asyncio"])  # Claude Code
# subprocess.check_call([sys.executable, "-m", "pip", "install", "google-genai"])      # Gemini
# subprocess.check_call([sys.executable, "-m", "pip", "install", "cassia"])            # Section 2
# subprocess.check_call([sys.executable, "-m", "pip", "install", "gs2txt[enrichment]"])  # Section 3

Imports

import warnings
warnings.filterwarnings("ignore")

import json
import re
import asyncio
import pandas as pd
from pathlib import Path

from drvi.model import DRVI
import scanpy as sc

0. Setup

Config

# Input/output directory holding the trained model and embeddings. Update accordingly.
io_dir = Path("./tmp_io/drvi_immune_128/").resolve()

# DRVI provides two complementary per-gene score matrices (both precomputed by the general pipeline):
#   OOD ("OOD_combined")             — SPECIFIC genes: highlights genes that uniquely mark a program;
#                                      genes shared across many programs are penalized.
#   IND ("IND_linear_weighted_mean") — DIRECT effect: the latent factor's effect on each gene, similar
#                                      to a log fold-change, so it also keeps differential genes that
#                                      are SHARED between programs.
score_key = "OOD_combined"                   # OOD (specific) — also used by CASSIA and gs2txt below
score_key_ind = "IND_linear_weighted_mean"   # IND (direct effect, logFC-like)

# Top genes sent to the LLM per score type, plus a cutoff for each score.
llm_top_n_genes = 100
drvi_score_cutoff = 0.5     # OOD cutoff (specific genes)
ind_score_cutoff = 0.5      # IND cutoff (direct-effect genes)

# Biological context passed to every tool.
llm_tissue_context = "human immune cells (PBMC / bone marrow)"
llm_species = "human"  # or "mouse"

# How many informative factor-directions to annotate. Set to an int for a quick/cheap smoke test
# (annotates the first N); None = annotate all. Applies to every section below.
# NOTE: the example outputs saved in this notebook were produced with the 8-direction sample below.
max_directions = None

Load model and embeddings

adata = sc.read_h5ad(io_dir / "adata_preprocesses.h5ad")
model = DRVI.load(io_dir / "drvi_model", adata)

embed_path = io_dir / "embed.h5ad"
embed = sc.read_h5ad(embed_path)

# Per-gene score matrices. scores_df (OOD, specific) is used by every tool; the direct-LLM section
# below also uses ind_scores (IND, direct effect) so the model sees both specific and shared genes.
scores_df = model.get_interpretability_scores(embed, adata, key=score_key)
ind_scores = model.get_interpretability_scores(embed, adata, key=score_key_ind)

INFO     File                                                                                                      
         /lustre/groups/ml01/code/amirali.moinfar/projects/drvi_tutorials/tmp_io/drvi_immune_128/drvi_model/model.p
         t already downloaded
INFO     DRVI: The model is trained with DRVI version 0.2.6.
INFO     DRVI: Updaging data setup config ...
INFO     DRVI: Done updating data source registry. Loading in DRVI version 0.2.6.
INFO     DRVI: Loading model from DRVI version 0.2.6.
INFO     DRVI: Done updating model args. Loading in 0.2.6.
INFO     DRVI: The model has been initialized

1. Direct LLM annotation

Instead of relying on a wrapper package’s hidden prompt, we send our own structured prompt and choose the backend. For each factor-direction the model receives both DRVI score views — the OOD specific genes and the IND direct-effect genes — with an explanation of what each means, the tissue context, is asked to reason, and returns a small JSON object (cell_type, biological_process, key_genes, confidence, reasoning) that we parse and store. Because you control the prompt, you can adapt it to your tissue and see exactly what was asked.

Choose a backend

Set LLM_BACKEND and fill in the model + credentials for that backend only:

• "ollama" — free, local/cluster, OpenAI-compatible. See the Ollama setup guide below.

• "claude" — Anthropic API via the anthropic SDK. Set ANTHROPIC_API_KEY.

• "claude_code" — Claude Agent SDK, which uses your existing Claude Code login — no API key needed. Requires the claude CLI installed and authenticated (claude login); the SDK talks to that local CLI process.

• "openai" — OpenAI API. Set OPENAI_API_KEY.

• "gemini" — Google Gemini API. Set GEMINI_API_KEY (or GOOGLE_API_KEY).

LLM_BACKEND = "claude_code"  # one of: "ollama", "claude", "claude_code", "openai", "gemini"

# Ollama (OpenAI-compatible; no API key needed)
OLLAMA_URL   = "http://127.0.0.1:11434"  # replace with your node and port
OLLAMA_MODEL = "qwen3.6:35b"

# Claude via the Anthropic API SDK — reads ANTHROPIC_API_KEY from the environment
CLAUDE_MODEL = "claude-opus-4-8"   # "claude-haiku-4-5" is cheaper/faster

# Claude via the Claude Agent SDK (uses your Claude Code login; no API key)
CLAUDE_CODE_MODEL = "opus"         # short alias ("opus"/"sonnet"/"haiku") or a full model ID

# OpenAI — reads OPENAI_API_KEY from the environment
OPENAI_MODEL = "gpt-4o"

# Gemini (google-genai) — reads GEMINI_API_KEY / GOOGLE_API_KEY from the environment
GEMINI_MODEL = "gemini-2.5-flash"

The backend dispatcher

One call_llm(system, user) function, five backends. Only the selected backend’s package needs to be installed.

def _run_async(coro):
    """Run an async coroutine from sync code, tolerating an already-running loop (e.g. Jupyter)."""
    try:
        asyncio.get_running_loop()
    except RuntimeError:
        return asyncio.run(coro)
    import nest_asyncio  # only needed inside a live loop (Jupyter)
    nest_asyncio.apply()
    return asyncio.get_event_loop().run_until_complete(coro)


def call_llm(system, user):
    if LLM_BACKEND == "ollama":
        from openai import OpenAI
        client = OpenAI(base_url=f"{OLLAMA_URL}/v1", api_key="ollama")
        resp = client.chat.completions.create(
            model=OLLAMA_MODEL,
            messages=[{"role": "system", "content": system}, {"role": "user", "content": user}],
            temperature=0,
        )
        return resp.choices[0].message.content

    if LLM_BACKEND == "openai":
        from openai import OpenAI
        client = OpenAI()  # reads OPENAI_API_KEY
        resp = client.chat.completions.create(
            model=OPENAI_MODEL,
            messages=[{"role": "system", "content": system}, {"role": "user", "content": user}],
            temperature=0,
        )
        return resp.choices[0].message.content

    if LLM_BACKEND == "claude":
        import anthropic
        client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY
        # Note: newer Claude models reject temperature/top_p — steer via the prompt instead.
        msg = client.messages.create(
            model=CLAUDE_MODEL,
            max_tokens=1024,
            system=system,
            messages=[{"role": "user", "content": user}],
        )
        return "".join(block.text for block in msg.content if block.type == "text")

    if LLM_BACKEND == "claude_code":
        # Claude Agent SDK — talks to your local, logged-in `claude` CLI (no API key).
        from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock

        async def _ask():
            text = ""
            options = ClaudeAgentOptions(
                system_prompt=system, model=CLAUDE_CODE_MODEL, max_turns=1, allowed_tools=[],
            )
            async for message in query(prompt=user, options=options):
                if isinstance(message, AssistantMessage):
                    for block in message.content:
                        if isinstance(block, TextBlock):
                            text += block.text
            return text

        return _run_async(_ask())

    if LLM_BACKEND == "gemini":
        from google import genai
        client = genai.Client()  # reads GEMINI_API_KEY / GOOGLE_API_KEY
        resp = client.models.generate_content(model=GEMINI_MODEL, contents=f"{system}\n\n{user}")
        return resp.text

    raise ValueError(f"Unknown LLM_BACKEND: {LLM_BACKEND!r}")

The predefined prompt

A fixed expert system prompt plus a per-factor user prompt that injects two ranked gene lists (OOD = specific genes, IND = direct-effect / logFC-like genes), explains what each means, asks the model to reason, and constrains the output to a small JSON object. Adapt the wording to your own tissue/organism if needed.

IDENTIFY_SYSTEM = (
    "You are an expert computational biologist specializing in single-cell transcriptomics and "
    "immunology. You interpret latent gene programs learned by DRVI, a disentangled variational "
    "model. Each program is summarized by two complementary ranked marker-gene lists — a "
    "specificity score and a direct-effect score — whose meanings are explained in the prompt. "
    "Given these lists and the tissue context, identify what the program most likely represents, "
    "reasoning from established marker-gene biology. Be precise and do not overstate confidence "
    "when the genes are ambiguous."
)


def build_identify_prompt(factor_label, ood_genes, ind_genes, tissue):
    return (
        f"Tissue context: {tissue}\n"
        f"DRVI program: {factor_label}\n\n"
        "You are given two complementary ranked marker-gene lists for this program "
        "(both ranked most-influential first):\n\n"
        "1. SPECIFIC genes (OOD score): genes that most *specifically* mark this program. This "
        "score penalizes genes that are shared across many programs, so these are the program's "
        "most distinctive identity markers.\n"
        f"{', '.join(ood_genes)}\n\n"
        "2. DIRECT-EFFECT genes (IND score): the latent factor's direct effect on each gene, "
        "analogous to a log fold-change. It does NOT penalize sharing, so it also includes "
        "differential genes that are shared between programs — useful for reading the broader "
        "biological process and shared machinery.\n"
        f"{', '.join(ind_genes)}\n\n"
        "Use the SPECIFIC list mainly to pin down cell-type identity, and the DIRECT-EFFECT list to "
        "read the broader process (including shared genes). Reason from both, then give your answer "
        "as a JSON object with exactly these keys:\n"
        '  "cell_type": most likely cell type or cell state (or "unclear")\n'
        '  "biological_process": dominant biological process or pathway (or "unclear")\n'
        '  "key_genes": up to 5 genes that most support the call (list of strings)\n'
        '  "confidence": one of "high", "medium", "low"\n'
        '  "reasoning": one or two sentences justifying the call\n'
        "Respond with ONLY the JSON object — no surrounding text and no code fences."
    )

Parse and run

LLMs sometimes wrap JSON in prose or code fences, so we extract the first JSON object defensively.

def parse_json(text):
    text = (text or "").strip()
    if text.startswith("```"):
        text = re.sub(r"^```[a-zA-Z]*\n?", "", text).rstrip("`").strip()
    match = re.search(r"\{.*\}", text, re.DOTALL)
    if not match:
        return {}
    try:
        return json.loads(match.group(0))
    except json.JSONDecodeError:
        return {}


def top_genes(scores, col, cutoff, top_n):
    s = scores[col]
    return s[s >= cutoff].nlargest(top_n).index.astype(str).tolist()


def identify_factors(ood_scores, ind_scores, tissue, ood_cutoff, ind_cutoff, top_n, max_dirs=None):
    rows = []
    for col in ood_scores.columns:
        ood_genes = top_genes(ood_scores, col, ood_cutoff, top_n)
        if not ood_genes:  # uninformative direction — skip
            continue
        ind_genes = top_genes(ind_scores, col, ind_cutoff, top_n)
        parsed = parse_json(
            call_llm(IDENTIFY_SYSTEM, build_identify_prompt(col, ood_genes, ind_genes, tissue))
        )
        key_genes = parsed.get("key_genes")
        rows.append({
            "factor": col[:-1].strip(),
            "direction": col[-1],
            "cell_type": parsed.get("cell_type"),
            "biological_process": parsed.get("biological_process"),
            "key_genes": ", ".join(key_genes) if isinstance(key_genes, list) else key_genes,
            "confidence": parsed.get("confidence"),
            "reasoning": parsed.get("reasoning"),
        })
        print(f"{col}: {parsed.get('cell_type')} / {parsed.get('biological_process')}")
        if max_dirs is not None and len(rows) >= max_dirs:
            break
    return pd.DataFrame(rows)


llm_direct_results = identify_factors(
    scores_df, ind_scores, llm_tissue_context, drvi_score_cutoff, ind_score_cutoff,
    llm_top_n_genes, max_directions,
)
with pd.option_context("display.max_colwidth", None):
    display(llm_direct_results)

DR 1-: Naive CD4+ T cell / Naive T-cell identity and quiescence / lymph-node homing (TCR signaling machinery)
DR 2-: Myeloid cells — classical (CD14+) monocytes with strong granulocytic/neutrophil-like features / Innate immune / inflammatory antimicrobial response (S100 alarmin signaling, phagocytosis, chemotaxis)
DR 3+: Naive/mature B cells / B-cell receptor signaling and MHC-II antigen presentation (B-lymphocyte identity)
DR 4-: CD4+ memory/helper T cell (activated, Treg/Th2-skewed, skin/tissue-homing) / T-cell activation and tissue-homing with regulatory/Th2 polarization (chemokine-receptor–guided trafficking and costimulation)
DR 5+: CD56dim CD16+ cytotoxic (mature/terminal effector) NK cells / NK-mediated cytotoxicity / granule-dependent killing and terminal effector differentiation
DR 6+: Monocyte/macrophage (myeloid), predominantly CD14+ classical monocytes with monocyte-derived macrophage features / Innate myeloid immune response — phagocytosis, complement/scavenger-receptor activity, and pro-inflammatory cytokine signaling
DR 7-: MAIT cells (mucosal-associated invariant T cells) / Innate-like semi-invariant T-cell effector/cytotoxic program (type-17/IL-18-responsive), driven by ZBTB16/RORA with GZMK-biased cytotoxicity
DR 8-: Cytotoxic effector lymphocytes — terminally differentiated effector CD8+ T cells (TEMRA) and CD56dim NK cells / Cytotoxic effector function / terminal effector differentiation (granzyme-perforin killing, TBX21/ZEB2/S1PR5-driven program)
DR 9-: Naive/central-memory CD8+ T cell / CD8 T-cell lineage identity with a quiescent naive/Tcf7-driven program (TCR signaling, lymph-node homing)
DR 10+: CD16+ non-classical monocytes / Monocyte/macrophage myeloid immune function — Fc-gamma receptor signaling, complement sensing, and patrolling phenotype
DR 11-: GZMK+ effector-memory CD8 T cell (Tem) / cytotoxic effector program / Th1-type type-I immune response
DR 12-: Erythroid lineage cells (erythroblasts/reticulocytes and erythroid progenitors) / Erythroid maturation — hemoglobin synthesis, heme/iron metabolism, and mitochondrial clearance (enucleation/reticulocyte maturation)
DR 13+: B cells (with cDC2/dendritic-cell overlap) / B-lymphocyte identity and antigen presentation / BCR signaling
DR 14+: GZMK+ CD8+ effector-memory T cell (EOMES+, activated/pre-exhausted) / Cytotoxic effector program with T-cell activation and inhibitory/exhaustion signaling
DR 15-: Erythroid lineage cells (proliferating erythroblasts / erythroid progenitors) / Erythropoiesis and heme/hemoglobin biosynthesis with active cell-cycle/proliferation
DR 16-: Plasmacytoid dendritic cell (pDC) / Type I interferon program / pDC identity (TCF4-driven, IRF7-mediated IFN-α response)
DR 17+: B cells (mature/memory B lymphocytes) / B-cell receptor signaling and humoral adaptive immune function
DR 18-: MAIT / type-17 (Th17-like) T cells / RORγt-driven type-17 effector program (IL-23/IL-18 responsiveness, mucosal homing)
DR 19-: Hematopoietic stem/progenitor cell (HSPC), likely GATA2+ myeloid/mast-basophil-biased progenitor / Early hematopoietic progenitor identity with lipoprotein/lipid metabolism (APOE/APOC1) and progenitor proliferation/self-renewal programs
DR 20-: Hematopoietic stem/progenitor cells (HSPCs), likely lymphoid-primed early progenitors / Early hematopoiesis / progenitor commitment with early lymphoid (pro-B/lymphoid) priming
DR 21-: Hematopoietic stem/progenitor cells (HSC/MPP) / Stemness and multilineage priming (megakaryocyte-erythroid/HSC transcriptional program)
DR 22-: Erythroid progenitor / proliferating erythroblast / Erythropoiesis (hemoglobin/heme synthesis and red-cell membrane assembly) coupled with cell-cycle proliferation
DR 23+: Erythroid lineage cells (erythroblasts / erythroid progenitors, incl. reticulocytes) / Erythroid differentiation with heme/hemoglobin biosynthesis and reticulocyte mitochondrial clearance (mitophagy)
DR 24-: Natural killer (NK) cell, CD56dim cytotoxic subset / Cytotoxic effector function / target-cell killing and NK activation
DR 25+: Regulatory T cells (Tregs), likely activated/effector Treg / Immunosuppression / regulatory T-cell identity and function (FOXP3-driven suppressive program)
DR 26+: Plasma cell / plasmablast (antibody-secreting B lineage) / Immunoglobulin secretion driven by the unfolded-protein/ER-stress response and terminal plasma-cell differentiation
DR 27-: Monocyte/macrophage (myeloid lineage; features of non-classical CD16+ monocytes and macrophage differentiation) / Innate immune myeloid effector function — complement production (C1Q), Fc-receptor/phagocytosis signaling and inflammatory activation
DR 28-: Conventional dendritic cells type 2 (cDC2 / CD1c+ DCs) / Antigen presentation and lipid-antigen sensing (MHC-II / CD1-mediated antigen presentation)
DR 29+: Myeloid antigen-presenting cells — cDC2 (type-2 conventional dendritic cells) with a classical-monocyte component / Myeloid/mononuclear-phagocyte identity and antigen presentation (Fc-receptor and C-type lectin sensing, innate immune recognition)
DR 30-: GATA2-driven early myeloid progenitor with mast/basophil–megakaryocyte–erythroid (MEBEMP/MEMP) bias / GATA1/GATA2/KLF1-orchestrated commitment along the mast-cell/basophil–megakaryocyte–erythroid axis (granule/histamine and platelet programs)
DR 31+: B-cell precursor (pro-B/pre-B cell) / early B-lymphopoiesis / VDJ recombination and pre-BCR assembly
DR 32-: Mononuclear phagocyte — tissue-resident/anti-inflammatory macrophage with a cDC2 (CD1C+ dendritic cell) component / Antigen presentation (MHC class II) combined with complement-mediated innate immunity/efferocytosis
DR 33-: Megakaryocytes / platelets / Platelet biogenesis and activation — cytoskeletal/tubulin machinery, alpha-granule proteins, and GPIb-IX-V / integrin αIIbβ3 hemostatic function
DR 34+: Granulocyte-monocyte progenitor / neutrophil precursor (promyelocyte–myelocyte) / Early granulopoiesis — primary (azurophilic) granule gene expression coupled with active cell-cycle proliferation
DR 35+: Granulocyte-monocyte progenitor / promyelocyte (early myeloid precursor) / Azurophilic (primary) granule biogenesis during early granulopoiesis
DR 36-: Granulocyte-monocyte / early myeloid progenitor (HSPC, bone marrow) / Myeloid lineage commitment and granulocyte progenitor differentiation (azurophilic granule / myeloperoxidase program)
DR 37+: Checkpoint-high CD4 T cells with T follicular helper (Tfh)/exhausted phenotype / Immune-checkpoint / T-cell exhaustion signaling combined with Tfh-like activation and cell-cycle proliferation
DR 38+: B-cell precursors (pro-B/pre-B cells) / Early B-lymphopoiesis / pre-B cell receptor assembly and B-lineage commitment
DR 40-: Neutrophils (mature granulocytes) / Neutrophil-mediated innate immune / inflammatory response (chemokine signaling, degranulation, phagocytosis)
DR 41+: Natural killer (NK) cells / NK-cell cytotoxic effector function (natural killer-mediated cytotoxicity)
DR 42+: Granulocytic progenitor (promyelocyte / GMP) with basophil–mast–eosinophil bias / Granulopoiesis and azurophilic/secretory granule protein synthesis
DR 43-: unclear (interferon-responding immune cells; the program is a cell-state signature not restricted to one lineage) / Type I interferon antiviral response (ISG signature)
DR 45+: cycling/proliferating cells / cell cycle (S and G2/M phase proliferation)
DR 46+: Conventional dendritic cells type 2 (cDC2 / CD1C+ DC) / MHC class II antigen presentation
DR 47-: Conventional dendritic cell type 1 (cDC1 / CD141+ BDCA3+ DC) / Antigen cross-presentation and MHC class II antigen presentation
DR 48-: Proliferating cells (cycling immune cells; mast/basophil progenitors possible) / Cell cycle — mitosis / G2-M phase proliferation
DR 49+: Mesenchymal stromal cell / fibroblast (LEPR+ bone marrow stroma) / Extracellular matrix production and stromal remodeling with pro-inflammatory/angiogenic signaling
DR 51-: Plasmacytoid dendritic cells (pDCs), possibly including AXL+ transitional/AS-DC subset / pDC identity and type I interferon production / antiviral response
DR 52-: Megakaryocyte / platelet lineage / Platelet biogenesis, alpha-granule content and platelet activation/adhesion (GPIb-IX-V, integrin αIIbβ3 signaling)
DR 53+: Plasmablasts / plasma cells (proliferating) / Antibody-secretory plasma cell differentiation (IRF4/PRDM1/XBP1-driven UPR and ER secretory machinery) coupled with active cell-cycle/proliferation
DR 55-: Cytotoxic effector/terminally-differentiated CD8+ T cell (ZNF683/Hobit+, likely with NK-like features) / Cytotoxic effector differentiation with exhaustion/terminal markers and an interferon-response signature
DR 56+: Osteoclast / osteoclast-like macrophage (monocyte-macrophage lineage) / Osteoclast differentiation and bone resorption (acidification and matrix degradation), overlaid on a complement-rich tissue-macrophage program

	factor	direction	cell_type	biological_process	key_genes	confidence	reasoning
0	DR 1	-	Naive CD4+ T cell	Naive T-cell identity and quiescence / lymph-node homing (TCR signaling machinery)	CCR7, LEF1, TCF7, CD40LG, IL7R	high	The specific list is dominated by canonical naive T-cell markers (CCR7, LEF1, TCF7, MAL, FHIT, TSHZ2, SATB1, BCL11B) together with pan-T CD3D/E/G and the CD4-helper marker CD40LG, indicating a resting/naive CD4+ T cell; the direct-effect list reinforces this with CCR7, LEF1, IL7R and TCR-proximal signaling genes (LCK, ITK, LAT, CD2, CD27/CD28).
1	DR 2	-	Myeloid cells — classical (CD14+) monocytes with strong granulocytic/neutrophil-like features	Innate immune / inflammatory antimicrobial response (S100 alarmin signaling, phagocytosis, chemotaxis)	S100A12, S100A8, CD14, FCN1, CSF3R	high	The specific list is dominated by classical-monocyte/myeloid identity markers (CD14, FCN1, VCAN, LYZ, S100A8/9/A12, CLEC4D/E, FPR1/2, TREM1, CSF3R) with S100-alarmin and neutrophil-associated genes (S100A12, CSF3R, RETN, CDA) indicating an inflammatory innate-immune myeloid program spanning classical monocytes and granulocytic cells; the direct-effect list reinforces this with PADI4, ALOX5AP, HP, NCF2, and CD36 reflecting antimicrobial/phagocytic machinery.
2	DR 3	+	Naive/mature B cells	B-cell receptor signaling and MHC-II antigen presentation (B-lymphocyte identity)	MS4A1, CD79A, CD19, TCL1A, FCER2	high	The specific list is dominated by canonical B-cell identity genes (MS4A1/CD20, CD79A/B, CD19, CD22, PAX5, VPREB3, BANK1, BLK, EBF1), and the strong TCL1A, FCER2/CD23 and CD200 signal points to a resting naive/follicular B-cell state, while the direct-effect list adds BCR machinery (BTK, BLNK, RASGRP3) and MHC-II genes reflecting antigen presentation.
3	DR 4	-	CD4+ memory/helper T cell (activated, Treg/Th2-skewed, skin/tissue-homing)	T-cell activation and tissue-homing with regulatory/Th2 polarization (chemokine-receptor–guided trafficking and costimulation)	TNFRSF4, IL7R, CCR10, GATA3, CD40LG	medium	The specific markers (TNFRSF4/OX40, IL7R, IL32, LTB) plus direct-effect genes CD40LG, GATA3, CCR4/CCR6/CCR10, FUT7, TNFRSF18(GITR) and IL2RA(CD25) point to an activated CD4+ helper/memory T-cell program with skin/tissue-homing and regulatory/Th2 features; AIRE is an unexpected co-varying gene and tempers confidence.
4	DR 5	+	CD56dim CD16+ cytotoxic (mature/terminal effector) NK cells	NK-mediated cytotoxicity / granule-dependent killing and terminal effector differentiation	NKG7, GNLY, PRF1, KLRF1, FCGR3A	high	The specific list is dominated by cytolytic effector genes (PRF1, GNLY, GZMB/GZMA/GZMH, NKG7) plus NK-restricted receptors (KLRF1/NKp80, NCR1/NKp46, NCR3, KIR2DL3/KIR3DL2, CD160, KLRD1) and terminal-effector markers (FGFBP2, S1PR5, CX3CR1, FCGR3A/CD16, B3GAT1/CD57), pinpointing mature CD56dim CD16+ cytotoxic NK cells; the direct-effect list reinforces this with FCER1G, SIGLEC7, NCAM1, TBX21 and additional cytotoxic machinery.
5	DR 6	+	Monocyte/macrophage (myeloid), predominantly CD14+ classical monocytes with monocyte-derived macrophage features	Innate myeloid immune response — phagocytosis, complement/scavenger-receptor activity, and pro-inflammatory cytokine signaling	CD14, FCN1, LYZ, CD163, TYROBP	high	The specific list is dominated by canonical monocyte/macrophage identity genes (CD14, FCN1, LYZ, S100A9, TYROBP/FCER1G, CD163, MARCO, CYBB), while the direct-effect list adds scavenger/complement and antigen-presentation machinery (VSIG4, C3AR1, CFD, CD68, CSF1R, HLA-DR genes), indicating a mononuclear phagocyte program spanning classical monocytes and monocyte-derived macrophages.
6	DR 7	-	MAIT cells (mucosal-associated invariant T cells)	Innate-like semi-invariant T-cell effector/cytotoxic program (type-17/IL-18-responsive), driven by ZBTB16/RORA with GZMK-biased cytotoxicity	SLC4A10, KLRB1, IL23R, NCR3, GZMK	high	The specific list is a textbook MAIT signature — SLC4A10 (the canonical MAIT marker), KLRB1/CD161, IL23R, NCR3 and GZMK — and the direct-effect list adds ZBTB16(PLZF), RORA, CCR6, IL18RAP/IL18R1 and CXCR6, confirming the PLZF-driven, IL-18-responsive innate-like T-cell program rather than a conventional CD8 subset.
7	DR 8	-	Cytotoxic effector lymphocytes — terminally differentiated effector CD8+ T cells (TEMRA) and CD56dim NK cells	Cytotoxic effector function / terminal effector differentiation (granzyme-perforin killing, TBX21/ZEB2/S1PR5-driven program)	FGFBP2, ZNF683, GZMH, FCRL6, GNLY	high	The specific markers (GZMH, FGFBP2, ZNF683/Hobit, NKG7, GZMA, KLRG1, GNLY, FCRL6) define a terminal cytotoxic effector signature shared by CD8 TEMRA and CD56dim NK cells, and the direct-effect list reinforces this with CX3CR1, S1PR5, TBX21, ZEB2, PRF1, FASLG plus mixed T (CD3D/CD8A) and NK (NCR1, KLRF1, NCAM1, KIRs) genes, indicating a cross-lineage cytotoxic effector axis rather than a single pure population.
8	DR 9	-	Naive/central-memory CD8+ T cell	CD8 T-cell lineage identity with a quiescent naive/Tcf7-driven program (TCR signaling, lymph-node homing)	CD8A, CD8B, CCR7, LEF1, TCF7	high	The specific list is dominated by canonical CD8 lineage genes (CD8A/CD8B, CD3D/E/G, LCK, ZAP70) together with a strong naive/quiescence signature (CCR7, LEF1, TCF7, SELL-like NELL2/LRRN3, PASK, BACH2, MYC, IL7R), pinpointing naive-to-central-memory CD8 T cells; the direct-effect list reinforces cytotoxic-lineage identity (CD8A/B, CRTAM, KLRC1/3/4, NCR3, RUNX3) though it mixes in shared myeloid/B genes typical of unpenalized effects.
9	DR 10	+	CD16+ non-classical monocytes	Monocyte/macrophage myeloid immune function — Fc-gamma receptor signaling, complement sensing, and patrolling phenotype	FCGR3A, CDKN1C, MS4A7, CX3CR1, LST1	high	The specific markers are a textbook non-classical (patrolling) monocyte signature — FCGR3A (CD16), CDKN1C, MS4A7, HES4, LST1, CX3CR1, and MTSS1 — with the direct-effect list adding broad monocyte/macrophage machinery (CSF1R, CD68, C1QA, TYROBP, FCER1G, AIF1, MAFB, SPI1), consistent with a mature FCGR3A-high monocyte program.
10	DR 11	-	GZMK+ effector-memory CD8 T cell (Tem)	cytotoxic effector program / Th1-type type-I immune response	GZMK, CCL5, GZMA, EOMES, CD8A	high	GZMK, CCL5 and GZMA with CD8A/CD8B, EOMES, TBX21, IFNG, CXCR3 and NK-receptor genes (KLRC1/KLRD1/NKG7) define a cytotoxic CD8 T cell, and the dominance of GZMK over GZMB with EOMES points specifically to a GZMK+ effector-memory/transitional CD8 T cell state.
11	DR 12	-	Erythroid lineage cells (erythroblasts/reticulocytes and erythroid progenitors)	Erythroid maturation — hemoglobin synthesis, heme/iron metabolism, and mitochondrial clearance (enucleation/reticulocyte maturation)	HBA1, BPGM, SLC25A37, FECH, KLF1	high	The specific marker HBA1 plus a coherent erythroid module in the direct-effect list (BPGM, NCOA4, GMPR, BNIP3L, SLC25A37/mitoferrin, FECH, BLVRB, HEMGN, TRIM58, KLF1, NFE2, TAL1, RHD, HMBS) unambiguously identifies erythroid cells undergoing hemoglobinization, heme/iron handling, and organelle clearance; scattered myeloid genes are shared/non-specific and do not define the program.
12	DR 13	+	B cells (with cDC2/dendritic-cell overlap)	B-lymphocyte identity and antigen presentation / BCR signaling	MS4A1, CD79A, CD19, BANK1, CD1C	high	The specific list is dominated by canonical B-cell identity and BCR-complex genes (MS4A1/CD20, CD79A/B, CD19, CD79B, BANK1, BLK, TNFRSF13B/TACI, FCRL2/FCRLA), pinning this to the B-lymphocyte lineage, while direct-effect genes (CD1C, CLECL1, LILRA4, PLD4, SPIB, TCF4) add a shared conventional/plasmacytoid dendritic-cell antigen-presenting-cell signature.
13	DR 14	+	GZMK+ CD8+ effector-memory T cell (EOMES+, activated/pre-exhausted)	Cytotoxic effector program with T-cell activation and inhibitory/exhaustion signaling	CD8A, GZMK, EOMES, TNFRSF9, TIGIT	high	The specific list is dominated by CD8 lineage (CD8A/CD8B) plus GZMK, GZMA, NKG7, CST7 and EOMES defining a GZMK-high cytotoxic effector-memory CD8 T cell, while TNFRSF9, TIGIT, LAG3, PDCD1, TOX and IFNG indicate an activated, pre-exhausted state; a minor NK-associated component (NCR1, KLRF1, KIR genes) appears only in the non-specific direct-effect list.
14	DR 15	-	Erythroid lineage cells (proliferating erythroblasts / erythroid progenitors)	Erythropoiesis and heme/hemoglobin biosynthesis with active cell-cycle/proliferation	HBA1, HEMGN, RHCE, TAL1, GFI1B	high	The specific markers (HBA1, RHCE/RHD blood-group antigens, HEMGN, CA2) and direct-effect genes (TAL1, NFE2, GFI1B, SLC25A37, FECH, HMBS, BLVRB, TFRC) are canonical erythroid identity and heme-synthesis genes, while co-expressed CDK1, MKI67, NUSAP1, and CENPF indicate these are actively cycling erythroid progenitors/erythroblasts expected in bone marrow.
15	DR 16	-	Plasmacytoid dendritic cell (pDC)	Type I interferon program / pDC identity (TCF4-driven, IRF7-mediated IFN-α response)	LILRA4, CLEC4C, IL3RA, IRF7, TCF4	high	The specific list is dominated by canonical pDC identity markers (LILRA4, CLEC4C/BDCA2, IL3RA/CD123, GZMB, PLD4, IRF7/IRF8, TCF4/E2-2, SPIB, BCL11A), and the direct-effect list reinforces the pDC type-I-IFN and secretory program (PTGDS, SERPINF1, DNASE1L3, MZB1), leaving little ambiguity.
16	DR 17	+	B cells (mature/memory B lymphocytes)	B-cell receptor signaling and humoral adaptive immune function	MS4A1, CD79A, CD19, BANK1, BLK	high	The specific list is dominated by canonical B-lineage identity genes (MS4A1/CD20, CD79A, CD19, CD22, BANK1, BLK, FCRL5, TNFRSF13B, SPIB, POU2AF1), unambiguously marking B cells, while the direct-effect list reinforces BCR/antibody machinery (IGLL5, TNFRSF17, CD27, HLA-DQ) consistent with mature and antigen-experienced B-cell programs.
17	DR 18	-	MAIT / type-17 (Th17-like) T cells	RORγt-driven type-17 effector program (IL-23/IL-18 responsiveness, mucosal homing)	KLRB1, SLC4A10, IL23R, CCR6, RORA	high	KLRB1 (CD161) is the single most specific marker, and the direct-effect list is dominated by a coherent type-17 signature — SLC4A10 (a hallmark MAIT gene), IL23R, CCR6, IL18R1/IL18RAP, RORA and MAF — indicating RORγt+ CD161-high MAIT/Th17-like T cells.
18	DR 19	-	Hematopoietic stem/progenitor cell (HSPC), likely GATA2+ myeloid/mast-basophil-biased progenitor	Early hematopoietic progenitor identity with lipoprotein/lipid metabolism (APOE/APOC1) and progenitor proliferation/self-renewal programs	GATA2, CYTL1, PRSS57, APOC1, CDK6	medium	The direct-effect list is dominated by classic bone-marrow progenitor genes (GATA2, CYTL1, PRSS57, HHEX, MEF2C, CDK6, MYC, EGFL7) together with strong APOE/APOC1 lipoprotein signal typical of early GATA2-driven progenitors, while the specific markers (ALDH1A1, APOC1) reinforce an immature progenitor identity, though the exact lineage bias (mast/basophil vs erythroid-megakaryocyte) is ambiguous.
19	DR 20	-	Hematopoietic stem/progenitor cells (HSPCs), likely lymphoid-primed early progenitors	Early hematopoiesis / progenitor commitment with early lymphoid (pro-B/lymphoid) priming	SPINK2, DNTT, PRSS57, IGLL1, CDCA7	high	SPINK2, PRSS57, CDCA7 and EGFL7 are canonical bone-marrow HSPC/blast markers, while DNTT (TdT), IGLL1 and MME (CD10) mark early lymphoid-primed progenitors, together indicating an immature progenitor program rather than a mature immune subset.
20	DR 21	-	Hematopoietic stem/progenitor cells (HSC/MPP)	Stemness and multilineage priming (megakaryocyte-erythroid/HSC transcriptional program)	CRHBP, CYTL1, SPINK2, MSI2, MEIS1	high	The specific markers CRHBP, CYTL1, SPINK2, MSI2 and MYCT1 are canonical human bone-marrow HSC/early progenitor genes, and the direct-effect list adds classic HSC/priming factors (MEIS1, HOPX, GATA2, MMRN1, VWF, SELP, ESAM), indicating a quiescent hematopoietic stem/progenitor program with megakaryocyte-erythroid lineage priming.
21	DR 22	-	Erythroid progenitor / proliferating erythroblast	Erythropoiesis (hemoglobin/heme synthesis and red-cell membrane assembly) coupled with cell-cycle proliferation	KLF1, HBA1, GFI1B, BLVRB, SLC25A37	high	The specific list is dominated by the erythroid master regulators and effectors KLF1, GFI1B, hemoglobin (HBA1), heme/biliverdin enzymes (BLVRB, HMBS, ALAS-like, CA2/CA3), the transferrin/iron machinery (TFRC, SLC25A37) and Rh/spectrin membrane genes (RHD, RHCE, SPTB), unambiguously marking committed erythroid cells, while the direct-effect list adds strong proliferation markers (TK1, RRM2, PCNA, MCM7, TYMS, CDC20, MYBL2), indicating an actively dividing erythroid progenitor/erythroblast stage.
22	DR 23	+	Erythroid lineage cells (erythroblasts / erythroid progenitors, incl. reticulocytes)	Erythroid differentiation with heme/hemoglobin biosynthesis and reticulocyte mitochondrial clearance (mitophagy)	HBA1, TRIM58, SLC25A37, HMBS, GATA1	high	The specific list is dominated by canonical erythroid identity and heme-synthesis genes (HBA1, HMBS, FECH, BPGM, HEMGN, TRIM58, mitoferrin SLC25A37, Rh blood-group RHCE/RHD, mitophagy factor BNIP3L), and the direct-effect list adds master erythroid regulators and iron-handling machinery (GATA1, TAL1, TFRC/CD71, SLC40A1), together clearly marking an erythropoietic program.
23	DR 24	-	Natural killer (NK) cell, CD56dim cytotoxic subset	Cytotoxic effector function / target-cell killing and NK activation	KLRF1, GNLY, NKG7, KLRD1, KLRC1	high	The specific list is dominated by NK-lineage receptors (KLRF1/NKp80, KLRC1, KLRD1, CD160, NCR1/NKp46) together with cytotoxic effectors (GNLY, GZMA, NKG7, XCL1/XCL2, IL2RB), a signature diagnostic of NK cells engaged in cytotoxic effector function; S1PR5, EOMES and SIGLEC7 further support a mature CD56dim NK identity.
24	DR 25	+	Regulatory T cells (Tregs), likely activated/effector Treg	Immunosuppression / regulatory T-cell identity and function (FOXP3-driven suppressive program)	FOXP3, IL2RA, CTLA4, IKZF2, TIGIT	high	The specific list is anchored by the Treg master regulator FOXP3 together with the canonical Treg surface/effector markers IL2RA (CD25), CTLA4, TIGIT and RTKN2, while the direct-effect list adds IKZF2 (Helios), TNFRSF9 (4-1BB), TNFRSF18 (GITR), ENTPD1 (CD39), CCR4/CCR6 and IRF4/BATF, all consistent with an activated effector regulatory T-cell suppressive program.
25	DR 26	+	Plasma cell / plasmablast (antibody-secreting B lineage)	Immunoglobulin secretion driven by the unfolded-protein/ER-stress response and terminal plasma-cell differentiation	MZB1, TNFRSF17, XBP1, PRDM1, DERL3	high	The specific markers are canonical antibody-secreting-cell genes — MZB1, TNFRSF17 (BCMA), the master regulators PRDM1/XBP1, CD38, SLAMF7 and FCRL5 — while the direct-effect list is dominated by immunoglobulin (IGLL5) and ER/secretory-stress machinery (DERL3, HERPUD1, SEL1L3, ERLEC1, FKBP11/FKBP2, SDF2L1, MANF), pinpointing terminally differentiated plasma cells engaged in high-volume Ig secretion.
26	DR 27	-	Monocyte/macrophage (myeloid lineage; features of non-classical CD16+ monocytes and macrophage differentiation)	Innate immune myeloid effector function — complement production (C1Q), Fc-receptor/phagocytosis signaling and inflammatory activation	FCGR3A, C1QA, FCN1, MARCO, CD68	high	The specific list is dominated by canonical myeloid/monocyte-macrophage identity genes (FCN1, FCGR3A/CD16, CD68, CD300E, MAFB, AIF1, TYROBP, FCER1G, CST3) while the direct-effect list adds complement (C1QA/B/C), scavenger receptor MARCO, and inflammatory mediators (TNF, IL6, CCL3/4), pointing to an activated monocyte-to-macrophage program with phagocytic and complement functions.
27	DR 28	-	Conventional dendritic cells type 2 (cDC2 / CD1c+ DCs)	Antigen presentation and lipid-antigen sensing (MHC-II / CD1-mediated antigen presentation)	CD1C, FCER1A, CLEC10A, ENHO, CLEC9A	high	The specific markers CD1C, FCER1A, and CLEC10A are canonical identity genes for CD1c+ conventional type 2 dendritic cells, and the direct-effect list adds supporting DC machinery (CLEC4A, CLEC9A, HLA-DQA1, IRF4, PLD4, SPIB) consistent with an antigen-presenting dendritic cell program.
28	DR 29	+	Myeloid antigen-presenting cells — cDC2 (type-2 conventional dendritic cells) with a classical-monocyte component	Myeloid/mononuclear-phagocyte identity and antigen presentation (Fc-receptor and C-type lectin sensing, innate immune recognition)	FCER1A, CLEC10A, LYZ, FCN1, CD163	medium	The most specific markers FCER1A and CLEC10A are canonical cDC2 identity genes, while LYZ, RNASE2, FCN1, MNDA, CD163 and shared genes (S100A8/9, VCAN, CCR2) point to an overlapping classical-monocyte/macrophage signature, so the program captures a myeloid antigen-presenting axis spanning cDC2 and monocytes rather than one pure population.
29	DR 30	-	GATA2-driven early myeloid progenitor with mast/basophil–megakaryocyte–erythroid (MEBEMP/MEMP) bias	GATA1/GATA2/KLF1-orchestrated commitment along the mast-cell/basophil–megakaryocyte–erythroid axis (granule/histamine and platelet programs)	GATA2, CPA3, FCER1A, ITGA2B, GATA1	medium	The specific list is dominated by GATA2/GATA1/KLF1 master regulators together with mast/basophil markers (CPA3, FCER1A, HDC, CSF2RB) and progenitor genes (PRSS57, SOX4, CDK6, MS4A3), while the direct-effect list adds megakaryocyte/erythroid machinery (ITGA2B, GP1BA, PEAR1, CMTM5, TAL1), indicating a shared early GATA2+ progenitor state feeding the mast/basophil–mega–erythroid branch rather than a single mature lineage.
30	DR 31	+	B-cell precursor (pro-B/pre-B cell)	early B-lymphopoiesis / VDJ recombination and pre-BCR assembly	DNTT, VPREB1, IGLL1, MME, EBF1	high	The specific markers DNTT (TdT), VPREB1/VPREB3, IGLL1 (surrogate light chain) and MME (CD10) together with the B-lineage transcription factors EBF1, PAX5, and pre-BCR signaling genes (CD79A/B, BLNK, CD19) are hallmarks of bone-marrow pro-B/pre-B precursors undergoing VDJ recombination.
31	DR 32	-	Mononuclear phagocyte — tissue-resident/anti-inflammatory macrophage with a cDC2 (CD1C+ dendritic cell) component	Antigen presentation (MHC class II) combined with complement-mediated innate immunity/efferocytosis	VSIG4, C1QA, CLEC10A, CD1C, HLA-DQA1	medium	The specific markers VSIG4 and MS4A6A plus strong complement C1QA/B/C point to resident anti-inflammatory macrophages, while CLEC10A, CD1C, FCER1A and abundant MHC-II genes indicate an overlapping cDC2 antigen-presenting signature, so the program spans the myeloid mononuclear-phagocyte compartment rather than one clean cell type.
32	DR 33	-	Megakaryocytes / platelets	Platelet biogenesis and activation — cytoskeletal/tubulin machinery, alpha-granule proteins, and GPIb-IX-V / integrin αIIbβ3 hemostatic function	PPBP, PF4, ITGA2B, GP9, TUBB1	high	The specific list is dominated by canonical platelet/megakaryocyte markers (PPBP/PF4/PF4V1 alpha-granule chemokines, GP9/GP1BA/GP6/ITGA2B/ITGB3 surface receptors, TUBB1/TUBA4A marginal-band tubulin), and the direct-effect list adds the megakaryocytic transcription factors GATA1, GFI1B, TAL1, MEIS1 and PBX1, together giving an unambiguous MK/platelet identity.
33	DR 34	+	Granulocyte-monocyte progenitor / neutrophil precursor (promyelocyte–myelocyte)	Early granulopoiesis — primary (azurophilic) granule gene expression coupled with active cell-cycle proliferation	MS4A3, ELANE, MPO, AZU1, CTSG	high	The direct-effect list is dominated by the azurophilic-granule program of proliferating neutrophil precursors (MS4A3, ELANE, MPO, AZU1, CTSG, PRTN3-like RETN/S100A8) alongside a strong cell-cycle signature (MKI67, TK1, RRM2, CDK1, PCNA), and the specific markers RETN/LYZ confirm a myeloid identity, together pointing to actively cycling bone-marrow granulocyte-monocyte progenitors/promyelocytes.
34	DR 35	+	Granulocyte-monocyte progenitor / promyelocyte (early myeloid precursor)	Azurophilic (primary) granule biogenesis during early granulopoiesis	MPO, AZU1, ELANE, PRSS57, MS4A3	high	The specific markers MPO and AZU1, together with direct-effect genes ELANE, CTSG, PRSS57, MS4A3 and IRF8, are the canonical azurophilic-granule and progenitor genes of promyelocytes/GMPs, while accompanying CSF1R/LYZ/MS4A6A reflect the shared myeloid differentiation program from which the monocyte lineage branches.
35	DR 36	-	Granulocyte-monocyte / early myeloid progenitor (HSPC, bone marrow)	Myeloid lineage commitment and granulocyte progenitor differentiation (azurophilic granule / myeloperoxidase program)	MPO, SPINK2, PRSS57, CLEC11A, MS4A3	high	The specific markers SPINK2, PRSS57, CLEC11A and IGLL1 mark hematopoietic stem/progenitor cells while MPO, CTSG, MS4A3, CSF3R and the transcription factors GATA2/ZBTB16 pin the program to committed granulocyte-monocyte (myeloid) progenitors laying down azurophilic-granule machinery in the marrow.
36	DR 37	+	Checkpoint-high CD4 T cells with T follicular helper (Tfh)/exhausted phenotype	Immune-checkpoint / T-cell exhaustion signaling combined with Tfh-like activation and cell-cycle proliferation	PDCD1, TOX, TIGIT, CTLA4, CXCR5	medium	The single most specific marker PDCD1 (PD-1) together with the direct-effect set enriched for exhaustion/checkpoint genes (TOX, TIGIT, HAVCR2/TIM-3, CTLA4, ENTPD1/CD39) and Tfh-associated genes (CXCR5, ICOS, CD200, MAF, POU2AF1) points to an activated CD4 T-cell state blending follicular-helper and exhaustion features, layered with a strong proliferation module (MKI67, TOP2A, BIRC5, CCNB1/2, TYMS); confidence is medium because the mixed Tfh/exhaustion/cycling signals overlap several closely related CD4 states.
37	DR 38	+	B-cell precursors (pro-B/pre-B cells)	Early B-lymphopoiesis / pre-B cell receptor assembly and B-lineage commitment	VPREB1, IGLL1, VPREB3, MME, EBF1	high	The surrogate light-chain genes VPREB1/VPREB3/IGLL1 together with MME (CD10), TCL1A, and the B-lineage transcription factors EBF1/PAX5/SOX4/CD19 are hallmark markers of bone-marrow pro-B/pre-B precursors assembling the pre-BCR, making this an unambiguous early B-lymphopoiesis program.
38	DR 40	-	Neutrophils (mature granulocytes)	Neutrophil-mediated innate immune / inflammatory response (chemokine signaling, degranulation, phagocytosis)	FCGR3B, CXCR1, CXCR2, TREM1, MMP9	high	The specific list is dominated by canonical neutrophil markers (FCGR3B/CD16b, AQP9, TREM1, G0S2, NAMPT, PTGS2, CXCL1), and the direct-effect list adds IL-8 receptors CXCR1/CXCR2, complement receptors C3AR1/C5AR1, and matrix metalloproteinases MMP9/MMP25, together clearly marking activated/inflammatory mature neutrophils rather than any lymphoid or monocytic subset.
39	DR 41	+	Natural killer (NK) cells	NK-cell cytotoxic effector function (natural killer-mediated cytotoxicity)	GNLY, NKG7, KLRD1, NCR1, NCAM1	high	The specific marker list is dominated by canonical NK identity and cytotoxicity genes (GNLY, NKG7, KLRD1/CD94, KLRF1, NCR1/NKp46, NCAM1/CD56, XCL1/XCL2, KLRC1, PRF1, SH2D1B), unambiguously defining a cytotoxic NK-cell program; presence of GZMK/ZNF683 hints at a CD56-bright/tissue-adapted NK flavor, while the myeloid/progenitor genes in the direct-effect list reflect shared machinery rather than identity.
40	DR 42	+	Granulocytic progenitor (promyelocyte / GMP) with basophil–mast–eosinophil bias	Granulopoiesis and azurophilic/secretory granule protein synthesis	MPO, ELANE, CTSG, CPA3, CLC	high	Top specific markers combine primary-granule genes of promyelocytes/GMPs (MPO, ELANE, AZU1, CTSG, PRSS57, MS4A3) with basophil/mast/eosinophil determinants (CLC, HDC, CPA3, RNASE2), indicating an immature marrow granulocytic progenitor skewed toward the basophil–mast–eosinophil branch; the direct-effect list reinforces active granule/secretory machinery (SRGN, CFD, S100P, ALOX5AP).
41	DR 43	-	unclear (interferon-responding immune cells; the program is a cell-state signature not restricted to one lineage)	Type I interferon antiviral response (ISG signature)	IFIT1, ISG15, MX1, RSAD2, OAS3	high	Both lists are dominated by canonical interferon-stimulated genes (IFIT1/2/3, ISG15, MX1/2, OAS1/2/3, RSAD2, IFI44L, HERC5) plus the IRF7/STAT1/STAT2/IRF9 signaling axis and chemokines CXCL10/CCL8/CCL2, indicating a type I IFN antiviral activation state shared across immune cell types rather than a single lineage identity.
42	DR 45	+	cycling/proliferating cells	cell cycle (S and G2/M phase proliferation)	MKI67, TOP2A, PCNA, RRM2, CDK1	high	The specific list is dominated by canonical S-phase (RRM2, TYMS, TK1, PCNA, MCM7) and G2/M mitotic genes (MKI67, TOP2A, CDK1, BIRC5, UBE2C, TPX2, CENPF), indicating this program captures actively proliferating cells rather than a distinct lineage identity.
43	DR 46	+	Conventional dendritic cells type 2 (cDC2 / CD1C+ DC)	MHC class II antigen presentation	CD1C, CLEC10A, LGALS2, HLA-DQA1, HLA-DRA	high	The specific markers CD1C, CLEC10A and LGALS2 together with a dominant MHC class II module (HLA-DQ/DP/DR, CD74) are the canonical signature of CD1C+ conventional type 2 dendritic cells engaged in antigen presentation, and the direct-effect list adds DC-associated genes (AXL, DNASE1L3, CD40, MS4A6A) consistent with this identity.
44	DR 47	-	Conventional dendritic cell type 1 (cDC1 / CD141+ BDCA3+ DC)	Antigen cross-presentation and MHC class II antigen presentation	CLEC9A, THBD, DNASE1L3, IRF8, CLNK	high	The specific list is led by the canonical human cDC1 signature — CLEC9A (DNGR-1), THBD (CD141/BDCA3), DNASE1L3, CLNK, CPVL and the cDC1 transcription factors IRF8/ID2 — combined with strong MHC-II (HLA-DR/DP/DQ, CD74), pinpointing BATF3-dependent cross-presenting dendritic cells; direct-effect genes (CD40, CLEC7A, XCR1-pathway, CD226, TNF) reflect their antigen-presentation and T-cell priming program.
45	DR 48	-	Proliferating cells (cycling immune cells; mast/basophil progenitors possible)	Cell cycle — mitosis / G2-M phase proliferation	MKI67, TOP2A, CDK1, CCNB1, UBE2C	high	The specific and direct-effect lists are dominated by canonical G2/M mitotic and proliferation genes (CDC20, UBE2C, CCNB1/2, TOP2A, CENPF, BIRC5, MKI67, CDK1, TPX2, ASPM), marking a cell-cycle/proliferation program rather than a distinct lineage; the presence of CPA3 and CLNK in the direct-effect list hints the cycling cells may include mast/basophil-lineage progenitors.
46	DR 49	+	Mesenchymal stromal cell / fibroblast (LEPR+ bone marrow stroma)	Extracellular matrix production and stromal remodeling with pro-inflammatory/angiogenic signaling	LEPR, PDGFRB, COL6A1, VCAN, CFD	high	The signature is dominated by canonical mesenchymal/fibroblast and bone-marrow stromal markers (LEPR, PDGFRB, VCAN, COL6A1/2, PCOLCE, FSTL1, SPARC, CFD, IGFBP7, APOD) with ECM and CTGF/TGFβ/angiogenic programs, indicating a non-immune LEPR+ stromal/fibroblast population rather than a hematopoietic cell.
47	DR 51	-	Plasmacytoid dendritic cells (pDCs), possibly including AXL+ transitional/AS-DC subset	pDC identity and type I interferon production / antiviral response	LILRA4, CLEC4C, IL3RA, IRF8, AXL	high	The specific list is dominated by canonical pDC markers (LILRA4, CLEC4C/BDCA-2, IL3RA/CD123, IRF8) together with the pDC transcription factors TCF4 and SPIB and the interferon regulators IRF7/IRF8 in the direct-effect list, unambiguously identifying a plasmacytoid DC program; the prominent AXL signal hints at an AXL+ transitional/AS-DC component.
48	DR 52	-	Megakaryocyte / platelet lineage	Platelet biogenesis, alpha-granule content and platelet activation/adhesion (GPIb-IX-V, integrin αIIbβ3 signaling)	ITGA2B, VWF, MMRN1, GP9, PF4	high	The specific markers (VWF, ITGA2B/CD41, ITGA2B, MMRN1, PLEK) together with a direct-effect list rich in platelet genes (GP9, GP6, GP1BA, ITGB3, PF4, SELP, CLEC1B, CMTM5) unambiguously identify the megakaryocyte/platelet lineage and its granule/adhesion machinery.
49	DR 53	+	Plasmablasts / plasma cells (proliferating)	Antibody-secretory plasma cell differentiation (IRF4/PRDM1/XBP1-driven UPR and ER secretory machinery) coupled with active cell-cycle/proliferation	TNFRSF17, MZB1, XBP1, PRDM1, MKI67	high	The specific list is dominated by canonical plasma-cell identity and secretory markers (TNFRSF17/BCMA, MZB1, TNFRSF13B/TACI, CD38, CD27, DERL3, SEC11C, FKBP11, SDF2L1) plus the plasma-cell transcription factors IRF4, PRDM1 and XBP1, while the direct-effect list adds a strong proliferation signature (MKI67, TYMS, TK1, RRM2, CENPE/CENPF, BIRC5, MYBL2), indicating cycling plasmablasts.
50	DR 55	-	Cytotoxic effector/terminally-differentiated CD8+ T cell (ZNF683/Hobit+, likely with NK-like features)	Cytotoxic effector differentiation with exhaustion/terminal markers and an interferon-response signature	ZNF683, GZMA, IFNG, B3GAT1, HAVCR2	medium	ZNF683 (Hobit) together with GZMA/PRF1/IFNG and terminal/exhaustion markers B3GAT1 (CD57), HAVCR2 (TIM-3), LAG3 and CD244 points to a terminally differentiated cytotoxic effector CD8 T cell, while the specific markers GBP1/OASL/ISG15/IFIT3 and APOBEC3H add a strong type-I/II interferon antiviral component; identity is confident but the exact CD8 vs NKT/NK-like boundary is ambiguous.
51	DR 56	+	Osteoclast / osteoclast-like macrophage (monocyte-macrophage lineage)	Osteoclast differentiation and bone resorption (acidification and matrix degradation), overlaid on a complement-rich tissue-macrophage program	CTSK, ACP5, MMP9, TCIRG1, TNFRSF11A	high	The specific list is dominated by the canonical osteoclast resorption module — CTSK, ACP5 (TRAP), MMP9, TCIRG1 (V-ATPase a3), with TNFRSF11A (RANK) in the direct-effect list — on a macrophage-lineage backbone (C1QA/B/C, CSF1R, MAFB, SPI1, CD68, APOE), which in a bone-marrow context marks osteoclasts derived from the monocyte/macrophage lineage.

Store results

embed.uns["llm_direct_results"] = llm_direct_results.convert_dtypes(
    convert_integer=False, convert_floating=False
)
embed.var.set_index("title", drop=False, inplace=True)
for d, suf in [("+", "positive"), ("-", "negative")]:
    sub = llm_direct_results.query("direction == @d").set_index("factor")
    embed.var[f"{suf}_direction_llm_celltype"] = sub["cell_type"]
    embed.var[f"{suf}_direction_llm_process"] = sub["biological_process"]
embed.var.index = embed.var["original_dim_id"].astype(int).astype(str)
embed.var.index.name = None

How to read this. This runs on every factor. When the gene list points clearly at one lineage, cell_type and biological_process tend to agree and confidence is "high". Because the output is fluent and self-reported, treat "low"/"medium" confidence calls with caution and always cross-check against the SMI, enrichment tools, and the literature. The key_genes and reasoning fields let you trace each call back to the factor’s marker list.

2. CASSIA

CASSIA (Nature Comms 2025) is a multi-agent system: a chain-of-thought annotation agent, a validation agent that loops (up to 3×) checking marker consistency, and a formatting agent that emits a general + detailed cell type. Backends: OpenAI, Anthropic, OpenRouter, or any OpenAI-compatible URL (Ollama). It writes CSV/JSON/HTML reports to the working directory on each run (cleaned up below).

Setup

import CASSIA

# CASSIA reaches an OpenAI-compatible endpoint; here we point it at Ollama.
cassia_output_name = "cassia_drvi"
cassia_provider = f"{OLLAMA_URL}/v1"
cassia_model = OLLAMA_MODEL

CASSIA.set_api_key("ollama", provider=cassia_provider)

Run

def run_cassia_annotation(scores_df, tissue, cutoff, top_n, output_name, provider, model, species,
                          max_dirs=None):
    rows = []
    for col in scores_df.columns:
        genes = scores_df[col][scores_df[col] >= cutoff].nlargest(top_n).index.tolist()
        if genes:
            cluster_id = f"{col[:-1].strip().replace(' ', '_')}{col[-1]}"
            rows.append({"cluster": cluster_id, "gene": ", ".join(genes)})
            if max_dirs is not None and len(rows) >= max_dirs:
                break

    cassia_input = pd.DataFrame(rows)
    print(f"CASSIA input: {len(cassia_input)} factor-directions")

    CASSIA.runCASSIA_batch(
        marker=cassia_input, output_name=output_name, provider=provider, model=model,
        tissue=tissue, species=species, max_workers=4, validate_api_key_before_start=False,
    )

    results = pd.read_csv(f"{output_name}_summary.csv")
    results.insert(0, "factor", results["Cluster ID"].str[:-1].str.replace("_", " "))
    results.insert(1, "direction", results["Cluster ID"].str[-1])

    for p in Path(".").glob(f"{output_name}*"):
        p.unlink()
    return results


cassia_results = run_cassia_annotation(
    scores_df=scores_df, tissue=llm_tissue_context, cutoff=drvi_score_cutoff, top_n=llm_top_n_genes,
    output_name=cassia_output_name, provider=cassia_provider, model=cassia_model, species=llm_species,
    max_dirs=max_directions,
)
display(cassia_results)

CASSIA Batch Analysis ✓
[████████████████████████████████████████] 100%
Completed: 52 | Processing: 0 | Pending: 0
Active: None


Warning: 16 other error(s):
  - DR_4-: LLM returned an empty response (provider=http://127.0.0.1:11434/v1, mo...
  - DR_2-: LLM returned an empty response (provider=http://127.0.0.1:11434/v1, mo...
  - DR_9-: LLM returned an empty response (provider=http://127.0.0.1:11434/v1, mo...
  - DR_10+: LLM returned an empty response (provider=http://127.0.0.1:11434/v1, mo...
  - DR_13+: LLM returned an empty response (provider=http://127.0.0.1:11434/v1, mo...
  ... and 11 more

All analyses completed. Results saved to 'cassia_drvi'.
HTML report generated: cassia_drvi_report.html
Three files have been created:
1. cassia_drvi_summary.csv (summary CSV)
2. cassia_drvi_conversations.json (conversation history JSON)
3. cassia_drvi_report.html (interactive HTML report)

	factor	direction	Cluster ID	Predicted General Cell Type	Predicted Detailed Cell Type	Possible Mixed Cell Types	Marker Number	Marker List	Iterations	Model	Provider	Tissue	Species
0	DR 1	-	DR_1-	CD4+ T lymphocyte	Naive CD4+ T Cell, Central Memory CD4+ T Cell ...	NaN	100	TSHZ2, FHIT, CCR7, MDS2, EPHX2, CD40LG, AK5, L...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
1	DR 11	-	DR_11-	Activated/Proliferating CD8+ Cytotoxic T Lymph...	Proliferating Effector CD8+ T Cell (TEM/TEFF),...	NaN	3	GZMK, CCL5, LYAR	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
2	DR 12	-	DR_12-	Erythroid lineage	Polychromatic Erythroblast, Orthochromatic Ery...	NaN	5	HBA1, DCAF12, BPGM, KRT1, SNCA	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
3	DR 14	+	DR_14+	CD8+ Cytotoxic T Lymphocytes	Terminally Differentiated/Senescent CD8+ T Cel...	NaN	17	GZMK, CMC1, CCL5, TNFRSF9, TIGIT, CCL4, GZMA, ...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
4	DR 15	-	DR_15-	Erythroid Precursors / Erythroblasts	Basophilic Erythroblast, Proerythroblast, Poly...	NaN	11	HBA1, RHCE, HEMGN, CA2, NUSAP1, RHD, CA3, MYL4...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
5	DR 17	+	DR_17+	B lymphocyte	Class-switched Memory B Cell (FCRL5+ subset), ...	NaN	26	CPNE5, BLK, MS4A1, AIM2, SSPN, BANK1, COCH, FC...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
6	DR 18	-	DR_18-	Innate Lymphoid/NK Lineage (NK/ILC Precursor o...	Mixed Innate Lymphocyte Population (NK/ILC Lin...	Mixed Innate Lymphocyte Population (NK/ILC Lin...	1	KLRB1	2	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
7	DR 19	-	DR_19-	Monocyte/Macrophage (Myeloid)	Classical Monocytes (CD14⁺), Inflammatory Macr...	NaN	5	FAM178B, APOC1, KCNH2, ALDH1A1, CNRIP1	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
8	DR 22	-	DR_22-	Erythroid Lineage (Proliferating Erythroblast/...	Basophilic Erythroblast, Proerythroblast / Ear...	NaN	17	KCNH2, AK1, FAM178B, KLF1, MYL4, CA3, BLVRB, C...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
9	DR 23	+	DR_23+	Erythroid (Red Blood Cell Lineage)	Reticulocyte, Orthochromatic Erythroblast, Pol...	Macrophage, Stromal cell	23	ARG1, TMCC2, TRIM58, SLC25A37, SLC2A1, HBA1, A...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
10	DR 24	-	DR_24-	Natural Killer (NK) cell	XCL1⁺ Cytotoxic NK Cell (LTI-like/ILC3-program...	NaN	12	KLRC1, LDB2, XCL1, GNLY, KLRF1, IL2RB, CD160, ...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
11	DR 25	+	DR_25+	CD4+ Regulatory T cells (Tregs)	Conventional/Natural CD4+ Tregs (cTregs/nTregs...	NaN	9	FOXP3, FANK1, IL2RA, CTLA4, RTKN2, DUSP4, IL32...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
12	DR 26	+	DR_26+	Plasma Cell (PC)	Long-lived Plasma Cell (LLPC) / Bone Marrow-Re...	NaN	35	IGLL5, MZB1, DERL3, JSRP1, TNFRSF17, FKBP11, C...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
13	DR 28	-	DR_28-	Plasmacytoid Dendritic Cells (pDCs)	Blood Plasmacytoid Dendritic Cells (Homeostati...	NaN	4	ENHO, FCER1A, CLEC10A, CD1C	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
14	DR 29	+	DR_29+	Macrophages	M2-like / Alternatively Activated Macrophages,...	NaN	11	LYZ, RNASE2, FCER1A, CSTA, CLEC10A, MTMR11, FC...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
15	DR 3	+	DR_3+	Germinal Center B cell	Germinal Center B cell, GC B cell, Light-zone ...	NaN	100	TCL1A, FCER2, MACROD2, MS4A1, CD72, VPREB3, FC...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
16	DR 31	+	DR_31+	Early B-cell Precursors / Pro-B Cells	Pro-B / Early Pre-B Cells, Large Pre-B Cells, ...	NaN	8	DNTT, CYGB, VPREB1, IGLL1, AKAP12, VPREB3, SOC...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
17	DR 32	-	DR_32-	Classical Monocytes / CD14++ Myeloid Lineage	Classical Monocytes (CD14++ CD16−), Bone Marro...	NaN	3	VSIG4, CLEC10A, MS4A6A	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
18	DR 34	+	DR_34+	Monocytes	Classical Inflammatory Monocytes (CD14++CD16-)...	NaN	2	RETN, LYZ	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
19	DR 35	+	DR_35+	Neutrophils (Granulocytic Lineage)	Mature Neutrophils, Inflammatory/Activated Neu...	NaN	2	MPO, AZU1	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
20	DR 37	+	DR_37+	T lymphocyte	Exhausted CD8+ T cell (TEX), Exhausted/Activat...	NaN	1	PDCD1	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
21	DR 38	+	DR_38+	Early B-lineage Progenitor / Hematopoietic Pre...	Pro-B Cell (Early/Mid Stage), Pre-B Cell (Larg...	NaN	7	VPREB1, IGLL1, CMTM8, TCL1A, VPREB3, MME, CD79B	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
22	DR 43	-	DR_43-	Inflammatory Monocytes	Inflammatory/Activated Classical Monocytes (CD...	NaN	33	CXCL10, CCL8, IFIT1, IFIT3, IFIT2, ISG15, RSAD...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
23	DR 45	+	DR_45+	Proliferating/Activated Immune Cell (Cell-Cycl...	Activated/Proliferating T Lymphocytes (CD4+ or...	NaN	22	RRM2, TYMS, TK1, PCNA, FAM111B, MKI67, HIST1H4...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
24	DR 46	+	DR_46+	Conventional Dendritic Cell (cDC)	cDC2 (CD141- conventional dendritic cell), Inf...	NaN	13	CD1C, HLA-DQA1, CLEC10A, LGALS2, HLA-DPB1, HLA...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
25	DR 47	-	DR_47-	Conventional Dendritic Cell type 1 (cDC1)	Conventional Dendritic Cell type 1 (cDC1), Con...	Monocytes/Macrophages	44	CLEC9A, CLNK, DNASE1L3, CPVL, HLA-DQB1, HLA-DQ...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
26	DR 48	-	DR_48-	Proliferating Immune Cell (G2/M-phase active L...	Activated Proliferating T Lymphocytes (CD4+ or...	NaN	14	CDC20, UBE2C, CCNB1, TOP2A, CENPF, CCNB2, ASPM...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
27	DR 5	+	DR_5+	Natural Killer (NK) Cell	Mature Cytotoxic NK Cell (CD56dim/CD16bright),...	NK × epithelial/stromal	60	FGFBP2, SPON2, MYOM2, PRF1, CCL4, NKG7, LAIR2,...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
28	DR 51	-	DR_51-	Plasmacytoid Dendritic Cell (pDC)	Activated Plasmacytoid Dendritic Cell (pDC), c...	pDC/cDC1 hybrid	12	AXL, SCT, LILRA4, PPP1R14A, TGFBI, IL3RA, CLEC...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
29	DR 52	-	DR_52-	Megakaryocytes	Mature/Polyploid Megakaryocytes, Proplatelet-f...	NaN	5	VWF, PLEK, PBX1, ITGA2B, MMRN1	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
30	DR 53	+	DR_53+	Plasma Cells / Antibody-Secreting Cells (ASCs)	Mucosal/Extramedullary Plasma Cells (IgA-biase...	NaN	78	HRASLS2, TNFRSF17, PERP, BMP8B, ITGB1, SEC11C,...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
31	DR 55	-	DR_55-	CD4+ Regulatory T Cell (Treg)	Activated/Inflammatory CD4+ Treg, Effector-Mem...	NaN	5	MT1E, APOBEC3H, GBP1, ZNF683, DUSP4	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
32	DR 56	+	DR_56+	Monocyte/Macrophage lineage (Myeloid cells)	Pro-resolving / M2-like Macrophage, Osteoclast...	NaN	13	C1QC, MMP9, C1QB, C1QA, ID3, ACP5, LILRB5, CTS...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
33	DR 6	+	DR_6+	Classical Monocytes / Inflammatory Myeloid Cells	Classical Monocytes / Inflammatory Monocytes, ...	NaN	35	NRG1, CD14, FCN1, MARCO, LYZ, CLEC4E, CTSS, CC...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
34	DR 7	-	DR_7-	Natural Killer (NK) cell	Mature Cytotoxic NK Cell (CD56^dim/CD16^+, KLR...	NaN	9	SLC4A10, KLRB1, IL23R, NCR3, GZMK, KLRG1, MYBL...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human
35	DR 8	-	DR_8-	Cytotoxic Natural Killer (NK) cell	CD56dim/CD16bright Terminally Differentiated C...	NaN	10	GZMH, FGFBP2, ZNF683, NKG7, CCL5, FCRL6, CST7,...	1	qwen3.6:35b	http://127.0.0.1:11434/v1	human immune cells (PBMC / bone marrow)	human

Store results

embed.uns["cassia_results"] = cassia_results.convert_dtypes(
    convert_integer=False, convert_floating=False
)
embed.var.set_index("title", drop=False, inplace=True)
for d, suf in [("+", "positive"), ("-", "negative")]:
    sub = cassia_results.query("direction == @d").set_index("factor")
    embed.var[f"{suf}_direction_cassia_general"] = sub["Predicted General Cell Type"]
    embed.var[f"{suf}_direction_cassia_detailed"] = sub["Predicted Detailed Cell Type"]
embed.var.index = embed.var["original_dim_id"].astype(int).astype(str)
embed.var.index.name = None

How to read this. This runs on every factor. We expect cell types to be captured well by this approach. Because the output is fluent and self-reported, treat results with caution and always cross-check against the SMI, marker databases, and the literature.

3. gs2txt

gs2txt runs pathway enrichment on the gene set first, then combines the enriched terms into a structured prompt so the LLM produces a free-text process description. Providers: OpenAI, Anthropic, or any OpenAI-compatible endpoint via base_url (Ollama). Install with the enrichment extra so gseapy is available.

Setup

from gs2txt import GeneSetAnnotator
from gs2txt.llm import OpenAIProvider

gs2txt_temperature = 0.1
gs2txt_enrichment_method = "pathway"

gs2txt_annotator = GeneSetAnnotator(
    llm_provider=OpenAIProvider(
        api_key="ollama", model_id=OLLAMA_MODEL,
        temperature=gs2txt_temperature, base_url=f"{OLLAMA_URL}/v1",
    ),
    enrichment_method=gs2txt_enrichment_method,
    organism=llm_species,
)

Run

def run_gs2txt(scores_df, annotator, cutoff, top_n, context, max_dirs=None):
    rows = []
    for col in scores_df.columns:
        top = scores_df[col][scores_df[col] >= cutoff].nlargest(top_n)
        if top.empty:
            continue
        rows.append({
            "factor": col[:-1].strip(),
            "direction": col[-1],
            "description": annotator.annotate(
                pd.DataFrame({"gene": top.index, "logFC": top.values}),
                max_gene_num=top_n,
                additional_context=f"DRVI factor {col} - {context}",
            ),
        })
        if max_dirs is not None and len(rows) >= max_dirs:
            break
    return pd.DataFrame(rows)


gs2txt_results = run_gs2txt(
    scores_df, gs2txt_annotator, drvi_score_cutoff, llm_top_n_genes, llm_tissue_context, max_directions
)
with pd.option_context("display.max_colwidth", None):
    display(gs2txt_results)

	factor	direction	description
0	DR 1	-	The perturbation represents antigen-driven T cell receptor signaling and subsequent activation cascades. Core components of the immunological synapse, proximal tyrosine kinases, and co-stimulatory receptors coordinate early signal transduction that triggers calcium flux, transcriptional reprogramming, and lineage commitment. This process encompasses immune synapse formation, downstream kinase activation, and the establishment of effector T cell programs following antigen recognition.
1	DR 2	-	The perturbed genes collectively orchestrate innate immune activation in myeloid lineages, coordinating pathogen recognition through pattern-recognition and complement receptors with downstream phagocytosis, inflammatory signaling, and antimicrobial effector mechanisms such as neutrophil extracellular trap formation. This integrated response functions as a primary host defense mechanism against microbial invasion and acute tissue inflammation.
2	DR 3	+	The perturbation primarily orchestrates antigen receptor-mediated signaling and subsequent clonal expansion of B lymphocytes. Proximal signal transduction cascades are coupled with lineage-specific transcriptional reprogramming to drive cellular proliferation and maturation. This coordinated molecular program underpins adaptive immune responses by regulating B cell activation, differentiation, and functional maturation within peripheral and bone marrow compartments.
3	DR 4	-	The perturbation activates costimulatory signaling that drives the proliferation, activation, and survival of T and B lymphocytes, thereby amplifying adaptive immune responses. This process coordinates cellular and humoral immunity by enhancing clonal expansion, immunoglobulin secretion, and the production of downstream inflammatory mediators following antigen recognition.
4	DR 5	+	This perturbation primarily drives natural killer cell activation and cytotoxic effector function, characterized by the coordinated upregulation of lytic granule components (perforin and granzymes), lineage-defining transcriptional regulators, and a balanced repertoire of activating and inhibitory surface receptors. The resulting molecular program enables precise target cell recognition, granule exocytosis, and secretion of pro-inflammatory chemokines to induce apoptosis in infected or transformed cells. Consequently, this gene expression signature reflects innate immune surveillance and natural killer cell-mediated cytotoxicity.
5	DR 6	+	The perturbation coordinates innate immune recognition and complement-mediated opsonization while simultaneously activating receptor tyrosine kinase signaling to promote striated muscle cell differentiation and suppress apoptosis. This reflects a unified physiological program linking pathogen or tissue damage sensing with subsequent cellular repair and survival mechanisms.
6	DR 7	-	The perturbation primarily drives the activation, proliferation, and cytotoxic effector functions of natural killer (NK) and NKT lymphocytes, while reinforcing interleukin-23-mediated Th17 lineage commitment. Surface receptors NKp30 and CD161 coordinate direct target cell recognition and killing, supported by transporter-dependent intracellular pH regulation that sustains lymphocyte expansion and immune synapse formation. This molecular program establishes a coordinated innate-like cytotoxic response integrated with adaptive Th1/Th17-type immunity to eliminate infected or transformed cells.
7	DR 8	-	This perturbation primarily governs the differentiation, activation, and functional polarization of cytotoxic and regulatory lymphocytes. It integrates antigen receptor signaling with growth factor modulation to balance effector killing capacity against suppressive immune tolerance. The coordinated regulation of these pathways directs adaptive immune cell maturation and fine-tunes interferon-mediated effector responses during inflammatory challenges.
8	DR 9	-	The perturbation predominantly regulates T cell receptor signaling and immunological synapse assembly, coordinating proximal kinase cascades and transcriptional reprogramming that drive CD8+ cytotoxic T cell activation, effector differentiation, and checkpoint-mediated immune regulation.
9	DR 10	+	The perturbation drives innate immune cell activation and antigen processing, characterized by coordinated signaling through Fc and pattern recognition receptors, enhanced loading of exogenous peptides onto MHC class I and II molecules, and subsequent production of inflammatory cytokines and chemokines. This process facilitates pathogen surveillance, antigenic peptide maturation, and the initiation of adaptive immune responses within myeloid lineages.
10	DR 11	-
11	DR 12	-	The perturbation integrates oxygen transport and hydrogen peroxide detoxification with C-degron-dependent ubiquitin-mediated proteolysis to regulate cellular redox homeostasis. This coordinated mechanism controls the stability of stress-responsive signaling molecules during oxidative and hypoxic challenges in hematopoietic and immune tissues.
12	DR 13	+	This perturbation coordinately suppresses B cell activation and proliferation while inhibiting actin cytoskeleton remodeling and membrane ruffling. The integrated downregulation of lymphocyte responsiveness and cellular motility functions to maintain immune homeostasis and restrain excessive inflammatory or autoimmune responses.
13	DR 14	+	This perturbation orchestrates the coordinated activation, trafficking, and cytotoxic effector functions of T cells and natural killer cells. Through integrated chemokine signaling, co-stimulatory receptor engagement, and immune checkpoint modulation, the program regulates lymphocyte recruitment to inflammatory sites while balancing proliferative survival and apoptotic clearance. Collectively, this molecular signature defines the regulation of adaptive and innate cytotoxic immune responses.
14	DR 15	-	This perturbation primarily reflects hemoglobin-mediated gas transport coupled with reactive oxygen species detoxification. The coordinated exchange of oxygen and carbon dioxide is functionally linked to hydrogen peroxide catabolism, collectively maintaining cellular redox homeostasis and protecting hematopoietic and circulating cells from oxidative stress.
15	DR 16	-	This perturbation primarily drives innate immune activation through Toll-like receptor signaling, culminating in robust type I interferon production and broad cytokine regulation. Concurrently, it modulates hematopoietic cell fate by suppressing leukocyte apoptosis and amplifying cytokine-mediated survival signals. Collectively, these mechanisms characterize a coordinated immune response focused on pathogen sensing, interferon-driven inflammation, and lymphoid-myeloid cell homeostasis.
16	DR 17	+	The perturbation predominantly orchestrates antigen receptor-mediated signaling in B lymphocytes, coordinating calcium-dependent signal transduction and kinase cascades that drive cellular activation and proliferation. This integrated network balances scaffold-regulated pathway modulation with inflammatory surveillance to fine-tune humoral immune responses. Consequently, this profile represents a core mechanism of adaptive immunity governing B cell maturation and effector function.
17	DR 18	-	The perturbation primarily modulates natural killer cell-mediated cytotoxicity and innate immune surveillance through CD161 receptor signaling on leukocytes. This mechanism fine-tunes effector cell activation, balancing pathogen clearance with the prevention of excessive inflammation or autoimmunity. Alterations in this pathway impair innate immune responses and are closely associated with susceptibility to intracellular infections and immune dysregulation.
18	DR 19	-	The perturbation coordinately regulates lipid homeostasis by suppressing fatty acid biosynthesis and catabolism while modulating cholesterol and phospholipid transport dynamics. It promotes lipoprotein particle assembly, remodeling, and efflux mechanisms, reflecting a metabolic shift toward reduced lipid turnover and altered intracellular lipid distribution. In immune cells, this profile supports anti-inflammatory reprogramming or the regulation of lipid-laden macrophage phenotypes. This perturbation is primarily involved in lipoprotein metabolism and cholesterol/phospholipid transport regulation.
19	DR 20	-	The perturbation primarily regulates post-meiotic germ cell differentiation by modulating serine protease activity during acrosome formation and sperm tail morphogenesis. This process drives spermatid development and the terminal maturation of haploid germ cells into fertilization-competent spermatozoa. Proper coordination of these proteolytic cascades is essential for male gametogenesis and subsequent fertilization capacity.
20	DR 21	-	This perturbation primarily modulates neuroendocrine stress signaling by attenuating corticotropin-releasing hormone activity, thereby regulating hypothalamic-pituitary-adrenal axis output and downstream synaptic excitability. It coordinates adaptive physiological responses to stressors through the negative regulation of neuropeptide receptor signaling and modulation of dopaminergic and glutamatergic neurotransmission.
21	DR 22	-	The perturbation predominantly regulates transmembrane potassium efflux, driving membrane repolarization following cellular depolarization. This process restores resting membrane potential by coordinating ion export across the plasma membrane, a critical mechanism for modulating electrical excitability and action potential duration. Consequently, it underpins fundamental electrophysiological homeostasis with downstream implications for cellular signaling and tissue-specific contractile function.
22	DR 23	+	The perturbed genes collectively coordinate glucose uptake and mTORC1-driven nutrient sensing with enhanced heme biosynthesis and hemoglobin accumulation. This metabolic shift supports the differentiation and maturation of bone marrow-derived hematopoietic cells, particularly within erythroid and myeloid lineages, while modulating intracellular redox homeostasis. This perturbation is primarily involved in metabolic reprogramming that couples nutrient sensing with heme production for hematopoietic cell maturation.
23	DR 24	-	This perturbation orchestrates the chemokine-mediated recruitment and activating receptor-driven stimulation of cytotoxic lymphocytes, fine-tuning T-helper 1 cytokine secretion and natural killer cell effector functions. Concurrent regulatory mechanisms modulate CD4+ T cell proliferation and establish homeostatic checkpoints to balance innate and adaptive immune responses within peripheral blood and bone marrow compartments.
24	DR 25	+	This perturbation drives the establishment and maintenance of peripheral immune tolerance through the coordinated expansion and functional activation of regulatory T cells. Key mediators including FOXP3, IL2RA, and CTLA4 enforce a suppressive transcriptional program that inhibits effector lymphocyte proliferation while promoting cytokine-dependent survival and lineage commitment. The enrichment of IL-2 signaling and negative regulatory pathways underscores a robust immunosuppressive state aimed at preventing autoimmunity and resolving inflammatory responses.
25	DR 26	+	The perturbed genes collectively orchestrate B-lymphocyte lineage specification and maturation while coordinating adaptive regulation of the secretory pathway, endoplasmic reticulum proteostasis, and glycolytic metabolism. This integrated program sustains lymphocyte proliferation and integrin-mediated trafficking to support immune cell differentiation and functional adaptation within bone marrow and peripheral tissues. The perturbation is primarily involved in B-cell development coupled with secretory pathway remodeling and metabolic reprogramming.
26	DR 27	-	This perturbation drives innate immune activation through pattern recognition receptor signaling and parallel initiation of the classical and lectin complement cascades. The coordinated response enhances opsonization, facilitating pathogen detection, inflammatory signaling, and clearance of foreign or damaged targets. Collectively, these changes represent a host defense mechanism centered on complement-mediated immunity and early innate immune surveillance.
27	DR 28	-	The perturbation orchestrates IgE receptor-triggered mast cell activation and granule exocytosis, integrating adaptive humoral responses with innate effector mechanisms to drive type 2 allergic inflammation. This process facilitates the rapid release of preformed mediators while modulating dendritic cell antigen presentation and T helper cell polarization. Consequently, this molecular program is primarily involved in IgE-mediated mast cell signaling and hypersensitivity pathogenesis.
28	DR 29	+	This perturbation primarily orchestrates innate antimicrobial immunity, centered on lysozyme-mediated degradation of bacterial cell walls and subsequent activation of inflammatory signaling cascades. The coordinated transcriptional response reflects a host defense mechanism aimed at neutralizing pathogenic bacteria through secreted effector molecules and recruitment of immune mediators.
29	DR 30	-	This perturbation orchestrates a coordinated vascular repair and tissue regeneration program, characterized by endothelial sprouting angiogenesis and the expansion of myeloid and erythroid lineages. The integrated transcriptional and cytokine signaling responses facilitate leukocyte mobilization, blood vessel remodeling, and restoration of vascular integrity following tissue injury or stress. This perturbation is primarily involved in angiogenesis-driven vascular repair and hematopoietic-immune cell proliferation.
30	DR 31	+	The perturbation primarily reflects early B lymphocyte differentiation and immunoglobulin gene diversification, driven by pre-B cell receptor assembly and targeted V(D)J recombination. This developmental program is essential for establishing antibody repertoire diversity and humoral immune competence within bone marrow and peripheral blood compartments. Disruption of these coordinated genetic and cellular checkpoints typically impairs adaptive immunity and predisposes to primary immunodeficiency states.
31	DR 32	-	The perturbed genes encode myeloid-expressed inhibitory receptors that function to actively suppress inflammatory signaling and maintain immune homeostasis. This regulatory program primarily dampens complement cascade activation, attenuates T cell proliferation and cytokine secretion, and limits innate immune responses in peripheral blood and bone marrow compartments. Consequently, this perturbation represents a coordinated immunosuppressive mechanism that restrains both adaptive and innate lymphocyte and myeloid activation.
32	DR 33	-	The perturbed genes collectively orchestrate platelet activation and hemostatic plug formation through coordinated actin cytoskeletal reorganization, integrin-mediated adhesion, and extracellular matrix remodeling. \nDysregulation of this network is commonly associated with thrombotic disorders, impaired vascular integrity, and aberrant megakaryocytic differentiation. \nThis perturbation is primarily involved in platelet activation, coagulation cascade initiation, and cytoskeletal dynamics regulation.
33	DR 34	+	This perturbation primarily drives innate immune activation and antimicrobial effector functions within circulating myeloid cells. Coordinated expression of lysozyme and resistin facilitates direct bacterial cell wall degradation while amplifying pro-inflammatory signaling cascades to clear Gram-positive and Gram-negative pathogens. This molecular signature represents a robust humoral defense response and acute inflammatory clearance mechanism.
34	DR 35	+	The perturbation centers on the myeloid oxidative burst, where MPO catalyzes hydrogen peroxide conversion into hypochlorous acid to drive microbial killing within phagosomes. This process integrates reactive oxygen species metabolism, phagosome maturation, and neutrophil extracellular trap formation to execute innate antibacterial defense. Perturbation of this pathway disrupts normal myeloid function and is frequently implicated in acute myeloid leukemia and chronic inflammatory states.
35	DR 36	-	This perturbation coordinately upregulates reactive oxygen species generation and hydrogen peroxide metabolism, driving neutrophil oxidative burst and extracellular trap formation. This myeloid effector response is integrated with immunoglobulin-mediated signaling, reflecting a coordinated activation of innate antimicrobial defense and adaptive immune surveillance. Collectively, the process represents inflammatory leukocyte activation centered on pathogen clearance and immune cell effector function.
36	DR 37	+
37	DR 38	+	The perturbation primarily reflects early B lymphopoiesis and pre-B cell receptor signaling during bone marrow development. VPREB1 and IGLL1 form the surrogate light chain that drives proliferation and survival checkpoints in developing B cells, with downstream PI3K-Akt and KRAS pathway modulation supporting this maturation transition. Disruption of this developmental axis impairs humoral immune competence and is characteristic of primary immunodeficiencies affecting B cell lineage commitment.
38	DR 40	-	The perturbation primarily disrupts Fc gamma receptor-mediated effector functions, specifically impairing antibody-dependent cellular cytotoxicity and natural killer cell degranulation. Modulation of FCGR3B surface expression by CMTM2 compromises the capacity of circulating leukocytes to recognize IgG-coated targets and execute cytolytic granule release. Consequently, downstream Fc receptor signaling cascades that drive NK cell activation, macrophage polarization, and immune complex clearance are attenuated, reflecting a focused defect in innate effector immunity and target cell elimination.
39	DR 41	+	The perturbed genes collectively drive the activation and effector functions of natural killer cells and cytotoxic T lymphocytes, coordinating cytolytic granule release and type 1 helper T cell cytokine production. This response is dynamically modulated by intersecting cytokine receptor signaling and inhibitory checkpoint pathways to fine-tune leukocyte-mediated cytotoxicity. The perturbation primarily represents coordinated NK and CD8+ T cell activation with balanced cytotoxic effector function and Th1-type immune polarization.
40	DR 42	+	This perturbation reflects the activation of neutrophil effector functions, characterized by the coordinated deployment of granule-derived antimicrobial enzymes and proteases to degrade pathogens and remodel extracellular matrices. The expression profile drives neutrophil extracellular trap formation and antibacterial clearance mechanisms, while modulating local inflammatory resolution through eicosanoid metabolism and histamine signaling. This program represents a core innate immune response mechanism for acute bacterial defense and tissue-invasive inflammation.
41	DR 43	-	The perturbed genes collectively orchestrate a robust interferon-mediated antiviral innate immune response, characterized by the coordinated induction of interferon-stimulated genes that establish an intracellular antiviral state and inhibit viral genome replication. Concurrent upregulation of chemokines facilitates leukocyte recruitment and amplifies inflammatory signaling within circulating immune cells. This perturbation primarily reflects the activation of type I and type II interferon signaling pathways to mount a comprehensive defense against viral infection.
42	DR 45	+	The perturbation drives coordinated cell cycle progression by upregulating DNA replication and nucleotide biosynthesis machinery, facilitating the G2/M phase transition, and organizing the mitotic spindle for cytokinesis. This signature reflects a robust proliferative state characterized by synchronized execution of DNA synthesis and mitotic division.
43	DR 46	+	This perturbation coordinately upregulates antigen processing and presentation machinery, centering on MHC class II complex assembly and exogenous peptide loading to initiate adaptive immune responses. The coordinated molecular program enhances dendritic cell and macrophage maturation, promotes T cell activation and leukocyte adhesion, and drives cytotoxic effector mechanisms within circulating and bone marrow-derived immune compartments.
44	DR 47	-	The perturbation primarily drives dendritic cell maturation and MHC class II-mediated antigen processing and presentation to CD4+ T cells. This mechanism amplifies adaptive immune responses and serves as a central driver in the pathogenesis of autoimmune, allergic, and transplant-related inflammatory conditions.
45	DR 48	-	The perturbation drives coordinated progression through mitosis, integrating spindle assembly, metaphase-to-anaphase transition, and sister chromatid segregation. This molecular program coordinates cyclin-dependent kinase activity, kinetochore-microtubule dynamics, and anaphase-promoting complex activation to ensure accurate chromosome alignment and separation. Consequently, this signature primarily reflects active mitotic cell cycle progression and the regulation of chromosomal stability during cell division.
46	DR 49	+	The perturbed gene network orchestrates a coordinated pro-inflammatory and profibrotic response, integrating cytokine signaling activation with hypoxia adaptation and extensive extracellular matrix remodeling. This functional module modulates immune cell activity, enforces proliferation arrest, and facilitates tissue repair under metabolic and inflammatory stress. Consequently, this perturbation primarily represents an inflammatory stress response coupled with fibrotic tissue remodeling and cellular homeostasis regulation.
47	DR 51	-	The perturbed genes collectively orchestrate cytokine-mediated immune cell activation and modulate leukocyte endocytic and secretory trafficking. Receptor tyrosine kinases and interleukin receptors establish a signaling network that amplifies inflammatory responses, while cytoskeletal regulators coordinate pinocytosis and extracellular secretion to support antigen sampling and cytokine release. This perturbation is primarily involved in cytokine-driven modulation of myeloid cell activation, endocytic trafficking, and secretory homeostasis in human immune cells.
48	DR 52	-	This perturbation primarily drives endothelial-mediated hemostasis and vascular inflammation, coordinating platelet adhesion, coagulation cascade initiation, and leukocyte recruitment to sites of vascular injury or infection. The functional shift reflects a coordinated pro-thrombotic state that bridges primary clot formation with innate immune activation, particularly through neutrophil extracellular trap deployment and pathogen recognition mechanisms. This perturbation is primarily involved in hemostatic plug assembly and vascular inflammatory response regulation.
49	DR 53	+	The perturbed genes collectively drive the activation, proliferation, and terminal differentiation of B lymphocytes into antibody-secreting plasma cells. This program integrates cytokine-mediated signaling with transcriptional reprogramming by IRF4 and XBP1 to support immunoglobulin synthesis and secretory adaptation. This perturbation is primarily involved in B cell lineage commitment, secretory maturation, and integrin-dependent leukocyte trafficking within immune microenvironments.
50	DR 55	-	The perturbation primarily reflects intracellular metal ion homeostasis and detoxification, driven by metallothionein-mediated sequestration of zinc, copper, and cadmium. This adaptive mechanism regulates essential mineral balance, mitigates heavy metal toxicity, and modulates downstream signaling cascades that suppress cellular proliferation. In hematopoietic and immune cells, it functions as a critical stress-response pathway coordinating metal detoxification with growth control.
51	DR 56	+	The perturbed genes collectively initiate classical complement activation and deploy proteolytic enzymes to clear cellular debris and remodel extracellular matrices. This functional signature characterizes osteoclast lineage differentiation and inflammatory macrophage polarization, linking immune surveillance with structural tissue breakdown. Consequently, this perturbation primarily represents complement-mediated myeloid effector function coupled with bone resorption and extracellular matrix turnover.

Store results

embed.uns["gs2txt_results"] = gs2txt_results.convert_dtypes(
    convert_integer=False, convert_floating=False
)
embed.var.set_index("title", drop=False, inplace=True)
for d, suf in [("+", "positive"), ("-", "negative")]:
    sub = gs2txt_results.query("direction == @d").set_index("factor")
    embed.var[f"{suf}_direction_gs2txt_label"] = sub["description"]
embed.var.index = embed.var["original_dim_id"].astype(int).astype(str)
embed.var.index.name = None

How to read this. Because gs2txt names genes and pathways, its summaries can be traced back to the factor’s top-ranked list — a useful gene-level complement to the ORA and TF tools. As with the others, the output is fluent and unscored, so interpret it with care and alongside the rest rather than on its own.

4. Save

import anndata as ad

ad.settings.allow_write_nullable_strings = True
embed.write_h5ad(embed_path)
print(f"Updated embedding saved to: {embed_path}")

Updated embedding saved to: /lustre/groups/ml01/code/amirali.moinfar/projects/drvi_tutorials/tmp_io/drvi_immune_128/embed.h5ad