AGENT SKILL

scrna-embedding

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
最近更新
2026-11-14
Stars
★ 12
Forks
5

01 前言 Front Matter

name
scrna-embedding
license
MIT
metadata
{ "tags": [ "scrna", "single-cell", "scvi", "scanvi", "embedding", "integration", "batch-correction", "h5ad", "10x" ], "author": "Yonghao Zhao", "version": "0.1.0", "openclaw": { "os": [ "darwin", "linux" ], "emoji": "🧬", "always": false, "install": [ { "kind": "uv", "package": "scanpy" }, { "kind": "uv", "package": "anndata" }, { "kind": "uv", "package": "torch" }, { "kind": "uv", "package": "scvi-tools" } ], "homepage": "https://github.com/ClawBio/ClawBio", "requires": { "bins": [ "python3" ] }, "trigger_keywords": [ "scvi", "scanvi", "embedding", "latent", "integration", "batch correction", "batch integration", "h5ad", "10x" ] } }
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.

02 资源文件 2

03 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

  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"].
  6. 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
  1. Feature selection:
  • Normalize + log1p on the full-gene branch
  • Select HVGs (flavor="seurat") for scVI training
  1. 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
  1. Latent downstream analysis:
  • Save obsm["X_scvi"]
  • Run neighbors with use_rep="X_scvi"
  • Compute UMAP
  • Export per-cell latent coordinates to CSV
  1. 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

04 同仓库更多 Skills

stanfish06
stanfish06/skillquarium

zarr-python

Stores and queries chunked N-D scientific arrays with Zarr-Python 3, including codecs, sharding, S3/GCS storage, and NumPy/Dask/Xarray integration. Use for array layout, bounded I/O, format migration, or scientific metadata preservation.

★ 12
stanfish06
stanfish06/skillquarium

yeet

Publish local changes to GitHub by confirming scope, committing intentionally, pushing the branch, and opening a draft PR through the GitHub app from this plugin, with `gh` used only as a fallback where connector coverage is insufficient.

★ 12
stanfish06
stanfish06/skillquarium

xarray

N-dimensional labeled arrays and datasets in Python. Built on top of NumPy and Dask. It introduces labels in the form of dimensions, coordinates, and attributes on top of raw NumPy-like arrays, making data analysis in physical sciences more intuitive and less error-prone. Use for working with multi-dimensional scientific data, NetCDF/GRIB/Zarr files, climate/weather/oceanographic datasets, remote sensing, geospatial imaging, large out-of-memory datasets with Dask, and labeled array operations.

★ 12
stanfish06
stanfish06/skillquarium

writing-mstest-tests

Use when asked to fix, rewrite, update, improve, modernize, show corrected code for, or explain existing MSTest tests or MSTest-specific configuration. Use for "review" when corrected code or edits are wanted, even for one pasted assertion or passing tests with bad failure output. Covers expected/actual labels; generic Boolean, collection, string, numeric, null, identity, exception, hard-cast, and object[] checks; TestContext/lifecycle; timeout/cancellation; OS/CI conditions, retry, cleanup, parallelization, MSTest.Sdk project setup, and MSTESTxxxx. Honor the installed MSTest version. DO NOT USE to design new test cases (code-testing), perform report-only audits, create project files rather than explain MSTest setup, run tests, migrate frameworks, or handle non-MSTest/non-.NET code.

★ 12
stanfish06
stanfish06/skillquarium

wgs-prs

End-to-end WGS to polygenic risk score pipeline. Takes paired-end FASTQ files (or a pre-existing VCF) through nf-core/sarek for variant calling, applies VCF QC (normalisation, hard filtering, Ti/Tv and Het/Hom checks), then computes polygenic risk scores via the PGS Catalog. Fills the FASTQ to VCF gap upstream of the gwas-prs skill.

★ 12
stanfish06
stanfish06/skillquarium

webapp-testing

Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.

★ 12