Date: 2025-10-30

# Getting htslib headers

#### 30 October 2025

iscream currently has Rhtslib as a “LinkingTo” dependency so if a system installation of htslib is not found with pkg-config, the installer will fall back to using Rhtslib as the htslib header source. However, we recommend getting a more up-to-date htslib from another source. You or your system administrator can install htslib with the system package manager which usually sets `PKG_CONFIG_PATH` automatically. On MacOS you can get htslib with the Homebrew package manager. On HPC systems, htslib may be provided as a module. Make sure these methods also set the `PKG_CONFIG_PATH`.

If you aren’t able to install htslib development libraries system-wide for lack of admin permissions, you can install them from other channels. We recommend pixi or conda since their htslib is compiled with libdeflate support and is faster than htslib without libdeflate. If you’re compiling your own htslib, compile libdeflate first and then htslib. With Rhtslib we’ve seen poorer performance compared to a standard htslib installation, both with and without libdeflate.

To see what htslib version iscream is using and whether it has libdeflate, run

    library(iscream)
    htslib_version()
    #> 1.21
    #> build=configure libcurl=yes S3=yes GCS=yes libdeflate=yes lzma=yes bzip2=yes plugins=no htscodecs=1.6.1

and check that `libdeflate=yes`.

Figure 1: Effect of htslib v1.18 source on iscream’s ‘make_mat()’ runtime from one bulk WGBS BED file

### 0.0.1 Conda/miniconda/mamba/micromamba

Create an `environment.yaml` with the following contents to install htslib 1.21:

    name: iscream
    channels:
      - bioconda
      - conda-forge
    dependencies:
      - htslib=1.21
      - pkg-config=0.29.2

Add this file to your project directory and run

    conda env create -f environment.yaml
    conda activate iscream
    export PKG_CONFIG_PATH=$CONDA_PREFIX/lib
    export LD_LIBRARY_PATH=$CONDA_PREFIX/lib/

Confirm that the headers are available for compilation

    pkg-config --cflags --libs htslib

You should get something like

    -I/home/user/miniconda3/envs/iscream/include -L/home/user/miniconda3/envs/iscream/lib -lhts

### 0.0.2 Pixi

Pixi uses the conda repositories to install packages. Create a `pixi.toml` file with this content and add the file to your project directory:

    [project]
    channels = ["conda-forge", "bioconda"]
    name = "iscream"
    platforms = ["linux-64"]
    version = "0.1.0"

    [activation.env]
    LD_LIBRARY_PATH="$CONDA_PREFIX/lib"

    [dependencies]
    htslib = "1.21.*"
    pkg-config = ">=0.29.2,<0.30"

To create an environment with the required system dependencies run

    pixi shell

Confirm that the headers are available for compilation

    pkg-config --cflags --libs htslib

You should get something like

    -I/home/user/iscream/.pixi/envs/default/include -L/home/user/iscream/.pixi/envs/default/lib -lhts

## 0.1 Session info

    sessionInfo()

    ## R version 4.5.1 Patched (2025-08-23 r88802)
    ## Platform: x86_64-pc-linux-gnu
    ## Running under: Ubuntu 24.04.3 LTS
    ##
    ## Matrix products: default
    ## BLAS:   /home/biocbuild/bbs-3.22-bioc/R/lib/libRblas.so
    ## LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.12.0  LAPACK version 3.12.0
    ##
    ## locale:
    ##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C
    ##  [3] LC_TIME=en_GB              LC_COLLATE=C
    ##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8
    ##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C
    ##  [9] LC_ADDRESS=C               LC_TELEPHONE=C
    ## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
    ##
    ## time zone: America/New_York
    ## tzcode source: system (glibc)
    ##
    ## attached base packages:
    ## [1] stats4    stats     graphics  grDevices utils     datasets  methods
    ## [8] base
    ##
    ## other attached packages:
    ##  [1] ggplot2_4.0.0               bsseq_1.46.0
    ##  [3] SummarizedExperiment_1.40.0 Biobase_2.70.0
    ##  [5] MatrixGenerics_1.22.0       matrixStats_1.5.0
    ##  [7] GenomicRanges_1.62.0        Seqinfo_1.0.0
    ##  [9] IRanges_2.44.0              S4Vectors_0.48.0
    ## [11] BiocGenerics_0.56.0         generics_0.1.4
    ## [13] iscream_1.0.0               BiocStyle_2.38.0
    ##
    ## loaded via a namespace (and not attached):
    ##  [1] tidyselect_1.2.1          dplyr_1.1.4
    ##  [3] farver_2.1.2              S7_0.2.0
    ##  [5] R.utils_2.13.0            Biostrings_2.78.0
    ##  [7] bitops_1.0-9              fastmap_1.2.0
    ##  [9] RCurl_1.98-1.17           GenomicAlignments_1.46.0
    ## [11] stringfish_0.17.0         XML_3.99-0.19
    ## [13] digest_0.6.37             lifecycle_1.0.4
    ## [15] statmod_1.5.1             magrittr_2.0.4
    ## [17] compiler_4.5.1            rlang_1.1.6
    ## [19] sass_0.4.10               tools_4.5.1
    ## [21] yaml_2.3.10               data.table_1.17.8
    ## [23] rtracklayer_1.70.0        knitr_1.50
    ## [25] labeling_0.4.3            S4Arrays_1.10.0
    ## [27] curl_7.0.0                DelayedArray_0.36.0
    ## [29] RColorBrewer_1.1-3        abind_1.4-8
    ## [31] BiocParallel_1.44.0       HDF5Array_1.38.0
    ## [33] withr_3.0.2               R.oo_1.27.1
    ## [35] grid_4.5.1                beachmat_2.26.0
    ## [37] Rhdf5lib_1.32.0           scales_1.4.0
    ## [39] gtools_3.9.5              tinytex_0.57
    ## [41] dichromat_2.0-0.1         cli_3.6.5
    ## [43] rmarkdown_2.30            crayon_1.5.3
    ## [45] RcppParallel_5.1.11-1     httr_1.4.7
    ## [47] rjson_0.2.23              DelayedMatrixStats_1.32.0
    ## [49] pbapply_1.7-4             cachem_1.1.0
    ## [51] rhdf5_2.54.0              parallel_4.5.1
    ## [53] BiocManager_1.30.26       XVector_0.50.0
    ## [55] restfulr_0.0.16           vctrs_0.6.5
    ## [57] Matrix_1.7-4              jsonlite_2.0.0
    ## [59] bookdown_0.45             magick_2.9.0
    ## [61] h5mread_1.2.0             locfit_1.5-9.12
    ## [63] limma_3.66.0              jquerylib_0.1.4
    ## [65] glue_1.8.0                parallelly_1.45.1
    ## [67] codetools_0.2-20          gtable_0.3.6
    ## [69] BiocIO_1.20.0             tibble_3.3.0
    ## [71] pillar_1.11.1             htmltools_0.5.8.1
    ## [73] rhdf5filters_1.22.0       BSgenome_1.78.0
    ## [75] R6_2.6.1                  sparseMatrixStats_1.22.0
    ## [77] evaluate_1.0.5            lattice_0.22-7
    ## [79] R.methodsS3_1.8.2         Rsamtools_2.26.0
    ## [81] cigarillo_1.0.0           bslib_0.9.0
    ## [83] Rcpp_1.1.0                SparseArray_1.10.0
    ## [85] permute_0.9-8             xfun_0.53
    ## [87] pkgconfig_2.0.3