@bgicli/bgicli 2.1.1 → 2.2.0

package/data/skills/spatial-transcriptomics-analysis/STAgent/SKILL.md

@@ -0,0 +1,75 @@
+<!--
+# 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: spatial-transcriptomics-agent
+description: Spatial analyst
+keywords:
+  - spatial
+  - h5ad
+  - H&E
+  - clustering
+  - SVG
+measurable_outcome: For each sample, deliver ≥1 spatial domain map + SVG list + narrative interpretation within 30 minutes.
+license: MIT
+metadata:
+  author: LiuLab
+  version: "1.0.0"
+compatibility:
+  - system: Python 3.9+
+allowed-tools:
+  - run_shell_command
+  - read_file
+  - web_fetch
+---
+
+# Spatial Transcriptomics Agent
+
+Run STAgent to align histology images with expression matrices, perform clustering/SVG detection, and generate literature-backed spatial reports.
+
+## When to Use
+- Analysis of Visium/Xenium or similar ST datasets.
+- Visual reasoning over spatial plots, H&E images, or cluster maps.
+- Automatically generating Scanpy/Squidpy code for new ST workflows.
+- Hypothesis generation about spatial gene expression patterns.
+
+## Core Capabilities
+1. **Dynamic code generation:** Create/execute Python scripts for QC, clustering, SVG detection.
+2. **Visual reasoning:** Interpret spatial plots to identify tissue domains and cell neighborhoods.
+3. **Literature retrieval:** Pull references that contextualize findings.
+4. **Report generation:** Deliver publication-style writeups with plots and SVG tables.
+
+## Workflow
+1. **Env setup:** `conda env create -f environment.yml && conda activate STAgent`.
+2. **Data prep:** Supply `expression_path` (`.h5ad`/Spaceranger) + `image_path` (H&E/IF) and metadata.
+3. **Task selection:** Choose tasks such as `cluster`, `find_svg`, `annotate_domains`, or composite instructions; run `python repo/src/main.py --data_path ... --task "..."`.
+4. **Execute & interpret:** Let STAgent generate scripts, run analyses, and interpret results with literature references.
+5. **Package outputs:** Save UMAP/spatial plots, SVG tables, QC details, and summary markdown.
+
+## Example Usage
+```text
+User: "Analyze this breast cancer ST dataset, find immune infiltrates."
+Agent: loads data, runs `sqidpy.gr.spatial_neighbors`, computes Leiden clusters, plots marker genes (CD3D, CD19), and summarizes which clusters map to tumor core vs. stromal/immune zones.
+```
+
+## Guardrails
+- Document coordinate systems and any scaling between imaging and expression coordinates.
+- Avoid definitive cell-type labels without supporting markers.
+- Capture QC parameters for reproducibility.
+
+## References
+- Source repo: https://github.com/LiuLab-Bioelectronics-Harvard/STAgent
+- See local `README.md` for detailed instructions.
+
+
+<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->

package/data/skills/spatial-transcriptomics-analysis/SpatialAgent/SKILL.md

@@ -0,0 +1,56 @@
+<!--
+# 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: 'spatial-agent'
+description: 'An agent that interprets spatial transcriptomics data to propose mechanistic hypotheses and analyze tissue organization.'
+measurable_outcome: Execute skill workflow successfully with valid output within 15 minutes.
+allowed-tools:
+  - read_file
+  - run_shell_command
+---
+
+
+# SpatialAgent
+
+SpatialAgent focuses on the biological interpretation of spatial transcriptomics data, specifically aiming to propose mechanistic hypotheses about tissue organization and cellular interactions.
+
+## When to Use This Skill
+
+*   **Mechanistic Interpretation**: When you have clusters or spatial domains and need to understand *why* they are organized that way.
+*   **Cell-Cell Interaction**: To predict and interpret ligand-receptor interactions in a spatial context.
+*   **Hypothesis Generation**: To propose biological mechanisms driving the observed spatial heterogeneity.
+
+## Core Capabilities
+
+1.  **Tissue Organization Analysis**: Decodes the structural logic of tissues (e.g., layers, niches).
+2.  **Cellular Interaction Prediction**: Identifies potential signaling pathways active at domain boundaries.
+3.  **Hypothesis Proposal**: Generates testable biological hypotheses based on spatial data.
+
+## Workflow
+
+1.  **Input Analysis**: Accepts processed ST data (e.g., cluster annotations, DEG lists per spatial domain).
+2.  **Knowledge Retrieval**: Queries biological knowledge bases regarding the observed cell types and genes.
+3.  **Synthesis**: Constructs a narrative explaining the spatial arrangement (e.g., "The proximity of fibroblasts and tumor cells suggests a desmoplastic reaction mediated by TGF-beta signaling...").
+
+## Example Usage
+
+**User**: "Why are the macrophages located at the boundary of the tumor core in this sample?"
+
+**Agent Action**:
+1.  Analyzes the gene expression of macrophages and adjacent tumor cells.
+2.  Checks for ligand-receptor pairs (e.g., CSF1-CSF1R).
+3.  Proposes: "Macrophages are likely recruited by CSF1 secreted by the tumor cells, forming an immunosuppressive barrier..."
+
+
+<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->

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

@@ -0,0 +1,266 @@
+<!--
+# 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-image-analysis
+description: Process and analyze tissue images from spatial transcriptomics data using Squidpy. Extract image features, segment cells/nuclei, and compute morphological features from H&E or IF images. Use when processing tissue images for spatial transcriptomics.
+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
+---
+
+# Image Analysis for Spatial Transcriptomics
+
+Extract features and segment tissue images in spatial transcriptomics data.
+
+## Required Imports
+
+```python
+import squidpy as sq
+import scanpy as sc
+import numpy as np
+import matplotlib.pyplot as plt
+from skimage import io, filters, segmentation
+```
+
+## Access Tissue Images
+
+```python
+# Get image from Visium data
+library_id = list(adata.uns['spatial'].keys())[0]
+img_dict = adata.uns['spatial'][library_id]['images']
+
+# High and low resolution images
+hires = img_dict['hires']
+lowres = img_dict['lowres']
+
+print(f'Hires shape: {hires.shape}')
+print(f'Lowres shape: {lowres.shape}')
+
+# Get scale factors
+scalef = adata.uns['spatial'][library_id]['scalefactors']
+spot_diameter = scalef['spot_diameter_fullres']
+hires_scale = scalef['tissue_hires_scalef']
+```
+
+## Create ImageContainer
+
+```python
+# Squidpy's ImageContainer for organized image handling
+img = sq.im.ImageContainer(adata.uns['spatial'][library_id]['images']['hires'])
+print(img)
+
+# Or load from file
+img = sq.im.ImageContainer('tissue_image.tif')
+
+# Access the image array
+arr = img['image'].values
+```
+
+## Extract Image Features per Spot
+
+```python
+# Calculate image features for each spot
+sq.im.calculate_image_features(
+    adata,
+    img,
+    features=['summary', 'histogram', 'texture'],
+    key_added='img_features',
+    spot_scale=1.0,  # Fraction of spot diameter
+    n_jobs=4,
+)
+
+# Features stored in adata.obsm['img_features']
+print(f"Image features shape: {adata.obsm['img_features'].shape}")
+```
+
+## Available Image Features
+
+```python
+# Summary statistics
+sq.im.calculate_image_features(adata, img, features='summary')
+# Mean, std, etc. per channel
+
+# Histogram features
+sq.im.calculate_image_features(adata, img, features='histogram', features_kwargs={'histogram': {'bins': 16}})
+# Intensity distribution
+
+# Texture features (GLCM)
+sq.im.calculate_image_features(adata, img, features='texture')
+# Contrast, homogeneity, correlation, ASM
+
+# Custom features
+sq.im.calculate_image_features(
+    adata, img,
+    features=['summary', 'texture'],
+    features_kwargs={
+        'summary': {'quantiles': [0.1, 0.5, 0.9]},
+        'texture': {'distances': [1, 2], 'angles': [0, np.pi/4, np.pi/2]},
+    }
+)
+```
+
+## Segment Cells/Nuclei
+
+```python
+# Segment using watershed
+sq.im.segment(
+    img,
+    layer='image',
+    method='watershed',
+    channel=0,  # Use first channel
+    thresh=0.5,
+)
+
+# Access segmentation mask
+seg_mask = img['segmented_watershed'].values
+```
+
+## Segment with Cellpose
+
+```python
+# Cellpose provides better cell segmentation
+from cellpose import models
+
+# Load model
+model = models.Cellpose(model_type='nuclei')
+
+# Get image array
+image = img['image'].values[:, :, 0]  # Single channel
+
+# Segment
+masks, flows, styles, diams = model.eval(image, diameter=30, channels=[0, 0])
+
+# Add to ImageContainer
+img.add_img(masks, layer='cellpose_masks')
+```
+
+## Extract Spot Image Crops
+
+```python
+# Get image crop around each spot
+def get_spot_crop(adata, img_arr, spot_idx, crop_size=100):
+    coords = adata.obsm['spatial'][spot_idx]
+    scalef = adata.uns['spatial'][library_id]['scalefactors']['tissue_hires_scalef']
+
+    x, y = int(coords[0] * scalef), int(coords[1] * scalef)
+    half = crop_size // 2
+
+    crop = img_arr[max(0, y-half):y+half, max(0, x-half):x+half]
+    return crop
+
+# Get crop for spot 0
+crop = get_spot_crop(adata, hires, 0)
+plt.imshow(crop)
+```
+
+## Color Deconvolution (H&E)
+
+```python
+from skimage.color import rgb2hed, hed2rgb
+
+# Separate H&E stains
+hed = rgb2hed(hires)
+hematoxylin = hed[:, :, 0]
+eosin = hed[:, :, 1]
+dab = hed[:, :, 2]
+
+# Visualize
+fig, axes = plt.subplots(1, 3, figsize=(15, 5))
+axes[0].imshow(hematoxylin, cmap='gray')
+axes[0].set_title('Hematoxylin')
+axes[1].imshow(eosin, cmap='gray')
+axes[1].set_title('Eosin')
+axes[2].imshow(hires)
+axes[2].set_title('Original')
+plt.tight_layout()
+```
+
+## Compute Morphological Features
+
+```python
+from skimage.measure import regionprops_table
+
+# Get properties from segmentation
+props = regionprops_table(
+    seg_mask,
+    intensity_image=hires[:, :, 0],
+    properties=['label', 'area', 'eccentricity', 'solidity', 'mean_intensity']
+)
+
+import pandas as pd
+morph_df = pd.DataFrame(props)
+print(morph_df.describe())
+```
+
+## Use Image Features for Clustering
+
+```python
+# Combine expression and image features
+import numpy as np
+
+# Get expression PCA
+expr_pca = adata.obsm['X_pca'][:, :20]
+
+# Get image features
+img_features = adata.obsm['img_features']
+
+# Scale and combine
+from sklearn.preprocessing import StandardScaler
+expr_scaled = StandardScaler().fit_transform(expr_pca)
+img_scaled = StandardScaler().fit_transform(img_features)
+
+# Weight combination
+alpha = 0.3  # Image weight
+combined = np.hstack([
+    (1 - alpha) * expr_scaled,
+    alpha * img_scaled
+])
+
+adata.obsm['X_combined'] = combined
+
+# Cluster on combined features
+sc.pp.neighbors(adata, use_rep='X_combined')
+sc.tl.leiden(adata, key_added='combined_leiden')
+```
+
+## Smooth Expression with Image
+
+```python
+# Use image similarity to smooth expression
+from scipy.spatial.distance import cdist
+
+# Compute image similarity matrix
+img_features = adata.obsm['img_features']
+img_sim = 1 / (1 + cdist(img_features, img_features, metric='euclidean'))
+
+# Normalize
+img_sim = img_sim / img_sim.sum(axis=1, keepdims=True)
+
+# Smooth expression
+X_smoothed = img_sim @ adata.X
+
+adata.layers['img_smoothed'] = X_smoothed
+```
+
+## Related Skills
+
+- spatial-data-io - Load spatial data with images
+- spatial-visualization - Visualize images with expression
+- spatial-domains - Use image features for domain detection
+
+
+<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->

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

@@ -0,0 +1,287 @@
+<!--
+# 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-communication
+description: Analyze cell-cell communication in spatial transcriptomics data using ligand-receptor analysis with Squidpy. Infer intercellular signaling, identify communication pathways, and visualize interaction networks. Use when analyzing cell-cell communication in spatial context.
+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 Cell-Cell Communication
+
+Analyze ligand-receptor interactions and cell-cell communication in spatial data.
+
+## Required Imports
+
+```python
+import squidpy as sq
+import scanpy as sc
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+```
+
+## Ligand-Receptor Analysis with Squidpy
+
+```python
+# Requires clustered data with cell type annotations
+adata = sc.read_h5ad('clustered_spatial.h5ad')
+
+# Build spatial neighbors if not already done
+sq.gr.spatial_neighbors(adata, coord_type='generic', n_neighs=6)
+
+# Run ligand-receptor analysis
+sq.gr.ligrec(
+    adata,
+    cluster_key='cell_type',  # Column with cell type annotations
+    n_perms=100,  # Permutations for significance testing
+    threshold=0.01,  # P-value threshold
+    copy=False,
+)
+
+# Results stored in adata.uns['cell_type_ligrec']
+```
+
+## Access Ligand-Receptor Results
+
+```python
+# Get results dictionary
+ligrec_results = adata.uns['cell_type_ligrec']
+
+# Access different result components
+means = ligrec_results['means']  # Mean expression
+pvalues = ligrec_results['pvalues']  # P-values from permutation test
+metadata = ligrec_results['metadata']  # Ligand-receptor pair annotations
+
+print(f'Tested {len(means.columns)} ligand-receptor pairs')
+print(f'Cell type combinations: {len(means.index)}')
+```
+
+## Filter Significant Interactions
+
+```python
+# Get significant interactions
+pval_threshold = 0.05
+
+# Flatten results to DataFrame
+interactions = []
+for source_target in pvalues.index:
+    for lr_pair in pvalues.columns:
+        pval = pvalues.loc[source_target, lr_pair]
+        mean_expr = means.loc[source_target, lr_pair]
+        if pval < pval_threshold and not np.isnan(mean_expr):
+            source, target = source_target
+            ligand, receptor = lr_pair
+            interactions.append({
+                'source': source,
+                'target': target,
+                'ligand': ligand,
+                'receptor': receptor,
+                'mean': mean_expr,
+                'pvalue': pval,
+            })
+
+interactions_df = pd.DataFrame(interactions)
+print(f'Significant interactions: {len(interactions_df)}')
+print(interactions_df.head(10))
+```
+
+## Visualize Ligand-Receptor Results
+
+```python
+# Dot plot of top interactions
+sq.pl.ligrec(
+    adata,
+    cluster_key='cell_type',
+    source_groups=['Macrophage', 'T_cell'],  # Filter source cell types
+    target_groups=['Epithelial', 'Fibroblast'],  # Filter target cell types
+    pvalue_threshold=0.05,
+    remove_empty_interactions=True,
+)
+```
+
+## Specific Ligand-Receptor Pairs
+
+```python
+# Analyze specific pairs of interest
+pairs_of_interest = [
+    ('CD40LG', 'CD40'),
+    ('TGFB1', 'TGFBR1'),
+    ('CCL2', 'CCR2'),
+]
+
+sq.pl.ligrec(
+    adata,
+    cluster_key='cell_type',
+    means_range=(0.5, 5),  # Filter by expression level
+    pvalue_threshold=0.01,
+)
+```
+
+## Custom Ligand-Receptor Database
+
+```python
+# Use custom ligand-receptor pairs
+custom_pairs = pd.DataFrame({
+    'ligand': ['GENE1', 'GENE2', 'GENE3'],
+    'receptor': ['GENE4', 'GENE5', 'GENE6'],
+})
+
+sq.gr.ligrec(
+    adata,
+    cluster_key='cell_type',
+    interactions=custom_pairs,
+    n_perms=100,
+)
+```
+
+## Interaction Heatmap
+
+```python
+# Create heatmap of interaction counts per cell type pair
+def count_interactions_per_pair(pvalues, threshold=0.05):
+    counts = {}
+    for source_target in pvalues.index:
+        sig_count = (pvalues.loc[source_target] < threshold).sum()
+        counts[source_target] = sig_count
+    return counts
+
+counts = count_interactions_per_pair(pvalues)
+
+# Convert to matrix
+cell_types = adata.obs['cell_type'].unique()
+count_matrix = pd.DataFrame(0, index=cell_types, columns=cell_types)
+for (source, target), count in counts.items():
+    count_matrix.loc[source, target] = count
+
+plt.figure(figsize=(8, 8))
+plt.imshow(count_matrix.values, cmap='Reds')
+plt.xticks(range(len(cell_types)), cell_types, rotation=45, ha='right')
+plt.yticks(range(len(cell_types)), cell_types)
+plt.colorbar(label='Number of significant interactions')
+plt.title('Cell-cell communication strength')
+plt.tight_layout()
+plt.savefig('interaction_heatmap.png', dpi=150)
+```
+
+## Network Visualization
+
+```python
+import networkx as nx
+
+# Build interaction network
+G = nx.DiGraph()
+
+# Add nodes (cell types)
+for ct in adata.obs['cell_type'].unique():
+    G.add_node(ct)
+
+# Add edges (interactions)
+for _, row in interactions_df.iterrows():
+    if G.has_edge(row['source'], row['target']):
+        G[row['source']][row['target']]['weight'] += 1
+    else:
+        G.add_edge(row['source'], row['target'], weight=1)
+
+# Draw network
+pos = nx.spring_layout(G, k=2, seed=42)
+weights = [G[u][v]['weight'] for u, v in G.edges()]
+
+plt.figure(figsize=(10, 10))
+nx.draw_networkx_nodes(G, pos, node_size=1000, node_color='lightblue')
+nx.draw_networkx_labels(G, pos, font_size=10)
+nx.draw_networkx_edges(G, pos, width=[w/max(weights)*5 for w in weights],
+                        edge_color='gray', arrows=True, arrowsize=20)
+plt.title('Cell-cell communication network')
+plt.axis('off')
+plt.savefig('communication_network.png', dpi=150)
+```
+
+## Spatial Visualization of Communication
+
+```python
+# Visualize ligand and receptor expression spatially
+ligand = 'CCL2'
+receptor = 'CCR2'
+
+fig, axes = plt.subplots(1, 3, figsize=(15, 5))
+
+# Ligand expression
+sc.pl.spatial(adata, color=ligand, ax=axes[0], show=False, title=f'{ligand} (ligand)')
+
+# Receptor expression
+sc.pl.spatial(adata, color=receptor, ax=axes[1], show=False, title=f'{receptor} (receptor)')
+
+# Cell types
+sc.pl.spatial(adata, color='cell_type', ax=axes[2], show=False, title='Cell types')
+
+plt.tight_layout()
+plt.savefig('ligand_receptor_spatial.png', dpi=150)
+```
+
+## Compare Communication Between Conditions
+
+```python
+# Run separately for each condition
+for condition in adata.obs['condition'].unique():
+    adata_cond = adata[adata.obs['condition'] == condition].copy()
+    sq.gr.spatial_neighbors(adata_cond, coord_type='generic', n_neighs=6)
+    sq.gr.ligrec(adata_cond, cluster_key='cell_type', n_perms=100)
+    adata_cond.uns[f'ligrec_{condition}'] = adata_cond.uns['cell_type_ligrec']
+
+# Compare interaction counts
+for condition in ['control', 'treated']:
+    results = adata.uns[f'ligrec_{condition}']
+    n_sig = (results['pvalues'] < 0.05).sum().sum()
+    print(f'{condition}: {n_sig} significant interactions')
+```
+
+## Pathway Enrichment of Communication Partners
+
+```python
+# Get genes involved in significant interactions
+ligands = interactions_df['ligand'].unique()
+receptors = interactions_df['receptor'].unique()
+comm_genes = list(set(ligands) | set(receptors))
+
+print(f'Genes involved in communication: {len(comm_genes)}')
+
+# Use for pathway enrichment with pathway-analysis skills
+# genes_for_enrichment = comm_genes
+```
+
+## Export Results
+
+```python
+# Save significant interactions
+interactions_df.to_csv('significant_interactions.csv', index=False)
+
+# Save as edge list for network tools
+edges = interactions_df[['source', 'target', 'ligand', 'receptor', 'mean', 'pvalue']]
+edges.to_csv('communication_edges.csv', index=False)
+```
+
+## Related Skills
+
+- spatial-neighbors - Build spatial graphs (prerequisite)
+- spatial-domains - Identify cell types for communication analysis
+- pathway-analysis - Enrich communication genes for pathways
+- single-cell/markers-annotation - Annotate cell types
+
+
+<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->