@bgicli/bgicli 2.1.1 → 2.2.0

package/data/skills/bio-imaging-mass-cytometry-quality-metrics/SKILL.md

@@ -0,0 +1,316 @@
+---
+name: bio-imaging-mass-cytometry-quality-metrics
+description: Quality metrics for IMC data including signal-to-noise, channel correlation, tissue integrity, and acquisition QC. Use when assessing data quality before analysis or troubleshooting problematic acquisitions.
+tool_type: python
+primary_tool: numpy
+---
+
+## Version Compatibility
+
+Reference examples tested with: matplotlib 3.8+, numpy 1.26+, pandas 2.2+, scipy 1.12+
+
+Before using code patterns, verify installed versions match. If versions differ:
+- Python: `pip show <package>` then `help(module.function)` to check signatures
+
+If code throws ImportError, AttributeError, or TypeError, introspect the installed
+package and adapt the example to match the actual API rather than retrying.
+
+# Quality Metrics
+
+**"Assess quality of my IMC acquisition"** → Evaluate IMC data quality through signal-to-noise ratios, channel correlations, tissue integrity scores, and acquisition-specific QC metrics.
+- Python: `numpy`/`scipy` for SNR calculation and channel correlation analysis
+
+## Signal-to-Noise Ratio
+
+```python
+import numpy as np
+from scipy import ndimage
+from skimage import io
+
+def calculate_snr(image, mask=None):
+    '''Calculate signal-to-noise ratio for an image channel.'''
+    if mask is None:
+        mask = image > np.percentile(image, 10)
+
+    signal = np.mean(image[mask])
+    noise = np.std(image[~mask])
+
+    if noise == 0:
+        return np.inf
+
+    snr = signal / noise
+    return snr
+
+def calculate_snr_all_channels(image_stack, channel_names, tissue_mask=None):
+    '''Calculate SNR for all channels in stack.'''
+    results = {}
+    for i, name in enumerate(channel_names):
+        snr = calculate_snr(image_stack[i], tissue_mask)
+        results[name] = snr
+    return results
+
+image_stack = io.imread('imc_image.tiff')
+channel_names = ['CD45', 'CD3', 'CD68', 'panCK', 'DNA']
+snr_values = calculate_snr_all_channels(image_stack, channel_names)
+
+for ch, snr in snr_values.items():
+    status = 'PASS' if snr > 3 else 'WARN' if snr > 1.5 else 'FAIL'
+    print(f'{ch}: SNR = {snr:.2f} [{status}]')
+```
+
+## Channel Correlation
+
+```python
+def calculate_channel_correlation(image_stack, channel_names):
+    '''Calculate pairwise correlation between channels.'''
+    n_channels = image_stack.shape[0]
+    flat_data = image_stack.reshape(n_channels, -1)
+
+    corr_matrix = np.corrcoef(flat_data)
+
+    import pandas as pd
+    corr_df = pd.DataFrame(corr_matrix, index=channel_names, columns=channel_names)
+    return corr_df
+
+def flag_unexpected_correlations(corr_df, expected_pairs=None, threshold=0.7):
+    '''Flag unexpected high correlations (possible spillover).'''
+    issues = []
+
+    if expected_pairs is None:
+        expected_pairs = []
+
+    for i, ch1 in enumerate(corr_df.columns):
+        for j, ch2 in enumerate(corr_df.columns):
+            if i >= j:
+                continue
+
+            corr = corr_df.loc[ch1, ch2]
+            pair = (ch1, ch2)
+            is_expected = pair in expected_pairs or (ch2, ch1) in expected_pairs
+
+            if corr > threshold and not is_expected:
+                issues.append({'channel_1': ch1, 'channel_2': ch2, 'correlation': corr, 'expected': is_expected})
+
+    return pd.DataFrame(issues)
+
+corr_matrix = calculate_channel_correlation(image_stack, channel_names)
+print('Channel correlations:')
+print(corr_matrix.round(2))
+
+expected = [('CD3', 'CD45')]
+issues = flag_unexpected_correlations(corr_matrix, expected)
+if len(issues) > 0:
+    print('\nUnexpected high correlations:')
+    print(issues)
+```
+
+## Tissue Integrity
+
+```python
+def assess_tissue_integrity(dna_channel, min_coverage=0.3):
+    '''Assess tissue coverage and integrity from DNA channel.'''
+    threshold = np.percentile(dna_channel, 50)
+    tissue_mask = dna_channel > threshold
+
+    total_pixels = dna_channel.size
+    tissue_pixels = np.sum(tissue_mask)
+    coverage = tissue_pixels / total_pixels
+
+    labeled, n_fragments = ndimage.label(tissue_mask)
+    fragment_sizes = ndimage.sum(tissue_mask, labeled, range(1, n_fragments + 1))
+
+    largest_fragment = np.max(fragment_sizes) if len(fragment_sizes) > 0 else 0
+    fragmentation = 1 - (largest_fragment / tissue_pixels) if tissue_pixels > 0 else 1
+
+    return {
+        'coverage': coverage,
+        'n_fragments': n_fragments,
+        'fragmentation': fragmentation,
+        'intact': coverage > min_coverage and fragmentation < 0.5
+    }
+
+dna_channel = image_stack[channel_names.index('DNA')]
+integrity = assess_tissue_integrity(dna_channel)
+
+print(f"Tissue coverage: {integrity['coverage']:.1%}")
+print(f"Fragments: {integrity['n_fragments']}")
+print(f"Fragmentation: {integrity['fragmentation']:.2f}")
+print(f"Status: {'PASS' if integrity['intact'] else 'FAIL'}")
+```
+
+## Acquisition QC
+
+```python
+def check_acquisition_artifacts(image_stack, channel_names):
+    '''Check for common acquisition artifacts.'''
+    results = []
+
+    for i, name in enumerate(channel_names):
+        channel = image_stack[i]
+
+        saturated = np.sum(channel >= channel.max() * 0.99) / channel.size
+        if saturated > 0.01:
+            results.append({'channel': name, 'issue': 'saturation', 'severity': saturated})
+
+        hot_pixels = np.sum(channel > np.percentile(channel, 99.9) * 2) / channel.size
+        if hot_pixels > 0.001:
+            results.append({'channel': name, 'issue': 'hot_pixels', 'severity': hot_pixels})
+
+        dead_regions = np.sum(channel == 0) / channel.size
+        if dead_regions > 0.05:
+            results.append({'channel': name, 'issue': 'dead_regions', 'severity': dead_regions})
+
+        row_means = np.mean(channel, axis=1)
+        row_cv = np.std(row_means) / np.mean(row_means)
+        if row_cv > 0.3:
+            results.append({'channel': name, 'issue': 'striping', 'severity': row_cv})
+
+    return pd.DataFrame(results)
+
+artifacts = check_acquisition_artifacts(image_stack, channel_names)
+if len(artifacts) > 0:
+    print('Artifacts detected:')
+    print(artifacts)
+else:
+    print('No major artifacts detected')
+```
+
+## Dynamic Range
+
+```python
+def assess_dynamic_range(channel, percentiles=(1, 99)):
+    '''Assess if channel uses full dynamic range.'''
+    low, high = np.percentile(channel, percentiles)
+    channel_range = high - low
+    max_possible = channel.max()
+
+    utilized = channel_range / max_possible if max_possible > 0 else 0
+
+    return {
+        'range_low': low,
+        'range_high': high,
+        'range_utilized': utilized,
+        'adequate': utilized > 0.1
+    }
+
+for i, name in enumerate(channel_names):
+    dr = assess_dynamic_range(image_stack[i])
+    status = 'OK' if dr['adequate'] else 'LOW'
+    print(f"{name}: {dr['range_utilized']:.1%} range used [{status}]")
+```
+
+## Segmentation Quality Metrics
+
+```python
+def segmentation_qc(segmentation_mask, image_stack, channel_names):
+    '''QC metrics for cell segmentation.'''
+    from skimage.measure import regionprops
+
+    props = regionprops(segmentation_mask)
+    n_cells = len(props)
+
+    if n_cells == 0:
+        return {'error': 'No cells found'}
+
+    areas = [p.area for p in props]
+    eccentricities = [p.eccentricity for p in props]
+
+    area_cv = np.std(areas) / np.mean(areas)
+    very_small = np.sum(np.array(areas) < np.percentile(areas, 5)) / n_cells
+    very_large = np.sum(np.array(areas) > np.percentile(areas, 95)) / n_cells
+    elongated = np.sum(np.array(eccentricities) > 0.9) / n_cells
+
+    return {
+        'n_cells': n_cells,
+        'mean_area': np.mean(areas),
+        'area_cv': area_cv,
+        'pct_very_small': very_small,
+        'pct_very_large': very_large,
+        'pct_elongated': elongated,
+        'quality': 'GOOD' if area_cv < 0.5 and elongated < 0.1 else 'REVIEW'
+    }
+
+seg_mask = io.imread('cell_segmentation.tiff')
+seg_qc = segmentation_qc(seg_mask, image_stack, channel_names)
+print(f"Cells: {seg_qc['n_cells']}")
+print(f"Mean area: {seg_qc['mean_area']:.1f} pixels")
+print(f"Quality: {seg_qc['quality']}")
+```
+
+## Batch QC Summary
+
+**Goal:** Generate a consolidated quality report across all acquisitions in a batch to identify samples requiring re-acquisition or exclusion.
+
+**Approach:** For each image, compute SNR, tissue integrity, segmentation metrics, and artifact counts, then aggregate into a summary table with pass/fail calls based on combined threshold criteria.
+
+```python
+def batch_qc_report(image_files, seg_files, channel_names, output_file):
+    '''Generate QC report for batch of images.'''
+    all_results = []
+
+    for img_file, seg_file in zip(image_files, seg_files):
+        image_stack = io.imread(img_file)
+        seg_mask = io.imread(seg_file)
+
+        result = {'sample': Path(img_file).stem}
+
+        snr_values = calculate_snr_all_channels(image_stack, channel_names)
+        result['mean_snr'] = np.mean(list(snr_values.values()))
+        result['min_snr'] = min(snr_values.values())
+
+        dna_idx = channel_names.index('DNA') if 'DNA' in channel_names else 0
+        integrity = assess_tissue_integrity(image_stack[dna_idx])
+        result['tissue_coverage'] = integrity['coverage']
+
+        seg_qc = segmentation_qc(seg_mask, image_stack, channel_names)
+        result['n_cells'] = seg_qc.get('n_cells', 0)
+
+        artifacts = check_acquisition_artifacts(image_stack, channel_names)
+        result['n_artifacts'] = len(artifacts)
+
+        result['pass_qc'] = (result['min_snr'] > 1.5 and result['tissue_coverage'] > 0.3 and result['n_artifacts'] == 0)
+
+        all_results.append(result)
+
+    results_df = pd.DataFrame(all_results)
+    results_df.to_csv(output_file, index=False)
+
+    print(f"QC Summary: {results_df['pass_qc'].sum()}/{len(results_df)} samples passed")
+    return results_df
+```
+
+## Visualization
+
+```python
+import matplotlib.pyplot as plt
+
+def plot_qc_summary(image_stack, channel_names, output_file):
+    '''Generate QC summary visualization.'''
+    n_channels = len(channel_names)
+
+    fig, axes = plt.subplots(2, n_channels, figsize=(3*n_channels, 6))
+
+    for i, name in enumerate(channel_names):
+        channel = image_stack[i]
+
+        axes[0, i].imshow(channel, cmap='viridis')
+        axes[0, i].set_title(name)
+        axes[0, i].axis('off')
+
+        axes[1, i].hist(channel.flatten(), bins=100, log=True)
+        axes[1, i].set_xlabel('Intensity')
+        axes[1, i].set_ylabel('Count')
+
+    plt.tight_layout()
+    plt.savefig(output_file, dpi=150)
+    plt.close()
+
+plot_qc_summary(image_stack, channel_names, 'qc_summary.png')
+```
+
+## Related Skills
+
+- data-preprocessing - Clean data before QC
+- cell-segmentation - Segmentation affects QC metrics
+- interactive-annotation - Manual review of QC failures
+- phenotyping - Analysis after QC passes

package/data/skills/bio-imaging-mass-cytometry-spatial-analysis/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: bio-imaging-mass-cytometry-spatial-analysis
+description: Spatial analysis of cell neighborhoods and interactions in IMC data. Covers neighbor graphs, spatial statistics, and interaction testing. Use when analyzing spatial relationships between cell types, testing for neighborhood enrichment, or identifying cell-cell interaction patterns in imaging mass cytometry data.
+tool_type: python
+primary_tool: squidpy
+---
+
+## Version Compatibility
+
+Reference examples tested with: anndata 0.10+, matplotlib 3.8+, numpy 1.26+, pandas 2.2+, scanpy 1.10+, scipy 1.12+, squidpy 1.3+
+
+Before using code patterns, verify installed versions match. If versions differ:
+- Python: `pip show <package>` then `help(module.function)` to check signatures
+
+If code throws ImportError, AttributeError, or TypeError, introspect the installed
+package and adapt the example to match the actual API rather than retrying.
+
+# Spatial Analysis for IMC
+
+**"Analyze spatial cell interactions in my IMC data"** → Build spatial neighborhood graphs, test for cell-cell interaction enrichment, and identify spatial domains from multiplexed imaging data.
+- Python: `squidpy.gr.spatial_neighbors()`, `squidpy.gr.nhood_enrichment()`
+
+## Build Spatial Graph
+
+```python
+import squidpy as sq
+import anndata as ad
+
+# Load phenotyped data
+adata = ad.read_h5ad('imc_phenotyped.h5ad')
+
+# Ensure spatial coordinates are set
+# adata.obsm['spatial'] should contain (x, y) coordinates
+
+# Build spatial neighbor graph
+sq.gr.spatial_neighbors(adata, coord_type='generic', delaunay=True)
+# Or by distance
+sq.gr.spatial_neighbors(adata, coord_type='generic', radius=50)  # 50 pixels
+
+print(f'Built graph with {adata.obsp["spatial_connectivities"].nnz} edges')
+```
+
+## Neighborhood Enrichment
+
+```python
+# Test if cell types are enriched near each other
+sq.gr.nhood_enrichment(adata, cluster_key='cell_type')
+
+# Visualize
+sq.pl.nhood_enrichment(adata, cluster_key='cell_type', save='nhood_enrichment.png')
+
+# Get z-scores
+zscore = adata.uns['cell_type_nhood_enrichment']['zscore']
+# Positive: enriched, Negative: depleted
+```
+
+## Co-occurrence Analysis
+
+```python
+# Analyze co-occurrence of cell types at multiple distances
+sq.gr.co_occurrence(adata, cluster_key='cell_type')
+
+# Plot
+sq.pl.co_occurrence(adata, cluster_key='cell_type', save='co_occurrence.png')
+```
+
+## Ripley's Statistics
+
+```python
+# Ripley's L function for spatial clustering
+sq.gr.ripley(adata, cluster_key='cell_type', mode='L')
+
+# Plot
+sq.pl.ripley(adata, cluster_key='cell_type', save='ripley.png')
+
+# Interpretation:
+# L(r) > r: clustering at distance r
+# L(r) < r: dispersion at distance r
+# L(r) = r: random distribution
+```
+
+## Cell-Cell Interaction
+
+```python
+# Permutation test for interactions
+sq.gr.interaction_matrix(adata, cluster_key='cell_type', normalized=True)
+
+# Get interaction matrix
+interaction = adata.uns['cell_type_interactions']
+```
+
+## Custom Neighborhood Analysis
+
+**Goal:** Characterize the local cellular microenvironment around each cell by quantifying the cell type composition of its spatial neighbors.
+
+**Approach:** Multiply the spatial connectivity matrix by a one-hot encoding of cell types, then normalize each row to produce fractional neighborhood composition vectors per cell.
+
+```python
+import pandas as pd
+import numpy as np
+from scipy.sparse import csr_matrix
+
+def neighborhood_composition(adata, cluster_key='cell_type'):
+    '''Calculate cell type composition of each cell's neighborhood'''
+
+    # Get connectivity matrix
+    conn = adata.obsp['spatial_connectivities']
+    cell_types = adata.obs[cluster_key]
+    type_categories = cell_types.cat.categories
+
+    # One-hot encode cell types
+    type_onehot = pd.get_dummies(cell_types).values
+
+    # Neighborhood composition = connectivity * one-hot
+    nhood_composition = conn @ type_onehot
+
+    # Normalize to fractions
+    nhood_sum = np.array(nhood_composition.sum(axis=1)).flatten()
+    nhood_sum[nhood_sum == 0] = 1  # Avoid division by zero
+    nhood_frac = nhood_composition / nhood_sum[:, np.newaxis]
+
+    # Add to adata
+    for i, ct in enumerate(type_categories):
+        adata.obs[f'nhood_frac_{ct}'] = nhood_frac[:, i]
+
+    return nhood_frac
+
+nhood_frac = neighborhood_composition(adata)
+```
+
+## Spatial Clustering
+
+```python
+# Leiden clustering on spatial + expression
+# Weight spatial vs molecular information
+
+# Combined graph
+sq.gr.spatial_neighbors(adata, coord_type='generic', radius=30)
+
+# Run spatial Leiden
+sc.tl.leiden(adata, adjacency=adata.obsp['spatial_connectivities'],
+             resolution=0.5, key_added='spatial_cluster')
+```
+
+## Interaction Hotspots
+
+```python
+def find_interaction_hotspots(adata, type1, type2, cluster_key='cell_type', radius=50):
+    '''Find regions with high interaction between two cell types'''
+
+    # Get cells of each type
+    mask1 = adata.obs[cluster_key] == type1
+    mask2 = adata.obs[cluster_key] == type2
+
+    spatial = adata.obsm['spatial']
+
+    # For each type1 cell, count nearby type2 cells
+    from scipy.spatial import cKDTree
+
+    tree2 = cKDTree(spatial[mask2])
+
+    interaction_scores = np.zeros(mask1.sum())
+    for i, (x, y) in enumerate(spatial[mask1]):
+        neighbors = tree2.query_ball_point([x, y], r=radius)
+        interaction_scores[i] = len(neighbors)
+
+    return interaction_scores
+
+cd8_tumor_interactions = find_interaction_hotspots(adata, 'CD8 T cell', 'Tumor', radius=30)
+```
+
+## Visualize Spatial Patterns
+
+```python
+import matplotlib.pyplot as plt
+
+# Spatial plot by cell type
+sq.pl.spatial_scatter(adata, color='cell_type', size=3, save='spatial_celltypes.png')
+
+# Multiple markers
+sq.pl.spatial_scatter(adata, color=['CD8', 'CD4', 'CD68'], size=2, save='spatial_markers.png')
+
+# Highlight specific interaction
+fig, ax = plt.subplots(figsize=(10, 10))
+spatial = adata.obsm['spatial']
+
+# Background: all cells gray
+ax.scatter(spatial[:, 0], spatial[:, 1], c='lightgray', s=1, alpha=0.5)
+
+# Highlight: CD8 and Tumor
+for ct, color in [('CD8 T cell', 'red'), ('Tumor', 'blue')]:
+    mask = adata.obs['cell_type'] == ct
+    ax.scatter(spatial[mask, 0], spatial[mask, 1], c=color, s=5, label=ct)
+
+ax.legend()
+ax.set_aspect('equal')
+plt.savefig('cd8_tumor_spatial.png', dpi=150)
+```
+
+## Statistical Testing
+
+```python
+from scipy import stats
+
+def spatial_association_test(adata, type1, type2, cluster_key='cell_type', n_perm=1000):
+    '''Permutation test for spatial association between cell types'''
+
+    # Observed interaction count
+    sq.gr.nhood_enrichment(adata, cluster_key=cluster_key)
+    obs_zscore = adata.uns[f'{cluster_key}_nhood_enrichment']['zscore']
+
+    idx1 = list(adata.obs[cluster_key].cat.categories).index(type1)
+    idx2 = list(adata.obs[cluster_key].cat.categories).index(type2)
+
+    observed = obs_zscore[idx1, idx2]
+
+    # The z-score is already normalized, so we can use it directly
+    # p-value from z-score
+    pvalue = 2 * (1 - stats.norm.cdf(abs(observed)))
+
+    return {'zscore': observed, 'pvalue': pvalue}
+
+result = spatial_association_test(adata, 'CD8 T cell', 'Tumor')
+print(f"CD8-Tumor association: z={result['zscore']:.2f}, p={result['pvalue']:.4f}")
+```
+
+## Export Results
+
+```python
+# Save spatial analysis results
+adata.write('imc_spatial_analyzed.h5ad')
+
+# Export neighborhood enrichment
+nhood_df = pd.DataFrame(
+    adata.uns['cell_type_nhood_enrichment']['zscore'],
+    index=adata.obs['cell_type'].cat.categories,
+    columns=adata.obs['cell_type'].cat.categories
+)
+nhood_df.to_csv('neighborhood_enrichment.csv')
+```
+
+## Related Skills
+
+- phenotyping - Assign cell types first
+- spatial-transcriptomics/spatial-statistics - Similar spatial methods
+- single-cell/cell-communication - Interaction concepts