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:

• mcpproject-init-toolsproject_init
• mcpgenome-locate-toolsgenomelocatefasta
• mcpHiCExplorer-toolshictomcool
• mcpHiCExplorer-toolscheckmcoolfile
• mcpHiCExplorer-toolsrun_hicFindTADs
• mcpHiCExplorer-toolsgeneratetrackini
• mcpHiCExplorer-toolsplottadsregion

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}TADcalling.
2. Genome assembly (genome): e.g. hg38, mm10, danRer11.

- Never guess or auto-detect.

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

1. 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:

• mcpproject-init-toolsproject_init

with:

• sample: the user-provided sample name
• task: TAD_calling

The tool will:

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

1. If the user provides a .hic file, convert it to .mcool file first using mcpHiCExplorer-toolshictomcool tool:

Call:

• mcpHiCExplorer-toolshictomcool

with:

• input_hic: the user-provided path (e.g. input.hic)
• sample: the user-provided sample name
• projdir: directory to save the view file. In this skill, it is the full path of the ${sample}TADcalling directory returned by mcpproject-init-toolsprojectinit.
• 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:

• mcpcooler-toolslistmcoolresolutions

with:

• mcoolpath: the user-provided path (e.g. input.mcool) or the path of the .mcool file returned by mcpHiCExplorer-toolshicto_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 mcpHiCExplorer-toolsrun_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:

• mcpHiCExplorer-toolsrun_hicFindTADs

with:

• sample: ${sample}
• projdir: directory to save the view file. In this skill, it is the full path of the ${sample}TADcalling directory returned by mcpproject-init-toolsprojectinit.
• 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
• mindepth: ${mindepth}, must be at least 3 times larger than the resolution.
• maxdepth: ${maxdepth}, must be at least 5 times larger than the resolution.

step: ${step}

• multipletesting: ${multipletesting}
• thresholdcomparisons: ${thresholdcomparisons}
• delta: ${delta}
• chromosomes: chromosomes to call TADs, e.g. chr22, space-separated list.

The tool will:

• Call mcpHiCExplorer-toolsrun_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:

• mcpHiCExplorer-toolsgeneratetrackini

with:

• sample: ${sample}
• projdir: directory to save the view file. In this skill, it is the full path of the ${sample}TADcalling directory returned by mcpproject-init-toolsprojectinit.
• 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:

• mcpHiCExplorer-toolsplottadsregion

with:

• sample: ${sample}
• projdir: directory to save the view file. In this skill, it is the full path of the ${sample}TADcalling directory returned by mcpproject-init-toolsprojectinit.
• 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.