Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/samtools/samtools

Tools (written in C using htslib) for manipulating next-generation sequencing data
https://github.com/samtools/samtools

Last synced: about 1 month ago
JSON representation

Tools (written in C using htslib) for manipulating next-generation sequencing data

Awesome Lists containing this project

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.21 # 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.21 # 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

    includes a module that

   allows direct access to files stored in an iRODS data management

   repository (see ).



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

as follows:



    cd .../samtools-1.21 # 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 /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.21 # Within the unpacked release directory

    ./configure --enable-plugins --with-plugin-path=$PWD/htslib-1.21

    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 \\>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},

}