HiCSeg

Network-Based Integration of Hi-C and ChIP-seq for Genome Segmentation

HiCSeg is an interpretable, network-based framework for integrating Hi-C contact maps and histone ChIP-seq profiles into a unified genome segmentation. It converts each modality into a comparable weighted network, applies community detection (Louvain / Leiden), and fuses the two networks by direct addition or Similarity Network Fusion (SNF). The reference case study segments human chromosome 14 in the GM12878 cell line.

HiCSeg is not intended to replace specialized compartment or subcompartment callers. It is a small, transparent framework for exploring how three-dimensional contact structure (Hi-C) and one-dimensional regulatory similarity (histone ChIP-seq) can be compared and fused.

Repository layout

R/            Reusable R functions (KR norm, network build, SNF, tracks)
python/       Reusable Python module (Louvain wrapper)
scripts/      End-to-end demo pipeline (chr14, GM12878) — run in numbered order
notebooks/    Louvain.ipynb reference notebook
data/example/ Chromosome-14 example inputs (Rao 2014 + Lieberman-Aiden 2009)
tools/        Bundled Leiden .jar (CWTS networkanalysis, MIT-licensed)

Install

HiCSeg mixes R, Python, and a Java tool for Leiden clustering.

# Python + Java (via conda)
conda env create -f environment.yml
conda activate hicseg

# R packages
Rscript install_deps.R

Requirements: R >= 4.0, Python >= 3.9, Java >= 11.

Quickstart — reproduce the chr14 example

Run the numbered scripts in order. Each writes its output under results/.

Rscript scripts/01_normalize_hic.R      data/example/chr14_25kb.RAWobserved.gz \
                                        data/example/chr14_25kb.KRnorm \
                                        data/example/chr14_25kb.KRexpected \
                                        results/chr14_25kb.normalized.rds
Rscript scripts/02_build_hic_network.R  results/chr14_25kb.normalized.rds \
                                        results/hic_network.txt
Rscript scripts/03_build_chipseq_network.R \
                                        data/example/chipseq_peaks/ \
                                        results/chipseq_network.txt
python  scripts/04_cluster_louvain.py   results/hic_network.txt \
                                        results/hic_louvain.txt
bash    scripts/05_cluster_leiden.sh    results/hic_network.txt \
                                        results/hic_leiden.txt
Rscript scripts/06_fuse_snf.R           results/hic_network.txt \
                                        results/chipseq_network.txt \
                                        results/fused_network.txt
Rscript scripts/07_make_bed_tracks.R    results/hic_leiden.txt \
                                        results/hic_leiden.bed

See scripts/README.md for a step-by-step walkthrough.

Applying HiCSeg to your own data

The functions under R/ and python/hicseg/ are the reusable pieces:

• R/kr_norm.R — KRnorm(A) Knight-Ruiz normalization of a contact matrix.
• R/hic_preprocess.R — sparse-matrix parsing, KR + expected normalization, Pearson correlation matrix.
• R/chipseq_binning.R — bin_peaks(peaks, chrom, resolution) scores each fixed-width bin as a length-weighted average of overlapping peak scores.
• R/signed_similarity.R — signed_similarity(X) transforms Pearson correlations to [0, 1] via S = 0.5 + 0.5 * cor(X).
• R/snf_fusion.R — snf_fuse(sim_hic, sim_chipseq, K, t) wraps SNFtool::SNF after building affinity matrices.
• R/bed_track.R — writes a colored Juicebox .bed track from cluster labels.
• python/hicseg/louvain.py — run_louvain(edges, resolution) wraps community.best_partition.

Visualization

Segmentation tracks are viewed in Juicebox by loading .hic contact maps and overlaying the .bed tracks produced by scripts/07_make_bed_tracks.R.

Citation

If you use HiCSeg, please cite:

Wu, Y.-H. and Chang, J.-M. HiCSeg: Network-Based Integration of Hi-C and ChIP-seq for Genome Segmentation.

Machine-readable metadata is in CITATION.cff.

License

HiCSeg is released under the GNU GPL v3.0. The bundled CWTS networkanalysis Leiden jar under tools/ is MIT-licensed; see tools/LICENSE.networkanalysis.