/homer-motif-analysis

name: "homer-motif-analysis"
description: "De novo and known TF motif enrichment in ChIP-seq/ATAC-seq peaks via HOMER. findMotifsGenome.pl finds over-represented patterns vs background; annotatePeaks.pl assigns context (TSS distance, gene, repeat). Use after MACS3 to identify enriched TFs, annotate peaks with nearest genes, and validate ChIP-seq via the target motif."
license: "GPL-3.0"

HOMER — Motif Analysis and Peak Annotation

Overview

HOMER (Hypergeometric Optimization of Motif EnRichment) is a suite of Perl/C++ tools for analyzing genomic regulatory elements. Its two primary commands are `findMotifsGenome.pl`, which performs de novo motif discovery and known motif enrichment against JASPAR/HOMER databases, and `annotatePeaks.pl`, which maps each peak to the nearest gene, distance to TSS, and genomic feature class (promoter, intron, intergenic, repeat). HOMER takes BED-format peak files from MACS3 or similar peak callers and a reference genome assembly as input, and outputs HTML/text reports ranking enriched motifs by p-value and fold enrichment over a matched background.

When to Use

• Identifying which transcription factors are bound in a ChIP-seq peak set by enriching their known motifs from JASPAR or the HOMER motif library
• Discovering novel sequence motifs de novo in open chromatin regions from ATAC-seq without prior knowledge of the binding TF
• Comparing motif landscapes between two conditions (e.g., treated vs. untreated peak sets) by running HOMER with one set as target and the other as background
• Annotating genomic peaks with nearest genes and distance to TSS for downstream functional analysis or integration with DESeq2 results
• Validating ChIP-seq experiment quality: a successful pull-down should show the target TF's canonical motif as the top hit
• Use `macs3-peak-calling` first to generate the peak BED files that serve as input to HOMER
• Use `jaspar-database` to cross-reference HOMER-discovered motifs with JASPAR IDs and additional TF metadata
• Use `MEME-CHIP` (web or local) when you need a more probabilistic ZOOPS/TCM model or the MEME Suite ecosystem
• Use `AME` (part of MEME Suite) as a faster alternative for known motif scanning without de novo discovery

Prerequisites

• **Software**: HOMER (Perl + compiled binaries), conda or manual install
• **Genomes**: must download genome sequence via `installGenome.pl` after HOMER install
• **Input**: BED file of peaks (at minimum: chr, start, end columns); ideally summit-centered peaks from MACS3
• **Python packages** (for parsing/visualization): `pandas`, `matplotlib`, `seaborn`

> **Check before installing**: The tool may already be available in the current environment (e.g., inside a `pixi` / `conda` env). Run `command -v findMotifsGenome.pl` first and skip the install commands below if it returns a path. When running inside a pixi project, invoke the tool via `pixi run findMotifsGenome.pl` rather than bare `findMotifsGenome.pl`.

# Install HOMER via conda (recommended — handles Perl dependencies)
conda install -c bioconda homer

# Verify installation
findMotifsGenome.pl 2>&1 | head -3
# Usage: findMotifsGenome.pl <peak/BED file> <genome> <output directory> [options]

annotatePeaks.pl 2>&1 | head -3
# Usage: annotatePeaks.pl <peak/BED file> <genome> [options]

# Install reference genomes (downloads 2-way masker + sequence; ~3–10 GB each)
installGenome.pl hg38
installGenome.pl mm10

# Install Python parsing dependencies
pip install pandas matplotlib seaborn

Pre-flight Interview

Settle these with the user before writing any analysis code.

decisions:
  - id: D1
    param: genomeAssembly
    kind: derived
    source: upstream
    ask: "Which assembly are the peak coordinates on?"
    default: "carried from the peak-calling stage"

  - id: D2
    param: searchWindow
    kind: required
    source: user
    ask: "How wide a window around each peak centre should be searched?"
    default: "200 bp for TF ChIP, 150 bp for ATAC"

  - id: D3
    param: backgroundRegions
    kind: required
    source: user
    ask: "Compare peaks against GC-matched random genomic regions, or against a specific control set?"
    default: "auto-generated GC-matched background"

  - id: D4
    param: repeatMasking
    kind: required
    source: user
    ask: "Mask repetitive sequence, which otherwise dominates the enrichment as false positives?"
    default: "masked"

  - id: D5
    param: denovoDiscovery
    kind: required
    source: user
    ask: "Search for previously undescribed motifs, or only test the known-motif library?"
    default: "known motifs only - de novo discovery is roughly ten times slower"

  - id: D6
    param: motifLengths
    kind: optional
    source: user
    depends_on: [D5]
    ask: "Which motif widths should the de novo search try?"
    default: "8, 10, 12"
    skip_if: "de novo discovery disabled"

  - id: D7
    param: numDenovoMotifs
    kind: optional
    source: user
    depends_on: [D5]
    ask: "How many de novo motifs should be reported?"
    default: 25
    skip_if: "de novo discovery disabled"

  - id: D8
    param: knownMotifMismatches
    kind: optional
    source: user
    ask: "How loosely may a sequence match a known motif and still count?"
    default: 2

  - id: D9
    param: threads
    kind: never_ask
    source: data
    reason: "Affects runtime only, not the enrichment"
    default: "min(8, available_cores)"

D1 is derived rather than asked: peak coordinates are meaningless outside the assembly they were called on, so the answer is whatever the upstream stage used, not a preference. D3 is the decision most often left at its default without thought - a background that does not match the peaks in GC content produces enrichment for GC content rather than for biology.

Quick Start

# Run de novo + known motif enrichment on TF ChIP-seq peaks (hg38, 200 bp window)
findMotifsGenome.pl peaks/tf_chip_summits.bed hg38 motif_output/ \
    -size 200