- Introduction
- Binary installation
- Getting help
- Compiling
- Debugging and troubleshooting
- License
- Credits
Sambamba is a high performance modern robust and fast tool (and
library), written in the D programming language, for working with SAM
and BAM files. Current functionality is an important
subset of samtools functionality, including view, index, sort,
markdup, and depth. Most tools support piping: just specify /dev/stdin
or /dev/stdout
as filenames.
For almost 5 years the main advantage over samtools
was parallelized BAM reading.
Finally in March 2017 samtools
1.4 was released, reaching parity on this.
That said, we still have quite a few interesting features to offer:
- faster
sort
(no benchmarks yet, sorry) - automatic index creation when writing any coordinate-sorted file
view -L <bed file>
utilizes BAM index to skip unrelated chunksdepth
allows to measure base, sliding window, or region coverages- Chanjo builds upon this and gets you to exon/gene levels of abstraction
markdup
, a fast implementation of Picard algorithmslice
quickly extracts a region into a new file, tweaking only first/last chunks
Sambamba is free and open source software, licensed under GPLv2+. See manual pages online to know more about what is available and how to use it.
For more information on Sambamba you can contact Artem Tarasov and Pjotr Prins.
For those not in the mood to learn/install new package managers, there are Github source and binary releases. Simply download the tarball, unpack it and run it. For example
wget https://github.com/biod/sambamba/releases/download/v0.6.6/sambamba_v0.6.6_linux.tar.bz2
tar xvjf sambamba_v0.6.6_linux.tar.bz2
./sambamba_v0.6.6
sambamba 0.6.6
Usage: sambamba [command] [args...]
Available commands: 'view', 'index', 'merge', 'sort',
'flagstat', 'slice', 'markdup', 'depth', 'mpileup'
To get help on a particular command, just call it without args.
A latest pre-release of sambamba 0.6.7 for Linux that includes debug information and all dependencies is available from this link. This 24Mb download reflects the development edition and includes recent versions of libraries, samtools and bcftools. It should install on any Linux distribution, including old ones on HPC clusters.
Install the tarball by unpacking it and running the contained install script with a target directory e.g.
wget http://test-gn2.genenetwork.org/ipfs/QmakasNfZhdbPA3xJYNxNX7at5FtYnS4hUNnvDbzxhZf2J/hb13hjys1064jmb6z17yc1f822hv9zsz-sambamba-0.6.7-pre1-7cff065-x86_64.tar.bz2
tar xvjf QmakasNfZhdbPA3xJYNxNX7at5FtYnS4hUNnvDbzxhZf2J/hb13hjys1064jmb6z17yc1f822hv9zsz-sambamba-0.6.7-pre1-7cff065-x86_64.tar.bz2
./install.sh ~/sambamba-test
~/sambamba-test/bin/sambamba
sambamba 0.6.7-pre1
Usage: sambamba [command] [args...]
Available commands: 'view', 'index', 'merge', 'sort',
'flagstat', 'slice', 'markdup', 'depth', 'mpileup'
Binaries are also available through the following packaging tools (note the version numbers):
With Conda use the bioconda
channel.
A GNU Guix package for sambamba is available. The development version is packaged here.
Debian: see Debian packages.
Users of Homebrew can also use the formula from homebrew-science
.
Sambamba has a mailing list for installation help and general discussion.
Before posting an issue search the issue tracker and mailing list first. It is likely someone may have encountered something similar. Also try running the latest version of sambamba to make sure it has not been fixed already. Support/installation questions should be aimed at the mailing list. The issue tracker is for development issues around the software itself. When reporting an issue include the output of the program and the contents of the .log.txt file in the output directory.
- I have found and issue with sambamba
- I have searched for it on the issue tracker (also check closed issues)
- I have searched for it on the mailing list
- I have tried the latest release of sambamba
- I have read and agreed to below code of conduct
- If it is a support/install question I have posted it to the mailing list
- If it is software development related I have posted a new issue on the issue tracker or added to an existing one
- In the message I have included the output of my sambamba run
- In the message I have included the relevant .log.txt file in the output directory
- I have made available the data to reproduce the problem (optional)
To find bugs the sambamba software developers may ask to install a development version of the software. They may also ask you for your data and will treat it confidentially. Please always remember that sambamba is written and maintained by volunteers with good intentions. Our time is valuable too. By helping us as much as possible we can provide this tool for everyone to use.
By using sambamba and communicating with its communtity you implicitely agree to abide by the code of conduct as published by the Software Carpentry initiative.
Note: in general there is no need to compile sambamba. You can use a recent binary install as listed above.
The preferred method for compiling Sambamba is with the LDC compiler which targets LLVM.
- zlib
- htslib (submodule)
- lz4 (submodule)
- BioD (submodule)
- undeaD (submodule)
- python2
The LDC compiler's github repository also provides binary images. The current preferred release for sambamba is LDC - the LLVM D compiler (>= 1.1.0). After installing LDC:
git clone --recursive https://github.com/biod/sambamba.git
cd sambamba
git clone https://github.com/dlang/undeaD
make sambamba-ldmd2-64
Installing LDC only means unpacking an archive and setting some
environmental variables, e.g. unpacking into $HOME
:
cd
wget https://github.com/ldc-developers/ldc/releases/download/v$ver/ldc2-$ver-linux-x86_64.tar.xz
tar xJf ldc2-$ver-linux-x86_64.tar.xz
export PATH=~/ldc2-$ver-linux-x86_64/bin/:$PATH
export LIBRARY_PATH=~/ldc2-$ver-linux-x86_64/lib/
To build sambamba the LDC compiler is also available in GNU Guix:
guix package -i ldc
brew install ldc
git clone --recursive https://github.com/biod/sambamba.git
cd sambamba
git clone https://github.com/dlang/undeaD
make sambamba-ldmd2-64
Sambamba development and issue tracker is on github. Developer documentation can be found in the source code and the development documentation.
In a crash sambamba can dump a core. To make this happen set
ulimit -c unlimited
and run your command. Send us the core file so we can reproduce the state at time of segfault.
Another option is to use catchsegv
catchsegv ./build/sambamba command
this will show state on stdout which can be sent to us.
In case of crashes it's helpful to have GDB stacktraces (bt
command). A full stacktrace for all threads:
thread apply all backtrace full
Note that GDB should be made aware of D garbage collector:
handle SIGUSR1 SIGUSR2 nostop noprint
A binary relocatable install of sambamba with debug information and all dependencies can be fetched from the binary link above. Unpack the tarball and run the contained install.sh script with TARGET
./install.sh ~/sambamba-test
Run sambamba in gdb with
gdb --args ~/sambamba-test/sambamba-*/bin/sambamba view --throw-error
Sambamba is distributed under GNU Public License v2+.
If you are using Sambamba in your research and want to support future work on Sambamba, please cite the following publication:
A. Tarasov, A. J. Vilella, E. Cuppen, I. J. Nijman, and P. Prins. Sambamba: fast processing of NGS alignment formats. Bioinformatics, 2015.
@article{doi:10.1093/bioinformatics/btv098,
author = {Tarasov, Artem and Vilella, Albert J. and Cuppen, Edwin and Nijman, Isaac J. and Prins, Pjotr},
title = {Sambamba: fast processing of NGS alignment formats},
journal = {Bioinformatics},
volume = {31},
number = {12},
pages = {2032-2034},
year = {2015},
doi = {10.1093/bioinformatics/btv098},
URL = { + http://dx.doi.org/10.1093/bioinformatics/btv098}