---
title: "Getting htslib headers"
output:
  BiocStyle::html_document:
    toc_float: true
vignette: >
  %\VignetteIndexEntry{Getting htslib headers}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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](#pixi) or [conda](#conda) since their htslib is compiled with
[*libdeflate*](https://github.com/ebiggers/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

```r
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`.


```{r, echo=FALSE, error=FALSE}
if (!require("ggplot2", quietly = TRUE)) {
  stop("The 'ggplot2' package must be installed for this functionality")
}
```

```{r, echo=FALSE, dpi=300, fig.width=6, fig.height=4, fig.align="center", fig.cap="Effect of htslib v1.18 source on iscream's 'make_mat()' runtime from one bulk WGBS BED file"}
data_dir <- system.file("extdata", package = "iscream")
df <- read.csv(file.path(data_dir, "htslib.csv"))
ggplot(df, aes(x = regions, y = time, color = source)) +
  geom_point(alpha = 0.8) +
  stat_summary(
    aes(x = regions, group = source),
    fun = "mean",
    geom = "line",
    linewidth = 0.5,
    show.legend = TRUE
  ) +
  labs(
    x = "Genomic regions",
    y = "Runtime (s)",
    color = "htslib source"
  ) +
  theme_bw()


```

### Conda/miniconda/mamba/micromamba

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

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

Add this file to your project directory and run

```bash
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
```bash
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
```

### [Pixi](https://pixi.sh/latest/)

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

```toml
[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

```bash
pixi shell
```

Confirm that the headers are available for compilation
```bash
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
```

## Session info

```{r si}
sessionInfo()
```