--- 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 ```bash # Standard usage python skills/scrna-embedding/scrna_embedding.py \ --input --output # Batch-aware integration python skills/scrna-embedding/scrna_embedding.py \ --input --output \ --batch-key sample_id # scANVI with explicit labels python skills/scrna-embedding/scrna_embedding.py \ --input --output \ --method scanvi --labels-key cell_type --unlabeled-category Unknown # 10x Matrix Market directory python skills/scrna-embedding/scrna_embedding.py \ --input --output # Demo mode python skills/scrna-embedding/scrna_embedding.py \ --demo --output # Via ClawBio runner python clawbio.py run scrna-embedding --input --output python clawbio.py run scrna-embedding --demo ``` ## Demo ```bash 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 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 ```text 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](https://docs.scvi-tools.org/) — model API and training interface. - [Scanpy documentation](https://scanpy.readthedocs.io/) — downstream AnnData analysis utilities. - [AnnData documentation](https://anndata.readthedocs.io/) — single-cell data model. --- Source attribution: ClawBio Original project: https://github.com/ClawBio/ClawBio License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Dave AI. ## Upstream license notice MIT License Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Dave AI resource metadata Creator / publisher: ClawBio Original project: https://github.com/ClawBio/ClawBio Attribution basis: Exact package in biomedical source index and publisher source table Fields of work: Data & Analytics, Education & Research Roles: Business Intelligence Analyst, Data Scientist, Researcher Specialties: API Tools: Anndata, Scanpy, Scvi Tools, Torch Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 68d384fee9ed8257636b4e5eb64848180e56099b8fa7ee0ee8bd2c80a9420386 Metadata reviewed: 2026-10-27 This metadata supersedes earlier Dave AI catalog attribution. Original instruction and supporting files are preserved.