bisnake2001/differential-tad-analysis

Differential TAD Analysis with HiCExplorer

Overview

This skill identifies differentially interacting TADs between two experimental conditions using HiCExplorer.
It assumes that TADs have already been called for the target condition.

Steps:

1. Normalize Hi-C matrices between conditions. Modify the chromosome name in the .mcool file if not started with "chr".
2. Prepare TAD domains (BED file) of the target sample. Make sure the consistence of the chromosame names between .mcool files and BED files. Modify the chromosome name in the BED file if not consistent with the .mcool file.
3. Perform differential TAD analysis.
4. Visualize the Hi-C contact maps for the target and control conditions.
5. Visualize and interpret significant TAD changes.

When to Use This Skill

Use this skill when:

• You have already called TADs for one condition.
• You want to detect TADs that show significant interaction changes between two Hi-C matrices.
• You are comparing chromatin architecture between experimental conditions (e.g., treated vs. control, different cell types).

---

Inputs & Outputs

Inputs

• File format: Two files in .mcool, .cool, or .hic format for the target and control conditions.
• Genome assembly: Prompt the user for genome assembly used.
• Resolution: Provided by user. ~10-50 kb is recommended. Default is 50 kb. 25 kb is the best but memory-consuming.

Outputs

${target}_${control}_differential_tad_analysis/
    normalize/
        ${target}_norm.cool
        ${control}_norm.cool
    TADs/
        ${target}_TAD_boundaries.bed  # Called TADs in BED format
        ${target}_TAD_boundaries.gff
        ${target}_TAD_domains.bed
        ${target}_TAD_score.bedgraph
        ${target}_TAD_tad_score.bm
    diff_TADs/
        ${target}_${control}_accepted.diff_tad
        ${target}_${control}_rejected.diff_tad
    plots/
        ${target}_${control}_contactmap_chrN.png

---

Allowed Tools

When using this skill, you should restrict yourself to the following MCP tools from server project-init-tools, genome-locate-tools, HiCExplorer-tools:

• mcp__project-init-tools__project_init
• mcp__HiCExplorer-tools__hic_to_mcool
• mcp__HiCExplorer-tools__run_hicFindTADs
• mcp__HiCExplorer-tools__hic_normalize
• mcp__HiCExplorer-tools__hic_differential_tad
• mcp__HiCExplorer-tools__generate_track_ini
• mcp__HiCExplorer-tools__plot_hic_contact_maps
• mcp__HiCExplorer-tools__plot_tads_region

Do NOT fall back to:

• raw shell commands (hicFindTADs, hicPlotTADs, etc.)
• ad-hoc Python snippets (e.g. importing cooler, bioframe, matplotlib manually in the reply).

---

Decision Tree

Step 0 — Gather Required Information from the User

Before calling any tool, ask the user:

1. Target sample name (target): used as prefix and for the output directory ${target}_${control}_differential_tad_analysis.
2. Control sample name (control): used as prefix and for the output directory ${target}_${control}_differential_tad_analysis.
3. Genome assembly (genome): e.g. hg38, mm10, danRer11.
   • Never guess or auto-detect.
4. Hi-C matrix path/URI (mcool_uri_target, mcool_uri_control): .
   • path/to/target.mcool::/resolutions/50000, path/to/control.mcool::/resolutions/50000 (.mcool files with resolution specified)
   • or .cool file path
   • or .hic file path
5. Resolution (resolution): default 50000 (50 kb).
   • If user does not specify, use 50000 as default.
   • Must be the same as the resolution used for ${mcool_uri_target} and ${mcool_uri_control}

---

Step 1: Initialize Project

1. Make director for this project:

Call:

• mcp__project-init-tools__project_init

with:

• sample: ${target}_${control}
• task: differential_tad_analysis

The tool will:

• Create ${target}_${control}_differential_tad_analysis directory.
• Get the full path of the ${target}_${control}_differential_tad_analysis directory, which will be used as ${proj_dir}.

---

2. If the user provides .hic files for the target and control conditions, convert it to .mcool file first using mcp__HiCExplorer-tools__hic_to_mcool tool for the target and control conditions separately:

Call:

• mcp__HiCExplorer-tools__hic_to_mcool

with:

• input_hic: the user-provided path (e.g. input.hic)
• sample: ${target}
• proj_dir: directory to save the view file. In this skill, it is the full path of the ${target}_${control}_differential_tad_analysis directory returned by mcp__project-init-tools__project_init.
• resolutions: the user-provided resolutions (e.g. [50000])

The tool will:

• Convert the .hic file to .mcool file for the target condition.
• Return the path of the .mcool file for the target condition.

---

Call:

• mcp__HiCExplorer-tools__hic_to_mcool

with:

• input_hic: the user-provided path (e.g. input.hic)
• sample: ${control}
• proj_dir: directory to save the view file. In this skill, it is the full path of the ${target}_${control}_differential_tad_analysis directory returned by mcp__project-init-tools__project_init.
• resolutions: the user-provided resolutions (e.g. [50000])

The tool will:

• Convert the .hic file to .mcool file for the control condition.
• Return the path of the .mcool file for the control condition.

If the conversion is successful, update ${mcool_uri_target} and ${mcool_uri_control} to the path of the .mcool files.

---

3. Inspect the .mcool files for the target and control conditions respectively to list available resolutions and confirm the analysis resolution with the user.

Call:

• mcp__cooler-tools__list_mcool_resolutions

with:

• mcool_path: the path of the .mcool file for the target condition. If the user provides the path of the .hic file, these are the .mcool files returned by mcp__HiCExplorer-tools__hic_to_mcool tool.

The tool will:

• List all resolutions in the .mcool file for the target condition.
• Return the resolutions as a list.

---

Call:

• mcp__cooler-tools__list_mcool_resolutions

with:

• mcool_path: the path of the .mcool file for the control condition. If the user provides the path of the .hic file, these are the .mcool files returned by mcp__HiCExplorer-tools__hic_to_mcool tool.

The tool will:

• List all resolutions in the .mcool file for the control condition.
• Return the resolutions as a list.

If the ${resolution} for the target condition or the control condition is not found, ask the user to specify the resolution again. Else, use ${resolution} for the target condition and ${resolution} for the control condition.

---

Step 2. Normalize Hi-C matrices

To ensure both matrices have comparable sequencing depth and coverage, perform normalization before analysis.

Call:

• mcp__HiCExplorer-tools__hic_normalize

with:

• sample_target: ${target}
• sample_control: ${control}
• proj_dir: Full path to project directory. In this skill, it is the full path of the ${target}_${control}_differential_tad_analysis directory returned by mcp__project-init-tools__project_init.
• mcool_uri_target: ${mcool_uri_target} with the resolution ${resolution} specified.
• mcool_uri_control: ${mcool_uri_control} with the resolution ${resolution} specified.
• resolution: ${resolution}, must be the same as the resolution used in previous steps and must be an integer.
• method: Normalization method: smallest, largest, or sum.

The tool will:

• Normalize the Hi-C matrices for the target and control conditions.
• Return the path of the normalized Hi-C matrices for the target and control conditions, which will be used as ${cool_target_norm} and ${cool_control_norm}.

---

Step 3. Prepare TAD domains for the target condition

Use mcp__HiCExplorer-tools__run_hicFindTADs for comprehensive TAD identification for the target condition. Customize parameters to suit the resolution and depth of your Hi-C data: Before calling the tool, ask the user for the following parameters:

• ${min_depth}: Minimum window size (e.g. 3x resolution, default 150000, must be at least 3 times larger than the resolution)
• ${max_depth}: Maximum window size (e.g. 6-10x resolution, default 300000, must be at least 5 times larger than the resolution)
• ${step}: Step size for sliding window (default 50000, 25000 is the best but memory-consuming)
• ${multiple_testing}: Multiple testing correction method (e.g. 'fdr')
• ${threshold_comparisons}: FDR threshold for significant TADs (default 0.05)
• ${delta}: Delta parameter for TAD boundary detection (default 0.01)
• ${chromosomes}: Chromosomes to call TADs (default chr22). It is suggested to call TADs on a certain chromosome because it is memory-consuming to call TADs on all chromosomes and this process would likely be killed by the system.

Call:

• mcp__HiCExplorer-tools__run_hicFindTADs

with:

• sample: ${target}
• proj_dir: directory to save the view file. In this skill, it is the full path of the ${sample}_TAD_calling directory returned by mcp__project-init-tools__project_init.
• mcool_uri: cooler URI with resolution specified, e.g. input.mcool::/resolutions/${resolution}
• resolution: ${resolution} must be the same as the resolution used for ${mcool_uri} and must be an integer
• min_depth: ${min_depth}, must be at least 3 times larger than the resolution.
• max_depth: ${max_depth}, must be at least 5 times larger than the resolution.
• step: ${step}
• multiple_testing: ${multiple_testing}
• threshold_comparisons: ${threshold_comparisons}
• delta: ${delta}
• chromosomes: chromosomes to call TADs, e.g. chr22, space-separated list.

The tool will:

• Call mcp__HiCExplorer-tools__run_hicFindTADs to identify TADs.
• Return the path of the TADs file under ${proj_dir}/TADs/ directory.

---

Step 4. Run differential TAD analysis

Detect TADs with statistically different intra- and inter-TAD interactions between the normalized matrices.

Call:

• mcp__HiCExplorer-tools__hic_differential_tad

with:

• target: ${target}
• control: ${control}
• cool_target_norm: ${cool_target_norm} returned by mcp__HiCExplorer-tools__hic_normalize tool.
• cool_control_norm: ${cool_control_norm} returned by mcp__HiCExplorer-tools__hic_normalize tool.
• proj_dir: directory to save the view file. In this skill, it is the full path of the ${target}_${control}_differential_tad_analysis directory returned by mcp__project-init-tools__project_init.
• target_tads: ${target}_TADs_domains.bed under ${proj_dir}/TADs/ directory returned by mcp__HiCExplorer-tools__run_hicFindTADs tool.
• p_value: Significance cutoff for differential TADs (default 0.05)
• region_mode: Region types used for testing: 'intra-TAD', 'left-inter-TAD', 'right-inter-TAD', or 'all' (default)
• reject_rule: Multiple region reject rule: 'one' (default) or 'all' for stricter criteria
• threads: Number of threads for chromosome-level parallelization (default 4)

The tool will:

• Run differential TAD analysis.
• Return the path of the differential TADs file under ${proj_dir}/diff_TADs/ directory.

---

Step 5. Visualize the Hi-C matrices

Before calling the tool, ask the user for the target region, like "chr22:1000000-2000000".

1. Visualize the Hi-C contact map for the target condition

Call :

• mcp__HiCExplorer-tools__plot_hic_contact_maps

with:

• sample: ${target}
• proj_dir: directory to save the view file. In this skill, it is the full path of the ${target}_${control}_differential_tad_analysis directory returned by mcp__project-init-tools__project_init.
• cool_norm: ${cool_target_norm} returned by mcp__HiCExplorer-tools__hic_normalize tool.
• region: region to plot, e.g. chr1:1000000-5000000
• dpi: DPI for the plot (default 300)
• log1p: Apply log1p transform to contact values (default True)
• per_chr: Use --perChr option of hicPlotMatrix (default True)

The tool will:

• Visualize the Hi-C contact map for the target condition.
• Return the path of the Hi-C contact map file under ${proj_dir}/plots/ directory.

---

2. Visualize the Hi-C contact map for the control condition

Call:

• mcp__HiCExplorer-tools__plot_hic_contact_maps

with:

• sample: ${control}
• proj_dir: directory to save the view file. In this skill, it is the full path of the ${target}_${control}_differential_tad_analysis directory returned by mcp__project-init-tools__project_init.
• cool_norm: ${cool_control_norm} returned by mcp__HiCExplorer-tools__hic_normalize tool.
• region: region to plot, e.g. chr1:1000000-5000000
• dpi: DPI for the plot (default 300)
• log1p: Apply log1p transform to contact values (default True)
• per_chr: Use --perChr option of hicPlotMatrix (default True)

The tool will:

• Visualize the Hi-C contact map for the control condition.
• Return the path of the Hi-C contact map file under ${proj_dir}/plots/ directory.

---

Step 6. Overlay differential TADs

1. generate the <track.ini> file first for visualization

Call:

• mcp__HiCExplorer-tools__generate_track_ini

with:

• sample: ${target}_${control}
• proj_dir: directory to save the view file. In this skill, it is the full path of the ${target}_${control}_differential_tad_analysis directory returned by mcp__project-init-tools__project_init.
• mcool_uri: cooler URI with resolution specified, e.g. input.mcool::/resolutions/${resolution}
• resolution: ${resolution} must be the same as the resolution used for ${mcool_uri} and must be an integer
• depth: depth for the Hi-C matrix view, e.g. 1500000
• min_value: minimum value for the Hi-C matrix view, e.g. 0.0
• max_value: maximum value for the Hi-C matrix view, e.g. 80.0
• if_diff_TADs: True
• target: ${target}, target sample name.
• control: ${control}, control sample name.

The tool will:

• Generate the <track.ini> file under ${proj_dir}/temp/ directory.
• Return the path of the <track.ini> file.

---

2. Contact Maps with TAD Overlays Before calling the tool, ask the user for the target region, like "chr22:1000000-2000000".

Call:

• mcp__HiCExplorer-tools__plot_tads_region

with:

• sample: ${target}_${control}
• proj_dir: directory to save the view file. In this skill, it is the full path of the ${sample}_TAD_calling directory returned by mcp__project-init-tools__project_init.
• region: user-provided target region, like "chr22:1000000-2000000"
• dpi: dpi for the contact map, default is 300

The tool will:

• Generate the contact map with TAD boundaries overlayed.
• Return the path of the contact map file under ${proj_dir}/plots/ directory.

---

Best Practices

• Ensure both Hi-C matrices are balanced and have identical resolutions.
• Confirm that the TAD BED file is derived from the target condition at the same resolution.
• Verify consistent normalization methods across all samples.
• Inspect the resulting visualizations to confirm biological plausibility.