Hi-C Compartments Calling (MCP-based)

Overview

This skill provides an automated workflow for compartments calling on .mcool, .cool or .hic Hi-C data.

Main steps include:

• •Refer to the Inputs & Outputs section to verify required files and output structure.
• •Always prompt user for genome assembly used.
• •Always prompt user for resolution used to call compartments. ~50-250 kb is recommended. 100 kb is default.
• •Locate the genome FASTA file from homer genome fasta file based on user input.
• •Rename chromosomes in the .mcool or .cool file to satisfy the chromosome format with "chr".
• •Generate chromosome-arm view files for compartment calling after changing the chromosome name.
• •Perform PCA-based compartment analysis and extract the first principal component (PC1).
• •Generate compartment interaction saddle plots and BigWig outputs for visualization.

When to Use This Skill

Use this skill when:

• •You want to identify A/B compartments from Hi-C .mcool or .cool files.
• •You need PC1 compartment scores and bigWig tracks for genome browser visualization.
• •You want a reproducible, normalized, automated compartment-calling workflow.

Inputs & Outputs

Inputs

• •File format: .mcool, .cool, or .hic (Hi-C data file) data.
• •Genome assembly: Prompt the user for genome assembly used.
• •Resolution: Prompt the user for resolution used to call compartments. The default resolution is 100 kb.

Outputs

${sample}_Compartments_calling/
    compartments/
      eigs.${resolution}.cis.vecs.tsv    # PC1 compartment scores  
      eigs.${resolution}.bw
      eigs.${resolution}.cis.lam.txt
      saddle.cis.${resolution}.digitized.tsv
      saddle.cis.${resolution}.saddledump.npz
    plots/         # PC1 track for genome browser  
      saddle.cis.${resolution}.pdf      # Saddle plot visualization 
    temp/
      expected.${resolution}.cis.tsv
      view_${genome}.tsv # Chromosome-arm view definition
      bins.${res}.tsv
      gc.${res}.tsv

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, genome-locate-tools:

• •mcp__project-init-tools__project_init
• •mcp__genome-locate-tools__genome_locate_fasta
• •mcp__HiCExplorer-tools__hic_to_mcool
• •mcp__cooler-tools__list_mcool_resolutions
• •mcp__cooler-tools__harmonize_chrom_names
• •mcp__cooler-tools__make_view_chromarms
• •mcp__cooler-tools__dump_bins_for_gc
• •mcp__cooltools-tools__run_genome_gc
• •mcp__cooltools-tools__run_expected_cis
• •mcp__cooltools-tools__run_eigs_cis
• •mcp__cooltools-tools__run_saddle
• •mcp__plot-hic-tools__plot_saddle_pdf

Do NOT fall back to:

• •raw shell commands (cooler dump, cooltools eigs-cis, cooltools saddle, 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}_Compartments_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/100000 (.mcool file with resolution specified)
   • •or .cool file path
   • •or .hic file path
4. •

   Resolution (resolution): default 100000 (100 kb).

   • •If user does not specify, use 100000 as default.
   • •Must be the same as the resolution used for ${mcool_uri}

Step 1 — Initialize Project & Locate Genome FASTA

1. •Make director for this project:

Call:

• •mcp__project-init-tools__project_init

with:

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

The tool will:

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

1. •If the user provides a .hic file, convert it to .mcool file 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}_loop_calling directory returned by mcp__project-init-tools__project_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.

1. •Locate genome fasta file:

Call:

• •mcp__genome-locate-tools__genome_locate_fasta

with:

• •genome: the user-provided genome assembly

The tool will:

• •Locate genome FASTA.
• •Verify the FASTA exists.

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

1. •Check the resolutions in mcool_uri:

Call:

• •mcp__cooler-tools__list_mcool_resolutions

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:

• •mcp__cooler-tools__harmonize_chrom_names

with:

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

The tool will:

• •Check if the chromosome names in the .mcool file.
• •If not, harmonize the chromosome names in the .mcool file.

Step 3 — Create Chromosome-Arm View File

Use bioframe to define chromosome arms based on centromeres:

Call:

• •mcp__cooler-tools__make_view_chromarms

with:

• •proj_dir: directory to save the expected-cis and eigs-cis files. In this skill, it is the full path of the ${sample}_Compartments_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
• •genome: genome assembly

The tool will:

• •Fetch chromsizes and centromeres via bioframe.
• •Generate chromosomal arms and filter them to those present in the cooler.
• •Return the path of the view file under ${proj_dir}/temp/ directory.

Step 4 — Compute GC Track for Bins

1. •Dump bins for GC track:

Call:

• •mcp__cooler-tools__dump_bins_for_gc with:
• •sample: the user-provided sample name
• •proj_dir: directory to save the GC track file. In this skill, it is the full path of the ${sample}_Compartments_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

The tool will:

• •Dump bins at the specified resolution from the cooler.
• •Return the path of the bins file under ${proj_dir}/temp/ directory.

1. •Compute GC track:

Call:

• •mcp__cooltools-tools__run_genome_gc

with:

• •sample: the user-provided sample name
• •proj_dir: directory to save the GC track file. In this skill, it is the full path of the ${sample}_Compartments_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
• •genome: genome assembly

The tool will:

• •Compute GC content for each bin.
• •Return the path of the GC track file under ${proj_dir}/temp/ directory.

Step 5 — Run Expected-cis and Eigs-cis (PCA Compartment Calling)

1. •Calculate expected cis:

Call:

• •mcp__cooltools-tools__run_expected_cis

with:

• •sample: the user-provided sample name
• •proj_dir: directory to save the expected-cis and eigs-cis files. In this skill, it is the full path of the ${sample}_Compartments_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
• •view_path: the path to the view file (e.g. ${proj_dir}/temp/view_${genome}.tsv)
• •clr_weight_name: the name of the weight column (default: weight)
• •ignore_diags: the number of diagonals to ignore based on resolution

The tool will:

• •Generate expected cis file.
• •Return the path of the expected cis file under ${proj_dir}/temp/ directory.

1. •Calculate eigs cis:

Call:

• •mcp__cooltools-tools__run_eigs_cis

with:

• •sample: the user-provided sample name
• •proj_dir: directory to save the expected-cis and eigs-cis files. In this skill, it is the full path of the ${sample}_Compartments_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
• •view_path: the view TSV from Step 3 (e.g. view_${genome}.tsv)
• •gc_tsv: GC track TSV from Step 4
• •clr_weight_name: balancing column name (default "weight", but can be set based on clr.bins().columns if the user tells you the correct name)
• •n_eigs: the number of principal components to compute (default 1)
• •make_bigwig: whether to make bigwig file for PC1 track (default True)

This tool will:

• •Run cooltools expected-cis to compute expected contact frequencies.
• •Run cooltools eigs-cis to perform PCA and extract PC1.
• •Return the path of the eigs-cis vecs file under ${proj_dir}/compartments/ directory.
• •Return the path of the bigWig file under ${proj_dir}/compartments/ directory.

If the user reports an error about balancing weights:

• •Ask the user which weight column should be used.
• •Re-run expected_and_eigs with the correct clr_weight_name.

Step 6 — Run Saddle Analysis

Call:

• •mcp__cooltools-tools__run_saddle

with:

• •sample: the user-provided sample name
• •proj_dir: directory to save the saddle file. In this skill, it is the full path of the ${sample}_Compartments_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
• •view_path: the view TSV from Step 3 (e.g. view_${genome}.tsv)
• •eigs_vecs_tsv: the eigs-cis vecs TSV from Step 5 (e.g. compartments/eigs.${resolution}.cis.vecs.tsv)
• •expected_cis_tsv: the expected-cis TSV from Step 5 (e.g. temp/expected_cis.${resolution}.tsv)
• •clr_weight_name: balancing column name (default "weight", but can be set based on clr.bins().columns if the user tells you the correct name)
• •qrange_low and qrange_high: default 0.02 and 0.98

The tool will:

• •Run cooltools saddle.
• •Generate saddle dump and related outputs, typically:
• •Return the path of the saddle dump file under ${proj_dir}/compartments/ directory.
• •Return the path of the other related outputs under ${proj_dir}/compartments/ directory.

Step 7 — Plot Saddle as PDF

Call:

• •mcp__plot-hic-tools__plot_saddle_pdf

with:

• •sample: the user-provided sample name
• •proj_dir: directory to save the saddle file. In this skill, it is the full path of the ${sample}_Compartments_calling directory returned by mcp__project-init-tools__project_init
• •resolution: ${resolution} must be the same as the resolution used for ${mcool_uri} and must be an integer
• •chr_name: the user-provided chromosome name, e.g. chr1

This tool will:

• •Load the corresponding .saddledump.npz file.
• •Plot the saddle matrix with LogNorm(1e-1, 1e1) and RdBu_r colormap.
• •Return the path of the compartment scores distribution PDF file under ${proj_dir}/plots/ directory.
• •Return the path of the saddle plot PDF file under ${proj_dir}/plots/ directory.
• •Return the path of the PC1 track PDF file under ${proj_dir}/plots/ directory.

If the saddledump file is missing, inform the user to run run_saddle first.

Best Practices

• •Always confirm the genome and resolution explicitly with the user.
• •Always use the defined MCP tools instead of ad-hoc code.
• •If the user asks “how to run this manually”, you may conceptually describe the steps but still prefer to recommend using the MCP pipeline for reproducibility.
• •If multiple resolutions are required, re-run the MCP tools with different resolution values and keep outputs in the same ${proj_dir} directory, using resolution in filenames for disambiguation.