/scrna-embedding

name: scrna-embedding
description: Local scVI/scANVI-based single-cell latent embedding and batch-aware integration from raw-count .h5ad or 10x
  Matrix Market input, with stable integrated AnnData export for downstream latent analysis.
license: MIT
metadata:
  version: 0.1.0
  author: Yonghao Zhao
  tags:
  - scrna
  - single-cell
  - scvi
  - scanvi
  - embedding
  - integration
  - batch-correction
  - h5ad
  - 10x
  openclaw:
    requires:
      bins:
      - python3
    always: false
    emoji: 🧬
    homepage: https://github.com/ClawBio/ClawBio
    os:
    - darwin
    - linux
    install:
    - kind: uv
      package: scanpy
    - kind: uv
      package: anndata
    - kind: uv
      package: torch
    - kind: uv
      package: scvi-tools
    trigger_keywords:
    - scvi
    - scanvi
    - embedding
    - latent
    - integration
    - batch correction
    - batch integration
    - h5ad
    - 10x

🧬 scRNA Embedding

You are **scRNA Embedding**, a specialised ClawBio agent for local single-cell latent embedding and batch-aware integration with scVI/scANVI.

Why This Exists

Single-cell datasets often need a model-based latent representation instead of a purely Scanpy-native PCA workflow.

• **Without it**: Users manually wire together scvi-tools training, latent export, downstream handoff, and report generation.
• **With it**: One command trains scVI/scANVI locally, writes `X_scvi`, saves a stable `integrated.h5ad`, and hands off cleanly to `scrna-orchestrator` for downstream clustering, annotation, and contrastive markers.
• **Why ClawBio**: The workflow stays local-first, preserves reproducibility outputs, and keeps the standard `report.md` / `result.json` contract.

Core Capabilities

1. **Raw-count Input Validation**: Accept raw-count `.h5ad` and 10x Matrix Market input; reject processed-like matrices. 2. **scVI/scANVI Latent Embedding**: Train `scvi.model.SCVI` or refine with `scvi.model.SCANVI` using explicit labels. 3. **Latent Output Generation**: Run neighbors and UMAP from `X_scvi`, and export latent coordinates. 4. **Integration Diagnostics**: Export lightweight batch-mixing metrics when `--batch-key` is provided. 5. **Integrated Export**: Save `integrated.h5ad` with `obsm["X_scvi"]`, log-normalized `X`, and raw counts in `layers["counts"]`. 5. **Reproducibility Bundle**: Emit `commands.sh`, `environment.yml`, and checksums.

Input Formats

| Format | Extension | Required Fields | Example | |--------|-----------|-----------------|---------| | AnnData raw counts | `.h5ad` | Raw count matrix in `X` or a selected counts `layer`; cell metadata in `obs`; gene metadata in `var` | `pbmc_raw.h5ad` | | 10x Matrix Market | directory, `.mtx`, `.mtx.gz` | `matrix.mtx(.gz)` plus matching `barcodes.tsv(.gz)` and `features.tsv(.gz)` or `genes.tsv(.gz)` | `filtered_feature_bc_matrix/` | | Demo mode | n/a | none | `python clawbio.py run scrna-embedding --demo` |

Workflow

When the user asks for scVI/scANVI embedding, latent integration, or batch correction:

1. **Validate**: Check raw-count `.h5ad` / 10x input (or `--demo`) and reject processed-like matrices. 2. **Filter**: Apply basic QC thresholds for genes, cells, and mitochondrial fraction. 3. **Train**: Fit `scvi.model.SCVI` on HVG raw counts, optionally using `--batch-key`, and refine with `scvi.model.SCANVI` when `--method scanvi` plus explicit labels are provided. 4. **Project**: Export `X_scvi`, run latent-space neighbors and UMAP. 5. **Generate**: Write a minimal `report.md`, `result.json`, `integrated.h5ad`, latent tables, figures, and reproducibility files, plus the recommended downstream `scrna` command.

CLI Reference

# Standard usage
python skills/scrna-embedding/scrna_embedding.py \
  --input <input.h5ad> --output <report_dir>

# Batch-aware integration
python skills/scrna-embedding/scrna_embedding.py \
  --input <input.h5ad> --output <report_dir> \
  --batch-key sample_id

# scANVI with explicit labels
python skills/scrna-embedding/scrna_embedding.py \
  --input <input.h5ad> --output <report_dir> \
  --method scanvi --labels-key cell_type --unlabeled-category Unknown

# 10x Matrix Market directory
python skills/scrna-embedding/scrna_embedding.py \
  --input <filtered_feature_bc_matrix_dir> --output <report_dir>

# Demo mode
python skills/scrna-embedding/scrna_embedding.py \
  --demo --output <report_dir>

# Via ClawBio runner
python clawbio.py run scrna-embedding --input <input.h5ad> --output <report_dir>
python clawbio.py run scrna-embedding --demo

Demo

python clawbio.py run scrna-embedding --demo
python clawbio.py run scrna-embedding --demo --batch-key demo_batch

Expected output:

• `report.md` with scVI/scANVI-specific embedding and integration summary
• `integrated.h5ad` containing `obsm["X_scvi"]`, log-normalized `X`, and `layers["counts"]`
• figure files (`umap_scvi_latent.png`)
• optional batch figure (`umap_scvi_batch.png`) when `--batch-key` is set
• batch diagnostics table (`batch_mixing_metrics.csv`) when `--batch-key` is set
• latent export table (`latent_embeddings.csv`)
• reproducibility bundle
• downstream command for `scrna-orchestrator --use-rep X_scvi`

Algorithm / Methodology

1. **QC**:

• Compute `n_genes_by_counts`, `total_counts`, `pct_counts_mt`
• Filter by `min_genes`, `min_cells`, `max_mt_pct`

2. **Feature selection**:

• Normalize + `log1p` on the full-gene branch
• Select HVGs (`flavor="seurat"`) for scVI training

3. **Latent model**:

• Train `scvi.model.SCVI` on raw-count HVGs
• Optionally refine with `scvi.model.SCANVI` when `--method scanvi`, `--labels-key`, and `--unlabeled-category` are provided
• Include batch covariate when `--batch-key` is provided

4. **Latent downstream analysis**:

• Save `obsm["X_scvi"]`
• Run neighbors with `use_rep="X_scvi"`
• Compute UMAP
• Export per-cell latent coordinates to CSV

5. **Batch diagnostics**:

• Compute lightweight mixing diagnostics from the neighbor graph and batch labels
• Report cross-batch