name: genomic-feature-annotation
description: This skill is used to perform genomic feature annotation and visualization for any file containing genomic region information using Homer (Hypergeometric Optimization of Motif EnRichment). It annotates regions such as promoters, exons, introns, intergenic regions, and TSS proximity, and generates visual summaries of feature distributions. ChIPseeker mode is also supported according to requirements.

Genomic Feature Annotation and Visualization with Homer

Overview

• Prepare genomic region files in BED or other supported formats. Ensure that the input genomic regions are provided in a valid BED format (chromosome, start, end). If the file does not meet this format, extract the required columns to create a valid BED file.regions file.
• Identify and specify the correct genome assembly for annotation.
• Always prompt user for the tool to use, choose from ChIPseeker or HOMER
• If the user choose HOMER, then:
  • Annotate the genomic regions using Homer's annotatePeaks.pl.
  • Generate annotation statistics and feature distribution summaries.
  • Visualize annotation results (e.g., pie charts, barplots).

When to use this skill

• Find target genes of a certain TF. This skill will return an annotated peak file with the nearby genes of the TF. Genes whose promoter annotated to the TF peaks could be candidate target genes of the TF.
• Annotate the genomic regions like TF peaks, histone modification peaks, ATAC-seq peaks, etc.
• Generate annotation statistics and feature distribution summaries.
• Visualize annotation results (e.g., pie charts, barplots).

Inputs & Outputs

Inputs

Genomic region formats supported:
- BED files: Standard genomic interval format
- narrowPeak: narrow peak format
- broadPeak: broad peak format

Outputs

genomic_feature_annotation/
    results/
        ${sample}.anno_genomic_features.txt
        ${sample}.anno_genomic_features_stats.txt
    logs/
        ${sample}.anno_genomic_features.log
    plots/
        ${sample}.anno_genomic_features.pdf

Decision Tree

Step 0 — Gather Required Information from the User

Before calling any tool, ask the user:

1. Sample name (sample): used as prefix and for the output directory ${sample}_genomic_feature_annotation.
2. Genome assembly (genome): e.g. hg38, mm10, danRer11.
3. Never guess or auto-detect.

Step 1: Initialize Project

1. Make director for this project:

Call:
- mcp__project-init-tools__project_init

with:
- sample: the user-provided sample name
- task: de_novo_motif_discovery

The tool will:
- Create ${sample}_genomic_feature_annotation directory.
- Get the full path of the ${sample}_genomic_feature_annotation directory, which will be used as ${proj_dir}.

Step 2 (Optional): Standardize chromosome names for BED files

This step is optional. Only perform this step if the input file is a BED file. If the input file is a gene list, skip this step.

From 1 format to chr1 format
From MT format to chrM format

Call:
- mcp__file-format-tools__standardize_bed_chrom_names

with:
- input_bed: the user-provided BED file
- output_bed: the path to save the standardized BED file

The tool will:
- Standardize the chromosome names in the BED file.
- Return the path of the standardized BED file.

Step 3: Genomic Feature Annotation

• (Option 1) HOMER mode
  Call:
  mcp__homer-tools__annotate_genomic_features

With:
- sample: the user-provided sample name
- proj_dir: directory to save the genomic feature annotation results. In this skill, it is the full path of the ${sample}_genomic_feature_annotation directory returned by mcp__project-init-tools__project_init
- regions_bed: the user-provided regions file in BED format. May end with .bed, .narrowPeak, .broadPeak, etc.
- genome: the user-provided genome assembly, e.g. hg38, mm10, danRer11
- ann: "custom homer annotation file (created by assignGenomeAnnotation.pl), (default: None).
- size_given: keep original region sizes (default: True)
- cpg: include CpG information (default: False)

The tool will:
- Annotate the genomic regions using Homer's annotatePeaks.pl.
- Return the path of the annotated regions file under ${proj_dir}/results/ directory, and the path to the log file under ${proj_dir}/logs/ directory.
- ${proj_dir}/results/${sample}.anno_genomic_features.txt
- ${proj_dir}/results/${sample}.anno_genomic_features_stats.txt
- ${proj_dir}/logs/${sample}.anno_genomic_features.log

• (Option 2) ChIPseeker mode

library(ChIPseeker)
library(TxDb.Mmusculus.UCSC.mm10.knownGene) # ajust this depend on species
library(org.Mm.eg.db) # ajust this depend on species
txdb <- TxDb.Mmusculus.UCSC.mm10.knownGene # ajust this depend on species
peak_file <- "$sample.narrowPeak" 
peak_anno <- annotatePeak(
  peak_file,
  TxDb     = txdb,
  tssRegion = c(-3000, 3000),     # define "promoter" window around TSS
  annoDb   = "org.Mm.eg.db"       # adds SYMBOL, GENENAME, etc.
)
pdf("plots/${sample}_anno_ChIPseeker.pdf", width = 6, height = 5)
plotAnnoPie(peak_anno)
plotAnnoBar(peak_anno)
plotDistToTSS(peak_anno)
dev.off()

Step 4: Visualize the annotation results (executed only in HOMER mode)

Call:
- mcp__plot-anno-tools__visualize_annotation_results

With:
- sample: the user-provided sample name
- proj_dir: directory to save the annotation results. In this skill, it is the full path of the ${sample}_genomic_feature_annotation directory returned by mcp__project-init-tools__project_init
- chart_type: Type of plot: 'pie' for pie chart, 'bar' for barplot. Default: 'pie'.

The tool will:
- Visualize the annotation results.
- Return the path of the plot file under ${proj_dir}/plots/ directory, and ends with .pdf.

Step 5. Interpretation of Results

Typical annotation categories:
- Promoter: -1 kb to +100 bp from TSS
- 5' UTR, Exon, Intron, 3' UTR, Intergenic, TTS

Quality indicators:
- Annotation rate: % of peaks successfully annotated.
- Promoter fraction: Often high in TF ChIP-seq.
- Intergenic fraction: Reflects enhancer-rich or noncoding regions.

Best Practices

• Use high-confidence regions (e.g., IDR-filtered peaks).
• Ensure genome naming convention matches input files.
• Use visualization to assess annotation patterns across datasets.
• Save annotation parameters and plots for reproducibility.