TADs Calling with HiCExplorer and Cooltools

Overview

This skill enables comprehensive identification and analysis of topologically associating domains (TADs) from Hi-C data stored in .mcool (or .cool) files. It integrates HiCExplorer for robust TAD calling and visualization capabilities.

Main steps include:

• •Refer to the Inputs & Outputs section to verify required files and output structure.
• •Data Preparation: Ensure .mcool files are formatted correctly and resolutions are verified.
• •Always prompt user for resolution used to call TADs.
• •TAD Calling: Use HiCExplorer to call TADs with customizable parameters.
• •Always prompt user for target genomic loci for visualization.
• •Visualization: Generate contact maps with TAD boundaries overlayed, for specific regions of the genome.

When to use this skill

Use this skill when:

• •You need to identify TADs in Hi-C data stored in .mcool (or .cool) files.
• •You want to visualize TADs in a specific region of the genome.
• •You need to perform automated TAD calling with HiCExplorer, including statistical corrections.

Inputs & Outputs

Inputs

• •File format: .mcool, .cool, or .hic (Hi-C data file).
• •Resolution: Provided by user. ~10-50 kb is recommended. Default is 50 kb. 25 kb is the best but memory-consuming.
• •Target region: Genome region provided by user to visualize TADs (e.g., "chr22:1000000-2000000").

Outputs

${sample}_TAD_calling/
    TADs/
        ${sample}_TAD_boundaries.bed  # Called TADs in BED format
        ${sample}_TAD_boundaries.gff
        ${sample}_TAD_domains.bed
        ... # other files output by the hicFindTADs
    plots/
        ${sample}_TADs_${genome_loci}.pdf  # TADs visualization (contact map)
    temp/
        ${sample}_track.ini            # Configuration file for visualization

Allowed Tools

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

• •mcp__project-init-tools__project_init
• •mcp__genome-locate-tools__genome_locate_fasta
• •mcp__HiCExplorer-tools__hic_to_mcool
• •mcp__HiCExplorer-tools__check_mcool_file
• •mcp__HiCExplorer-tools__run_hicFindTADs
• •mcp__HiCExplorer-tools__generate_track_ini
• •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. •Sample name (sample): used as prefix and for the output directory ${sample}_TAD_calling.
2. •Genome assembly (genome): e.g. hg38, mm10, danRer11.
   • •Never guess or auto-detect.
3. •Hi-C matrix path/URI (mcool_uri): e.g. .mcool file path or .hic file path.
   • •path/to/sample.mcool::/resolutions/50000 (.mcool file with resolution specified)
   • •or .cool file path
   • •or .hic file path
4. •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}

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: TAD_calling

The tool will:

• •Create ${sample}_TAD_calling directory.
• •Get the full path of the ${sample}_TAD_calling directory, which will be used as ${proj_dir}.

1. •If the user provides a .hic file, convert it to .mcool file first using mcp__HiCExplorer-tools__hic_to_mcool tool:

Call:

• •mcp__HiCExplorer-tools__hic_to_mcool

with:

• •input_hic: the user-provided path (e.g. input.hic)
• •sample: the user-provided sample name
• •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.
• •resolutions: the user-provided resolutions (e.g. [50000])

The tool will:

• •Convert the .hic file to .mcool file.
• •Return the path of the .mcool file.

If the conversion is successful, update ${mcool_uri} to the path of the .mcool file.

1. •Inspect the .mcool file to list available resolutions and confirm the analysis resolution with the user.

Call:

• •mcp__cooler-tools__list_mcool_resolutions

with:

• •mcool_path: the user-provided path (e.g. input.mcool) or the path of the .mcool file returned by mcp__HiCExplorer-tools__hic_to_mcool

The tool will:

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

If the ${resolution} is not found, ask the user to specify the resolution again. Else, use ${resolution}.

Step 2: HiCExplorer TAD Calling

Use mcp__HiCExplorer-tools__run_hicFindTADs for comprehensive TAD identification. 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: ${sample}
• •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 3: Visualization

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

Call:

• •mcp__HiCExplorer-tools__generate_track_ini

with:

• •sample: ${sample}
• •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
• •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

The tool will:

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

1. •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: ${sample}
• •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

• •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.