KMC

KMC is a disk-based program for counting k-mers from (possibly gzipped) FASTQ/FASTA files. KMC is one of many projects developed by REFRESH Bioinformatics Group.

For accessing k-mers stored in database produced by KMC there is an API (kmc_api directory). Note that for KMC versions 0.x and 1.x dababase format differs from produced by KMC version 2.x. From version 2.2.0 API is unified for both formats and all new features/bug fixes are present only for 2.x branch (standalone API for older KMC version is not longer under development, so new version of API should be used even for databases produced by older KMC version).

Quick start

Getting the executable

The simplest way to get the KMC is to download newest release for appropriate operating system from KMC releases.

Counting the k-mers from a single fastq file

./kmc -k27 input.fastq 27mers .

The command above will count all the 27-mers occurring in input.fastq at least twice (configurable with -ci switch). The result will be stored in a KMC database, which is split into two files: 27mers.kmc_pre and 27mers.kmc_suf. KMC will create hundreds of intermediate files. In the case of the above command, those will be created in the current working directory(the . at the end of the command). It may be more convinient to use dedicated directory for KMC temporary files, for example:

mkdir kmc_tmp # create directory for kmc temporary files
./kmc -k27 input.fastq 27mers kmc_tmp

Create text dump from KMC database binary format

Having the k-mers counted it is possible to dump KMC binary database to textual form with kmc_tools.

./kmc_tools transform 27mers dump 27mers.txt

Installation details

Compile from sources

git clone --recurse-submodules https://github.com/refresh-bio/kmc.git
cd kmc
make -j32

= The following libraries come with KMC in a binary (64-bit compiled for x86 platform) form. If your system needs other binary formats, you should put the following libraries in kmc_core/libs:

zlib - for support for gzip-compressed input FASTQ/FASTA files

The following libraries come with KMC in a source coude form.

pybind11 - used to create python wrapper of KMC API (https://github.com/pybind/pybind11)

If needed, you can also redefine maximal length of k-mer, which is 256 in the current version.

Note: KMC is highly optimized and spends only as many bytes for k-mer (rounded up to 8) as necessary, so using large values of MAX_K does not affect the KMC performance for short k-mers.

Some parts of KMC use C++17 features, so you need a compatible C++ compiler

After that, you can run make to compile kmc and kmc_dump applications.

Additional infromation for MAC OS installation

There might be a need to change g++ path in makefile_mac. If needed we recommend install g++ with brew (http://brew.sh/).

Note that KMC creates a hundreds of temporary files, while default limit for opened files is small for under MAC OS platform. To increase this number use following command before running KMC:

ulimit -n 2048

Directory structure

bin - after compilation executables and libraries after compilation will be stored here
include - after compilation header file to use kmc core through the C++ API will be stored here
kmc_core - source code of kmc core library
kmc_CLI - source code of kmc command line interface
kmc_tools - source codes of kmc_tools program
kmc_core/libs - libraries used by KMC
kmc_api - C++ source codes implementing API to access KMC databases; must be used by any program that wants to process databases produced by kmc
kmc_dump - source codes of kmc_dump program listing k-mers in databases produced by kmc (deprecated, use kmc_tools instead)
py_kmc_api - python wrapper for kmc API
tests - tests files

Use the KMC directly from code through the API

It is possible to use the KMC directly from C++ code through. Detailed API description is available at wiki

Python wrapper for KMC API

Python wrapper for KMC API was created using pybind11. Warning: python binding is experimental. The library used to create binding as well as public interface may change in the future. Warning 2: python wrapper for C++ KMC API is much slower (much, much more than I have been expecting) than native C++ API. In fact the first attempt to create python wrapper was to use ctypes, but it turned out it was even slower than in case when pybind11 is used. The wrapper is designed and was tested only for python3. The main goal was to make it as similar to C++ API as possible. For this reason the API may be not [pythonic] (https://blog.startifact.com/posts/older/what-is-pythonic.html) enough for regular python programmer. Suggestions or pull requests to make it more robust are welcome.

Python module wrapping KMC API must be compiled.

for windows there is a visual studio project (note that there will be probably the need to change include directories and library directories to point python include and libs location)
for linux or mac one should run make py_kmc_api

As a result of pybind11 .so file (for linux and mac os) or .pyd (for windows) is created and may be used as a python module. *.pyd file is in fact DLL file, the only difference is its extension.

for windows following file is created: x64/Release/py_kmc_api.pyd
for linux/mac os the following file is created: bin/py_kmc_apipython3-config --extension-suffix

To be able to use this file one should make it visible for python. One way to do this is to extend PYTHONPATH environment variable. For linux/mac os one may just

source py_kmc_api/set_path.sh

while, for windows:

py_kmc_api\set_path.bat

it will export apropriate file. The example of Python wrapper for KMC API is presented in file: py_kmc_api/py_kmc_dump.py

Detailed API description is available at wiki

Binaries

After compilation you will obtain two binaries:

bin/kmc - the main program for counting k-mer occurrences
bin/kmc_dump - the program listing k-mers in a database produced by kmc
bin/kmc_tools - the program allowing to manipulate kmc databases (set operations, transformations, etc.)
bin/libkmc_core.a - compiled KMC code sources
py_kmc_api.cpython-39-x86_64-linux-gnu.so - compiled python wrapper for KMC API

License

KMC software distributed under GNU GPL 3 licence.
gzip is free, open-source
pybind11 (https://github.com/pybind/pybind11) is open-source (BDS-style license)

In case of doubt, please consult the original documentations.

Archival source codes, binaries and documentation = Archival source codes, binaries and documentation are available at wiki.

Warranty

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.