Visualization of different minimizer schemes supported in Digest and code example using library
What is the Digest library?
- a
C++library that supports various sub-sampling schemes for $k$-mers in DNA sequences.Digestlibrary utilizes the rolling hash-function from ntHash to order the $k$-mers in a window.
- a set of Python bindings that allow the user to run functions from the C++ library in Python.
How to install and build into your project?
Step 1: Install library
After cloning from GitHub, we use the Meson build-system to install the library.
PREFIXis an absolute path to library files will be install (*.hand*.afiles)- IMPORTANT:
PREFIXshould not be the root directory of thedigest/repo to avoid any issues with installation. - We suggest using
--prefix=$(pwd)/buildfrom within the root directory of thedigest/repo.
- IMPORTANT:
- These commands generate an
includeandlibfolders inPREFIXfolder
Step 2: Include Digest in your project
(a) Using <tt>Meson</tt>:
If your coding project uses Meson to build the executable(s), you can include a file called subprojects/digest.wrap in your repository and let Meson install it for you.
(b) Using <tt>g++</tt>:
To use Digest in your C++ project, you just need to include the header files (*.h) and library file (*.a) that were installed in the first step. Assuming that build/ is the directory you installed them in, here is how you can compile.
Detailed Look at Example Usage (2 ways):
There are three types of minimizer schemes that can be used:
- Windowed Minimizer: classifies a kmer as a minimizer if it is the smallest in the user specifed large window, using rightmost kmer to break ties.
- Modimizer: classifies a kmer as a minimizer if the hash of the kmer is congruent to the user specified value in the user specified mod-space.
- Syncmer: classifies a large window as a minimizer if its smallest value is equal to the value of the hashes of the leftmost or rightmost kmer in the window (doesn't care if the smallest hash value is not unique). Note that because of how the large window is defined if you are using the SKIPOVER policy and your sequence has non-ACTG characters, it is possible for this large window to have varying lengths in terms of number of characters.
The general steps to use Digest is as follows: (1) include the relevant header files, (2) declare the Digest object and (3) find the positions where the minimizers are present in the sequence.
1. Find positions of minimizers:
- This code snippet will find up to 100 Windowed Minimizers and store their positions in the vector called
output. digest::BadCharPolicy::WRITEOVERmeans that anytime the code encounters an non-ACTGcharacter, it will replace it with anA.digest::BadCharPolicy::SKIPOVERwill skip any $k$-mers with non-ACTGcharacters
digest::ds::Adaptiveis our recommended data-structure for finding the minimum value in a window (see wiki for other options)
2. Find both positions and hash values of minimizers
If you would like to obtain both the positions and hash values for each minimizer, you can pass a vector of paired integers to do so.
Documentation:
Documentation generated with Doxygen can be found here
Python binding support
Included in the library are function bindings for each sub-sampling scheme for use in Python. To install the Python module, first install the library with meson (see above for detailed instructions), and install with pip. For this setup, the meson prefix must be set to --prefix=/$DIGEST_REPO/build:
Alternatively, copy the lib and include directories from the earlier meson installation to a directory in the repo called build, and run pip install .
We recommend using a conda or python virtual environment. Once installed, you can import and use the Digest library in Python:
