bisnake2001/regulatory-community-analysis-ChIA-PET

Protein-Mediated Regulatory Community Analysis from ChIA-PET

1. Overview

Main steps include:

• Refer to the Inputs & Outputs section to check available inputs and design the output structure.
• Standardize the information contained in the BED format peak file.
• Build a chromatin interaction network where:
  • nodes = protein binding sites (peaks)
  • edges = protein-mediated loops.
• Detect regulatory communities (3D modules) using graph clustering.
• Prioritize hub anchors using network centrality.
• Visualize the largest regulatory communities.

Tools called in this skill:

• mcp__igraph-tools__build_chromatin_network
• mcp__igraph-tools__analyze_chromatin_network
• mcp__igraph-tools__plot_chromatin_communities

---

2. When to use this skill

Use this skill when you have ChIA-PET data in BEDPE and BED format and you want to:

• Reveal regulatory communities (3D modules) formed by:
  • promoters
  • enhancers
  • other regulatory elements
• Identify hub anchors (peaks involved in many interactions) for a particular protein.
• Study protein-mediated rewiring of chromatin structure between conditions by comparing networks.
• Generate interpretable network visualizations for specific communities or loci.

Typical biological questions:

• Which promoters act as 3D regulatory hubs for my ChIA-PET factor (e.g., RNAPII, CTCF)?
• Which enhancers cluster with a given gene in 3D?
• Do disease-associated loci participate in specific regulatory communities?
• How does the chromatin interaction network structure change under perturbation (e.g., KO, treatment)?

---

Inputs & Outputs

Inputs

<sample>.bedpe # ChIA-PET loops: chr1  start1  end1  chr2  start2  end2  PET_count  [optional extra fields...]
<sample>.bed # Tab-delimited file with at least 3 columns: chr, start, end

Outputs

ChIA_PET_community/
  communities/
    ${sample}_communities_membership.tsv # Network membership table
    ${sample}.graphml
  plots/
    ${sample}_communities.pdf # Community network plots
  temp/
    ... # other temp files

---

Decision tree

Step 1: Standardize the information contained in the BED format peak file

• Check whether the <peak_id> and <type> (e.g. promoter or other annotations) information if provided in the BED file.
• If not provided, assign "peak_${i}" as the <peak_id> column and "others" as the <type> column.
• Make sure that order of the information in the BED file is:
  • 'chr' 'start' 'end' 'peak_id' 'type'

Step 2: Build the Chromatin Interaction Network

Call:

• mcp__igraph-tools__build_chromatin_network

with:

• loops_file: path to BEDPE-like loops file.
• peaks_file: path to annotated peaks BED file.
• proj_dir: project directory (e.g. ChIA_PET_community).
• graph_name (optional): output GraphML filename.
• min_pet (optional): filter on PET counts (default 1).

This tool will:

• Reads the loops and peaks files.
• Builds an undirected igraph:
• Saves the graph as:
  • ${sample}.graphml (GraphML)

---

Step 2: Detect Communities and Compute Network Centrality

Call:

• mcp__igraph-tools__analyze_chromatin_network

with:

• graph_path: GraphML file from Step 1 (e.g. ${sample}.graphml).
• proj_dir: same project directory.
• membership_name (optional): output TSV name, (e.g. ${sample}_communities_membership.tsv).
• weight_attr (optional): edge weight attribute, default "weight".
• seed (optional): random seed for community detection, default 1.

This tool will:

• Load the GraphML network.

• Run Louvain (multilevel) community detection

• Compute centralities

• Export a membership table: ${sample}_communities_membership.tsv with columns

• Update the GraphML file with the new vertex attributes (community & centralities).

Step 3 — Visualize Top Regulatory Communities

Call:

• mcp__igraph-tools__plot_chromatin_communities

with:

• graph_path: GraphML file with community attributes (from Step 2).
• proj_dir: project directory.
• pdf_name (optional): output PDF filename (e.g. ${sample}_communities.pdf).
• top_n (optional): number of largest communities to plot, default 12.
• size_attr (optional): vertex attribute for node size, default "degree".
• community_attr (optional): vertex attribute containing community IDs, default "community".

This tool will:

• Load the graph and verify that community_attr is present.
• Compute plot aesthetics
• Identify the largest communities (by vertex count), up to top_n.
• For each community:
  • Create an induced subgraph.
  • Compute a Fruchterman–Reingold layout.
  • Draw nodes + edges + labels into a separate page of a multi-page PDF.
• Save the PDF as:
  • ${sample}_communities.pdf