Goal
Turn notebook-style OmicVerse DEG analysis into a compact execution spine for condition-vs-condition comparisons inside selected cell types. Keep this skill focused on DEG only; differential abundance and compositional analysis are a separate job with a different input contract and backend surface.
Quick Workflow
- Inspect the input
AnnData, the condition column, the cell-type column, and whether raw counts are available inadata.raworadata.layers["counts"]. - Choose a DEG backend before running anything:
wilcoxonort-testfor the scanpy rank-gene path,memento-defor the count-aware memento path. - Subset to the required cell types with
celltype_keyandcelltype_group; leavecelltype_group=Noneonly when you really want all cell types pooled into one DEG run. - Run
DEG.run(...)with an explicitmax_cellspolicy and method-specific kwargs when using memento. - Collect results with
get_results(), then verify the expected statistical columns and expression-percentage columns before saving or plotting.
Interface Summary
ov.single.DEG(adata, condition, ctrl_group, test_group, method='wilcoxon', use_raw=None)initializes the wrapper.methodbranches arewilcoxon,t-test, andmemento-de.use_raw=Noneauto-detectsadata.raw; if raw exists, the wrapper copiesadata.raw.Xinto a fresh object and uses that matrix for DEG.DEG.run(celltype_key, celltype_group=None, max_cells=100000, **kwargs)subsets by cell type and dispatches to the selected backend.wilcoxonandt-testnormalize and log-transform only when the active matrix still looks integer-valued.memento-deexpects count-like input; ifXis not integer-valued, the wrapper first looks foradata.layers["counts"]and otherwise tries count recovery from log-normalized values.- memento-specific kwargs are passed through
run(...); the notebook usedcapture_rate,num_cpus, andnum_boot. DEG.get_results()returns a DEG table and augments it withbaseMean,pct_ctrl,pct_test, andpct_diff.
Stage Selection
- Use
method='wilcoxon'when you want the notebook's fast nonparametric path on one or more selected cell types. - Use
method='t-test'only when a t-test is acceptable for the data distribution and normalization state. - Use
method='memento-de'when the user explicitly wants memento's differential-mean path or needs the extra branch-specific kwargs. - Keep
celltype_groupexplicit for targeted comparisons such as one lineage or cluster; set it toNoneonly when a pooled all-cell-type DEG run is actually intended. - Treat violin plots as optional reporting after DEG, not as part of the reusable execution contract.
Input Contract
- Start from an
AnnDataobject with a condition column inobs. - Provide control and test labels that exist in that condition column.
- Provide a cell-type column for
celltype_key. - Prefer preserving raw counts in
adata.raworadata.layers["counts"], especially formemento-de. - Expect the wrapper to coerce dense matrices to CSR internally.
Minimal Execution Patterns
import omicverse as ov
deg = ov.single.DEG(
adata,
condition="condition",
ctrl_group="Control",
test_group="Salmonella",
method="wilcoxon",
)
deg.run(
celltype_key="cell_label",
celltype_group=["TA"],
max_cells=100000,
)
res = deg.get_results()
deg = ov.single.DEG(
adata,
condition="condition",
ctrl_group="Control",
test_group="Salmonella",
method="memento-de",
use_raw=False,
)
deg.run(
celltype_key="cell_label",
celltype_group=["TA"],
capture_rate=0.07,
num_cpus=12,
num_boot=5000,
)
res = deg.get_results()
Constraints
- Do not merge DEG and DCT into one skill at execution time; they are independently triggerable and use different backends.
- Do not assume the notebook's example cell type or example genes are universal defaults.
- Do not leave
methodimplicit; branch choice changes both the statistical engine and the data expectations. - Do not claim that
memento-deran on raw counts unless you actually confirmed raw counts, acountslayer, or successful count recovery. - Keep smoke and acceptance commands shell-agnostic. Do not rely on
zsh-specific syntax, shell startup files, or shell-only features when a direct${PYTHON} script.pycommand is enough. - Do not put local paths or environment names into the reusable instructions.
Validation
- Check that the selected control and test labels both remain after subsetting.
- Check that
DEG.run(...)used the intended cell-type subset. - For
wilcoxonandt-test, check that the result table contains at leastlog2FC,pvalue,padj,qvalue,baseMean,pct_ctrl,pct_test, andpct_diff. - For
memento-de, check that the result table still gainsbaseMean,pct_ctrl,pct_test, andpct_diffafterget_results(). - If the dataset is large, say whether
max_cellscaused downsampling. - If only a bounded smoke path was run, say so explicitly.
Resource Map
- Use the branch selection notes when choosing the DEG backend or deciding whether all cell types should be pooled.
- Use the source grounding notes when you need the live signatures, defaults, or branch-specific behavior.
- Use the notebook map when tracing which tutorial cells became which reusable instruction.
- Use the compatibility notes when notebook prose and current runtime behavior diverge.