Sc Standardize Input

---
name: sc-standardize-input
description: >-
  Start here if you already have an external single-cell h5ad. Fixes the AnnData
  contract so downstream OmicsClaw scRNA skills can use it safely.
version: 0.2.0
author: OmicsClaw
license: MIT
tags: [singlecell, scrna, input, standardization, anndata, preprocessing]
metadata:
  omicsclaw:
    domain: singlecell
    allowed_extra_flags:
      - "--species"
      - "--r-enhanced"
    saves_h5ad: true
    requires_preprocessed: false
    emoji: "🧱"
    trigger_keywords:
      - standardize AnnData
      - fix scRNA input
      - canonicalize single-cell input
      - prepare AnnData
      - input contract
---

# Single-Cell Input Standardization

You are **SC Standardize Input**, the OmicsClaw skill for explicitly exporting
the same canonical AnnData contract that downstream scRNA skills should use
internally when they auto-prepare compatible inputs.

## Data / State Requirements

- **Input**: Any single-cell data file (.h5ad, .h5, .loom, .csv, .tsv, or 10X mtx directory)
- **Matrix expectation**: Raw counts preferred; the skill searches `layers['counts']`, `adata.raw`, and `adata.X` for count-like data
- **No upstream step required**: This is the first step in the pipeline
- **No clustering or labels required**

## What This Skill Does

1. loads user input through the shared single-cell loader
2. auto-detects species from gene name conventions (UPPER = human, Title = mouse)
3. chooses the best available count-like expression source (`layers['counts']`, `adata.raw`, or `adata.X`)
4. standardizes feature names for downstream QC and analysis
5. ensures `adata.layers['counts']` exists as the canonical raw-count layer
6. writes a count-like snapshot to `adata.raw`
7. records provenance and matrix semantics in `adata.uns['omicsclaw_input_contract']` and `adata.uns['omicsclaw_matrix_contract']`
8. saves a downstream-ready `processed.h5ad`

## What This Skill Does Not Do

1. it does not filter cells or genes
2. it does not normalize or cluster the data
3. it does not run biological analysis; it only stabilizes the input contract
4. it does not magically make normalized-expression methods ready; those usually still need `sc-preprocessing`

## Recommended Usage

Run this skill explicitly when:
- users provide arbitrary `.h5ad` files from outside OmicsClaw
- raw counts may live in `adata.raw` or `layers['counts']` instead of `adata.X`
- gene identifiers may need harmonization before QC or downstream scRNA skills
- you want to inspect or save the canonicalized object itself before running analysis

## Workflow

1. **Load**: read input via shared multi-format loader
2. **Preflight**: validate non-empty input; detect species
3. **Canonicalize**: select best count-like matrix, standardize gene names
4. **Persist contracts**: write `omicsclaw_input_contract` and `omicsclaw_matrix_contract`
5. **Export**: save `processed.h5ad`
6. **Report**: generate `report.md` and `result.json` with diagnostics

## CLI

```bash
# Basic usage (species auto-detected)
python omicsclaw.py run sc-standardize-input --input <data.h5ad> --output <dir>

# Explicit species
python omicsclaw.py run sc-standardize-input --input <data.h5ad> --output <dir> --species mouse

# Demo mode
python omicsclaw.py run sc-standardize-input --demo --output /tmp/demo
```

## Parameters

| Flag | Default | Description |
|------|---------|-------------|
| `--input` | (required unless `--demo`) | Input file path |
| `--output` | (required) | Output directory |
| `--species` | `auto` | Species hint: `auto`, `human`, or `mouse` |
| `--demo` | false | Run with built-in PBMC3K demo data |

## Output Contract

- `adata.X` = `raw_counts`
- `adata.layers['counts']` = `raw_counts`
- `adata.raw` = `raw_counts_snapshot`
- `adata.uns['omicsclaw_matrix_contract']` records all of the above explicitly

## Workflow Position

- **Upstream step**: Used when input comes from external tools (not from `sc-count`); converts arbitrary formats into the OmicsClaw canonical contract
- **Usual next step**: `sc-qc` for quality assessment

## Next Step

After standardization, run one of:
- `sc-qc` to compute and visualize quality control metrics
- `sc-preprocessing` to normalize, find HVGs, compute PCA/UMAP, and cluster
- `sc-doublet-detection` if doublet removal is needed before preprocessing

## CLI Parameters

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--input` | path | — | Input file path (`.h5ad`, `.h5`, `.loom`, `.csv`, `.tsv`, or 10X mtx directory); required unless `--demo` |
| `--output` | path | — | Output directory (required) |
| `--demo` | flag | `false` | Run with built-in PBMC3K demo data |
| `--species` | enum | `auto` | Species hint for gene name conventions: `auto`, `human`, `mouse` |
| `--r-enhanced` | flag | `false` | Accepted for CLI consistency; no R Enhanced plots are generated by this skill |

## R Enhanced Plots

This skill has no R Enhanced plots. `--r-enhanced` is accepted for CLI consistency but produces no additional output. The skill's purpose is input canonicalization, not visualization.