README

Samtools implements various utilities for post-processing alignments in the
SAM, BAM, and CRAM formats, including indexing, variant calling (in conjunction
with bcftools), and a simple alignment viewer.


Building samtools
=================

The typical simple case of building Samtools using the HTSlib bundled within
this Samtools release tarball is done as follows:

    cd .../samtools-1.20 # Within the unpacked release directory
    ./configure
    make

You may wish to copy the resulting samtools executable into somewhere on your
$PATH, or run it where it is.

Rather than running-in-place like that, the next simplest typical case is to
install samtools etc properly into a directory of your choosing.  Building for
installation using the HTSlib bundled within this Samtools release tarball,
and building the various HTSlib utilities such as bgzip is done as follows:

    cd .../samtools-1.20 # Within the unpacked release directory
    ./configure --prefix=/path/to/location
    make all all-htslib
    make install install-htslib

You will likely wish to add /path/to/location/bin to your $PATH.

See INSTALL for full building and installation instructions and details.

Building with HTSlib plug-in support
====================================

Enabling plug-ins causes some parts of HTSlib to be built as separate modules.
There are two advantages to this:

 * The static library libhts.a has fewer dependencies, which makes linking
   third-party code against it easier.

 * It is possible to build extra plug-ins in addition to the ones that are
   bundled with HTSlib.  For example, the hts-plugins repository
   <https://github.com/samtools/htslib-plugins> includes a module that
   allows direct access to files stored in an iRODS data management
   repository (see <https://irods.org/>).

To build with plug-ins, you need to use the --enable-plugins configure option
as follows:

    cd .../samtools-1.20 # Within the unpacked release directory
    ./configure --enable-plugins --prefix=/path/to/location
    make all all-htslib
    make install install-htslib

There are two other configure options that affect plug-ins.  These are:
   --with-plugin-dir=DIR     plug-in installation location
   --with-plugin-path=PATH   default plug-in search path

The default for --with-plugin-dir is <prefix>/libexec/htslib.
--with-plugin-path sets the built-in search path used to find the plug-ins.  By
default this is the directory set by the --with-plugin-dir option.  Multiple
directories should be separated by colons.

Setting --with-plugin-path is useful if you want to run directly from
the source distribution instead of installing the package.  In that case
you can use:

    cd .../samtools-1.20 # Within the unpacked release directory
    ./configure --enable-plugins --with-plugin-path=$PWD/htslib-1.20
    make all all-htslib

It is possible to override the built-in search path using the HTS_PATH
environment variable.  Directories should be separated by colons.  To
include the built-in path, add an empty entry to HTS_PATH:

   export HTS_PATH=:/my/path            # Search built-in path first
   export HTS_PATH=/my/path:            # Search built-in path last
   export HTS_PATH=/my/path1::/my/path2 # Search built-in path between others

Using an optimised zlib library
===============================

Samtools has been minimally tested against both the Intel-optimised and
CloudFlare-optimised zlibs and shown to work.

They can be downloaded from:

    https://github.com/jtkukunas/zlib     # Intel
    https://github.com/cloudflare/zlib    # CloudFlare

Neither Samtools nor HTSlib needs recompiling to use these optimised libraries,
but the LD_LIBRARY_PATH environment variable should be set to a directory
containing the libz.so.1 file.

Benchmarks comparing the various zlibs are available at:

    http://www.htslib.org/benchmarks/zlib.html

It is recommended that you perform your own rigorous tests for an entire
pipeline if you wish to switch to one of the optimised zlib implementations.

Citing
======

Please cite this paper when using SAMtools for your publications:

Twelve years of SAMtools and BCFtools
Petr Danecek, James K Bonfield, Jennifer Liddle, John Marshall, Valeriu Ohan, Martin O Pollard, Andrew Whitwham, Thomas Keane, Shane A McCarthy, Robert M Davies, Heng Li
GigaScience, Volume 10, Issue 2, February 2021, giab008, https://doi.org/10.1093/gigascience/giab008

@article{10.1093/gigascience/giab008,
    author = {Danecek, Petr and Bonfield, James K and Liddle, Jennifer and Marshall, John and Ohan, Valeriu and Pollard, Martin O and Whitwham, Andrew and Keane, Thomas and McCarthy, Shane A and Davies, Robert M and Li, Heng},
    title = "{Twelve years of SAMtools and BCFtools}",
    journal = {GigaScience},
    volume = {10},
    number = {2},
    year = {2021},
    month = {02},
    abstract = "{SAMtools and BCFtools are widely used programs for processing and analysing high-throughput sequencing data. They include tools for file format conversion and manipulation, sorting, querying, statistics, variant calling, and effect analysis amongst other methods.The first version appeared online 12 years ago and has been maintained and further developed ever since, with many new features and improvements added over the years. The SAMtools and BCFtools packages represent a unique collection of tools that have been used in numerous other software projects and countless genomic pipelines.Both SAMtools and BCFtools are freely available on GitHub under the permissive MIT licence, free for both non-commercial and commercial use. Both packages have been installed \\&gt;1 million times via Bioconda. The source code and documentation are available from https://www.htslib.org.}",
    issn = {2047-217X},
    doi = {10.1093/gigascience/giab008},
    url = {https://doi.org/10.1093/gigascience/giab008},
    note = {giab008},
    eprint = {https://academic.oup.com/gigascience/article-pdf/10/2/giab008/36332246/giab008.pdf},
}