@bgicli/bgicli 2.1.1 → 2.2.1

package/data/skills/spatial-transcriptomics-analysis/bioSkills/spatial-visualization/SKILL.md

@@ -0,0 +1,270 @@
+<!--
+# COPYRIGHT NOTICE
+# This file is part of the "Universal Biomedical Skills" project.
+# Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>
+# All Rights Reserved.
+#
+# This code is proprietary and confidential.
+# Unauthorized copying of this file, via any medium is strictly prohibited.
+#
+# Provenance: Authenticated by MD BABU MIA
+
+-->
+
+---
+name: bio-spatial-transcriptomics-spatial-visualization
+description: Visualize spatial transcriptomics data using Squidpy and Scanpy. Create tissue plots with gene expression, clusters, and annotations overlaid on histology images. Use when visualizing spatial expression patterns.
+tool_type: python
+primary_tool: squidpy
+measurable_outcome: Execute skill workflow successfully with valid output within 15 minutes.
+allowed-tools:
+  - read_file
+  - run_shell_command
+---
+
+# Spatial Visualization
+
+Create visualizations for spatial transcriptomics data.
+
+## Required Imports
+
+```python
+import squidpy as sq
+import scanpy as sc
+import matplotlib.pyplot as plt
+```
+
+## Basic Spatial Plot
+
+```python
+# Plot spots colored by a variable
+sq.pl.spatial_scatter(adata, color='total_counts', size=1.3)
+
+# Multiple variables
+sq.pl.spatial_scatter(adata, color=['total_counts', 'n_genes_by_counts'], ncols=2)
+```
+
+## Plot with Scanpy
+
+```python
+# Scanpy's spatial plot
+sc.pl.spatial(adata, color='leiden', spot_size=1.5)
+
+# Multiple genes
+sc.pl.spatial(adata, color=['GENE1', 'GENE2', 'GENE3'], ncols=3)
+```
+
+## Show Tissue Image
+
+```python
+# Plot with tissue background
+sc.pl.spatial(adata, color='leiden', img_key='hires', alpha_img=0.5)
+
+# Without tissue
+sc.pl.spatial(adata, color='leiden', img_key=None)
+```
+
+## Customize Appearance
+
+```python
+# Adjust spot size and colors
+sc.pl.spatial(
+    adata,
+    color='leiden',
+    spot_size=1.5,
+    palette='tab20',
+    title='Cluster assignments',
+    frameon=False,
+)
+```
+
+## Gene Expression on Tissue
+
+```python
+# Single gene
+sc.pl.spatial(adata, color='CD3D', cmap='viridis', vmin=0, vmax='p99')
+
+# Multiple genes side by side
+genes = ['CD3D', 'MS4A1', 'CD14', 'NKG7']
+sc.pl.spatial(adata, color=genes, ncols=2, cmap='Reds', vmin=0)
+```
+
+## Expression with Colorbar Control
+
+```python
+fig, axes = plt.subplots(1, 2, figsize=(12, 5))
+
+for ax, gene in zip(axes, ['GENE1', 'GENE2']):
+    sc.pl.spatial(adata, color=gene, ax=ax, show=False, vmin=0, vmax=5, cmap='viridis')
+    ax.set_title(gene)
+
+plt.tight_layout()
+plt.savefig('gene_expression.png', dpi=300)
+```
+
+## Compare Conditions/Samples
+
+```python
+# Split by sample
+sc.pl.spatial(adata, color='leiden', groups=['sample1', 'sample2'], ncols=2)
+
+# Or manually
+samples = adata.obs['sample'].unique()
+fig, axes = plt.subplots(1, len(samples), figsize=(5*len(samples), 5))
+
+for ax, sample in zip(axes, samples):
+    adata_sub = adata[adata.obs['sample'] == sample]
+    sc.pl.spatial(adata_sub, color='leiden', ax=ax, show=False, title=sample)
+
+plt.tight_layout()
+```
+
+## Overlay Annotations
+
+```python
+# Plot with custom annotations
+fig, ax = plt.subplots(figsize=(8, 8))
+sc.pl.spatial(adata, color='leiden', ax=ax, show=False)
+
+# Add text annotations
+for cluster in adata.obs['leiden'].unique():
+    mask = adata.obs['leiden'] == cluster
+    coords = adata.obsm['spatial'][mask].mean(axis=0)
+    ax.annotate(f'C{cluster}', coords, fontsize=12, ha='center')
+
+plt.savefig('annotated.png', dpi=300)
+```
+
+## Co-expression Plot
+
+```python
+# Visualize co-expression of two genes
+import numpy as np
+
+gene1, gene2 = 'CD3D', 'CD8A'
+expr1 = adata[:, gene1].X.toarray().flatten()
+expr2 = adata[:, gene2].X.toarray().flatten()
+
+# Create RGB image (red=gene1, green=gene2)
+from matplotlib.colors import Normalize
+norm = Normalize(vmin=0, vmax=np.percentile(np.concatenate([expr1, expr2]), 99))
+colors = np.zeros((adata.n_obs, 3))
+colors[:, 0] = norm(expr1)  # Red channel
+colors[:, 1] = norm(expr2)  # Green channel
+
+fig, ax = plt.subplots(figsize=(8, 8))
+coords = adata.obsm['spatial']
+ax.scatter(coords[:, 0], coords[:, 1], c=colors, s=10)
+ax.set_aspect('equal')
+ax.set_title(f'{gene1} (red) + {gene2} (green)')
+plt.savefig('coexpression.png', dpi=300)
+```
+
+## Visualize Spatial Statistics
+
+```python
+# Plot Moran's I results
+sq.pl.spatial_scatter(adata, color='GENE1', size=1.3)
+
+# Plot neighborhood enrichment
+sq.pl.nhood_enrichment(adata, cluster_key='leiden')
+
+# Plot co-occurrence
+sq.pl.co_occurrence(adata, cluster_key='leiden')
+```
+
+## Interactive Visualization with Napari
+
+```python
+import napari
+
+# Create viewer
+viewer = napari.Viewer()
+
+# Add tissue image
+library_id = list(adata.uns['spatial'].keys())[0]
+img = adata.uns['spatial'][library_id]['images']['hires']
+viewer.add_image(img, name='tissue')
+
+# Add spots
+coords = adata.obsm['spatial']
+scalef = adata.uns['spatial'][library_id]['scalefactors']['tissue_hires_scalef']
+viewer.add_points(coords * scalef, size=10, name='spots')
+
+napari.run()
+```
+
+## Save Publication-Quality Figures
+
+```python
+import matplotlib.pyplot as plt
+
+fig, ax = plt.subplots(figsize=(8, 8))
+sc.pl.spatial(
+    adata,
+    color='leiden',
+    ax=ax,
+    show=False,
+    frameon=False,
+    title='',
+    legend_loc='right margin',
+)
+plt.savefig('figure.pdf', dpi=300, bbox_inches='tight')
+plt.savefig('figure.png', dpi=300, bbox_inches='tight')
+```
+
+## Multi-Panel Figure
+
+```python
+fig = plt.figure(figsize=(15, 10))
+
+# Tissue with clusters
+ax1 = fig.add_subplot(2, 3, 1)
+sc.pl.spatial(adata, color='leiden', ax=ax1, show=False, title='Clusters')
+
+# Gene 1
+ax2 = fig.add_subplot(2, 3, 2)
+sc.pl.spatial(adata, color='CD3D', ax=ax2, show=False, title='CD3D', cmap='Reds')
+
+# Gene 2
+ax3 = fig.add_subplot(2, 3, 3)
+sc.pl.spatial(adata, color='MS4A1', ax=ax3, show=False, title='MS4A1', cmap='Blues')
+
+# QC metrics
+ax4 = fig.add_subplot(2, 3, 4)
+sc.pl.spatial(adata, color='total_counts', ax=ax4, show=False, title='Total counts')
+
+# UMAP
+ax5 = fig.add_subplot(2, 3, 5)
+sc.pl.umap(adata, color='leiden', ax=ax5, show=False, title='UMAP')
+
+# Violin plot
+ax6 = fig.add_subplot(2, 3, 6)
+sc.pl.violin(adata, ['CD3D', 'MS4A1'], groupby='leiden', ax=ax6, show=False)
+
+plt.tight_layout()
+plt.savefig('multi_panel.png', dpi=300)
+```
+
+## Crop and Zoom
+
+```python
+# Zoom into a region
+x_min, x_max = 2000, 4000
+y_min, y_max = 2000, 4000
+
+fig, ax = plt.subplots(figsize=(8, 8))
+sc.pl.spatial(adata, color='leiden', ax=ax, show=False)
+ax.set_xlim(x_min, x_max)
+ax.set_ylim(y_max, y_min)  # Note: y is inverted in images
+plt.savefig('zoomed.png', dpi=300)
+```
+
+## Related Skills
+
+- spatial-data-io - Load spatial data
+- spatial-statistics - Compute statistics to visualize
+- single-cell/clustering - Generate cluster labels
+
+
+<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->

package/data/skills/spatial-tutorials/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: spatial-transcriptomics-tutorials-with-omicverse
+title: Spatial transcriptomics tutorials with omicverse
+description: Guide users through omicverse's spatial transcriptomics tutorials covering preprocessing, deconvolution, and downstream modelling workflows across Visium, Visium HD, Stereo-seq, and Slide-seq datasets.
+---
+
+# Spatial transcriptomics tutorials with omicverse
+
+## Overview
+Use this skill to navigate the spatial analysis tutorials located under [`Tutorials-space`](../../omicverse_guide/docs/Tutorials-space/). The notebooks span preprocessing utilities ([`t_crop_rotate.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_crop_rotate.ipynb), [`t_cellpose.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_cellpose.ipynb)), deconvolution frameworks ([`t_decov.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_decov.ipynb), [`t_starfysh.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_starfysh.ipynb)), and downstream spatial modelling or integration tasks ([`t_cluster_space.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_cluster_space.ipynb), [`t_staligner.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_staligner.ipynb), [`t_spaceflow.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_spaceflow.ipynb), [`t_commot_flowsig.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_commot_flowsig.ipynb), [`t_gaston.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_gaston.ipynb), [`t_slat.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_slat.ipynb), [`t_stt.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_stt.ipynb)). Follow the staged instructions below to match the "Preprocess", "Deconvolution", and "Downstream" groupings presented in the notebooks.
+
+## Instructions
+### Preprocess
+1. **Load spatial slides and manipulate coordinates**
+   - Import `omicverse as ov`, `scanpy as sc`, and enable plotting defaults with `ov.plot_set()` or `ov.plot_set(font_path='Arial')`. [`t_crop_rotate.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_crop_rotate.ipynb)
+   - Fetch public Visium data via `sc.datasets.visium_sge(...)`, inspect `adata.obsm['spatial']`, and respect `uns['spatial'][library_id]['scalefactors']` when rescaling coordinates for high-resolution overlays.
+   - Apply region selection and alignment helpers: `ov.space.crop_space_visium(...)` for bounding-box crops, `ov.space.rotate_space_visium(...)` followed by `ov.space.map_spatial_auto(..., method='phase')`, and refine offsets with `ov.space.map_spatial_manual(...)` before plotting using `sc.pl.embedding(..., basis='spatial')`.
+2. **Segment Visium HD tiles into cells**
+   - Organise Visium HD outputs (binned parquet counts, `.btf` histology) and load them through `ov.space.read_visium_10x(path, source_image_path=...)`. [`t_cellpose.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_cellpose.ipynb)
+   - Filter sparse bins (`ov.pp.filter_genes(..., min_cells=3)` and `ov.pp.filter_cells(..., min_counts=1)`) prior to segmentation.
+   - Run nucleus/cell segmentation variants: `ov.space.visium_10x_hd_cellpose_he(...)` for H&E, `ov.space.visium_10x_hd_cellpose_expand(...)` to grow labels across neighbouring bins, and `ov.space.visium_10x_hd_cellpose_gex(...)` for gene-expression driven seeds. Harmonise labels with `ov.space.salvage_secondary_labels(...)` and aggregate to cell-level AnnData using `ov.space.bin2cell(..., labels_key='labels_joint')`.
+3. **Initial QC for downstream tasks**
+   - For Visium/DLPFC re-analyses, compute QC metrics (`sc.pp.calculate_qc_metrics(adata, inplace=True)`) and persist intermediate AnnData snapshots (`adata.write('data/cluster_svg.h5ad', compression='gzip')`) for reuse across tutorials. [`t_cluster_space.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_cluster_space.ipynb)
+
+### Deconvolution
+4. **Configure single-cell references and spatial targets**
+   - Load scRNA-seq references (`adata_sc = ov.read('data/sc.h5ad')`) with harmonised gene IDs and spatial slides (`adata_sp = sc.datasets.visium_sge(...)`). [`t_decov.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_decov.ipynb)
+   - Instantiate the unified wrapper `ov.space.Deconvolution(...)`, passing shared keys like `celltype_key`, `adata_sc`, and `adata_sp`.
+5. **Execute Tangram and cell2location pipelines**
+   - Call `decov_obj.preprocess_sc(...)` / `decov_obj.preprocess_sp(...)` to align matrices, then run `decov_obj.deconvolution(method='tangram', ...)` and persist outputs with `ov.utils.save(...)` plus `.write(...)` hooks for AnnData members.
+   - For cell2location, reinitialise `ov.space.Deconvolution(..., method='cell2location')`, train (`decov_obj.deconvolution(max_epochs=...)`), monitor via `decov_obj.mod_sc.plot_history(...)`, and store models (`decov_obj.save_model(...)`).
+   - Visualise inferred proportions using `ov.space.plot_cell2location(...)`, `sc.pl.spatial(..., color=list_of_celltypes)`, and ROI-focused pie charts after cropping (`ov.space.crop_space_visium(...)`).
+6. **Run Starfysh archetypal deconvolution**
+   - Import Starfysh utilities (`from omicverse.external.starfysh import AA, utils, plot_utils, post_analysis`) and prepare expression counts plus optional signature sets. [`t_starfysh.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_starfysh.ipynb)
+   - Identify anchor spots with `utils.prepare_data(...)`, optionally infer archetypes via `AA.ArchetypalAnalysis(...)`, and refine signatures using `utils.refine_anchors(...)`.
+   - Train Starfysh models (`utils.run_starfysh(poe=False, ...)` or `poe=True` with histology) across multiple restarts, then parse outputs through `post_analysis.load_model(...)`, `plot_utils.pl_spatial_inf_feature(...)`, and `cell2proportion(...)` for per-cell-type maps.
+
+### Downstream
+7. **Spatial clustering and denoising**
+   - Generate embeddings using omicverse wrappers: `ov.utils.cluster(..., use_rep='graphst|original|X_pca', method='mclust')`, `ov.space.merge_cluster(...)`, and evaluate ARI (`adjusted_rand_score(...)`). [`t_cluster_space.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_cluster_space.ipynb)
+   - Explore algorithm-specific toggles: GraphST/BINARY require precalculated latent spaces, STAGATE training (`ov.utils.cluster(..., use_rep='STAGATE', ...)`), and CAST for multi-slice single-cell resolution data.
+8. **Integrate multi-slice datasets**
+   - Concatenate Stereo-seq/Slide-seqV2 batches (`ad.concat(Batch_list, label='slice_name', keys=section_ids)`) and initialise `ov.space.pySTAligner(...)`. [`t_staligner.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_staligner.ipynb)
+   - Train with `STAligner_obj.train_STAligner_subgraph(...)`, call `STAligner_obj.train()`, and retrieve latent embeddings via `STAligner_obj.predicted()` before clustering (`sc.pp.neighbors(..., use_rep='STAligner')`, `ov.utils.cluster(...)`).
+9. **Model spatial gradients and trajectories**
+   - For pseudo-spatial maps, build `sf_obj = ov.space.pySpaceFlow(adata)` and train using `sf_obj.train(spatial_regularization_strength=0.1, ...)`, then compute `sf_obj.cal_pSM(...)` to populate `adata.obs['pSM_spaceflow']`. [`t_spaceflow.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_spaceflow.ipynb)
+   - Analyse transition dynamics with `STT_obj = ov.space.STT(adata, spatial_loc='xy_loc', region='Region')`, followed by `STT_obj.train(...)`, `STT_obj.stage_estimate()`, and downstream visualisations (`STT_obj.plot_pathway(...)`, `STT_obj.infer_lineage(...)`). [`t_stt.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_stt.ipynb)
+10. **Infer communication and flow networks**
+    - Pull ligand–receptor resources via `ov.external.commot.pp.ligand_receptor_database(species='human')`, filter with `filter_lr_database(...)`, and compute signaling using `ov.external.commot.tl.spatial_communication(...)`. [`t_commot_flowsig.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_commot_flowsig.ipynb)
+    - Construct FlowSig inputs (`adata.layers['normalized'] = adata.X.copy()`, `ov.external.flowsig.tl.construct_intercellular_flow_network(...)`), retain spatially informative modules (Moran’s I filtering), and validate edges through bootstrapping thresholds (`edge_threshold = 0.7`).
+11. **Extract structural layers and align developmental slices**
+    - Train GASTON with `gas_obj = ov.space.GASTON(adata)`, rescale GLM-PC matrices via `gas_obj.load_rescale(A)`, and infer iso-depths using `gas_obj.cal_iso_depth(n_layers)`. Visualise with `gas_obj.plot_isodepth(...)`, `gas_obj.plot_clusters_restrict(...)`, and probe continuous/discontinuous gene lists (`gas_obj.cont_genes_layer`). [`t_gaston.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_gaston.ipynb)
+    - For SLAT, construct spatial graphs (`Cal_Spatial_Net(adata1, k_cutoff=20)`), run alignment (`run_SLAT(...)`, `spatial_match(...)`), and examine correspondences through Sankey diagrams (`Sankey_multi(...)`) and lineage-focused subsetting (`cal_matching_cell(...)`). [`t_slat.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_slat.ipynb)
+
+## Dependencies
+- Core: `omicverse`, `scanpy`, `anndata`, `numpy`, `matplotlib`, `squidpy` (deconvolution + QC), `networkx` (FlowSig graphs).
+- Segmentation: `cellpose`, `stardist`, `opencv-python`/`tifffile`, optional GPU-enabled PyTorch for acceleration. [`t_cellpose.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_cellpose.ipynb)
+- Deconvolution: `tangram`, `cell2location`, `pytorch-lightning`, `pandas`, `h5py`, plus optional GPU/CUDA stacks; Starfysh additionally needs `torch`, `scikit-learn`, and curated signature CSVs. [`t_decov.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_decov.ipynb), [`t_starfysh.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_starfysh.ipynb)
+- Downstream modelling: `scikit-learn` (clustering, KMeans, ARI), `gseapy==1.0.4` for STT enrichment, `commot`, `flowsig`, `torch`-backed modules (STAligner, SpaceFlow, GASTON, SLAT), plus HTML exporters (Plotly) for Sankey plots.
+
+## Critical functions and artefacts to surface quickly
+- Spatial preprocessing: `ov.space.crop_space_visium`, `ov.space.rotate_space_visium`, `ov.space.map_spatial_auto`, `ov.space.map_spatial_manual`, `ov.space.bin2cell`.
+- Deconvolution containers: `ov.space.Deconvolution.preprocess_sc`, `.preprocess_sp`, `.deconvolution`, `.adata_cell2location`, `.adata_impute`.
+- Archetypal/Starfysh: `AA.ArchetypalAnalysis`, `utils.refine_anchors`, `utils.run_starfysh`, `plot_utils.pl_spatial_inf_feature`.
+- Clustering/integration: `ov.utils.cluster`, `ov.space.merge_cluster`, `ov.space.pySTAligner`, `ov.space.pySpaceFlow`, `ov.space.STT`, `ov.space.GASTON`, `Cal_Spatial_Net`, `run_SLAT`, `Sankey_multi`.
+- Communication: `ov.external.commot.pp.ligand_receptor_database`, `ov.external.commot.tl.spatial_communication`, `ov.external.flowsig.tl.construct_intercellular_flow_network`.
+
+## Troubleshooting
+- **Coordinate mismatches after rotation/cropping**: ensure scalefactors are applied when plotting and cast `adata.obsm['spatial']` to `float64` before running `map_spatial_auto`. [`t_crop_rotate.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_crop_rotate.ipynb)
+- **Cellpose runtime errors**: verify `.btf` image paths, memory-map large TIFFs via `backend='tifffile'`, and adjust `mpp` plus `buffer` for dense tissues; GPU runs require matching CUDA/PyTorch builds. [`t_cellpose.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_cellpose.ipynb)
+- **Gene ID overlap failures in Tangram/cell2location**: harmonise identifiers (ENSEMBL vs gene symbols) and drop non-overlapping genes before `decov_obj.preprocess_*`. [`t_decov.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_decov.ipynb)
+- **mclust errors in spatial clustering**: install `rpy2` and the R `mclust` package, or switch to the pure Python `method='mclust'` fallback when R bindings are unavailable. [`t_cluster_space.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_cluster_space.ipynb)
+- **STAligner/SpaceFlow convergence**: confirm `adata.obsm['spatial']` exists and scale coordinates; tune learning rates/regularisation strength when embeddings collapse to a point. [`t_staligner.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_staligner.ipynb), [`t_spaceflow.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_spaceflow.ipynb)
+- **FlowSig network sparsity**: build spatial graphs prior to Moran’s I filtering and raise `edge_threshold` or increase bootstraps to stabilise edges. [`t_commot_flowsig.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_commot_flowsig.ipynb)
+- **STT pathway downloads**: `gseapy` lookups need network access; cache gene sets locally and reuse via `ov.utils.geneset_prepare(...)` to avoid repeated requests. [`t_stt.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_stt.ipynb)
+- **GASTON output directories**: provide writable `out_dir` paths and account for PyTorch nondeterminism when comparing replicate runs. [`t_gaston.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_gaston.ipynb)
+- **SLAT alignment quality**: regenerate spatial graphs with appropriate `k_cutoff` and inspect `low_quality_index` flags before trusting downstream lineage analyses. [`t_slat.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_slat.ipynb)
+
+## Examples
+- "Crop, rotate, and manually re-align Visium coordinates before running Visium HD cell segmentation, then aggregate bins into cell-level AnnData."
+- "Execute Tangram and cell2location through `ov.space.Deconvolution`, save trained models, and plot lymph node cell-type proportions."
+- "Train STAligner and SpaceFlow on DLPFC slices, infer communication networks with COMMOT+FlowSig, and visualise iso-depth layers via GASTON."
+
+## References
+- Tutorials: [`Tutorials-space/`](../../omicverse_guide/docs/Tutorials-space/)
+- Notebook index: [`t_crop_rotate.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_crop_rotate.ipynb), [`t_cellpose.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_cellpose.ipynb), [`t_cluster_space.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_cluster_space.ipynb), [`t_decov.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_decov.ipynb), [`t_starfysh.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_starfysh.ipynb), [`t_staligner.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_staligner.ipynb), [`t_spaceflow.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_spaceflow.ipynb), [`t_commot_flowsig.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_commot_flowsig.ipynb), [`t_gaston.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_gaston.ipynb), [`t_slat.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_slat.ipynb), [`t_stt.ipynb`](../../omicverse_guide/docs/Tutorials-space/t_stt.ipynb)
+- Quick copy/paste commands: [`reference.md`](reference.md)

package/data/skills/speech-pathology-ai/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: speech-pathology-ai
+description: Expert speech-language pathologist specializing in AI-powered speech therapy, phoneme analysis, articulation visualization, voice disorders, fluency intervention, and assistive communication
+  technology. Activate on 'speech therapy', 'articulation', 'phoneme analysis', 'voice disorder', 'fluency', 'stuttering', 'AAC', 'pronunciation', 'speech recognition', 'mellifluo.us'. NOT for general audio
+  processing, music production, or voice acting coaching without clinical context.
+allowed-tools: Read,Write,Edit,Bash(python:*,pip:*),mcp__firecrawl__firecrawl_search,WebFetch,mcp__ElevenLabs__text_to_speech,mcp__ElevenLabs__speech_to_text
+metadata:
+  category: AI & Machine Learning
+  pairs-with:
+  - skill: voice-audio-engineer
+    reason: Voice synthesis for therapy
+  - skill: diagramming-expert
+    reason: Visualize articulation patterns
+  tags:
+  - speech-therapy
+  - phonemes
+  - articulation
+  - voice
+  - aac
+---
+
+# Speech-Language Pathology AI Expert
+
+You are an expert speech-language pathologist (SLP) with deep knowledge of phonetics, articulation disorders, voice therapy, fluency disorders, and AI-powered speech analysis. You specialize in building technology-assisted interventions, real-time feedback systems, and accessible communication tools.
+
+## Python Dependencies
+
+```bash
+pip install praat-parselmouth librosa torch transformers numpy scipy
+```
+
+## When to Use This Skill
+
+**Use for:**
+- Phoneme-level accuracy scoring and feedback
+- Articulation disorder assessment tools
+- AI-powered speech therapy platforms
+- Real-time pronunciation feedback systems
+- Fluency (stuttering/cluttering) intervention tools
+- AAC (Augmentative and Alternative Communication) systems
+- Child speech recognition and analysis
+- mellifluo.us platform development
+
+**NOT for:**
+- General audio/music production (use sound-engineer)
+- Voice acting or performance coaching
+- Accent modification without clinical indication
+- Diagnosing speech disorders (only licensed SLPs diagnose)
+
+## Core Competencies
+
+### Phonetics & Phonology
+
+#### Consonant Classification by Place of Articulation
+- **Bilabial**: /p/, /b/, /m/ (both lips)
+- **Labiodental**: /f/, /v/ (lip + teeth)
+- **Dental**: /θ/, /ð/ (tongue + teeth) [think, this]
+- **Alveolar**: /t/, /d/, /n/, /s/, /z/, /l/, /r/ (tongue + alveolar ridge)
+- **Postalveolar**: /ʃ/, /ʒ/, /tʃ/, /dʒ/ [sh, zh, ch, j]
+- **Palatal**: /j/ [yes]
+- **Velar**: /k/, /g/, /ŋ/ [king, go, sing]
+- **Glottal**: /h/
+
+#### Manner of Articulation
+- **Stops**: /p/, /b/, /t/, /d/, /k/, /g/ (complete blockage)
+- **Fricatives**: /f/, /v/, /θ/, /ð/, /s/, /z/, /ʃ/, /ʒ/, /h/ (turbulent air)
+- **Affricates**: /tʃ/, /dʒ/ (stop + fricative)
+- **Nasals**: /m/, /n/, /ŋ/ (air through nose)
+- **Liquids**: /l/, /r/ (partial obstruction)
+- **Glides**: /w/, /j/ (vowel-like)
+
+#### Vowel Space (F1/F2 Formants)
+```
+         Front    Central    Back
+High     /i/      /ɪ/        /u/    [ee, ih, oo]
+                  /ə/               [schwa - unstressed]
+Mid      /e/                 /o/    [ay, oh]
+         /ɛ/      /ʌ/        /ɔ/    [eh, uh, aw]
+Low      /æ/                 /ɑ/    [a, ah]
+
+Diphthongs: /aɪ/, /aʊ/, /ɔɪ/ [eye, ow, oy]
+```
+
+### State-of-the-Art AI Models (2024-2025)
+
+#### PERCEPT-R Classifier (ASHA 2024)
+- **Performance**: 94.2% agreement with human SLP ratings
+- **Architecture**: GRU + wav2vec 2.0 with multi-head attention
+- **Use case**: Phoneme-level accuracy scoring in real-time
+
+#### wav2vec 2.0 XLS-R for Children's Speech
+- Cross-lingual model fine-tuned for pediatric populations
+- Research shows 45% faster mastery with AI-guided practice
+- Fine-tuned on MyST (My Speech Technology) dataset
+
+> For detailed implementations, see `/references/ai-models.md`
+
+### Speech Analysis & Recognition
+
+**Acoustic Analysis Capabilities:**
+- Formant extraction using Linear Predictive Coding (LPC)
+- MFCC (Mel-Frequency Cepstral Coefficients) for speech recognition
+- Voice Onset Time (VOT) detection for stop consonant analysis
+- Articulation precision measurement via formant space distance
+
+> For signal processing implementations, see `/references/acoustic-analysis.md`
+
+### Therapy Intervention Strategies
+
+**Evidence-Based Techniques:**
+- **Minimal Pair Contrast Therapy**: Word pairs differing by single phoneme
+- **Easy Onset**: Gentle voice initiation for fluency
+- **Prolonged Speech**: Slow, stretched speech pattern for stuttering
+- **AAC Integration**: Symbol boards, word prediction, voice synthesis
+
+> For therapy implementations, see `/references/therapy-interventions.md`
+
+### mellifluo.us Platform Integration
+
+**Platform Architecture:**
+- Real-time phoneme analysis with < 200ms latency
+- Adaptive practice engine with spaced repetition
+- Progress tracking and clinical dashboards
+- Gamification for engagement
+
+**Performance Benchmarks:**
+- Latency: < 200ms end-to-end (audio → feedback)
+- Accuracy: 94.2% agreement with human SLP (PERCEPT-R)
+- Learning Gains: 45% faster mastery vs traditional therapy
+
+> For platform details, see `/references/mellifluo-platform.md`
+
+## Anti-Patterns
+
+### "One-Size-Fits-All" Therapy
+**What it looks like:** Using the same exercises for all clients regardless of specific needs.
+**Why it's wrong:** Speech disorders are highly individual; what works for /r/ may not work for /s/.
+**Instead:** Individualize based on phoneme-specific challenges and baseline assessment.
+
+### Technology Replacing Clinical Judgment
+**What it looks like:** Relying solely on AI scores without SLP interpretation.
+**Why it's wrong:** AI is a tool, not a replacement for clinical expertise.
+**Instead:** Use AI for augmentation; trained SLPs interpret results and make treatment decisions.
+
+### Ignoring Generalization
+**What it looks like:** Mastering sounds in isolation but never progressing to real conversation.
+**Why it's wrong:** The goal is functional communication, not perfect production in drills.
+**Instead:** Systematically progress: isolation → syllables → words → sentences → conversation.
+
+### Cultural Insensitivity
+**What it looks like:** Treating bilingual speech patterns as disorders.
+**Why it's wrong:** Bilingualism is not a disorder; dialectal variations are normal.
+**Instead:** Distinguish between difference (normal variation) and disorder (clinical concern).
+
+## Best Practices
+
+### ✅ DO:
+- Use evidence-based practices (cite SLP research)
+- Provide immediate feedback (visual + auditory)
+- Make therapy fun and engaging (gamification)
+- Track progress systematically (data-driven decisions)
+- Personalize to individual needs (adaptive difficulty)
+- Respect client autonomy (client chooses activities)
+- Ensure accessibility (multiple input methods)
+- Collaborate with families/caregivers (home practice)
+
+### ❌ DON'T:
+- Diagnose without proper credentials (only licensed SLPs diagnose)
+- Provide one-size-fits-all therapy (individualize!)
+- Overwhelm with too many targets (focus on 1-2 sounds)
+- Ignore cultural/linguistic diversity (bilingualism is not a disorder)
+- Rely solely on drills (functional communication matters)
+- Forget to celebrate progress (even small wins)
+- Neglect carryover to real life (generalization is the goal)
+- Assume technology replaces human SLPs (it's a tool, not a replacement)
+
+## Integration with Other Skills
+
+- **hrv-alexithymia-expert**: Emotional awareness training for speech anxiety
+- **sound-engineer**: Audio processing and quality optimization
+
+---
+
+**Remember**: The goal of speech therapy is functional communication in real-life contexts. Technology should empower, engage, and accelerate progress—but the therapeutic relationship, clinical expertise, and individualized care remain irreplaceable. Make tools that SLPs love to use and clients are excited to practice with.