[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7EDNHJC587P04Y7PH603VSG":3,"skill-same:01M7EDNHJC587P04Y7PH603VSG":66},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":30,"commitSha":31,"skillDirectory":32,"forksCount":14,"repositoryHtmlUrl":33,"repositoryHomepageUrl":33,"ownerHtmlUrl":34,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":35,"install":36,"resources":49},"01M7EDNHJC587P04Y7PH603VSG","bio-genome-intervals-interval-arithmetic",null,"Performs set operations on genomic intervals - intersect (-wa\u002F-wb\u002F-wo\u002F-wao\u002F-loj\u002F-c\u002F-v\u002F-u), subtract (-A), merge (-d, -c\u002F-o), complement, cluster, multiinter, unionbedg, map, and groupby - with bedtools (CLI) and pybedtools\u002Fpyranges\u002Fbioframe (Python). Covers the sorted-input contract and the -sorted chromosome-order footgun, reciprocal\u002Ffractional overlap (-f\u002F-F\u002F-r\u002F-e) and the A-vs-B asymmetry, -split for spliced\u002FBED12\u002FBAM features, and jaccard\u002Ffisher as mechanics only. Use when finding overlapping or unique regions between BED\u002Fpeak\u002Ffeature files, building consensus peaksets, removing blacklisted regions, transferring annotation values onto intervals, or computing interval-set similarity; route overlap-significance testing to overlap-significance.","Mr-Nobody-Anonymous\u002FAll-skills","Mr-Nobody-Anonymous","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F184253119?v=4","01M7AEXFJHKTYQW5R0ZCQQTWFV","anonymous","01M7C00M3GQR4QKP9GZA42GFAK",0,"MIT","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fbiology\u002Fbio-genome-intervals-interval-arithmetic\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: bio-genome-intervals-interval-arithmetic\ndescription: Performs set operations on genomic intervals - intersect (-wa\u002F-wb\u002F-wo\u002F-wao\u002F-loj\u002F-c\u002F-v\u002F-u), subtract (-A), merge (-d, -c\u002F-o), complement, cluster, multiinter, unionbedg, map, and groupby - with bedtools (CLI) and pybedtools\u002Fpyranges\u002Fbioframe (Python). Covers the sorted-input contract and the -sorted chromosome-order footgun, reciprocal\u002Ffractional overlap (-f\u002F-F\u002F-r\u002F-e) and the A-vs-B asymmetry, -split for spliced\u002FBED12\u002FBAM features, and jaccard\u002Ffisher as mechanics only. Use when finding overlapping or unique regions between BED\u002Fpeak\u002Ffeature files, building consensus peaksets, removing blacklisted regions, transferring annotation values onto intervals, or computing interval-set similarity; route overlap-significance testing to overlap-significance.\ntool_type: mixed\nprimary_tool: bedtools\nsource: \"https:\u002F\u002Fgithub.com\u002FGPTomics\u002FbioSkills\"\nsource_repository: \"GPTomics\u002FbioSkills\"\nsource_path: \"genome-intervals\u002Finterval-arithmetic\u002FSKILL.md\"\nlicense: \"MIT\"\nimported_at: \"2026-09-20\"\n---\n\n## Version Compatibility\n\nReference examples tested with: bedtools 2.31+, pybedtools 0.10+, pyranges 0.1+ (or 1.0+ - see note), bioframe 0.7+.\n\nBefore using code patterns, verify installed versions match. If versions differ:\n- CLI: `bedtools --version` then `bedtools \u003Csubcommand> --help` to confirm flags\n- Python: `pip show \u003Cpackage>` then `help(module.function)` to check signatures\n\npyranges has a major-version API split: pyranges 0.x and the 1.0 rewrite (package `pyranges1`) differ in method names and return shapes. Verify with `import pyranges; pyranges.__version__` before pasting v0 idioms. If code throws an error, introspect the installed package and adapt rather than retrying.\n\n# Interval Arithmetic\n\n**\"Which of my peaks overlap promoters, and how do I combine\u002Fsubtract\u002Fannotate interval sets?\"** -> Apply exact, deterministic set operations to sorted interval files, guarding the preconditions (prior `sort`, the `-sorted` chromosome-order contract, `-split`) that otherwise corrupt the answer.\n- CLI: `bedtools intersect -a a.bed -b b.bed -u`, `bedtools merge`, `bedtools subtract`, `bedtools map -c 4 -o mean`\n- Python: `a.intersect(b, u=True)`, `a.merge()` (pybedtools); `pr_a.overlap(pr_b)` (pyranges); `bf.overlap(df1, df2)` (bioframe)\n\n## The Single Most Important Modern Insight -- The Arithmetic Is Exact; the Danger Is the Silent Preconditions\n\nThe set operations themselves are exact and deterministic - bedtools, pyranges, and bioframe compute identical geometry on the same 0-based half-open intervals. The bugs are never in the arithmetic; they hide in four preconditions that fail quietly, returning a plausible wrong answer with exit code 0:\n\n1. **`merge`, `map`, `closest`, `groupby` require prior `sort`.** `merge` only collapses records that are adjacent *in file order* - on unsorted input, overlapping intervals survive un-merged and downstream counts are wrong, with no warning.\n2. **`-sorted` requires sorted input in a shared chromosome order.** It swaps `intersect`'s in-memory interval tree for a low-memory chromosome sweep. Modern bedtools (>=~2.25) detects unsorted or differently-ordered `-sorted` input and errors out (exit 1: `... is not sorted` \u002F `chromomsome sort ordering ... is inconsistent`); older versions silently swept past overlaps and under-reported. Pass `-g genome.txt` to pin the expected chromosome order (reproducible, and it catches the subtler missing-chromosome cases). The mismatch that stays SILENT on every version is a chromosome-NAME difference (`chr1` vs `1`), which returns an empty result with no error.\n3. **`-split` changes whether the count is exons or the spanning envelope.** A BED12 record or spliced BAM read (CIGAR `N`) spans introns; without `-split` bedtools intersects the whole intron-spanning envelope, silently inflating RNA-seq overlaps. With `-split` it intersects only the blocks (exons).\n4. **A raw overlap count is not association.** Long features, clustered features, and uneven coverage all inflate it; the number means nothing without a null. bedtools `fisher` is a weak analytic screen, not the answer - route rigorous significance to overlap-significance.\n\n## Tool Taxonomy\n\n| Tool | Role | Mechanism | When |\n|------|------|-----------|------|\n| bedtools | CLI interval algebra (reference implementation) | streaming sweep on sorted input; in-memory tree otherwise | shell pipelines, large files, reproducible one-liners |\n| pybedtools | Python wrapper over bedtools | shells out to the bedtools binary; BedTool objects, flags as kwargs | inside a Python script; need exact bedtools parity; chaining with pandas |\n| pyranges | pure-Python vectorized engine | native NumPy\u002Fpandas PyRanges; no bedtools dependency | large in-memory joins, no bedtools install, dataframe-native; mind the v0\u002Fv1 split |\n| bioframe | functions on a plain pandas DataFrame | vectorized pandas merges; columns `chrom\u002Fstart\u002Fend` | data already in pandas \u002F the cooler-Hi-C ecosystem |\n\nAll three Python engines compute the same overlaps; the porting bugs are about default strand handling and return shape (pyranges `overlap` vs `join` vs `intersect`; bioframe `overlap` with `how=`), not geometry.\n\n## Decision Tree by Scenario\n\n| Scenario | Recommended | Why |\n|----------|-------------|-----|\n| Quick overlap on the command line | `bedtools intersect -u` | no Python overhead; reproducible one-liner |\n| Inside a pandas\u002FPython pipeline | pybedtools or pyranges\u002Fbioframe | stays in-process; pyranges\u002Fbioframe need no bedtools binary |\n| Whole-genome-scale intersect | `intersect -sorted -g genome.txt` | low-memory sweep; modern bedtools errors on a sort\u002Forder mismatch, `-g` pins the expected chromosome order |\n| Spliced reads \u002F BED12 vs exons | add `-split` | otherwise the intron-spanning envelope is intersected (RNA-seq inflation) |\n| Are two SV\u002FCNV calls the same event? | `-f 0.5 -r` (50% reciprocal) | one-sided fractions let a giant interval swallow a tiny one |\n| Transfer\u002Faggregate B values onto A | `bedtools map -c COL -o OP` | columnar alternative to `intersect -wo \\| groupby` |\n| Build consensus peakset from replicates | `cat \\| sort \\| merge -d N` | collapses replicate peaks within N bp |\n| Multi-sample shared-region map | `multiinter` \u002F `unionbedg` | presence\u002Fabsence (intervals) or stacked signal matrix |\n| Is the overlap more than chance? | -> overlap-significance | raw count is length\u002Fcoverage-confounded; needs a permutation null |\n| Peaks not yet called | -> chip-seq\u002Fpeak-calling or atac-seq\u002Fatac-peak-calling | this category operates on existing intervals |\n\n## Intersect - the Workhorse\n\nThe output-mode flags do not change *what overlaps*; they change *what gets printed* (the #1 source of confusion). Full flag semantics are in usage-guide.md.\n\n```bash\nbedtools intersect -a peaks.bed -b genes.bed -u            # whole A, once, if it overlaps >=1 B\nbedtools intersect -a peaks.bed -b genes.bed -v            # A features with NO overlap (set difference)\nbedtools intersect -a peaks.bed -b genes.bed -c            # per-A count of B hits (0 if none)\nbedtools intersect -a peaks.bed -b genes.bed -wa -wb       # whole A + whole B, one line per pair (\"join\")\nbedtools intersect -a peaks.bed -b genes.bed -loj          # left outer join: every A, NULL B if none\nbedtools intersect -a peaks.bed -b genes.bed -wo           # A+B+bp-of-overlap, only A with overlap\nbedtools intersect -a peaks.bed -b genes.bed -wao          # like -wo but A-with-no-overlap kept (B=., overlap=0)\n```\n\n```python\nimport pybedtools\n\na = pybedtools.BedTool('peaks.bed')\nb = pybedtools.BedTool('genes.bed')\na.intersect(b, u=True)            # flags become kwargs\na.intersect(b, wa=True, wb=True)\na.intersect(b, c=True)\n```\n\n## Subtract, Merge, Complement, Cluster\n\n```bash\nbedtools subtract -a a.bed -b b.bed             # clip the overlapping portions out of A (A can fragment)\nbedtools subtract -a a.bed -b b.bed -A          # drop the ENTIRE A feature if any part overlaps B\nbedtools sort -i a.bed | bedtools merge -d 0    # collapse overlapping + book-ended; -d 0 is the default\nbedtools sort -i a.bed | bedtools merge -c 4,5 -o distinct,sum   # summarize columns while merging\nbedtools complement -i a.bed -g genome.txt      # the gaps: genome NOT covered by A (genome file required)\nbedtools sort -i a.bed | bedtools cluster -d 0  # assign a cluster id to overlapping\u002Fadjacent features\n```\n\nValid `-o` operations: `sum, min, max, absmin, absmax, mean, median, mode, antimode, stdev, sstdev, collapse, distinct, count, count_distinct, first, last`. `merge -d 0` merges overlapping and book-ended (touching) features but NOT a 1 bp gap; `-d 1` does.\n\n## Map - Transfer Values, and Groupby - Aggregate\n\n**Goal:** Summarize a column of overlapping B features onto each A interval (e.g. mean signal per gene).\n\n**Approach:** For each sorted A interval, `map` collects overlapping B features and applies an aggregation `-o` to a B column `-c`; `groupby` is the single-file SQL-style aggregator after an `intersect -wo`.\n\n```bash\nbedtools map -a genes.bed -b scores.bedgraph -c 4 -o mean      # both inputs MUST be sorted\nbedtools intersect -a genes.bed -b peaks.bed -wo \\\n  | bedtools groupby -g 1,2,3,4 -c 13 -o sum                   # group on A cols, sum the overlap-bp col\n```\n\n```python\nimport pybedtools\n\ngenes = pybedtools.BedTool('genes.bed').sort()\nscores = pybedtools.BedTool('scores.bedgraph').sort()\ngenes.map(scores, c=4, o='mean')\n```\n\n## Multi-Sample: Multiinter and Unionbedg\n\n```bash\nbedtools multiinter -header -names s1 s2 s3 -i s1.bed s2.bed s3.bed   # which files cover each sub-interval\nbedtools unionbedg -header -names s1 s2 s3 -i s1.bg s2.bg s3.bg       # stack bedGraph signal into a matrix\n```\n\n`multiinter` is the interval presence\u002Fabsence map (build a consensus by filtering its `num`\u002F`list` columns); `unionbedg` is its signal-track analog.\n\n## Jaccard and Fisher - Mechanics Only\n\n`jaccard` is a single similarity scalar `|A n B| \u002F |A u B|` in [0,1], useful for all-vs-all dataset clustering - it is NOT a significance test (no p-value). `fisher` builds a 2x2 table and returns a Fisher p, but it estimates the in-neither cell from a mean-interval-size\u002Fgenome-size heuristic, ignores genome structure, and is prone to inflation - treat it as a fast triage screen only.\n\n```bash\nbedtools jaccard -a a.bed -b b.bed -g genome.txt        # both sorted; reports jaccard + n_intersections\nbedtools fisher  -a a.bed -b b.bed -g genome.txt         # weak analytic null; validate any low p by simulation\n```\n\nFor a defensible enrichment p-value (size-preserving permutation in an accessible workspace, GAT\u002FregioneR\u002FLOLA\u002FGREAT), route to overlap-significance.\n\n## Per-Method Failure Modes\n\n### Merge without sorting first\n**Trigger:** `bedtools merge` (or `cluster`\u002F`map`\u002F`groupby`) on unsorted input. **Mechanism:** merge only collapses records adjacent in file order. **Symptom:** overlapping intervals survive un-merged; counts wrong, no error. **Fix:** `bedtools sort -i in.bed | bedtools merge`.\n\n### `-sorted` on unsorted or differently-ordered input\n**Trigger:** `intersect -sorted` on unsorted input or files in different chromosome orders. **Mechanism:** the sweep walks both files in lockstep assuming a shared order. **Symptom:** modern bedtools (>=~2.25) errors out (`... is not sorted` \u002F `chromomsome sort ordering ... is inconsistent`, exit 1); pre-2.25 returned a silently smaller set. **Fix:** sort every input identically and pass `-g genome.txt` to pin the order; on an old bedtools, suspect this when a result is surprisingly small.\n\n### Missing `-split` on spliced features\n**Trigger:** intersecting BED12 \u002F spliced BAM without `-split`. **Mechanism:** the intron-spanning envelope is treated as solid. **Symptom:** intronic positions \"overlap\" exons; RNA-seq overlap inflated\u002Fsmeared. **Fix:** add `-split` whenever an operand is BED12 or a spliced alignment and exon-level truth is required.\n\n### `-f` vs `-F` swapped, or default 1 bp overlap\n**Trigger:** thresholding the wrong set, or no `-f` at all. **Mechanism:** `-f` is a fraction of A, `-F` a fraction of B (default `-f 1e-9` = any 1 bp); A and B play asymmetric roles. **Symptom:** a tiny peak \"inside\" a 2 Mb gene by one base; swapping `-a`\u002F`-b` changes counts. **Fix:** threshold the *small* set; use `-r` for \"same event\" concordance.\n\n### complement\u002Fshuffle without a genome file\n**Trigger:** `complement` (or `closest`\u002F`map` order assumptions) without `-g`. **Mechanism:** bedtools cannot know where chromosomes end. **Symptom:** error, or gaps\u002Fcoordinates that run past chromosome ends. **Fix:** pass a correct `-g genome.txt` built from the same assembly.\n\n### chrom-naming mismatch (`chr1` vs `1`)\n**Trigger:** BED uses `chr1`, genome\u002Fother file uses `1`. **Mechanism:** chromosomes never match. **Symptom:** empty\u002Fzero output, no error. **Fix:** harmonize naming across all inputs and the genome file.\n\n## Quantitative Thresholds\n\n| Threshold | Source | Rationale |\n|-----------|--------|-----------|\n| Overlap fraction `-f` (state explicitly) | analysis choice | default `-f 1e-9` (1 bp) is rarely the biological question; threshold the small set |\n| 50% reciprocal overlap (`-f 0.5 -r`) | SV\u002FCNV field convention | \"are these the same event\"; one-sided lets a big interval swallow a small one |\n| Merge `-d` (e.g. 100 bp for replicate consensus) | replicate-merge convention | collapses near-coincident replicate peaks; tune per assay\u002Fresolution |\n| `merge -d 0` (default) | bedtools default | merges overlapping + book-ended, NOT a 1 bp gap (use `-d 1` for that) |\n\n## Common Errors\n\n| Error \u002F symptom | Cause | Solution |\n|-----------------|-------|----------|\n| Empty intersect output | chrom naming mismatch (`chr1` vs `1`) | harmonize naming across files + genome.txt |\n| `merge` left overlaps behind | input not sorted | `sort` before `merge`\u002F`cluster`\u002F`map`\u002F`groupby` |\n| `-sorted` errors or (old bedtools) returns too few | unsorted or mismatched chromosome order | sort all inputs identically; add `-g genome.txt` to pin order |\n| RNA-seq overlap looks inflated | missing `-split` on BED12\u002Fspliced BAM | add `-split` |\n| Negative start \u002F past-chromosome-end | wrong\u002Fmissing `-g genome.txt` | pass a correct chrom-sizes file |\n| pyranges AttributeError | 0.x vs 1.0 API mismatch | check `pyranges.__version__`; use matching method names |\n\n## References\n\n- Quinlan AR, Hall IM. 2010. BEDTools: a flexible suite of utilities for comparing genomic features. *Bioinformatics* 26:841-842.\n- Dale RK, Pedersen BS, Quinlan AR. 2011. Pybedtools: a flexible Python library for manipulating genomic datasets and annotations. *Bioinformatics* 27:3423-3424.\n- Stovner EB, Sætrom P. 2020. PyRanges: efficient comparison of genomic intervals in Python. *Bioinformatics* 36:918-919.\n- Open2C, Abdennur N, Fudenberg G, Flyamer IM, Galitsyna AA, Goloborodko A, Imakaev M, Venev SV. 2024. Bioframe: operations on genomic intervals in pandas dataframes. *Bioinformatics* 40:btae088.\n\n## Related Skills\n\n- bed-file-basics - BED format, coordinate systems, and the conversions this skill depends on\n- overlap-significance - Whether an overlap count exceeds a matched null (permutation, GAT\u002FregioneR\u002FLOLA\u002FGREAT)\n- proximity-operations - closest, window, flank, slop for adjacency rather than membership\n- coverage-analysis - per-base depth and bedGraph signal feeding map\u002Funionbedg\n- gtf-gff-handling - exon\u002Ffeature models whose `-split` behavior this skill depends on\n- chip-seq\u002Fpeak-calling - source of the peak BED files these operations consume\n- atac-seq\u002Fconsensus-peakset - replicate merge via merge\u002Fmultiinter\n","## Version Compatibility\n\nReference examples tested with: bedtools 2.31+, pybedtools 0.10+, pyranges 0.1+ (or 1.0+ - see note), bioframe 0.7+.\n\nBefore using code patterns, verify installed versions match. If versions differ:\n- CLI: `bedtools --version` then `bedtools \u003Csubcommand> --help` to confirm flags\n- Python: `pip show \u003Cpackage>` then `help(module.function)` to check signatures\n\npyranges has a major-version API split: pyranges 0.x and the 1.0 rewrite (package `pyranges1`) differ in method names and return shapes. Verify with `import pyranges; pyranges.__version__` before pasting v0 idioms. If code throws an error, introspect the installed package and adapt rather than retrying.\n\n# Interval Arithmetic\n\n**\"Which of my peaks overlap promoters, and how do I combine\u002Fsubtract\u002Fannotate interval sets?\"** -> Apply exact, deterministic set operations to sorted interval files, guarding the preconditions (prior `sort`, the `-sorted` chromosome-order contract, `-split`) that otherwise corrupt the answer.\n- CLI: `bedtools intersect -a a.bed -b b.bed -u`, `bedtools merge`, `bedtools subtract`, `bedtools map -c 4 -o mean`\n- Python: `a.intersect(b, u=True)`, `a.merge()` (pybedtools); `pr_a.overlap(pr_b)` (pyranges); `bf.overlap(df1, df2)` (bioframe)\n\n## The Single Most Important Modern Insight -- The Arithmetic Is Exact; the Danger Is the Silent Preconditions\n\nThe set operations themselves are exact and deterministic - bedtools, pyranges, and bioframe compute identical geometry on the same 0-based half-open intervals. The bugs are never in the arithmetic; they hide in four preconditions that fail quietly, returning a plausible wrong answer with exit code 0:\n\n1. **`merge`, `map`, `closest`, `groupby` require prior `sort`.** `merge` only collapses records that are adjacent *in file order* - on unsorted input, overlapping intervals survive un-merged and downstream counts are wrong, with no warning.\n2. **`-sorted` requires sorted input in a shared chromosome order.** It swaps `intersect`'s in-memory interval tree for a low-memory chromosome sweep. Modern bedtools (>=~2.25) detects unsorted or differently-ordered `-sorted` input and errors out (exit 1: `... is not sorted` \u002F `chromomsome sort ordering ... is inconsistent`); older versions silently swept past overlaps and under-reported. Pass `-g genome.txt` to pin the expected chromosome order (reproducible, and it catches the subtler missing-chromosome cases). The mismatch that stays SILENT on every version is a chromosome-NAME difference (`chr1` vs `1`), which returns an empty result with no error.\n3. **`-split` changes whether the count is exons or the spanning envelope.** A BED12 record or spliced BAM read (CIGAR `N`) spans introns; without `-split` bedtools intersects the whole intron-spanning envelope, silently inflating RNA-seq overlaps. With `-split` it intersects only the blocks (exons).\n4. **A raw overlap count is not association.** Long features, clustered features, and uneven coverage all inflate it; the number means nothing without a null. bedtools `fisher` is a weak analytic screen, not the answer - route rigorous significance to overlap-significance.\n\n## Tool Taxonomy\n\n| Tool | Role | Mechanism | When |\n|------|------|-----------|------|\n| bedtools | CLI interval algebra (reference implementation) | streaming sweep on sorted input; in-memory tree otherwise | shell pipelines, large files, reproducible one-liners |\n| pybedtools | Python wrapper over bedtools | shells out to the bedtools binary; BedTool objects, flags as kwargs | inside a Python script; need exact bedtools parity; chaining with pandas |\n| pyranges | pure-Python vectorized engine | native NumPy\u002Fpandas PyRanges; no bedtools dependency | large in-memory joins, no bedtools install, dataframe-native; mind the v0\u002Fv1 split |\n| bioframe | functions on a plain pandas DataFrame | vectorized pandas merges; columns `chrom\u002Fstart\u002Fend` | data already in pandas \u002F the cooler-Hi-C ecosystem |\n\nAll three Python engines compute the same overlaps; the porting bugs are about default strand handling and return shape (pyranges `overlap` vs `join` vs `intersect`; bioframe `overlap` with `how=`), not geometry.\n\n## Decision Tree by Scenario\n\n| Scenario | Recommended | Why |\n|----------|-------------|-----|\n| Quick overlap on the command line | `bedtools intersect -u` | no Python overhead; reproducible one-liner |\n| Inside a pandas\u002FPython pipeline | pybedtools or pyranges\u002Fbioframe | stays in-process; pyranges\u002Fbioframe need no bedtools binary |\n| Whole-genome-scale intersect | `intersect -sorted -g genome.txt` | low-memory sweep; modern bedtools errors on a sort\u002Forder mismatch, `-g` pins the expected chromosome order |\n| Spliced reads \u002F BED12 vs exons | add `-split` | otherwise the intron-spanning envelope is intersected (RNA-seq inflation) |\n| Are two SV\u002FCNV calls the same event? | `-f 0.5 -r` (50% reciprocal) | one-sided fractions let a giant interval swallow a tiny one |\n| Transfer\u002Faggregate B values onto A | `bedtools map -c COL -o OP` | columnar alternative to `intersect -wo \\| groupby` |\n| Build consensus peakset from replicates | `cat \\| sort \\| merge -d N` | collapses replicate peaks within N bp |\n| Multi-sample shared-region map | `multiinter` \u002F `unionbedg` | presence\u002Fabsence (intervals) or stacked signal matrix |\n| Is the overlap more than chance? | -> overlap-significance | raw count is length\u002Fcoverage-confounded; needs a permutation null |\n| Peaks not yet called | -> chip-seq\u002Fpeak-calling or atac-seq\u002Fatac-peak-calling | this category operates on existing intervals |\n\n## Intersect - the Workhorse\n\nThe output-mode flags do not change *what overlaps*; they change *what gets printed* (the #1 source of confusion). Full flag semantics are in usage-guide.md.\n\n```bash\nbedtools intersect -a peaks.bed -b genes.bed -u            # whole A, once, if it overlaps >=1 B\nbedtools intersect -a peaks.bed -b genes.bed -v            # A features with NO overlap (set difference)\nbedtools intersect -a peaks.bed -b genes.bed -c            # per-A count of B hits (0 if none)\nbedtools intersect -a peaks.bed -b genes.bed -wa -wb       # whole A + whole B, one line per pair (\"join\")\nbedtools intersect -a peaks.bed -b genes.bed -loj          # left outer join: every A, NULL B if none\nbedtools intersect -a peaks.bed -b genes.bed -wo           # A+B+bp-of-overlap, only A with overlap\nbedtools intersect -a peaks.bed -b genes.bed -wao          # like -wo but A-with-no-overlap kept (B=., overlap=0)\n```\n\n```python\nimport pybedtools\n\na = pybedtools.BedTool('peaks.bed')\nb = pybedtools.BedTool('genes.bed')\na.intersect(b, u=True)            # flags become kwargs\na.intersect(b, wa=True, wb=True)\na.intersect(b, c=True)\n```\n\n## Subtract, Merge, Complement, Cluster\n\n```bash\nbedtools subtract -a a.bed -b b.bed             # clip the overlapping portions out of A (A can fragment)\nbedtools subtract -a a.bed -b b.bed -A          # drop the ENTIRE A feature if any part overlaps B\nbedtools sort -i a.bed | bedtools merge -d 0    # collapse overlapping + book-ended; -d 0 is the default\nbedtools sort -i a.bed | bedtools merge -c 4,5 -o distinct,sum   # summarize columns while merging\nbedtools complement -i a.bed -g genome.txt      # the gaps: genome NOT covered by A (genome file required)\nbedtools sort -i a.bed | bedtools cluster -d 0  # assign a cluster id to overlapping\u002Fadjacent features\n```\n\nValid `-o` operations: `sum, min, max, absmin, absmax, mean, median, mode, antimode, stdev, sstdev, collapse, distinct, count, count_distinct, first, last`. `merge -d 0` merges overlapping and book-ended (touching) features but NOT a 1 bp gap; `-d 1` does.\n\n## Map - Transfer Values, and Groupby - Aggregate\n\n**Goal:** Summarize a column of overlapping B features onto each A interval (e.g. mean signal per gene).\n\n**Approach:** For each sorted A interval, `map` collects overlapping B features and applies an aggregation `-o` to a B column `-c`; `groupby` is the single-file SQL-style aggregator after an `intersect -wo`.\n\n```bash\nbedtools map -a genes.bed -b scores.bedgraph -c 4 -o mean      # both inputs MUST be sorted\nbedtools intersect -a genes.bed -b peaks.bed -wo \\\n  | bedtools groupby -g 1,2,3,4 -c 13 -o sum                   # group on A cols, sum the overlap-bp col\n```\n\n```python\nimport pybedtools\n\ngenes = pybedtools.BedTool('genes.bed').sort()\nscores = pybedtools.BedTool('scores.bedgraph').sort()\ngenes.map(scores, c=4, o='mean')\n```\n\n## Multi-Sample: Multiinter and Unionbedg\n\n```bash\nbedtools multiinter -header -names s1 s2 s3 -i s1.bed s2.bed s3.bed   # which files cover each sub-interval\nbedtools unionbedg -header -names s1 s2 s3 -i s1.bg s2.bg s3.bg       # stack bedGraph signal into a matrix\n```\n\n`multiinter` is the interval presence\u002Fabsence map (build a consensus by filtering its `num`\u002F`list` columns); `unionbedg` is its signal-track analog.\n\n## Jaccard and Fisher - Mechanics Only\n\n`jaccard` is a single similarity scalar `|A n B| \u002F |A u B|` in [0,1], useful for all-vs-all dataset clustering - it is NOT a significance test (no p-value). `fisher` builds a 2x2 table and returns a Fisher p, but it estimates the in-neither cell from a mean-interval-size\u002Fgenome-size heuristic, ignores genome structure, and is prone to inflation - treat it as a fast triage screen only.\n\n```bash\nbedtools jaccard -a a.bed -b b.bed -g genome.txt        # both sorted; reports jaccard + n_intersections\nbedtools fisher  -a a.bed -b b.bed -g genome.txt         # weak analytic null; validate any low p by simulation\n```\n\nFor a defensible enrichment p-value (size-preserving permutation in an accessible workspace, GAT\u002FregioneR\u002FLOLA\u002FGREAT), route to overlap-significance.\n\n## Per-Method Failure Modes\n\n### Merge without sorting first\n**Trigger:** `bedtools merge` (or `cluster`\u002F`map`\u002F`groupby`) on unsorted input. **Mechanism:** merge only collapses records adjacent in file order. **Symptom:** overlapping intervals survive un-merged; counts wrong, no error. **Fix:** `bedtools sort -i in.bed | bedtools merge`.\n\n### `-sorted` on unsorted or differently-ordered input\n**Trigger:** `intersect -sorted` on unsorted input or files in different chromosome orders. **Mechanism:** the sweep walks both files in lockstep assuming a shared order. **Symptom:** modern bedtools (>=~2.25) errors out (`... is not sorted` \u002F `chromomsome sort ordering ... is inconsistent`, exit 1); pre-2.25 returned a silently smaller set. **Fix:** sort every input identically and pass `-g genome.txt` to pin the order; on an old bedtools, suspect this when a result is surprisingly small.\n\n### Missing `-split` on spliced features\n**Trigger:** intersecting BED12 \u002F spliced BAM without `-split`. **Mechanism:** the intron-spanning envelope is treated as solid. **Symptom:** intronic positions \"overlap\" exons; RNA-seq overlap inflated\u002Fsmeared. **Fix:** add `-split` whenever an operand is BED12 or a spliced alignment and exon-level truth is required.\n\n### `-f` vs `-F` swapped, or default 1 bp overlap\n**Trigger:** thresholding the wrong set, or no `-f` at all. **Mechanism:** `-f` is a fraction of A, `-F` a fraction of B (default `-f 1e-9` = any 1 bp); A and B play asymmetric roles. **Symptom:** a tiny peak \"inside\" a 2 Mb gene by one base; swapping `-a`\u002F`-b` changes counts. **Fix:** threshold the *small* set; use `-r` for \"same event\" concordance.\n\n### complement\u002Fshuffle without a genome file\n**Trigger:** `complement` (or `closest`\u002F`map` order assumptions) without `-g`. **Mechanism:** bedtools cannot know where chromosomes end. **Symptom:** error, or gaps\u002Fcoordinates that run past chromosome ends. **Fix:** pass a correct `-g genome.txt` built from the same assembly.\n\n### chrom-naming mismatch (`chr1` vs `1`)\n**Trigger:** BED uses `chr1`, genome\u002Fother file uses `1`. **Mechanism:** chromosomes never match. **Symptom:** empty\u002Fzero output, no error. **Fix:** harmonize naming across all inputs and the genome file.\n\n## Quantitative Thresholds\n\n| Threshold | Source | Rationale |\n|-----------|--------|-----------|\n| Overlap fraction `-f` (state explicitly) | analysis choice | default `-f 1e-9` (1 bp) is rarely the biological question; threshold the small set |\n| 50% reciprocal overlap (`-f 0.5 -r`) | SV\u002FCNV field convention | \"are these the same event\"; one-sided lets a big interval swallow a small one |\n| Merge `-d` (e.g. 100 bp for replicate consensus) | replicate-merge convention | collapses near-coincident replicate peaks; tune per assay\u002Fresolution |\n| `merge -d 0` (default) | bedtools default | merges overlapping + book-ended, NOT a 1 bp gap (use `-d 1` for that) |\n\n## Common Errors\n\n| Error \u002F symptom | Cause | Solution |\n|-----------------|-------|----------|\n| Empty intersect output | chrom naming mismatch (`chr1` vs `1`) | harmonize naming across files + genome.txt |\n| `merge` left overlaps behind | input not sorted | `sort` before `merge`\u002F`cluster`\u002F`map`\u002F`groupby` |\n| `-sorted` errors or (old bedtools) returns too few | unsorted or mismatched chromosome order | sort all inputs identically; add `-g genome.txt` to pin order |\n| RNA-seq overlap looks inflated | missing `-split` on BED12\u002Fspliced BAM | add `-split` |\n| Negative start \u002F past-chromosome-end | wrong\u002Fmissing `-g genome.txt` | pass a correct chrom-sizes file |\n| pyranges AttributeError | 0.x vs 1.0 API mismatch | check `pyranges.__version__`; use matching method names |\n\n## References\n\n- Quinlan AR, Hall IM. 2010. BEDTools: a flexible suite of utilities for comparing genomic features. *Bioinformatics* 26:841-842.\n- Dale RK, Pedersen BS, Quinlan AR. 2011. Pybedtools: a flexible Python library for manipulating genomic datasets and annotations. *Bioinformatics* 27:3423-3424.\n- Stovner EB, Sætrom P. 2020. PyRanges: efficient comparison of genomic intervals in Python. *Bioinformatics* 36:918-919.\n- Open2C, Abdennur N, Fudenberg G, Flyamer IM, Galitsyna AA, Goloborodko A, Imakaev M, Venev SV. 2024. Bioframe: operations on genomic intervals in pandas dataframes. *Bioinformatics* 40:btae088.\n\n## Related Skills\n\n- bed-file-basics - BED format, coordinate systems, and the conversions this skill depends on\n- overlap-significance - Whether an overlap count exceeds a matched null (permutation, GAT\u002FregioneR\u002FLOLA\u002FGREAT)\n- proximity-operations - closest, window, flank, slop for adjacency rather than membership\n- coverage-analysis - per-base depth and bedGraph signal feeding map\u002Funionbedg\n- gtf-gff-handling - exon\u002Ffeature models whose `-split` behavior this skill depends on\n- chip-seq\u002Fpeak-calling - source of the peak BED files these operations consume\n- atac-seq\u002Fconsensus-peakset - replicate merge via merge\u002Fmultiinter\n",{"name":5,"source":24,"license":15,"tool_type":25,"description":7,"imported_at":26,"source_path":27,"primary_tool":28,"source_repository":29},"https:\u002F\u002Fgithub.com\u002FGPTomics\u002FbioSkills","mixed","2026-09-20","genome-intervals\u002Finterval-arithmetic\u002FSKILL.md","bedtools","GPTomics\u002FbioSkills","main","2d1750717747097b602acf30bd09a7cbd4b4c6ea","awesome_skills\u002Fbiology\u002Fbio-genome-intervals-interval-arithmetic","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous","2026-11-09 11:45:36",{"source":8,"skillName":5,"commands":37,"prompt":47,"zipAvailable":48},[38,41,44],{"tool":39,"command":40},"npx","npx skills add Mr-Nobody-Anonymous\u002FAll-skills --skill bio-genome-intervals-interval-arithmetic",{"tool":42,"command":43},"bunx","bunx skills add Mr-Nobody-Anonymous\u002FAll-skills --skill bio-genome-intervals-interval-arithmetic",{"tool":45,"command":46},"pnpm","pnpm dlx skills add Mr-Nobody-Anonymous\u002FAll-skills --skill bio-genome-intervals-interval-arithmetic","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fbiology\u002Fbio-genome-intervals-interval-arithmetic\u002FSKILL.md",true,[50,56,60],{"path":51,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":54,"sourceHtmlUrl":55},"examples\u002Fintersect_examples.sh","SCRIPT","脚本",2230,"https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fbiology\u002Fbio-genome-intervals-interval-arithmetic\u002Fexamples\u002Fintersect_examples.sh",{"path":57,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":58,"sourceHtmlUrl":59},"examples\u002Finterval_operations.py",2278,"https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fbiology\u002Fbio-genome-intervals-interval-arithmetic\u002Fexamples\u002Finterval_operations.py",{"path":61,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":64,"sourceHtmlUrl":65},"usage-guide.md","REFERENCE","参考文档",6268,"https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fbiology\u002Fbio-genome-intervals-interval-arithmetic\u002Fusage-guide.md",[67,75,82,89,96,103],{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":74},"01M7FFFZPC2025JQQHPHDX154J","dei-assessment","Assess diversity, equity, and inclusion with metrics. TRIGGERS - Use when user needs help with dei-assessment related tasks.","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fhr-people\u002Fdei-assessment\u002FSKILL.md",[],[],"2026-11-16 10:05:34",{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":74},"01M7FFFWN8H4WA7A6Y398QKB6J","dei-action-plan","Create DEI action plans with goals and initiatives. TRIGGERS - Use when user needs help with dei-action-plan related tasks.","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fhr-people\u002Fdei-action-plan\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":74},"01M7FFFSHTM0QZRVZ2NRJTJ0PY","culture-fit-assessment","Design culture add assessment processes. TRIGGERS - Use when user needs help with culture-fit-assessment related tasks.","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fhr-people\u002Fculture-fit-assessment\u002FSKILL.md",[],[],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":74},"01M7FFFMA12RKEQA38KHJSXXPS","cowork-to-code-bridge","Use an already-installed, independently verified cowork-to-code bridge to run narrowly approved actions on the user's own macOS, Linux, or WSL2 machine through a local file queue.","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fhr-people\u002Fcowork-to-code-bridge\u002FSKILL.md",[],[],{"skillNo":97,"name":98,"nameZh":6,"description":99,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":74},"01M7FFFH1F6M8YRGW5V487GH1K","counter-offer-response","Draft counter-offer responses for retention. TRIGGERS - Use when user needs help with counter-offer-response related tasks.","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fhr-people\u002Fcounter-offer-response\u002FSKILL.md",[],[],{"skillNo":104,"name":105,"nameZh":6,"description":106,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":109,"publishedAt":74},"01M7FFFDGEHV8Y7J9N40HZXW52","continuous-feedback-system","Design continuous feedback systems. TRIGGERS - Use when user needs help with continuous-feedback-system related tasks.","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fhr-people\u002Fcontinuous-feedback-system\u002FSKILL.md",[],[]]