@bgicli/bgicli 2.1.1 → 2.2.0

package/data/skills/bio-atac-seq-motif-deviation/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: bio-atac-seq-motif-deviation
+description: Analyze transcription factor motif accessibility variability using chromVAR. Use when identifying which TF motifs show variable accessibility across samples or conditions in ATAC-seq data.
+tool_type: r
+primary_tool: chromVAR
+---
+
+## Version Compatibility
+
+Reference examples tested with: ggplot2 3.5+, limma 3.58+
+
+Before using code patterns, verify installed versions match. If versions differ:
+- R: `packageVersion('<pkg>')` then `?function_name` to verify parameters
+
+If code throws ImportError, AttributeError, or TypeError, introspect the installed
+package and adapt the example to match the actual API rather than retrying.
+
+# Motif Deviation Analysis
+
+**"Which TF motifs show variable accessibility across my samples?"** → Compute per-sample deviation scores for TF motif accessibility to identify regulators driving chromatin state differences.
+- R: `chromVAR::computeDeviations(counts, motifs)`
+
+Measure per-sample variability in transcription factor motif accessibility using chromVAR. This identifies TFs whose binding sites show differential accessibility across conditions.
+
+## Required Packages
+
+```r
+library(chromVAR)
+library(motifmatchr)
+library(BSgenome.Hsapiens.UCSC.hg38)  # or appropriate genome
+library(JASPAR2020)
+library(TFBSTools)
+library(SummarizedExperiment)
+```
+
+## Basic Workflow
+
+**Goal:** Run chromVAR to compute per-sample TF motif deviation scores from ATAC-seq peak counts.
+
+**Approach:** Load peak counts into a SummarizedExperiment, correct for GC bias, filter low-quality peaks, match JASPAR motifs, and compute deviation z-scores.
+
+### 1. Load Peak Counts
+
+```r
+library(chromVAR)
+library(SummarizedExperiment)
+
+# From count matrix and peak ranges
+peaks <- read.table('peaks.bed', col.names = c('chr', 'start', 'end'))
+peak_ranges <- GRanges(seqnames = peaks$chr, ranges = IRanges(peaks$start, peaks$end))
+
+counts <- read.table('counts.txt', header = TRUE, row.names = 1)
+counts_matrix <- as.matrix(counts)
+
+fragment_counts <- SummarizedExperiment(
+    assays = list(counts = counts_matrix),
+    rowRanges = peak_ranges
+)
+```
+
+### 2. Add GC Bias Correction
+
+```r
+library(BSgenome.Hsapiens.UCSC.hg38)
+
+fragment_counts <- addGCBias(fragment_counts, genome = BSgenome.Hsapiens.UCSC.hg38)
+```
+
+### 3. Filter Low-Quality Peaks
+
+```r
+# min_depth=1500: Minimum total reads per sample. Adjust based on library size.
+# min_in_peaks=0.15: Minimum fraction of reads in peaks (FRiP). 0.15 = 15%.
+fragment_counts <- filterSamples(fragment_counts, min_depth = 1500, min_in_peaks = 0.15)
+
+# min_count=10: Require peaks with >=10 reads across samples.
+# n_samples_frac=0.1: Peak must be detected in >=10% of samples.
+fragment_counts <- filterPeaks(fragment_counts, non_overlapping = TRUE,
+                                min_count = 10, n_samples_frac = 0.1)
+```
+
+## Get Motif Annotations
+
+### From JASPAR
+
+```r
+library(JASPAR2020)
+library(TFBSTools)
+library(motifmatchr)
+
+# Get vertebrate motifs from JASPAR
+pfm <- getMatrixSet(JASPAR2020, opts = list(collection = 'CORE', tax_group = 'vertebrates'))
+
+# Match motifs to peaks
+# p.cutoff=5e-5: Motif match p-value threshold. Lower = more stringent.
+motif_ix <- matchMotifs(pfm, fragment_counts, genome = BSgenome.Hsapiens.UCSC.hg38, p.cutoff = 5e-5)
+```
+
+### From CIS-BP or Custom PWMs
+
+```r
+# Load custom motifs from file
+library(universalmotif)
+motifs <- read_meme('custom_motifs.meme')
+pfm_list <- lapply(motifs, function(m) convert_motifs(m, class = 'TFBSTools-PFMatrix'))
+
+motif_ix <- matchMotifs(pfm_list, fragment_counts, genome = BSgenome.Hsapiens.UCSC.hg38)
+```
+
+## Compute Deviations
+
+```r
+# Compute chromVAR deviation scores
+dev <- computeDeviations(object = fragment_counts, annotations = motif_ix)
+
+# Extract deviation scores (z-scores)
+deviation_scores <- deviations(dev)
+
+# Extract variability across samples
+variability <- computeVariability(dev)
+```
+
+## Interpreting Results
+
+### Deviation Scores
+
+```r
+# Deviation z-scores: positive = more accessible than expected
+# Compare across samples
+dev_matrix <- deviations(dev)
+print(dim(dev_matrix))  # motifs x samples
+
+# Get top variable motifs
+var_df <- variability
+var_df <- var_df[order(-var_df$variability), ]
+head(var_df, 20)
+```
+
+### Variability Interpretation
+
+| Variability | Interpretation |
+|-------------|----------------|
+| > 2.0 | Highly variable across samples |
+| 1.0 - 2.0 | Moderately variable |
+| < 1.0 | Low variability |
+
+## Visualization
+
+### Deviation Heatmap
+
+```r
+library(pheatmap)
+
+# Get top variable motifs
+# n_top=50: Number of top variable motifs to display.
+n_top <- 50
+top_motifs <- head(rownames(var_df), n_top)
+top_dev <- deviation_scores[top_motifs, ]
+
+# Add sample annotations
+sample_info <- data.frame(
+    Condition = colData(fragment_counts)$condition,
+    row.names = colnames(top_dev)
+)
+
+pheatmap(top_dev, annotation_col = sample_info, scale = 'row',
+         clustering_method = 'ward.D2', show_rownames = TRUE)
+```
+
+### Variability Plot
+
+```r
+plotVariability(variability, use_plotly = FALSE)
+```
+
+### PCA of Deviation Scores
+
+```r
+library(ggplot2)
+
+# PCA on deviation scores
+pca <- prcomp(t(deviation_scores), scale. = TRUE)
+pca_df <- data.frame(PC1 = pca$x[,1], PC2 = pca$x[,2],
+                     Condition = colData(fragment_counts)$condition)
+
+ggplot(pca_df, aes(x = PC1, y = PC2, color = Condition)) +
+    geom_point(size = 3) +
+    theme_minimal() +
+    labs(title = 'PCA of chromVAR Deviations')
+```
+
+## Differential Motif Accessibility
+
+**Goal:** Identify TF motifs with significantly different accessibility between experimental groups.
+
+**Approach:** Fit a linear model (limma) to deviation z-scores across groups and extract significant motifs with empirical Bayes moderation.
+
+### Compare Two Groups
+
+```r
+library(limma)
+
+# Get sample groups
+groups <- factor(colData(fragment_counts)$condition)
+
+# Design matrix
+design <- model.matrix(~ groups)
+
+# Fit linear model to deviation scores
+fit <- lmFit(deviation_scores, design)
+fit <- eBayes(fit)
+
+# Get differential motifs
+# p.value=0.05: FDR threshold for significance.
+diff_motifs <- topTable(fit, coef = 2, number = Inf, p.value = 0.05)
+print(head(diff_motifs, 20))
+```
+
+### Volcano Plot
+
+```r
+library(ggplot2)
+
+all_results <- topTable(fit, coef = 2, number = Inf)
+all_results$significant <- all_results$adj.P.Val < 0.05
+
+ggplot(all_results, aes(x = logFC, y = -log10(adj.P.Val), color = significant)) +
+    geom_point(alpha = 0.6) +
+    geom_hline(yintercept = -log10(0.05), linetype = 'dashed') +
+    scale_color_manual(values = c('grey', 'red')) +
+    theme_minimal() +
+    labs(title = 'Differential Motif Accessibility',
+         x = 'Log2 Fold Change', y = '-log10(adjusted p-value)')
+```
+
+## Working with Single-Cell ATAC-seq
+
+```r
+# For scATAC-seq, aggregate cells by cluster first
+# Then run chromVAR on pseudo-bulk profiles
+
+# Or use chromVAR with sparse matrices
+library(Matrix)
+
+# Create SummarizedExperiment with sparse counts
+sparse_counts <- Matrix(counts_matrix, sparse = TRUE)
+fragment_counts <- SummarizedExperiment(
+    assays = list(counts = sparse_counts),
+    rowRanges = peak_ranges
+)
+
+# Proceed with standard workflow
+fragment_counts <- addGCBias(fragment_counts, genome = BSgenome.Hsapiens.UCSC.hg38)
+```
+
+## Background Peaks Strategy
+
+```r
+# Custom background for better bias correction
+# n_iterations=50: Number of background sets. Higher = more stable but slower.
+bg <- getBackgroundPeaks(object = fragment_counts, niterations = 50)
+
+# Use custom background in deviation calculation
+dev <- computeDeviations(object = fragment_counts, annotations = motif_ix, background_peaks = bg)
+```
+
+## Export Results
+
+```r
+# Save deviation scores
+write.csv(as.data.frame(deviation_scores), 'chromvar_deviations.csv')
+
+# Save variability
+write.csv(variability, 'chromvar_variability.csv')
+
+# Save differential results
+write.csv(diff_motifs, 'differential_motifs.csv')
+```
+
+## Complete Workflow
+
+**Goal:** Run end-to-end chromVAR analysis from peak counts to motif variability scores.
+
+**Approach:** Load counts, correct GC bias, filter peaks, match JASPAR motifs, compute deviations, and plot variability.
+
+```r
+library(chromVAR)
+library(motifmatchr)
+library(BSgenome.Hsapiens.UCSC.hg38)
+library(JASPAR2020)
+library(TFBSTools)
+
+# 1. Load data
+fragment_counts <- getCounts('peaks.bed', c('sample1.bam', 'sample2.bam', 'sample3.bam'))
+
+# 2. Add GC bias
+fragment_counts <- addGCBias(fragment_counts, genome = BSgenome.Hsapiens.UCSC.hg38)
+
+# 3. Filter
+fragment_counts <- filterPeaks(fragment_counts)
+
+# 4. Get motifs
+pfm <- getMatrixSet(JASPAR2020, opts = list(collection = 'CORE', tax_group = 'vertebrates'))
+motif_ix <- matchMotifs(pfm, fragment_counts, genome = BSgenome.Hsapiens.UCSC.hg38)
+
+# 5. Compute deviations
+dev <- computeDeviations(fragment_counts, motif_ix)
+
+# 6. Analyze variability
+variability <- computeVariability(dev)
+plotVariability(variability)
+```
+
+## Related Skills
+
+- differential-accessibility - Peak-level differential analysis with DiffBind
+- footprinting - TF footprinting with TOBIAS
+- atac-qc - Quality control before chromVAR
+- chip-seq/motif-analysis - Alternative motif enrichment approaches

package/data/skills/bio-atac-seq-nucleosome-positioning/SKILL.md

@@ -0,0 +1,321 @@
+---
+name: bio-atac-seq-nucleosome-positioning
+description: Extract nucleosome positions from ATAC-seq data using NucleoATAC, ATACseqQC, and fragment analysis. Use when analyzing chromatin organization, identifying nucleosome-free regions at promoters, or characterizing nucleosome occupancy patterns from ATAC-seq fragment size distributions.
+tool_type: mixed
+primary_tool: NucleoATAC
+---
+
+## Version Compatibility
+
+Reference examples tested with: Rsamtools 2.18+, matplotlib 3.8+, numpy 1.26+, pyBigWig 0.3+, pysam 0.22+, samtools 1.19+
+
+Before using code patterns, verify installed versions match. If versions differ:
+- Python: `pip show <package>` then `help(module.function)` to check signatures
+- R: `packageVersion('<pkg>')` then `?function_name` to verify parameters
+- CLI: `<tool> --version` then `<tool> --help` to confirm flags
+
+If code throws ImportError, AttributeError, or TypeError, introspect the installed
+package and adapt the example to match the actual API rather than retrying.
+
+# Nucleosome Positioning
+
+**"Map nucleosome positions from ATAC-seq"** → Separate nucleosome-free and mono-nucleosome fragments by size, then call nucleosome center positions and occupancy scores.
+- CLI: `nucleoatac run --bed peaks.bed --bam atac.bam --fasta ref.fa`
+- R: `ATACseqQC::splitGAlignmentsByCut()` for fragment separation
+
+Extract nucleosome positions and occupancy from ATAC-seq fragment size patterns.
+
+## Background
+
+ATAC-seq fragments reflect chromatin structure:
+- **< 100 bp**: Nucleosome-free regions (NFR)
+- **180-247 bp**: Mono-nucleosome
+- **315-473 bp**: Di-nucleosome
+- **558-615 bp**: Tri-nucleosome
+
+## ATACseqQC (R)
+
+### Installation
+
+```r
+BiocManager::install('ATACseqQC')
+```
+
+### Fragment Size Distribution
+
+```r
+library(ATACseqQC)
+library(Rsamtools)
+
+# Read BAM
+bamfile <- 'sample.bam'
+
+# Fragment size distribution
+fragSize <- fragSizeDist(bamfile, 'sample')
+
+# Nucleosome-free and mono-nucleosome ratios
+# Automatic QC metrics
+```
+
+### Nucleosome Positioning
+
+**Goal:** Map nucleosome positions around TSS using ATAC-seq fragment size classes.
+
+**Approach:** Read BAM, apply Tn5 shift correction, split fragments into NFR and mono-nucleosome classes by size, then compute signal profiles around TSS.
+
+```r
+library(ATACseqQC)
+library(TxDb.Hsapiens.UCSC.hg38.knownGene)
+library(BSgenome.Hsapiens.UCSC.hg38)
+
+# Get TSS regions
+txs <- transcripts(TxDb.Hsapiens.UCSC.hg38.knownGene)
+tss <- promoters(txs, upstream=1000, downstream=1000)
+
+# Read BAM
+gal <- readBamFile(bamfile, asMates=TRUE, bigFile=TRUE)
+
+# Shift reads (Tn5 offset correction)
+gal_shifted <- shiftGAlignmentsList(gal)
+
+# Split by nucleosome-free and nucleosomal
+objs <- splitGAlignmentsByCut(gal_shifted, txs=txs,
+                               genome=BSgenome.Hsapiens.UCSC.hg38)
+
+# nucleosome-free fragments
+nfr <- objs$NussomeFree
+
+# Mono-nucleosome fragments
+mono <- objs$mononucleosome
+
+# Signal around TSS
+sigs <- featureAlignedSignal(cvglist=objs,
+                             feature.gr=tss,
+                             upstream=1000,
+                             downstream=1000)
+```
+
+### V-Plot (Fragment Size vs Position)
+
+```r
+# V-plot showing nucleosome positioning around TSS
+vp <- vPlot(gal_shifted, tss,
+            genome=BSgenome.Hsapiens.UCSC.hg38,
+            upstream=1000, downstream=1000)
+```
+
+### Footprinting
+
+```r
+# Transcription factor footprinting
+library(MotifDb)
+
+# Get motif
+motif <- query(MotifDb, 'CTCF')[[1]]
+
+# Find motif occurrences
+library(motifmatchr)
+motif_pos <- matchMotifs(motif, BSgenome.Hsapiens.UCSC.hg38,
+                         genome='hg38', out='positions')
+
+# Calculate footprint
+fp <- factorFootprints(gal_shifted, motif_pos,
+                       genome=BSgenome.Hsapiens.UCSC.hg38,
+                       upstream=100, downstream=100)
+```
+
+## NucleoATAC (Python)
+
+### Installation
+
+```bash
+pip install nucleoatac
+```
+
+### Run NucleoATAC
+
+**Goal:** Call precise nucleosome center positions and occupancy scores from ATAC-seq data.
+
+**Approach:** Run NucleoATAC on defined genomic regions with a reference genome, producing nucleosome position calls and occupancy tracks.
+
+```bash
+# Call nucleosomes
+nucleoatac run --bed regions.bed --bam sample.bam --fasta reference.fa \
+    --out nucleoatac_output --cores 8
+```
+
+### Output Files
+
+| File | Description |
+|------|-------------|
+| `.nucpos.bed` | Nucleosome positions |
+| `.nucpos.redundant.bed` | All nucleosome calls |
+| `.nfrpos.bed` | NFR positions |
+| `.occ.bedgraph` | Nucleosome occupancy track |
+| `.nucmap_combined.bed` | Combined nucleosome map |
+
+### Visualize Output
+
+```bash
+# Convert to bigWig for visualization
+bedGraphToBigWig nucleoatac_output.occ.bedgraph chrom.sizes nucleosome_occ.bw
+```
+
+## Fragment Analysis (Custom)
+
+### Extract Fragment Sizes
+
+**Goal:** Visualize ATAC-seq fragment size distribution to assess nucleosome periodicity.
+
+**Approach:** Extract template lengths from properly paired reads, then plot the histogram with NFR and mono-nucleosome cutoff markers.
+
+```python
+import pysam
+import numpy as np
+import matplotlib.pyplot as plt
+
+bam = pysam.AlignmentFile('sample.bam', 'rb')
+
+fragment_sizes = []
+for read in bam.fetch():
+    if read.is_proper_pair and read.is_read1:
+        frag_size = abs(read.template_length)
+        if 0 < frag_size < 1000:
+            fragment_sizes.append(frag_size)
+
+bam.close()
+
+# Plot distribution
+plt.figure(figsize=(10, 6))
+plt.hist(fragment_sizes, bins=200, edgecolor='none', alpha=0.7)
+plt.axvline(100, color='red', linestyle='--', label='NFR cutoff')
+plt.axvline(180, color='blue', linestyle='--', label='Mono-nuc start')
+plt.xlabel('Fragment Size (bp)')
+plt.ylabel('Count')
+plt.legend()
+plt.savefig('fragment_distribution.png', dpi=300)
+```
+
+### Split by Fragment Size
+
+```bash
+# Extract nucleosome-free reads
+samtools view -h sample.bam | \
+    awk '$9 > -100 && $9 < 100 || $1 ~ /^@/' | \
+    samtools view -b > nfr.bam
+
+# Extract mono-nucleosome reads
+samtools view -h sample.bam | \
+    awk '($9 >= 180 && $9 <= 247) || ($9 <= -180 && $9 >= -247) || $1 ~ /^@/' | \
+    samtools view -b > mono_nuc.bam
+```
+
+### Signal Around Features
+
+```python
+import pysam
+import numpy as np
+import pyBigWig
+
+def signal_around_sites(bam_file, sites, upstream=1000, downstream=1000):
+    bam = pysam.AlignmentFile(bam_file, 'rb')
+    window_size = upstream + downstream
+    signal = np.zeros(window_size)
+
+    for chrom, pos, strand in sites:
+        start = pos - upstream if strand == '+' else pos - downstream
+        end = pos + downstream if strand == '+' else pos + upstream
+
+        for read in bam.fetch(chrom, max(0, start), end):
+            if read.is_proper_pair and read.is_read1:
+                frag_center = read.reference_start + abs(read.template_length) // 2
+                rel_pos = frag_center - start
+                if 0 <= rel_pos < window_size:
+                    signal[rel_pos] += 1
+
+    bam.close()
+    return signal / len(sites)
+
+# Load TSS sites
+tss_sites = []  # Load from GTF
+nfr_signal = signal_around_sites('nfr.bam', tss_sites)
+mono_signal = signal_around_sites('mono_nuc.bam', tss_sites)
+```
+
+## DANPOS
+
+### Installation
+
+```bash
+conda install -c bioconda danpos
+```
+
+### Run DANPOS
+
+```bash
+# Single sample
+danpos.py dpos sample.bam -o danpos_output
+
+# Compare conditions
+danpos.py dpeak -b treatment.bam -c control.bam -o danpos_diff
+```
+
+## Complete Workflow
+
+**Goal:** Run end-to-end nucleosome positioning analysis from BAM to heatmaps and V-plots.
+
+**Approach:** Read BAM, shift reads for Tn5 offset, split fragments by size class, compute signal profiles around TSS, and generate heatmaps and V-plots.
+
+```r
+library(ATACseqQC)
+library(TxDb.Hsapiens.UCSC.hg38.knownGene)
+library(BSgenome.Hsapiens.UCSC.hg38)
+
+bamfile <- 'sample.bam'
+
+# 1. Fragment size QC
+fragSize <- fragSizeDist(bamfile, 'sample')
+pdf('fragment_size.pdf')
+plot(fragSize)
+dev.off()
+
+# 2. Read and shift
+gal <- readBamFile(bamfile, asMates=TRUE, bigFile=TRUE)
+gal_shifted <- shiftGAlignmentsList(gal)
+
+# 3. Get TSS regions
+txs <- transcripts(TxDb.Hsapiens.UCSC.hg38.knownGene)
+tss <- promoters(txs, upstream=2000, downstream=2000)
+
+# 4. Split by fragment size
+objs <- splitGAlignmentsByCut(gal_shifted, txs=txs,
+                               genome=BSgenome.Hsapiens.UCSC.hg38)
+
+# 5. Calculate signals
+sigs <- featureAlignedSignal(cvglist=objs,
+                             feature.gr=tss,
+                             upstream=2000,
+                             downstream=2000)
+
+# 6. Plot heatmap
+pdf('nucleosome_heatmap.pdf', width=8, height=10)
+featureAlignedHeatmap(sigs, tss, upstream=2000, downstream=2000)
+dev.off()
+
+# 7. V-plot
+pdf('vplot.pdf')
+vPlot(gal_shifted, tss, genome=BSgenome.Hsapiens.UCSC.hg38,
+      upstream=1000, downstream=1000)
+dev.off()
+
+# 8. Export nucleosome-free and nucleosomal BAMs
+export(objs$NuclsomeFree, 'nfr.bam')
+export(objs$mononucleosome, 'mono_nucleosome.bam')
+```
+
+## Related Skills
+
+- atac-seq/atac-peak-calling - Call accessibility peaks
+- atac-seq/atac-qc - Quality control metrics
+- atac-seq/footprinting - TF footprinting
+- chip-seq/peak-annotation - Annotate nucleosome positions