genomic-feature-annotation

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.

⭐2stars🔀1forks📁View on GitHub🕐Updated Dec 12, 2025⬇️2downloads

When & Why to Use This Skill

This Claude skill automates genomic feature annotation and visualization using industry-standard bioinformatics tools like HOMER and ChIPseeker. It enables researchers to accurately map genomic regions—such as promoters, exons, introns, and intergenic regions—from BED or peak files, providing comprehensive statistical summaries and high-quality visual distributions to streamline genomic data analysis.

Use Cases

  • Identifying potential target genes of Transcription Factors (TFs) by mapping ChIP-seq peaks to the nearest Transcription Start Sites (TSS) and promoter regions.
  • Characterizing the functional distribution of epigenetic marks or chromatin accessibility sites (ATAC-seq) across the genome for various species like hg38 or mm10.
  • Generating publication-ready visual summaries, including pie charts and bar plots, to represent the percentage distribution of genomic features within a dataset.
  • Standardizing genomic data formats by converting chromosome naming conventions (e.g., '1' to 'chr1') and validating BED file structures for downstream bioinformatics pipelines.
namegenomic-feature-annotation
descriptionThis 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.
    • 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.