Genomics Epigenomics

---
name: genomics-epigenomics
description: Load when summarising a peak file (BED / narrowPeak) from ATAC-seq / ChIP-seq / CUT&Tag — peak count, width distribution, per-chromosome counts, score statistics. Skip when calling peaks from BAM (run MACS / Genrich externally first) or when working with single-cell ATAC (use `scatac-preprocessing`).
version: 0.5.0
author: OmicsClaw
license: MIT
tags:
- genomics
- epigenomics
- atac-seq
- chip-seq
- cut-tag
- peaks
- macs
- bed
requires:
- pandas
- numpy
---

# genomics-epigenomics

## When to use

The user has a peak file (BED, narrowPeak, or broadPeak) from
ATAC-seq, ChIP-seq, or CUT&Tag and wants peak summary statistics:
total peak count, median / mean width, per-chromosome distribution,
optional score column statistics. The script consumes peak files —
it does NOT call peaks from BAM. `--method` (`macs2` / `macs3` /
`homer` / `genrich`) and `--assay` (`chip-seq` / `atac-seq` /
`cut-tag`) are recorded as metadata only.

For single-cell ATAC processing use `scatac-preprocessing`.

## Inputs & Outputs

| Input | Format | Required |
|---|---|---|
| Peaks | `.bed` (3-col or 6-col) or `.narrowPeak` (10-col); broadPeak (9-col) loads as BED6 with cols 7-9 dropped | yes (unless `--demo`) |
| Assay metadata | `--assay {chip-seq,atac-seq,cut-tag}` (default `chip-seq`) | no |
| Caller metadata | `--method {macs2,macs3,homer,genrich}` (default `macs2`) | no |

| Output | Path | Notes |
|---|---|---|
| Peaks summary | `tables/peaks_summary.csv` | per-peak start/end/width/score |
| Per-chromosome | `tables/peaks_per_chromosome.csv` | peaks count per chromosome |
| Report | `report.md` + `result.json` | always; `result.json["data"]["peaks_per_chrom"]` mirrors the table |

## Flow

1. Load peak file (`--input <peaks.bed|narrowPeak>`) or generate a demo at `output_dir/demo_peaks.narrowPeak` (`genomics_epigenomics.py:211`).
2. Parse coordinates; compute per-peak width.
3. Aggregate per-chromosome counts; per-`--assay` expected-width range is added to the report (`genomics_epigenomics.py:172-178`).
4. Write `tables/peaks_summary.csv` (`genomics_epigenomics.py:352`) + `tables/peaks_per_chromosome.csv` (`:360`) + `report.md` + `result.json` (`:366`).

## Gotchas

- **No peak caller is invoked.** This skill summarises an existing BED/narrowPeak file — it does NOT run MACS / Genrich. Run them upstream and feed the output here.
- **`--method` is metadata-only; `--assay` changes the report.** `--method` is recorded in `result.json` only. `--assay` controls the per-assay expected-peak-width range injected into the summary (`genomics_epigenomics.py:172-178`) — `chip-seq` reports 200-2000 bp, `atac-seq` 150-500 bp, `cut-tag` 150-300 bp. Peak parsing itself is identical across assays.
- **`--input` REQUIRED unless `--demo`.** `genomics_epigenomics.py:334` raises `ValueError("--input required when not using --demo")`; non-existent paths raise `FileNotFoundError` at `:337`.
- **3-column BED has no score column.** Without a score (col 5 in BED6 / narrowPeak), the summary statistics for "score" are NaN. Pre-convert to narrowPeak or BED6 for score-aware stats. Note: broadPeak's "signalValue" (col 7) and qValue (col 9) are NOT read — the parser only handles up to BED6 plus the narrowPeak 10-col extension.
- **Coordinate convention is 0-based half-open (BED).** Width = `end - start`. If your input uses 1-based closed coordinates, widths are off-by-one.
- **Demo BED has 500 fixed-pattern peaks.** Useful for orchestrator smoke tests; not biologically meaningful.

## Key CLI

```bash
# Demo
python omicsclaw.py run genomics-epigenomics --demo --output /tmp/epi_demo

# Real ATAC-seq peaks
python omicsclaw.py run genomics-epigenomics \
  --input sample_peaks.narrowPeak --output results/ \
  --assay atac-seq --method macs3
```

## See also

- `references/parameters.md` — every CLI flag
- `references/methodology.md` — peak-file format conventions, score interpretation
- `references/output_contract.md` — `tables/peaks_summary.csv` + per-chromosome
- Adjacent skills: `scatac-preprocessing` (parallel — single-cell ATAC), `genomics-alignment` (upstream — BAMs feed peak callers), `genomics-qc` (upstream — FASTQ QC before alignment), `bulkrna-de` (parallel — bulk RNA-seq differential expression)