Nested TAD Detection from .mcool Using OnTAD

Overview

This skill performs nested TAD (hierarchical TAD/subTAD) detection from Hi-C data using OnTAD, starting from a .mcool, .cool or .hic file.

Main steps include:

• Refer to the Inputs & Outputs section to verify required files and output structure.
• Inspect the .mcool file to list available resolutions and alway remember to confirm the chromosome name and analysis resolution with the user.
• Extract a balanced or raw dense Hi-C matrix for a selected chromosome and resolution from the .mcool file.
• Ensure matrix quality (symmetry, no all-zero rows/columns, reasonable contact decay).
• Run OnTAD to call TADs and nested TAD structures.
• Parse and standardize OnTAD output into BED-like tables and hierarchical annotation files.

When to use this skill

Use this skill when you want to identify TADs and nested sub-TADs from high- or mid-resolution Hi-C data, especially when your contact maps are stored as Cooler multi-resolution files (.mcool) and you need chromosome- and resolution-specific OnTAD calls.

Typical biological questions / use-cases:

• Comparing TAD hierarchy between cell types (e.g., GM12878 vs K562) or conditions (control vs treated).
• Investigating whether inner subTADs are enriched for active regulatory elements, specific histone marks, or gene expression.
• Studying boundary usage, boundary sharing, or hierarchical TAD levels around key loci (e.g., HOX clusters, oncogenes).
• Integrating nested TAD structure with ChIP-seq, ATAC-seq, or WGBS to understand spatial regulatory architecture.

Data quality & replication assumptions:

• Hi-C experiments should have sufficient depth for the target resolution (e.g., ≥5–10 kb typically requires deep sequencing).
• Preferably, use biological replicates per condition and call TADs on either:

- individual replicate matrices (and then merge/consensus), or - replicate-merged matrices (if justified).

• The .mcool should be properly normalized or at least QC’d (ICE/balanced weights available if using --balanced).

Inputs & Outputs

Inputs

Required core inputs:

• Hi-C matrix file

- Multi-resolution Cooler file (.mcool), e.g.: - sample.mcool - Or one-resolution Cooler file (.cool), e.g.: - sample.cool - Or Hi-C file (.hic), e.g.: - sample.hic

• User-supplied parameters (must come from user feedback)

- Chromosome name: e.g., chr1, chr2, chrX - Resolution of interest: e.g., 10000, 25000, 40000 (in bp) - Chromosome length: e.g., 133275309

• Software and environment

- cooler command-line utilities (or Python cooler module) available in $PATH or environment. - OnTAD installed and callable (e.g., OnTAD or OnTAD_linux command). - python (3.x) and basic scientific Python stack if using Python-based extraction.

Optional entry point:

• Precomputed dense Hi-C matrix (OnTAD-ready)

- Plain text dense square matrix (no header), e.g. projdir/matrices/chr1725kb_dense.matrix. - If this is already present, you may skip the .mcool → dense matrix conversion and jump directly to OnTAD.

Operational rules for missing inputs:

• If .mcool or .cool or .hic file is missing:

"sample.mcool not available, provide required files or skip and proceed ?"

• If chromosome list not specified:

Ask the user explicitly rather than assuming default.

• If OnTAD executable is not found:

Ask user to install/locate OnTAD before proceeding.

Outputs

Default output directory structure:

${sample}_nested_TAD_detection/
    matrices/
        ${chromosome}_${resolution}_dense.txt
        ${chromosome}_${resolution}_dense.log
    nested_TADs/
        ${chromosome}_${resolution}_OnTAD.tad
        ${chromosome}_${resolution}_OnTAD.bed
        ${chromosome}_${resolution}_OnTAD.log

Allowed Tools

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

• mcpproject-init-toolsproject_init
• mcpcooler-toolslistmcoolresolutions
• mcpcooler-toolsharmonizechromnames
• mcpcooler-toolsdump_chroms
• mcpcooler-toolsdumpdensematrix
• mcpOnTAD-toolsrun_ontad

Do NOT fall back to:

• raw shell commands (OnTAD, 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}nestedTAD_detection.

1. Genome assembly (genome): e.g. hg38, mm10, danRer11.

- Never guess or auto-detect.

1. Hi-C matrix path/URI (mcool_uri):

- path/to/sample.mcool::/resolutions/25000 (.mcool file with resolution specified) - or .cool file path - or .hic file path

1. Resolution (resolution): default 25000 (100 kb).

- If user does not specify, use 25000 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: hicmatrixqc

The tool will:

• Create ${sample}nestedTAD_detection directory.
• Return the full path of the ${sample}nestedTADdetection directory, which will be used as ${projdir}.

1. If the user provides a .hic file, convert it to .mcool file 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}nestedTADdetection directory returned by mcpproject-init-toolsproject_init.

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.

Step 2: List Available Resolutions in the .mcool file & Modify the Chromosome Names if Necessary

1. Check the resolutions in mcool_uri:

Call:

• mcpcooler-toolslistmcoolresolutions

with:

• mcool_path: the user-provided path (e.g. input.mcool) without resolution specified.

The tool will:

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

If the user defined or default ${resolution} is not found in the list, ask the user to specify the resolution again. Else, use ${resolution} for the following steps.

1. Check if the chromosome names in the .mcool file are started with "chr", and if not, modify them to start with "chr":

Call:

• mcpcooler-toolsharmonizechromnames

with:

• sample: the user-provided sample name
• projdir: directory to save the expected-cis and eigs-cis files. In this skill, it is the full path of the ${sample}Compartmentscalling 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

The tool will:

• Check if the chromosome names in the .mcool file.
• If not, harmonize the chromosome names in the .mcool file.
• If the chromosome names are modified, return the path of the modified .mcool file under ${proj_dir}/ directory

Step 3: Check chromosome length

Call:

• mcpcooler-toolsdump_chroms

with:

• 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

The tool will:

• Return the chromosome name and length as a table.

Step 4: Extract dense matrix from .mcool

Call:

• mcpcooler-toolsdumpdensematrix

with:

• sample: the user-provided sample name
• projdir: directory to save the view file. In this skill, it is the full path of the ${sample}nestedTADdetection directory returned by mcpproject-init-toolsproject_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
• chrom: the user-provided chromosome name (e.g. chr17)
• balanced: whether to use balanced matrix (default: True)

The tool will:

• Extract the dense matrix from the .mcool file.
• Return the path of the dense matrix file.

Step 5: Run OnTAD

Call:

• mcpOnTAD-toolsrun_ontad

with:

• sample: the user-provided sample name
• projdir: directory to save the view file. In this skill, it is the full path of the ${sample}nestedTADdetection directory returned by mcpproject-init-toolsproject_init.
• densematrix: the path to the dense matrix file (e.g. ${projdir}/matrices/chr1725kbdense.matrix)
• chrom: the user-provided chromosome name (e.g. chr17)
• chromlength: the corresponding chromosome length (e.g. 83257441) returned by mcpcooler-toolsdumpchroms tool.
• resolution: the user-provided resolution (e.g. 25000)
• penalty: the penalty parameter for OnTAD (e.g. 0.1)
• maxsz: the maximum TAD size (in bins) (e.g. 200)

The tool will:

• Run OnTAD to call TADs and nested TAD structures.
• Return the path of the OnTAD output file (.tad, .bed, .log).