bisnake2001/hic-matrix-qc

Hi-C Contact Matrix QC for .mcool Files

Overview

This skill performs QC on Hi-C matrices stored in .cool or .mcool format files at a user-selected resolution.

Main steps include:

• Refer to the Inputs & Outputs section to check required inputs and set up the output directory structure.
• Always wait the user feedback if required files are not available in the current working directory by asking
  "${files} not available, provide required files or skip and proceed ?"
• Inspect the .mcool file to list available resolutions and confirm the analysis resolution with the user.
• Compute coverage and cis/trans ratios.
• Assess coverage uniformity across bins from coverage tables.
• Compute cis expected contact frequency and distance-dependent contact decay (P(s) curves).
• Visualize contact decay and P(s) scaling curves.
• If multiple Hi-C replicates are provided, compute pairwise correlation of balanced matrices at the chosen resolution.
• Summarize QC metrics and plots into a structured output directory.

---

When to use this skill

Use the hic-matrix-qc skill when you need to evaluate the quality of Hi-C contact matrices that are already stored in .cool, .mcool or .hic format.

---

Inputs & Outputs

Inputs

• File format: .mcool, .cool, or .hic (Hi-C data file).
• Genome assembly: Prompt the user for genome assembly used.
• Resolution: Choose the desired resolution for matrix QC. ~50-100 kb is recommended. Default is 100 kb.

Optional: Multiple Hi-C matrices for replicate QC rep1.mcool rep2.mcool rep3.mcool

Outputs

${sample}_hic_matrix_qc/
  logs/
    hic_qc.log               # Commands, parameters, and software versions
  metrics/
    coverage.${resolution}.tsv               # Per-bin cis/total coverage from cooltools coverage
    cis_trans_summary.${resolution}.txt      # Summarized cis, total, trans counts, and ratios
    ps_scaling_summary.${resolution}.txt     # Optional table with P(s) slope(s) in defined distance ranges
    replicate_correlation.${resolution}.tsv  # Pairwise correlation coefficients between replicates
  plots/
    coverage_histogram.${resolution}.pdf     # Coverage uniformity plot
    ps_curve.${resolution}.pdf               # P(s) curve (contact probability vs distance)
    decay_curve.${resolution}.pdf            # Contact decay curve (raw/normalized)
    replicate_correlation_heatmap.${resolution}.pdf  # Correlation matrix heatmap (if multiple replicates)
  comparison/
    replicate_vectors_${resolution}.npz      # (Optional) Stored vectors used for replicate correlations
  temp/
    expected_cis.${resolution}.tsv           # Expected cis contacts vs distance from expected-cis

---

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:

• mcp__project-init-tools__project_init
• mcp__cooler-tools__compute_coverage_and_cis_trans
• mcp__plot-hic-tools__plot_coverage_histogram
• mcp__cooltools-tools__run_expected_cis
• mcp__plot-hic-tools__plot_ps_and_decay
• mcp__plot-hic-tools__replicate_correlation

Do NOT fall back to:

• raw shell commands (cooltools coverage, cooltools expected-cis, cooltools dots, 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}_hic_matrix_qc.

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

   • Never guess or auto-detect.

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

   • 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: hic_matrix_qc

The tool will:

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

---

2. 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}_hic_matrix_qc 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.

---

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

---

2. 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.
• If the chromosome names are modified, return the path of the modified .mcool file under ${proj_dir}/ directory

---

Step 3: Compute coverage and cis/trans ratio

• Quantify cis and total coverage and derive cis/trans ratio at the chosen resolution.
• If the cooler is unbalanced or has a different weight column name, ask the user for the correct weight name or whether to use raw counts (empty --clr_weight_name).

Call: mcp__cooler-tools__compute_coverage_and_cis_trans

with:

• proj_dir: directory to save the view file. In this skill, it is the full path of the ${sample}_hic_matrix_qc 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
• clr_weight_name: name of the weight column (default: weight)
• cis_column: name of the cis column (default: cov_cis_weight)
• total_column: name of the total column (default: cov_tot_weight)

The tool will:

• Compute coverage and cis/trans ratio at the chosen resolution.
• Output: coverage.${resolution}.tsv cis_trans_summary.${resolution}.txt

---

Step 4: Assess coverage uniformity

Assess coverage uniformity by plotting a histogram of per-bin coverage.

Call: mcp__plot-hic-tools__plot_coverage_histogram with:

• 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}_hic_matrix_qc directory returned by mcp__project-init-tools__project_init.
• resolution: ${resolution}
• column: which column to histogram, e.g. cis, total, or n_valid (default: cis)
• bins: number of histogram bins (default: 50)

The tool will:

• Draw the histogram of per-bin coverage.
• Return the path of the coverage histogram plot.

After the tool runs, inform user with this:

• A reasonably broad distribution is expected; a long tail is common.
• Many zero-coverage bins may indicate insufficient depth at this resolution.
• A few bins with extremely high coverage may indicate local artifacts (e.g. centromeres, rDNA, mapping issues).

---

Step 5: Compute cis expected and P(s) contact decay curve

1. Use bioframe to define chromosome arms based on centromeres:

Call:

• mcp__cooler-tools__make_view_chromarms

with:

• 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}_hic_matrix_qc 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: the user-provided 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.

---

2. Calculate expected cis:

Call:

• mcp__cooltools-tools__run_expected_cis

with:

• 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}_hic_matrix_qc 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)
• expected_cis_tsv: the path to the expected cis file (e.g. ${proj_dir}/temp/expected_cis.${resolution}.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.

---

3. Plot the P(s) curve (log–log distance vs expected contacts) and decay curve (raw counts vs balanced P(s))

Call:

• mcp__plot-hic-tools__plot_ps_and_decay

with:

• 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}_hic_matrix_qc 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:

• Plot the P(s) curve (log–log distance vs expected contacts)
• Plot the decay curve (raw counts vs balanced P(s))
• Return the path of the P(s) curve plot and decay curve plot.

---

Step 6: Replicate correlation of Hi-C matrices (optional)

• Quantify similarity between Hi-C replicates at matrix level.
• Assumes:
  • At least two .mcool files (e.g. rep1.mcool, rep2.mcool, etc.).
  • Same genome assembly and resolution.

Call:

• mcp__plot-hic-tools__replicate_correlation

with:

• mcool_uris: list of cooler URIs with resolution specified, one per replicate, e.g. ['rep1.mcool::/resolutions/${resolution}', 'rep2.mcool::/resolutions/${resolution}']
• output_prefix: prefix for the output files, e.g. hic_qc_replicates_${resolution}
• chroms: list of chromosomes to use for correlation, e.g. ['chr1', 'chr2']
• use_balanced: whether to use balanced matrices (default: True)

The tool will:

• Compute replicate correlation of Hi-C matrices.
• Return the path of the replicate correlation file.

After the tool runs, inform user with this:

• Very low correlations (<0.7) between supposed biological replicates may indicate experimental issues or mismatched samples.

---

Notes & troubleshooting

• If balancing weights are missing or correlation is calculated on raw counts, explicitly record this in logs and interpret with caution.