ClawBio scrna-embedding

Name: scrna-embedding
Author: ClawBio

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.

install

source · Clone the upstream repo

git clone https://github.com/ClawBio/ClawBio

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/ClawBio/ClawBio "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/scrna-embedding" ~/.claude/skills/clawbio-clawbio-scrna-embedding && rm -rf "$T"

manifest: skills/scrna-embedding/SKILL.md

🧬 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

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

Input Formats

Format Extension Required Fields Example

AnnData raw counts

.h5ad

Raw count matrix in

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)

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:

Validate: Check raw-count
```
.h5ad
```
/ 10x input (or
```
--demo
```
) and reject processed-like matrices.
Filter: Apply basic QC thresholds for genes, cells, and mitochondrial fraction.
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.
Project: Export
```
X_scvi
```
, run latent-space neighbors and UMAP.
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

, 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

Compute

n_genes_by_counts

total_counts

pct_counts_mt

Filter by
```
min_genes
```
,
```
min_cells
```
,
```
max_mt_pct
```

Feature selection:

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

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

Latent downstream analysis:

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

Batch diagnostics:

Compute lightweight mixing diagnostics from the neighbor graph and batch labels
Report cross-batch neighbor fraction, neighbor entropy, and batch silhouette

Example Queries

"Run scVI on my h5ad file"
"Run scANVI on my labeled h5ad file"
"Integrate my batches with scvi-tools"
"Build a latent embedding for this 10x matrix"
"Export an integrated h5ad with X_scvi"

Output Structure

output_directory/
├── report.md
├── result.json
├── integrated.h5ad
├── figures/
│   ├── umap_scvi_latent.png
│   └── umap_scvi_batch.png           # only when batch integration is enabled
├── tables/
│   ├── latent_embeddings.csv
│   └── batch_mixing_metrics.csv      # only when batch integration is enabled
└── reproducibility/
    ├── commands.sh
    ├── environment.yml
    └── checksums.sha256

Dependencies

Required:

```
scanpy
```
>= 1.10
```
anndata
```
>= 0.12
```
torch
```
```
scvi-tools
```

Out of scope (v1):

```
totalVI
```
multimodal integration
condition-level DE
remote model downloads

Safety

Local-first: No patient data upload.
Disclaimer: Reports include the ClawBio medical disclaimer.
Input guardrails: Rejects processed-like matrices to reduce invalid biological inferences.
No remote model fetches: v1 uses only local code and local data.
Reproducibility: Writes command/environment/checksum bundle.

Integration with Bio Orchestrator

Trigger conditions:

User explicitly asks for
```
scvi
```
, latent embedding, batch integration, or batch correction
Input is single-cell data and the request is specifically model-based embedding rather than generic Scanpy clustering

Routing note:

Generic single-cell clustering / marker requests still belong to
```
scrna-orchestrator
```
```
scrna-embedding
```
is the advanced entry point for scVI-style latent integration and export

Citations

scvi-tools documentation — model API and training interface.
Scanpy documentation — downstream AnnData analysis utilities.
AnnData documentation — single-cell data model.