Hicberg

Python package to reconstruct genomic signals coming from repeated elements in paired-end data like Hi-C, Micro-C.

• Associated publication: https://www.biorxiv.org/content/10.1101/2025.06.20.660295v1
• Documentation and analyses examples: https://hicberg.readthedocs.io
• scripts used for the analysis presented in the article https://github.com/axelcournac/hicberg_bioanalysis

Installation

We highly recommend installing Hicberg through Mamba.

You can create an specific environment and activate it:

mamba create -n hicberg_env python=3.10 -c conda-forge
mamba activate hicberg_env

Install important dependancies with mamba (safer):

mamba install -c bioconda -c conda-forge pysam numpy scipy

Then install last stable version of Hicberg 1.0.2 from github:

pip install git+https://github.com/koszullab/hicberg.git@main

1.0.2 version will be available soon on bioconda.

Usage

Hicberg requires a FASTA file containing the reference genome against which the reads will be aligned, as well as two paired-end FASTQ files generated from a Hi-C, MicroC, ChIP-seq, or Mnase experiment. You can always run:

hicberg --help

Differents modes can be used to compute the probabilities of alignments for the different possibilities of reads coming from repeated elements.

Example

hicberg pipeline -e DpnII,HinfI --cpus 8 -o /home/bob/ -n output_repo_library1/ yeast_reference_genome.fa  reads_R1.fastq reads_R2.fastq 

Important options

When running hicberg, there are a handful parameters which are especially important:

• -e DpnII,HinfI: Restriction enzymes used in the Hi-C protocole (e.g DpnII, HinfI).
• -k 100: maximum number of alignments returned by Bowtie2 for a read (for organisms with repetitive elements with a large number of occurrences, we recommend limiting the search space, by default reports all alignments.).
• -m standard: mode for the computation of probabilites: random, ps, standard (uses coverage and p(s)), full (uses coverage, p(s) and density laws), by default standard mode is used.
• --cpus 10: number of cpu to allocate.
• -c plasmid2micron,chrMT: circular chromosomes or molecules present in the genome (used in the computation of p(s) behavior).
• -o: directory in which the output directory will be placed.
• -n: name of the output folder that will contain the reconstructed data for a given experiment.
• -b: Bin size of the matrices (default: 2000 bp).
• -hcsp: To process by hicstuff the pairs file (filtering of non informative events). (default: False).
• --start-stage: Stage to start the pipeline (can be: fastq, bam, groups, build, stats, rescue, final).
• --trim5: Trim bases from 5' (left) end of each read before alignment (default: 0).

Input Files

• Input Hi-C data should be in paired-end data in fastq format. The fastq files can be given in compressed format like .gz.
• The reference genome could be in fasta format or directy the index for bowtie2.

Output Files

Several files are generated by Hicberg.

• unrescued.pairs.cool: cool file of the Hi-C contact maps without hicberg reconstruction which correspond to what standard pipelines generate.
• rescued.pairs.cool: cool file of the Hi-C contact maps with hicberg reconstruction.
• if the option -hcsp is set to True, process from hicstuff https://github.com/koszullab/hicstuff are also applied like filtering of uncuts, recircularised events.., removal of duplicates. These files contained the extention .filtered (e.g: rescued.pairs.filtered.cool).

The cool format is an efficient and compact format for Hi-C data based on HDF5. It is maintained by the Mirny lab and documented here: https://open2c.github.io/cooler/ For more informations, see the cooler documentation.

Hicberg also genrates plots files in pdf format for the different statistical trends like the p(s) for each chromosome, the coverages, the contact maps with and without hicberg reconstructions that can be found in plots repository. Hicberg generates .npy files which content the different statistical trends that can be found in statistics repository. Hicberg keeps the alignment files in .bam format of the different groups (group 0 = non aligned reads, group 1 = uniquely mapped reads, group 2 = multi-mapping reads and group 2.rescued = alignment chosen by hicberg for multi-mapping reads in the alignments repository.

Contributing

All contributions are welcome, in the form of bug reports, suggestions, documentation or pull requests. We use the Numpy standard for docstrings when documenting functions.

The code formatting standard we use is black, with --line-length=79 to follow PEP8 recommendations. We use pytest with the pytest-doctest and pytest-pylint plugins as our testing framework. Ideally, new functions should have associated unit tests, placed in the tests folder. To test the code, you can run:

coverage run --source=hicberg -m pytest -v tests --cov-report=xml

Authors

• @sebgra

Citation

https://www.biorxiv.org/content/10.1101/2025.06.20.660295v1