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
- 脚本scrna_embedding.py39.1 KB
- 脚本tests/test_scrna_embedding.py20.1 KB
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 stableintegrated.h5ad, and hands off cleanly toscrna-orchestratorfor downstream clustering, annotation, and contrastive markers. - Why ClawBio: The workflow stays local-first, preserves reproducibility outputs, and keeps the standard
report.md/result.jsoncontract.
Core Capabilities
- Raw-count Input Validation: Accept raw-count
.h5adand 10x Matrix Market input; reject processed-like matrices. - scVI/scANVI Latent Embedding: Train
scvi.model.SCVIor refine withscvi.model.SCANVIusing 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-keyis provided. - Integrated Export: Save
integrated.h5adwithobsm["X_scvi"], log-normalizedX, and raw counts inlayers["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 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:
- 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.SCVIon HVG raw counts, optionally using--batch-key, and refine withscvi.model.SCANVIwhen--method scanviplus 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 downstreamscrnacommand.
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.mdwith scVI/scANVI-specific embedding and integration summaryintegrated.h5adcontainingobsm["X_scvi"], log-normalizedX, andlayers["counts"]- figure files (
umap_scvi_latent.png) - optional batch figure (
umap_scvi_batch.png) when--batch-keyis set - batch diagnostics table (
batch_mixing_metrics.csv) when--batch-keyis set - latent export table (
latent_embeddings.csv) - reproducibility bundle
- downstream command for
scrna-orchestrator --use-rep X_scvi
Algorithm / Methodology
- QC:
- Compute
n_genes_by_counts,total_counts,pct_counts_mt - Filter by
min_genes,min_cells,max_mt_pct
- Feature selection:
- Normalize +
log1pon the full-gene branch - Select HVGs (
flavor="seurat") for scVI training
- Latent model:
- Train
scvi.model.SCVIon raw-count HVGs - Optionally refine with
scvi.model.SCANVIwhen--method scanvi,--labels-key, and--unlabeled-categoryare provided - Include batch covariate when
--batch-keyis 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.10anndata>= 0.12torchscvi-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-embeddingis 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.
04 同仓库更多 Skills
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.
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.
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.
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.
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.
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.