@bgicli/bgicli 2.1.1 → 2.2.0

package/data/skills/simulation-orchestrator/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: simulation-orchestrator
+description: Orchestrate multi-simulation campaigns including parameter sweeps, batch jobs, and result aggregation. Use for running parameter studies, managing simulation batches, tracking job status, combining results from multiple runs, or automating simulation workflows.
+allowed-tools: Read, Bash, Write, Grep, Glob
+---
+
+# Simulation Orchestrator
+
+## Goal
+
+Provide tools to manage multi-simulation campaigns: generate parameter sweeps, track job execution status, and aggregate results from completed runs.
+
+## Requirements
+
+- Python 3.10+
+- No external dependencies (uses Python standard library only)
+- Works on Linux, macOS, and Windows
+
+## Inputs to Gather
+
+Before running orchestration scripts, collect from the user:
+
+| Input | Description | Example |
+|-------|-------------|---------|
+| Base config | Template simulation configuration | `base_config.json` |
+| Parameter ranges | Parameters to sweep with bounds | `dt:[1e-4,1e-2],kappa:[0.1,1.0]` |
+| Sweep method | How to sample parameter space | `grid`, `lhs`, `linspace` |
+| Output directory | Where to store campaign files | `./campaign_001` |
+| Simulation command | Command to run each simulation | `python sim.py --config {config}` |
+
+## Decision Guidance
+
+### Choosing a Sweep Method
+
+```
+Need every combination (full factorial)?
+├── YES → Use grid (warning: exponential growth with parameters)
+└── NO → Is space-filling coverage needed?
+    ├── YES → Use lhs (Latin Hypercube Sampling)
+    └── NO → Use linspace for uniform sampling per parameter
+```
+
+| Method | Best For | Sample Count |
+|--------|----------|--------------|
+| `grid` | Low dimensions (1-3), need exact corners | n^d (exponential) |
+| `linspace` | 1D sweeps, uniform spacing | n per parameter |
+| `lhs` | High dimensions, space-filling | user-specified budget |
+
+### Campaign Size Guidelines
+
+| Parameters | Grid Points Each | Total Runs | Recommendation |
+|------------|------------------|------------|----------------|
+| 1 | 10 | 10 | Grid is fine |
+| 2 | 10 | 100 | Grid acceptable |
+| 3 | 10 | 1,000 | Consider LHS |
+| 4+ | 10 | 10,000+ | Use LHS or DOE |
+
+## Script Outputs (JSON Fields)
+
+| Script | Output Fields |
+|--------|---------------|
+| `scripts/sweep_generator.py` | `configs`, `parameter_space`, `sweep_method`, `total_runs` |
+| `scripts/campaign_manager.py` | `campaign_id`, `status`, `jobs`, `progress` |
+| `scripts/job_tracker.py` | `job_id`, `status`, `start_time`, `end_time`, `exit_code` |
+| `scripts/result_aggregator.py` | `summary`, `statistics`, `best_run`, `failed_runs` |
+
+## Workflow
+
+### Step 1: Generate Parameter Sweep
+
+Create configurations for all parameter combinations:
+
+```bash
+python3 scripts/sweep_generator.py \
+    --base-config base_config.json \
+    --params "dt:1e-4:1e-2:5,kappa:0.1:1.0:3" \
+    --method linspace \
+    --output-dir ./campaign_001 \
+    --json
+```
+
+### Step 2: Initialize Campaign
+
+Create campaign tracking structure:
+
+```bash
+python3 scripts/campaign_manager.py \
+    --action init \
+    --config-dir ./campaign_001 \
+    --command "python sim.py --config {config}" \
+    --json
+```
+
+### Step 3: Track Job Status
+
+Monitor running jobs:
+
+```bash
+python3 scripts/job_tracker.py \
+    --campaign-dir ./campaign_001 \
+    --update \
+    --json
+```
+
+### Step 4: Aggregate Results
+
+Combine results from completed runs:
+
+```bash
+python3 scripts/result_aggregator.py \
+    --campaign-dir ./campaign_001 \
+    --metric objective_value \
+    --json
+```
+
+## CLI Examples
+
+```bash
+# Generate 5x3=15 runs varying dt (5 values) and kappa (3 values)
+python3 scripts/sweep_generator.py \
+    --base-config sim.json \
+    --params "dt:1e-4:1e-2:5,kappa:0.1:1.0:3" \
+    --method linspace \
+    --output-dir ./sweep_001 \
+    --json
+
+# Generate LHS samples for 4 parameters with budget of 20 runs
+python3 scripts/sweep_generator.py \
+    --base-config sim.json \
+    --params "dt:1e-4:1e-2,kappa:0.1:1.0,M:1e-6:1e-4,W:0.5:2.0" \
+    --method lhs \
+    --samples 20 \
+    --output-dir ./lhs_001 \
+    --json
+
+# Check campaign status
+python3 scripts/campaign_manager.py \
+    --action status \
+    --config-dir ./sweep_001 \
+    --json
+
+# Get summary statistics from completed runs
+python3 scripts/result_aggregator.py \
+    --campaign-dir ./sweep_001 \
+    --metric final_energy \
+    --json
+```
+
+## Conversational Workflow Example
+
+**User**: I want to run a parameter sweep on dt and kappa for my phase-field simulation. I want to try 5 values of dt between 1e-4 and 1e-2, and 4 values of kappa between 0.1 and 1.0.
+
+**Agent workflow**:
+1. Calculate total runs: 5 x 4 = 20 runs
+2. Generate sweep configurations:
+   ```bash
+   python3 scripts/sweep_generator.py \
+       --base-config simulation.json \
+       --params "dt:1e-4:1e-2:5,kappa:0.1:1.0:4" \
+       --method linspace \
+       --output-dir ./dt_kappa_sweep \
+       --json
+   ```
+3. Initialize campaign:
+   ```bash
+   python3 scripts/campaign_manager.py \
+       --action init \
+       --config-dir ./dt_kappa_sweep \
+       --command "python phase_field.py --config {config}" \
+       --json
+   ```
+4. After user runs simulations, aggregate results:
+   ```bash
+   python3 scripts/result_aggregator.py \
+       --campaign-dir ./dt_kappa_sweep \
+       --metric interface_width \
+       --json
+   ```
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| `Base config not found` | Invalid file path | Verify base config file exists |
+| `Invalid parameter format` | Malformed param string | Use format `name:min:max:count` or `name:min:max` |
+| `Output directory exists` | Would overwrite | Use `--force` or choose new directory |
+| `No completed jobs` | No results to aggregate | Wait for jobs to complete or check for failures |
+| `Metric not found` | Result files missing field | Verify metric name in result JSON |
+
+## Integration with Other Skills
+
+The simulation-orchestrator works with other simulation-workflow skills:
+
+```
+parameter-optimization          simulation-orchestrator
+        │                              │
+        │ DOE samples ────────────────>│ Generate configs
+        │                              │
+        │                              │ Run simulations
+        │                              │
+        │<──────────────────────────── │ Aggregate results
+        │                              │
+        │ Sensitivity analysis         │
+        │ Optimizer selection          │
+```
+
+### Typical Combined Workflow
+
+1. Use `parameter-optimization/doe_generator.py` to get sample points
+2. Use `simulation-orchestrator/sweep_generator.py` to create configs
+3. Run simulations (user's responsibility)
+4. Use `simulation-orchestrator/result_aggregator.py` to collect results
+5. Use `parameter-optimization/sensitivity_summary.py` to analyze
+
+## Limitations
+
+- **Not a job scheduler**: Does not submit jobs to SLURM/PBS; generates configs and tracks status
+- **No parallel execution**: User must run simulations externally (can use GNU parallel, SLURM, etc.)
+- **File-based tracking**: Status tracked via files; no database or real-time monitoring
+- **Local filesystem**: Assumes all files accessible from local machine
+
+## References
+
+- `references/campaign_patterns.md` - Common campaign structures
+- `references/sweep_strategies.md` - Parameter sweep design guidance
+- `references/aggregation_methods.md` - Result aggregation techniques
+
+## Version History
+
+- **v1.0.0** (2024-12-24): Initial release with sweep, campaign, tracking, and aggregation

package/data/skills/simulation-validator/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: simulation-validator
+description: Validate simulations before, during, and after execution. Use for pre-flight checks, runtime monitoring, post-run validation, diagnosing failed simulations, checking convergence, detecting NaN/Inf, or verifying mass/energy conservation.
+allowed-tools: Read, Bash, Write, Grep, Glob
+---
+
+# Simulation Validator
+
+## Goal
+
+Provide a three-stage validation protocol: pre-flight checks, runtime monitoring, and post-flight validation for materials simulations.
+
+## Requirements
+
+- Python 3.8+
+- No external dependencies (uses Python standard library only)
+- Works on Linux, macOS, and Windows
+
+## Inputs to Gather
+
+Before running validation scripts, collect from the user:
+
+| Input | Description | Example |
+|-------|-------------|---------|
+| Config file | Simulation configuration (JSON/YAML) | `simulation.json` |
+| Log file | Runtime output log | `simulation.log` |
+| Metrics file | Post-run metrics (JSON) | `results.json` |
+| Required params | Parameters that must exist | `dt,dx,kappa` |
+| Valid ranges | Parameter bounds | `dt:1e-6:1e-2` |
+
+## Decision Guidance
+
+### When to Run Each Stage
+
+```
+Is simulation about to start?
+├── YES → Run Stage 1: preflight_checker.py
+│         └── BLOCK status? → Fix issues, do NOT run simulation
+│         └── WARN status? → Review warnings, document if accepted
+│         └── PASS status? → Proceed to run simulation
+│
+Is simulation running?
+├── YES → Run Stage 2: runtime_monitor.py (periodically)
+│         └── Alerts? → Consider stopping, check parameters
+│
+Has simulation finished?
+├── YES → Run Stage 3: result_validator.py
+│         └── Failed checks? → Do NOT use results
+│                            → Run failure_diagnoser.py
+│         └── All passed? → Results are valid
+```
+
+### Choosing Validation Thresholds
+
+| Metric | Conservative | Standard | Relaxed |
+|--------|--------------|----------|---------|
+| Mass tolerance | 1e-6 | 1e-3 | 1e-2 |
+| Residual growth | 2x | 10x | 100x |
+| dt reduction | 10x | 100x | 1000x |
+
+## Script Outputs (JSON Fields)
+
+| Script | Output Fields |
+|--------|---------------|
+| `scripts/preflight_checker.py` | `report.status`, `report.blockers`, `report.warnings` |
+| `scripts/runtime_monitor.py` | `alerts`, `residual_stats`, `dt_stats` |
+| `scripts/result_validator.py` | `checks`, `confidence_score`, `failed_checks` |
+| `scripts/failure_diagnoser.py` | `probable_causes`, `recommended_fixes` |
+
+## Three-Stage Validation Protocol
+
+### Stage 1: Pre-flight (Before Simulation)
+
+1. Run `scripts/preflight_checker.py --config simulation.json`
+2. **BLOCK status**: Stop immediately, fix all blocker issues
+3. **WARN status**: Review warnings, document accepted risks
+4. **PASS status**: Proceed to simulation
+
+```bash
+python3 scripts/preflight_checker.py \
+    --config simulation.json \
+    --required dt,dx,kappa \
+    --ranges "dt:1e-6:1e-2,dx:1e-4:1e-1" \
+    --min-free-gb 1.0 \
+    --json
+```
+
+### Stage 2: Runtime (During Simulation)
+
+1. Run `scripts/runtime_monitor.py --log simulation.log` periodically
+2. Configure alert thresholds based on problem type
+3. Stop simulation if critical alerts appear
+
+```bash
+python3 scripts/runtime_monitor.py \
+    --log simulation.log \
+    --residual-growth 10.0 \
+    --dt-drop 100.0 \
+    --json
+```
+
+### Stage 3: Post-flight (After Simulation)
+
+1. Run `scripts/result_validator.py --metrics results.json`
+2. **All checks PASS**: Results are valid for analysis
+3. **Any check FAIL**: Do NOT use results, diagnose failure
+
+```bash
+python3 scripts/result_validator.py \
+    --metrics results.json \
+    --bound-min 0.0 \
+    --bound-max 1.0 \
+    --mass-tol 1e-3 \
+    --json
+```
+
+### Failure Diagnosis
+
+When validation fails:
+
+```bash
+python3 scripts/failure_diagnoser.py --log simulation.log --json
+```
+
+## Conversational Workflow Example
+
+**User**: My phase field simulation crashed after 1000 steps. Can you help me figure out why?
+
+**Agent workflow**:
+1. First, check the log for obvious errors:
+   ```bash
+   python3 scripts/failure_diagnoser.py --log simulation.log --json
+   ```
+2. If diagnosis suggests numerical blow-up, check runtime stats:
+   ```bash
+   python3 scripts/runtime_monitor.py --log simulation.log --json
+   ```
+3. Recommend fixes based on findings:
+   - If residual grew rapidly → reduce time step
+   - If dt collapsed → check stability conditions
+   - If NaN detected → check initial conditions
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| `Config not found` | File path invalid | Verify config path exists |
+| `Non-numeric value` | Parameter is not a number | Fix config file format |
+| `out of range` | Parameter outside bounds | Adjust parameter or bounds |
+| `Output directory not writable` | Permission issue | Check directory permissions |
+| `Insufficient disk space` | Disk nearly full | Free up space or reduce output |
+
+## Interpretation Guidance
+
+### Status Meanings
+
+| Status | Meaning | Action |
+|--------|---------|--------|
+| PASS | All checks passed | Proceed with confidence |
+| WARN | Non-critical issues found | Review and document |
+| BLOCK | Critical issues found | Must fix before proceeding |
+
+### Confidence Score Interpretation
+
+| Score | Meaning |
+|-------|---------|
+| 1.0 | All validation checks passed |
+| 0.75+ | Most checks passed, minor issues |
+| 0.5-0.75 | Significant issues, review carefully |
+| < 0.5 | Major problems, do not trust results |
+
+### Common Failure Patterns
+
+| Pattern in Log | Likely Cause | Recommended Fix |
+|----------------|--------------|-----------------|
+| NaN, Inf, overflow | Numerical instability | Reduce dt, increase damping |
+| max iterations, did not converge | Solver failure | Tune preconditioner, tolerances |
+| out of memory | Memory exhaustion | Reduce mesh, enable out-of-core |
+| dt reduced | Adaptive stepping triggered | May be okay if controlled |
+
+## Limitations
+
+- **Not a real-time monitor**: Scripts analyze logs after-the-fact
+- **Regex-based**: Log parsing depends on pattern matching; may miss unusual formats
+- **No automatic fixes**: Scripts diagnose but don't modify simulations
+
+## References
+
+- `references/validation_protocol.md` - Detailed checklist and criteria
+- `references/log_patterns.md` - Common failure signatures and regex patterns
+
+## Version History
+
+- **v1.1.0** (2024-12-24): Enhanced documentation, decision guidance, Windows compatibility
+- **v1.0.0**: Initial release with 4 validation scripts

package/data/skills/single-annotation/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: single-cell-annotation-skills-with-omicverse
+title: Single-cell annotation skills with omicverse
+description: Guide Claude through SCSA, MetaTiME, CellVote, CellMatch, GPTAnno, and weighted KNN transfer workflows for annotating single-cell modalities.
+---
+
+# Single-cell annotation skills with omicverse
+
+## Overview
+Use this skill to reproduce and adapt the single-cell annotation playbook captured in omicverse tutorials: SCSA [`t_cellanno.ipynb`](../../../omicverse_guide/docs/Tutorials-single/t_cellanno.ipynb), MetaTiME [`t_metatime.ipynb`](../../../omicverse_guide/docs/Tutorials-single/t_metatime.ipynb), CellVote [`t_cellvote.md`](../../../omicverse_guide/docs/Tutorials-single/t_cellvote.md) & [`t_cellvote_pbmc3k.ipynb`](../../../omicverse_guide/docs/Tutorials-single/t_cellvote_pbmc3k.ipynb), CellMatch [`t_cellmatch.ipynb`](../../../omicverse_guide/docs/Tutorials-single/t_cellmatch.ipynb), GPTAnno [`t_gptanno.ipynb`](../../../omicverse_guide/docs/Tutorials-single/t_gptanno.ipynb), and label transfer [`t_anno_trans.ipynb`](../../../omicverse_guide/docs/Tutorials-single/t_anno_trans.ipynb). Each section below highlights required inputs, training/inference steps, and how to read the outputs.
+
+## Instructions
+1. **SCSA automated cluster annotation**
+   - *Data requirements*: PBMC3k raw counts from 10x Genomics (`pbmc3k_filtered_gene_bc_matrices.tar.gz`) or the processed `sample/rna.h5ad`. Download instructions are embedded in the notebook; unpack to `data/filtered_gene_bc_matrices/hg19/`. Ensure an SCSA SQLite database is available (e.g. `pySCSA_2024_v1_plus.db` from the Figshare/Drive links listed in the tutorial) and point `model_path` to its location.
+   - *Preprocessing & model fit*: Load with `sc.read_10x_mtx`, run QC (`ov.pp.qc`), normalization and HVG selection (`ov.pp.preprocess`), scaling (`ov.pp.scale`), PCA (`ov.pp.pca`), neighbors, Leiden clustering, and compute rank markers (`sc.tl.rank_genes_groups`). Instantiate `scsa = ov.single.pySCSA(...)` choosing `target='cellmarker'` or `'panglaodb'`, tissue scope, and thresholds (`foldchange`, `pvalue`).
+   - *Inference & interpretation*: Call `scsa.cell_anno(clustertype='leiden', result_key='scsa_celltype_cellmarker')` or `scsa.cell_auto_anno` to append predictions to `adata.obs`. Compare to manual marker-based labels via `ov.utils.embedding` or `sc.pl.dotplot`, inspect marker dictionaries (`ov.single.get_celltype_marker`), and query supported tissues with `scsa.get_model_tissue()`. Use the ROI/ROE helpers (`ov.utils.roe`, `ov.utils.plot_cellproportion`) to validate abundance trends.
+
+2. **MetaTiME tumour microenvironment states**
+   - *Data requirements*: Batched TME AnnData with an scVI latent embedding. The tutorial uses `TiME_adata_scvi.h5ad` from Figshare (`https://figshare.com/ndownloader/files/41440050`). If starting from counts, run scVI (`scvi.model.SCVI`) first to populate `adata.obsm['X_scVI']`.
+   - *Preprocessing & model fit*: Optionally subset to non-malignant cells via `adata.obs['isTME']`. Rebuild neighbors on the latent representation (`sc.pp.neighbors(adata, use_rep="X_scVI")`) and embed with pymde (`adata.obsm['X_mde'] = ov.utils.mde(...)`). Initialise `TiME_object = ov.single.MetaTiME(adata, mode='table')` and, if finer granularity is desired, over-cluster with `TiME_object.overcluster(resolution=8, clustercol='overcluster')`.
+   - *Inference & interpretation*: Run `TiME_object.predictTiME(save_obs_name='MetaTiME')` to assign minor states and `Major_MetaTiME`. Visualise using `TiME_object.plot` or `sc.pl.embedding`. Interpret the outputs by comparing cluster-level distributions and confirming that MetaTiME and Major_MetaTiME columns align with expected niches.
+
+3. **CellVote consensus labelling**
+   - *Data requirements*: A clustered AnnData (e.g. PBMC3k stored as `CELLVOTE_PBMC3K` env var or `data/pbmc3k.h5ad`) plus at least two precomputed annotation columns (simulated in the tutorial as `scsa_annotation`, `gpt_celltype`, `gbi_celltype`). Prepare per-cluster marker genes via `sc.tl.rank_genes_groups`.
+   - *Preprocessing & model fit*: After standard preprocessing (normalize, log1p, HVGs, PCA, neighbors, Leiden) build a marker dictionary `marker_dict = top_markers_from_rgg(adata, 'leiden', topn=10)` or via `ov.single.get_celltype_marker`. Instantiate `cv = ov.single.CellVote(adata)`.
+   - *Inference & interpretation*: Call `cv.vote(clusters_key='leiden', cluster_markers=marker_dict, celltype_keys=[...], species='human', organization='PBMC', provider='openai', model='gpt-4o-mini')`. Offline examples monkey-patch arbitration to avoid API calls; online voting requires valid credentials. Final consensus labels live in `adata.obs['CellVote_celltype']`. Compare each cluster’s majority vote with the input sources (`adata.obs[['leiden', 'scsa_annotation', ...]]`) to justify decisions.
+
+4. **CellMatch ontology mapping**
+   - *Data requirements*: Annotated AnnData such as `pertpy.dt.haber_2017_regions()` with `adata.obs['cell_label']`. Download Cell Ontology JSON (`cl.json`) via `ov.single.download_cl(...)` or manual links, and optionally Cell Taxonomy resources (`Cell_Taxonomy_resource.txt`). Ensure access to a SentenceTransformer model (`sentence-transformers/all-MiniLM-L6-v2`, `BAAI/bge-base-en-v1.5`, etc.), downloading to `local_model_dir` if offline.
+   - *Preprocessing & model fit*: Create the mapper with `ov.single.CellOntologyMapper(cl_obo_file='new_ontology/cl.json', model_name='sentence-transformers/all-MiniLM-L6-v2', local_model_dir='./my_models')`. Run `mapper.map_adata(...)` to assign ontology-derived labels/IDs, optionally enabling taxonomy matching (`use_taxonomy=True` after calling `load_cell_taxonomy_resource`).
+   - *Inference & interpretation*: Explore mapping summaries (`mapper.print_mapping_summary_taxonomy`) and inspect embeddings coloured by `cell_ontology`, `cell_ontology_cl_id`, or `enhanced_cell_ontology`. Use helper queries such as `mapper.find_similar_cells('T helper cell')`, `mapper.get_cell_info(...)`, and category browsing to validate ontology coverage.
+
+5. **GPTAnno LLM-powered annotation**
+   - *Data requirements*: The same PBMC3k dataset (raw matrix or `.h5ad`) and cluster assignments. Access to an LLM endpoint—configure `AGI_API_KEY` for OpenAI-compatible providers (`provider='openai'`, `'qwen'`, `'kimi'`, etc.), or supply a local model path for `ov.single.gptcelltype_local`.
+   - *Preprocessing & model fit*: Follow the QC, normalization, HVG, scaling, PCA, neighbor, Leiden, and marker discovery steps described above (reusing outputs from the SCSA workflow). Build the marker dictionary automatically with `ov.single.get_celltype_marker(adata, clustertype='leiden', rank=True, key='rank_genes_groups', foldchange=2, topgenenumber=5)`.
+   - *Inference & interpretation*: Invoke `ov.single.gptcelltype(...)` specifying tissue/species context and desired provider/model. Post-process responses to keep clean labels (`result[key].split(': ')[-1]...`) and write them to `adata.obs['gpt_celltype']`. Compare embeddings (`ov.pl.embedding(..., color=['leiden','gpt_celltype'])`) to verify cluster identities. If operating offline, call `ov.single.gptcelltype_local` with a downloaded instruction-tuned checkpoint.
+
+6. **Weighted KNN annotation transfer**
+   - *Data requirements*: Cross-modal GLUE outputs with aligned embeddings, e.g. `data/analysis_lymph/rna-emb.h5ad` (annotated RNA) and `data/analysis_lymph/atac-emb.h5ad` (query ATAC) where both contain `obsm['X_glue']`.
+   - *Preprocessing & model fit*: Load both modalities, optionally concatenate for QC plots, and compute a shared low-dimensional embedding with `ov.utils.mde`. Train a neighbour model using `ov.utils.weighted_knn_trainer(train_adata=rna, train_adata_emb='X_glue', n_neighbors=15)`.
+   - *Inference & interpretation*: Transfer labels via `labels, uncert = ov.utils.weighted_knn_transfer(query_adata=atac, query_adata_emb='X_glue', label_keys='major_celltype', knn_model=knn_transformer, ref_adata_obs=rna.obs)`. Store predictions in `atac.obs['transf_celltype']` and uncertainties in `atac.obs['transf_celltype_unc']`; copy to `major_celltype` if you want consistent naming. Visualise (`ov.utils.embedding`) and inspect uncertainty to flag ambiguous cells.
+
+## Critical API Reference - EXACT Function Signatures
+
+### pySCSA - IMPORTANT: Parameter is `clustertype`, NOT `cluster`
+
+**CORRECT usage:**
+```python
+# Step 1: Initialize pySCSA
+scsa = ov.single.pySCSA(
+    adata,
+    foldchange=1.5,
+    pvalue=0.01,
+    species='Human',
+    tissue='All',
+    target='cellmarker'  # or 'panglaodb'
+)
+
+# Step 2: Run annotation - NOTE: use clustertype='leiden', NOT cluster='leiden'!
+anno_result = scsa.cell_anno(clustertype='leiden', cluster='all')
+
+# Step 3: Add cell type labels to adata.obs
+scsa.cell_auto_anno(adata, clustertype='leiden', key='scsa_celltype')
+# Results are stored in adata.obs['scsa_celltype']
+```
+
+**WRONG - DO NOT USE:**
+```python
+# WRONG! 'cluster' is NOT a valid parameter for cell_auto_anno!
+# scsa.cell_auto_anno(adata, cluster='leiden')  # ERROR!
+```
+
+### COSG Marker Genes - Results stored in adata.uns, NOT adata.obs
+
+**CORRECT usage:**
+```python
+# Step 1: Run COSG marker gene identification
+ov.single.cosg(adata, groupby='leiden', n_genes_user=50)
+
+# Step 2: Access results from adata.uns (NOT adata.obs!)
+marker_names = adata.uns['rank_genes_groups']['names']  # DataFrame with cluster columns
+marker_scores = adata.uns['rank_genes_groups']['scores']
+
+# Step 3: Get top markers for specific cluster
+cluster_0_markers = adata.uns['rank_genes_groups']['names']['0'][:10].tolist()
+
+# Step 4: To create celltype column, manually map clusters to cell types
+cluster_to_celltype = {
+    '0': 'T cells',
+    '1': 'B cells',
+    '2': 'Monocytes',
+}
+adata.obs['cosg_celltype'] = adata.obs['leiden'].map(cluster_to_celltype)
+```
+
+**WRONG - DO NOT USE:**
+```python
+# WRONG! COSG does NOT create adata.obs columns directly!
+# adata.obs['cosg_celltype']  # This key does NOT exist after running COSG!
+# adata.uns['cosg_celltype']  # This key also does NOT exist!
+```
+
+### Common Pitfalls to Avoid
+
+1. **pySCSA parameter confusion**:
+   - `clustertype` = which obs column contains cluster labels (e.g., 'leiden')
+   - `cluster` = which specific clusters to annotate ('all' or specific cluster IDs)
+   - These are DIFFERENT parameters!
+
+2. **COSG result access**:
+   - COSG is a marker gene finder, NOT a cell type annotator
+   - Results are per-cluster gene rankings stored in `adata.uns['rank_genes_groups']`
+   - To assign cell types, you must manually map clusters to cell types based on markers
+
+3. **Result storage patterns in OmicVerse**:
+   - Cell type annotations → `adata.obs['<key>']`
+   - Marker gene results → `adata.uns['<key>']` (includes 'names', 'scores', 'logfoldchanges')
+   - Differential expression → `adata.uns['rank_genes_groups']`
+
+## Examples
+- "Run SCSA with both CellMarker and PanglaoDB references on PBMC3k, then benchmark against manual marker assignments before feeding the results into CellVote."
+- "Annotate tumour microenvironment states in the MetaTiME Figshare dataset, highlight Major_MetaTiME classes, and export the label distribution per patient."
+- "Download Cell Ontology resources, map `haber_2017_regions` clusters to ontology terms, and enrich ambiguous clusters using Cell Taxonomy hints."
+- "Propagate RNA-derived `major_celltype` labels onto GLUE-integrated ATAC cells and report clusters with high transfer uncertainty."
+
+## References
+- Tutorials and notebooks: [`t_cellanno.ipynb`](../../../omicverse_guide/docs/Tutorials-single/t_cellanno.ipynb), [`t_metatime.ipynb`](../../../omicverse_guide/docs/Tutorials-single/t_metatime.ipynb), [`t_cellvote.md`](../../../omicverse_guide/docs/Tutorials-single/t_cellvote.md), [`t_cellvote_pbmc3k.ipynb`](../../../omicverse_guide/docs/Tutorials-single/t_cellvote_pbmc3k.ipynb), [`t_cellmatch.ipynb`](../../../omicverse_guide/docs/Tutorials-single/t_cellmatch.ipynb), [`t_gptanno.ipynb`](../../../omicverse_guide/docs/Tutorials-single/t_gptanno.ipynb), [`t_anno_trans.ipynb`](../../../omicverse_guide/docs/Tutorials-single/t_anno_trans.ipynb).
+- Sample data & assets: PBMC3k matrix from 10x Genomics, MetaTiME `TiME_adata_scvi.h5ad` (Figshare), SCSA database downloads, GLUE embeddings under `data/analysis_lymph/`, Cell Ontology `cl.json`, and Cell Taxonomy resource.
+- Quick copy commands: [`reference.md`](reference.md).