Contents

1 Processing sequencing Hi-C libraries with HiCool

The HiCool R/Bioconductor package provides an end-to-end interface to process and normalize Hi-C paired-end fastq reads into .(m)cool files.

  1. The heavy lifting (fastq mapping, pairs parsing and pairs filtering) is performed by the underlying lightweight hicstuff python library (https://github.com/koszullab/hicstuff).
  2. Pairs filering is done using the approach described in Cournac et al., 2012 and implemented in hicstuff.
  3. cooler (https://github.com/open2c/cooler) library is used to parse pairs into a multi-resolution, balanced .mcool file. .(m)cool is a compact, indexed HDF5 file format specifically tailored for efficiently storing HiC-based data. The .(m)cool file format was developed by Abdennur and Mirny and published in 2019.
  4. Internally, all these external dependencies are automatically installed and managed in R by a basilisk environment.

The main processing function offered in this package is HiCool(). To process .fastq reads into .pairs & .mcool files, one needs to provide:

x <- HiCool(
    r1 = '<PATH-TO-R1.fq.gz>', 
    r2 = '<PATH-TO-R2.fq.gz>', 
    restriction = '<RE1(,RE2)>', 
    binning = "<minimum resolution>", 
    genome = '<GENOME_ID>'
)

Here is a concrete example of Hi-C data processing.

library(HiCool)
hcf <- HiCool(
    r1 = HiContactsData::HiContactsData(sample = 'yeast_wt', format = 'fastq_R1'), 
    r2 = HiContactsData::HiContactsData(sample = 'yeast_wt', format = 'fastq_R2'), 
    restriction = 'DpnII,HinfI', 
    binning = 1000, 
    genome = 'R64-1-1', 
    output = './HiCool/'
)
#> see ?HiContactsData and browseVignettes('HiContactsData') for documentation
#> loading from cache
#> see ?HiContactsData and browseVignettes('HiContactsData') for documentation
#> loading from cache
#> HiCool :: Recovering bowtie2 genome index from AWS iGenomes...
#> HiCool :: Initializing processing of fastq files [tmp folder: /var/folders/r0/l4fjk6cj5xj0j3brt4bplpl40000gt/T//RtmpFkRGLV/L5MTJZ]...
#> HiCool :: Mapping fastq files...
#> HiCool :: Tidying up everything for you...
#> HiCool :: .fastq to .mcool processing done!
#> HiCool :: Check ./HiCool/folder to find the generated files
#> HiCool :: Generating HiCool report. This might take a while.
#> HiCool :: Report generated and available @ /private/var/folders/r0/l4fjk6cj5xj0j3brt4bplpl40000gt/T/RtmpRCLHyn/Rbuild61853d9ddf4/HiCool/vignettes/HiCool/626f213158b0_7833^mapped-R64-1-1^L5MTJZ.html
#> HiCool :: All processing successfully achieved. Congrats!
hcf
#> CoolFile object
#> .mcool file: ./HiCool//matrices/626f213158b0_7833^mapped-R64-1-1^L5MTJZ.mcool 
#> resolution: 1000 
#> pairs file: ./HiCool//pairs/626f213158b0_7833^mapped-R64-1-1^L5MTJZ.pairs 
#> metadata(3): log args stats
S4Vectors::metadata(hcf)
#> $log
#> [1] "./HiCool//logs/626f213158b0_7833^mapped-R64-1-1^L5MTJZ.log"
#> 
#> $args
#> $args$r1
#> [1] "/Users/biocbuild/Library/Caches/org.R-project.R/R/ExperimentHub/626f213158b0_7833"
#> 
#> $args$r2
#> [1] "/Users/biocbuild/Library/Caches/org.R-project.R/R/ExperimentHub/626f2eb59bd6_7834"
#> 
#> $args$genome
#> [1] "/private/var/folders/r0/l4fjk6cj5xj0j3brt4bplpl40000gt/T/RtmpFkRGLV/R64-1-1"
#> 
#> $args$binning
#> [1] "1000"
#> 
#> $args$restriction
#> [1] "DpnII,HinfI"
#> 
#> $args$iterative
#> [1] TRUE
#> 
#> $args$balancing_args
#> [1] " --min-nnz 10 --mad-max 5 "
#> 
#> $args$threads
#> [1] 1
#> 
#> $args$output
#> [1] "./HiCool/"
#> 
#> $args$exclude_chr
#> [1] "Mito|chrM|MT"
#> 
#> $args$keep_bam
#> [1] FALSE
#> 
#> $args$scratch
#> [1] "/var/folders/r0/l4fjk6cj5xj0j3brt4bplpl40000gt/T//RtmpFkRGLV"
#> 
#> $args$wd
#> [1] "/private/var/folders/r0/l4fjk6cj5xj0j3brt4bplpl40000gt/T/RtmpRCLHyn/Rbuild61853d9ddf4/HiCool/vignettes"
#> 
#> 
#> $stats
#> $stats$nFragments
#> [1] 1e+05
#> 
#> $stats$nPairs
#> [1] 64761
#> 
#> $stats$nDangling
#> [1] 9266
#> 
#> $stats$nSelf
#> [1] 1910
#> 
#> $stats$nDumped
#> [1] 32
#> 
#> $stats$nFiltered
#> [1] 53553
#> 
#> $stats$nDups
#> [1] 613
#> 
#> $stats$nUnique
#> [1] 52940
#> 
#> $stats$threshold_uncut
#> [1] 7
#> 
#> $stats$threshold_self
#> [1] 7

2 Optional parameters

Extra optional arguments can be passed to the hicstuff workhorse library:

3 Output files

The important files generated by HiCool are the following:

The diagnosis plots illustrate how pairs were filtered during the processing, using a strategy described in Cournac et al., BMC Genomics 2012. The event_distance chart represents the frequency of ++, +-, -+ and -- pairs in the library, as a function of the number of restriction sites between each end of the pairs, and shows the inferred filtering threshold. The event_distribution chart indicates the proportion of each type of pairs (e.g. dangling, uncut, abnormal, …) and the total number of pairs retained (3D intra + 3D inter).

Notes:

4 System dependencies

Processing Hi-C sequencing libraries into .pairs and .mcool files requires several dependencies, to (1) align reads to a reference genome, (2) manage alignment files (SAM), (3) filter pairs, (4) bin them to a specific resolution and (5)

All system dependencies are internally managed by basilisk.utils. HiCool maintains a conda environment containing:

The first time HiCool() is executed, a fresh conda environment will be created and required dependencies automatically installed. This ensures compatibility between the different system dependencies needed to process Hi-C fastq files.

5 Session info

sessionInfo()
#> R version 4.5.1 Patched (2025-06-14 r88325)
#> Platform: aarch64-apple-darwin20
#> Running under: macOS Ventura 13.7.1
#> 
#> Matrix products: default
#> BLAS:   /Library/Frameworks/R.framework/Versions/4.5-arm64/Resources/lib/libRblas.0.dylib 
#> LAPACK: /Library/Frameworks/R.framework/Versions/4.5-arm64/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.1
#> 
#> locale:
#> [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
#> 
#> time zone: America/New_York
#> tzcode source: internal
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#>  [1] HiContactsData_1.11.0 ExperimentHub_2.99.5  AnnotationHub_3.99.6 
#>  [4] BiocFileCache_2.99.5  dbplyr_2.5.0          BiocGenerics_0.55.1  
#>  [7] generics_0.1.4        HiCool_1.9.1          HiCExperiment_1.9.2  
#> [10] BiocStyle_2.37.0     
#> 
#> loaded via a namespace (and not attached):
#>  [1] DBI_1.2.3                   httr2_1.2.1                
#>  [3] rlang_1.1.6                 magrittr_2.0.3             
#>  [5] matrixStats_1.5.0           compiler_4.5.1             
#>  [7] RSQLite_2.4.2               dir.expiry_1.17.0          
#>  [9] png_0.1-8                   vctrs_0.6.5                
#> [11] stringr_1.5.1               pkgconfig_2.0.3            
#> [13] crayon_1.5.3                fastmap_1.2.0              
#> [15] XVector_0.49.0              rmdformats_1.0.4           
#> [17] rmarkdown_2.29              sessioninfo_1.2.3          
#> [19] tzdb_0.5.0                  strawr_0.0.92              
#> [21] purrr_1.1.0                 bit_4.6.0                  
#> [23] xfun_0.52                   cachem_1.1.0               
#> [25] jsonlite_2.0.0              blob_1.2.4                 
#> [27] rhdf5filters_1.21.0         DelayedArray_0.35.2        
#> [29] Rhdf5lib_1.31.0             BiocParallel_1.43.4        
#> [31] parallel_4.5.1              R6_2.6.1                   
#> [33] bslib_0.9.0                 stringi_1.8.7              
#> [35] RColorBrewer_1.1-3          reticulate_1.43.0          
#> [37] GenomicRanges_1.61.1        jquerylib_0.1.4            
#> [39] Rcpp_1.1.0                  Seqinfo_0.99.2             
#> [41] bookdown_0.43               SummarizedExperiment_1.39.1
#> [43] knitr_1.50                  IRanges_2.43.0             
#> [45] Matrix_1.7-3                tidyselect_1.2.1           
#> [47] dichromat_2.0-0.1           abind_1.4-8                
#> [49] yaml_2.3.10                 codetools_0.2-20           
#> [51] curl_6.4.0                  lattice_0.22-7             
#> [53] tibble_3.3.0                InteractionSet_1.37.1      
#> [55] Biobase_2.69.0              basilisk.utils_1.21.2      
#> [57] withr_3.0.2                 KEGGREST_1.49.1            
#> [59] evaluate_1.0.4              Biostrings_2.77.2          
#> [61] pillar_1.11.0               BiocManager_1.30.26        
#> [63] filelock_1.0.3              MatrixGenerics_1.21.0      
#> [65] stats4_4.5.1                plotly_4.11.0              
#> [67] vroom_1.6.5                 BiocVersion_3.22.0         
#> [69] S4Vectors_0.47.0            ggplot2_3.5.2              
#> [71] scales_1.4.0                glue_1.8.0                 
#> [73] lazyeval_0.2.2              tools_4.5.1                
#> [75] BiocIO_1.19.0               data.table_1.17.8          
#> [77] rhdf5_2.53.3                grid_4.5.1                 
#> [79] tidyr_1.3.1                 crosstalk_1.2.1            
#> [81] AnnotationDbi_1.71.1        basilisk_1.21.5            
#> [83] cli_3.6.5                   rappdirs_0.3.3             
#> [85] S4Arrays_1.9.1              viridisLite_0.4.2          
#> [87] dplyr_1.1.4                 gtable_0.3.6               
#> [89] sass_0.4.10                 digest_0.6.37              
#> [91] SparseArray_1.9.1           htmlwidgets_1.6.4          
#> [93] farver_2.1.2                memoise_2.0.1              
#> [95] htmltools_0.5.8.1           lifecycle_1.0.4            
#> [97] httr_1.4.7                  bit64_4.6.0-1