bedtools-genomic-intervals
Genomic interval ops on BED/BAM/GFF/VCF. Find overlaps, merge intervals, compute coverage, extract FASTA, find nearest features. Core for ChIP-seq peak annotation, region filtering, genome arithmetic. Use tabix for indexed single-region queries; use deeptools for normalized bigWig coverage.
Install / Use
npx skills add jaechang-hits/SciAgent-Skills --skill bedtools-genomic-intervalsInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Our assessment of bedtools-genomic-intervals
bedtools-genomic-intervals scores 91/100 on our quality scale, 1179th of 4,716 Development & Engineering skills we index (top 25%).
Its SKILL.md is 17 KB long, well organised into 91 sections with 19 code examples: a thorough specification that gives an agent plenty to work with.
It has 367 GitHub stars, a meaningful sign that others use it.
Maintenance, license and trust
- The repository was last updated about 3 months ago, so bedtools-genomic-intervals is actively maintained.
- Our last check on 2026-11-20 found the source still online.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-05. Automated pattern scan on 2026-10-05. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
bedtools-genomic-intervals compared with similar skills
All 4 of these similar skills score higher than bedtools-genomic-intervals; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| bedtools-genomic-intervals (this skill)by jaechang-hits | 91 | 367 | 3mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 118.9k | 11d ago | CLAUDE.md |
| hyperframesby heygen-com | 100 | 87.1k | today | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.6k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.5k | 5d ago | CLAUDE.md |
Frequently asked questions
- How do I install bedtools-genomic-intervals?
- Run
npx skills add jaechang-hits/SciAgent-Skills --skill bedtools-genomic-intervals. The install tabs above show the steps for each supported agent. - Which AI agents does bedtools-genomic-intervals work with?
- It is written for Zed, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is bedtools-genomic-intervals safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is bedtools-genomic-intervals still maintained?
- The repository was last updated about 3 months ago, so bedtools-genomic-intervals is actively maintained.
Skill content
View source on GitHubname: "bedtools-genomic-intervals" description: "Genomic interval ops on BED/BAM/GFF/VCF. Find overlaps, merge intervals, compute coverage, extract FASTA, find nearest features. Core for ChIP-seq peak annotation, region filtering, genome arithmetic. Use tabix for indexed single-region queries; use deeptools for normalized bigWig coverage." license: "GPL-2.0"
bedtools — Genomic Interval Analysis Toolkit
Overview
bedtools is the standard toolkit for operating on genomic intervals in BED, BAM, GFF, and VCF formats. It solves the core problem of genome arithmetic: finding overlaps between feature sets, computing coverage, extracting sequences, merging adjacent regions, and annotating features with nearest neighbors. bedtools operates on sorted coordinate lists and runs at C speed, making it practical for whole-genome analyses.
When to Use
- Intersecting ChIP-seq peaks with gene annotations to find promoter-overlapping peaks
- Merging overlapping ATAC-seq peaks or called regions across replicates
- Computing read coverage depth over target capture regions
- Extracting FASTA sequences for motif discovery or primer design
- Finding the nearest gene to each regulatory element or variant
- Subtracting blacklist or repeat regions from peak calls
- Expanding genomic intervals by fixed distance (promoter regions)
- Use
tabixinstead for fast indexed queries of a single genomic region - For normalized coverage bigWig tracks, use
deeptools bamCoverageinstead - Use
mosdepthinstead for whole-genome per-base depth (10× faster)
Prerequisites
- Python packages: None required (command-line only)
- Input requirements: BED/BAM/GFF/VCF files; FASTA reference for
getfasta; genome file (chromosome sizes) forslop/flank/genomecov - Sorting: Most operations require coordinate-sorted input
Check before installing: The tool may already be available in the current environment (e.g., inside a
pixi/condaenv). Runcommand -v bedtoolsfirst and skip the install commands below if it returns a path. When running inside a pixi project, invoke the tool viapixi run bedtoolsrather than barebedtools.
# Bioconda (recommended)
conda install -c bioconda bedtools
# Homebrew (macOS)
brew install bedtools
# Verify
bedtools --version
# bedtools v2.31.0
# Create genome file from FASTA index
samtools faidx reference.fa
cut -f1,2 reference.fa.fai > genome.txt # chr → size table
Pre-flight Interview
Settle these with the user before writing any analysis code.
decisions:
- id: D1
param: overlapRequirement
kind: required
source: user
ask: "How much of a feature must overlap before the two count as intersecting - a single base, or a stated fraction?"
default: "one base"
- id: D2
param: reciprocalOverlap
kind: required
source: user
depends_on: [D1]
ask: "Must the fraction hold for both features, or only for the query?"
default: "query only"
skip_if: "overlap requirement left at a single base"
- id: D3
param: strandedness
kind: required
source: data
ask: "Do the features carry strand, and must two features share it to be considered overlapping?"
default: "strand ignored"
- id: D4
param: mergeDistance
kind: optional
source: user
ask: "How close may two intervals be before they are merged into one?"
default: "touching or overlapping only"
- id: D5
param: coverageScaling
kind: optional_conditional
source: upstream
ask: "Should coverage be scaled to a per-million factor so samples are comparable?"
default: "raw coverage"
- id: D6
param: sortedInput
kind: never_ask
source: data
reason: "The sweep algorithm needs sorted input and changes memory and speed, not the intervals returned"
default: "used when inputs are sorted"
D3 is the quiet one. For stranded features - genes, stranded RNA coverage, motif hits - ignoring strand reports antisense overlaps as real, and the output is a perfectly ordinary BED file with too many rows.
Quick Start
# Find peaks overlapping genes, then merge overlapping peaks
bedtools intersect -a peaks.bed -b genes.bed -wa -wb > peaks_with_genes.bed
bedtools merge -i peaks.bed > merged_peaks.bed
bedtools coverage -a genes.bed -b reads.bam > gene_coverage.bed
Core API
Module 1: Interval Intersection and Overlap Analysis
Find regions that overlap between two feature sets.
# Basic intersection: output overlapping regions
bedtools intersect -a peaks.bed -b genes.bed
# Report original A and B features for each overlap
bedtools intersect -a peaks.bed -b genes.bed -wa -wb
# Count B overlaps per A feature (adds column)
bedtools intersect -a peaks.bed -b genes.bed -c
# Output: chr1 1000 2000 peak1 gene_count
# Peaks with ANY overlap (report each peak once)
bedtools intersect -a peaks.bed -b genes.bed -u
# Peaks with NO overlap in B (invert filter)
bedtools intersect -a peaks.bed -b blacklist.bed -v
# Require reciprocal 50% overlap both ways
bedtools intersect -a exp1.bed -b exp2.bed -f 0.5 -F 0.5 -r
# Same-strand intersections only
bedtools intersect -a peaks.bed -b genes.bed -s
# Multiple database files with overlap counts per file
bedtools intersect -a query.bed -b enhancers.bed promoters.bed \
-names enh prom -C
# Memory-efficient mode for pre-sorted large files
bedtools intersect -a sorted_peaks.bed -b sorted_genes.bed -sorted
Module 2: Interval Merging and Arithmetic
Combine overlapping intervals and perform set operations.
# Merge overlapping and adjacent intervals
sort -k1,1 -k2,2n peaks.bed | bedtools merge -i stdin
# Merge intervals within 500 bp of each other
bedtools merge -i peaks.bed -d 500
# Merge and count original features
bedtools merge -i peaks.bed -c 1 -o count
# Output: chr1 1000 5000 3 (3 original peaks merged)
# Merge and collapse feature names
bedtools merge -i peaks.bed -c 4 -o collapse -delim ";"
# Output: chr1 1000 5000 peak1;peak2;peak3
# Subtract B from A (remove covered bases)
bedtools subtract -a peaks.bed -b blacklist.bed
# Remove entire A feature if ANY B overlap
bedtools subtract -a peaks.bed -b exclusion.bed -A
# Find genomic gaps (complement of covered regions)
bedtools complement -i merged.bed -g genome.txt
Module 3: Coverage Analysis
Calculate depth and breadth of read coverage over features.
# Coverage stats per feature (count, bases covered, % covered)
bedtools coverage -a target_genes.bed -b aligned.bam
# Output: chr start end gene n_overlapping_reads bases_covered feature_len fraction_covered
# Per-base depth within each feature
bedtools coverage -a targets.bed -b aligned.bam -d
# Output: chr start end name position depth
# Coverage histogram per feature
bedtools coverage -a features.bed -b aligned.bam -hist
# Genome-wide BEDGRAPH (coverage per bin)
bedtools genomecov -ibam aligned.bam -bg -o coverage.bedgraph
# Include zero-coverage regions (for whole-genome coverage)
bedtools genomecov -ibam aligned.bam -bga > full_coverage.bedgraph
# Per-base depth for whole genome
bedtools genomecov -ibam aligned.bam -d > depth.txt
# Scaled BEDGRAPH (RPM normalization: total=50M reads → scale=1/50)
bedtools genomecov -ibam aligned.bam -bg -scale 0.00000002 > rpm.bedgraph
# Strand-specific coverage tracks
bedtools genomecov -ibam rnaseq.bam -bg -strand + > forward.bedgraph
bedtools genomecov -ibam rnaseq.bam -bg -strand - > reverse.bedgraph
Module 4: Sequence Extraction and Nearest Feature
Extract genomic sequences and annotate features with neighbors.
# Extract FASTA sequences for each BED region
bedtools getfasta -fi genome.fa -bed regions.bed -fo sequences.fasta
# Strand-aware extraction (reverse complement - strand)
bedtools getfasta -fi genome.fa -bed regions.bed -s -fo stranded.fasta
# Custom FASTA headers (name + coords)
bedtools getfasta -fi genome.fa -bed peaks.bed -name -fo named.fasta
# Extract and concatenate exons (BED12 spliced transcripts)
bedtools getfasta -fi genome.fa -bed transcripts.bed12 -split -fo exons.fasta
# Find nearest gene to each peak (with distance)
bedtools closest -a peaks.bed -b genes.bed -d
# Output: peak fields... | gene fields... | distance_bp
# Nearest feature on same strand only
bedtools closest -a peaks.bed -b genes.bed -s -d
# Ignore overlapping features (find nearest non-overlapping)
bedtools closest -a peaks.bed -b genes.bed -io -d
# Multiple annotation databases
bedtools closest -a query.bed -b genes.bed enhancers.bed \
-names genes enhancers -d
Module 5: Interval Manipulation
Expand, contract, and shift genomic intervals.
# Expand regions by 500 bp on each side
bedtools slop -i peaks.bed -g genome.txt -b 500
# Asymmetric: 2000 bp upstream, 500 bp downstream of TSS
bedtools slop -i tss.bed -g genome.txt -l 2000 -r 500
# Strand-aware expansion (upstream = 5' side)
bedtools slop -i genes.bed -g genome.txt -l 1000 -r 200 -s
# Create flanking regions (not overlapping the feature)
bedtools flank -i genes.bed -g genome.txt -b 1000
bedtools flank -i genes.bed -g genome.txt -l 2000 -r 0 -s # upstream only
Key Concepts
Coordinate Systems
BED files use 0-based half-open intervals: start is 0-indexed (like Python), end is exclusive. A region chr1:1000-2000 in BED covers bases 1000–1999 (1000 bases).
chr1 1000 2000 peak1 ← covers positions 1000,1001,...,1999
# BED: 0-based start, exclusive end
# VCF: 1-based position (POS)
# GFF: 1-based start and end (both inclusive)
bedtools converts internally — input format is auto-detected. Problems arise when mixing tools with different conventions.
Sorting Requirements
Most bedtools operations require coordinate-sorted input. Pre-sort with:
sort -k1,1 -k2,2n input.bed > sorted.bed
# For large files, use -S 4G for 4 GB sort buffer
sort -k1,1 -k2,2n -S 4G --parallel=8 input.bed > sorted.bed
The -sorted flag in bedtools intersect uses a sweep algorithm that requires sorted input but uses O(1) memory instead of O(N).
Common Workflows
Workflow 1: ChIP-seq Peak Annotation
Goal: Annotate peaks with overlapping genes, distances to TSS, and filter blacklisted regions.
#!/bin/bash
PEAKS="peaks.bed"
GENES="refseq_genes.bed"
TSS="refseq_tss.bed" # BED with TSS positions
BLACKLIST="encode_blacklist_hg38.bed"
GENOME="hg38.genome"
# 1. Remove blacklisted regions
bedtools subtract -a $PEAKS -b $BLACKLIST -A > peaks_clean.bed
echo "After blacklist filter: $(wc -l < peaks_clean.bed) peaks"
# 2. Annotate with overlapping gene (allow 2 kb from gene body)
bedtools slop -i $GENES -g $GENOME -b 2000 > genes_padded.bed
bedtools intersect -a peaks_clean.bed -b genes_padded.bed -wa -wb \
> peaks_gene_overlap.bed
# 3. For non-overlapping peaks: find nearest gene
bedtools intersect -a peaks_clean.bed -b genes_padded.bed -v > peaks_distal.bed
bedtools closest -a peaks_distal.bed -b $TSS -d > peaks_distal_nearest.bed
echo "Promoter peaks: $(wc -l < peaks_gene_overlap.bed)"
echo "Distal peaks: $(wc -l < peaks_distal.bed)"
Workflow 2: Coverage Analysis for WES Target Regions
Goal: Calculate on-target read depth and coverage breadth for exome sequencing QC.
#!/bin/bash
BAM="sample.deduped.bam"
TARGETS="capture_targets.bed"
# Per-target coverage statistics
bedtools coverage -a $TARGETS -b $BAM > per_target_coverage.bed
# Summary: total targets, mean depth, % at ≥20×
awk 'BEGIN{n=0; depth=0; covered=0}
{n++; depth+=$7; if($8>=20) covered++}
END{printf "Targets: %d\nMean depth: %.1f×\n%% at 20×: %.1f%%\n",
n, depth/n, covered/n*100}' per_target_coverage.bed
# Per-base depth for IGV visualization
bedtools coverage -a $TARGETS -b $BAM -d > per_base_depth.txt
echo "Per-base depth written to per_base_depth.txt"
Key Parameters
| Parameter
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
118.9kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
hyperframes
87.1kAI video you can actually edit. HyperFrames is a free, open-source AI video editor. Describe any video and get a real project you can change down to the frame.
ai-job-search
72.6kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.5kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
