sc-standardize-input

sc-standardize-input

When to use

The user has a single-cell expression file from outside OmicsClaw (a public .h5ad, a 10X mtx directory, a .loom, etc.) and needs the canonical AnnData contract every downstream scRNA skill assumes: raw counts in layers["counts"] and adata.raw, harmonised feature names, and a uns["omicsclaw_matrix_contract"] provenance record. Run this once before sc-qc / sc-preprocessing / etc.

Use from a step

standardizer = load_skill("sc-standardize-input")
adata = standardizer.standardize(read_input("external.h5ad"), species="human")
write_output(adata, "intermediate/adata_standardized.h5ad")

standardize returns a new AnnData. It does not filter, normalize or cluster. A runnable PBMC example is in examples/example_step.py.

API

<!-- api:begin generated from _api.py; regenerate with run.py api <skill dir> --write -->

standardize(adata, *, species: str='auto')

Return a canonical copy with count-like X, layers['counts'] and raw.

Select counts from layers['counts'], aligned raw or X, in that order; harmonize feature names and record the matrix and input contracts.

:param adata: AnnData with at least one count-like expression matrix. :param species: 'auto' uses infer_species; 'human' or 'mouse' overrides it. :returns: A new AnnData. run_info reports the selected matrix and warnings. :raises ValueError: The species is invalid or no count-like matrix is present.

infer_species(adata) -> str

Infer human or mouse from feature names, defaulting to human.

:param adata: AnnData whose feature names or gene-symbol metadata are examined. :returns: The species hint used by standardize(species="auto").

run_info(adata, *, keep: bool=True) -> dict

Read standardization diagnostics stored as JSON in adata.uns.

:param adata: The AnnData returned by standardize. :param keep: False removes these diagnostics after reading; default True. :returns: A dictionary, or an empty dictionary before standardize runs.

<!-- api:end -->

Methods and parameters

species="auto" uses the existing gene-name heuristic; use human or mouse when the organism is known. infer_species exposes that heuristic. Counts are selected from layers["counts"], aligned raw, then X. run_info reports the chosen source and any warnings. This method has no random state or optional backend.

Inputs & Outputs

Inputs

• Input kinds: file, directory
• Modalities: scrna
• File types: .h5ad, .h5, .loom, .csv, .tsv

Outputs

• processed.h5ad
• report.md
• result.json
• Processed AnnData (saves_h5ad) — adds layers: counts

Flow

1. Load via the shared multi-format single-cell loader.
2. Pre-flight: validate non-empty input; auto-detect species from gene name case (UPPER → human, Title → mouse).
3. Pick the best count-like matrix among layers["counts"], adata.raw, and adata.X (orchestrated by canonicalize_singlecell_adata in skills/singlecell/_lib/adata_utils.py, which calls the matrix_looks_count_like heuristic at _lib/adata_utils.py).
4. Harmonise feature names (Ensembl ↔ symbol, deduplicate).
5. Persist uns["omicsclaw_input_contract"] + uns["omicsclaw_matrix_contract"].
6. Save processed.h5ad; emit report.md + result.json.

Gotchas

• --r-enhanced is accepted but produces no R plots. sc_standardize_input.py declares the flag for CLI consistency; this skill is input canonicalisation, not visualisation. Pass it freely, but expect no R Enhanced figures.
• Count-source selection uses a count-like heuristic, not file provenance. Check run_info(adata)["expression_source"] and warnings, or the CLI's result.json["summary"], before downstream normalization.
• Species auto-detect is gene-case-based. UPPER-case symbols → human, Title-case → mouse. Non-standard gene-name conventions (Ensembl IDs only, lowercase) silently fall through to the auto default. Pass --species human or --species mouse explicitly when working with non-symbol matrices.
• No filtering, no normalisation, no clustering. Even if result.json looks complete, the output is still raw counts in canonical form — run sc-qc and sc-preprocessing next.

Key CLI

# Demo (built-in PBMC3K)
python skills/singlecell/scrna/sc-standardize-input/sc_standardize_input.py --demo --output /tmp/sc_std_demo

# Real run with species hint
python skills/singlecell/scrna/sc-standardize-input/sc_standardize_input.py \
  --input external.h5ad --output results/ --species mouse

See also

• references/parameters.md — every CLI flag and tuning hint
• references/methodology.md — count-source heuristic, species detection logic
• references/output_contract.md — exact processed.h5ad + result.json shape
• Adjacent skills: sc-count (FASTQ → AnnData; skip standardisation when used), sc-qc (next step), sc-preprocessing (full normalise+cluster pipeline)

Dependencies

Python packages this skill's script needs. They are not installed for you — check before a long run.

anndata, matplotlib, numpy, pandas, scanpy, scipy