Meryl
Introduction
This is a kmer coounting program, part of a larger suite of tools at kmer.sourceforge.net
It's by Brian Walenz of Kanu (MinION genome assembly fame).
Simple example
Typically, it's a two stage process. A database of kmers must be built. This is the -B option below:
meryl -B -C -m 22 -s /data/references/ecolik12.fasta -o ecoli-22mers
-C is for canonical, which is kmers on both forward(-f) and (-r) strands.
Then the second stage would be as follows:
meryl -Dh -s ecoli-22mers > ecoli-22mers.fasta
Help file
It usually overflows on the screen, so here it is in full:
usage: meryl [personality] [global options] [options]
where personality is:
-P -- compute parameters
-B -- build table
-S -- scan table
-M -- "math" operations
-D -- dump table
-P: Given a sequence file (-s) or an upper limit on the
number of mers in the file (-n), compute the table size
(-t in build) to minimize the memory usage.
-m # (size of a mer; required)
-c # (homopolymer compression; optional)
-p (enable positions)
-s seq.fasta (seq.fasta is scanned to determine the number of mers)
-n # (compute params assuming file with this many mers in it)
Only one of -s, -n need to be specified. If both are given
-s takes priority.
-B: Given a sequence file (-s) and lots of parameters, compute
the mer-count tables. By default, both strands are processed.
-f (only build for the forward strand)
-r (only build for the reverse strand)
-C (use canonical mers, assumes both strands)
-L # (DON'T save mers that occur less than # times)
-U # (DON'T save mers that occur more than # times)
-m # (size of a mer; required)
-c # (homopolymer compression; optional)
-p (enable positions)
-s seq.fasta (sequence to build the table for)
-o tblprefix (output table prefix)
-v (entertain the user)
By default, the computation is done as one large sequential process.
Multi-threaded operation is possible, at additional memory expense, as
is segmented operation, at additional I/O expense.
Threaded operation: Split the counting in to n almost-equally sized
pieces. This uses an extra h MB (from -P) per thread.
-threads n (use n threads to build)
Segmented, sequential operation: Split the counting into pieces that
will fit into no more than m MB of memory, or into n equal sized pieces.
Each piece is computed sequentially, and the results are merged at the end.
Only one of -memory and -segments is needed.
-memory mMB (use at most m MB of memory per segment)
-segments n (use n segments)
Segmented, batched operation: Same as sequential, except this allows
each segment to be manually executed in parallel.
Only one of -memory and -segments is needed.
-memory mMB (use at most m MB of memory per segment)
-segments n (use n segments)
-configbatch (create the batches)
-countbatch n (run batch number n)
-mergebatch (merge the batches)
Initialize the compute with -configbatch, which needs all the build options.
Execute all -countbatch jobs, then -mergebatch to complete.
meryl -configbatch -B [options] -o file
meryl -countbatch 0 -o file
meryl -countbatch 1 -o file
...
meryl -countbatch N -o file
meryl -mergebatch N -o file
Batched mode can run on the grid.
-sge jobname unique job name for this execution. Meryl will submit
jobs with name mpjobname, ncjobname, nmjobname, for
phases prepare, count and merge.
-sgebuild "options" any additional options to sge, e.g.,
-sgemerge "options" "-p -153 -pe thread 2 -A merylaccount"
N.B. - -N will be ignored
N.B. - be sure to quote the options
-M: Given a list of tables, perform a math, logical or threshold operation.
Unless specified, all operations take any number of databases.
Math operations are:
min count is the minimum count for all databases. If the mer
does NOT exist in all databases, the mer has a zero count, and
is NOT in the output.
minexist count is the minimum count for all databases that contain the mer
max count is the maximum count for all databases
add count is sum of the counts for all databases
sub count is the first minus the second (binary only)
abs count is the absolute value of the first minus the second (binary only)
Logical operations are:
and outputs mer iff it exists in all databases
nand outputs mer iff it exists in at least one, but not all, databases
or outputs mer iff it exists in at least one database
xor outputs mer iff it exists in an odd number of databases
Threshold operations are:
lessthan x outputs mer iff it has count < x
lessthanorequal x outputs mer iff it has count <= x
greaterthan x outputs mer iff it has count > x
greaterthanorequal x outputs mer iff it has count >= x
equal x outputs mer iff it has count == x
Threshold operations work on exactly one database.
-s tblprefix (use tblprefix as a database)
-o tblprefix (create this output)
-v (entertain the user)
NOTE: Multiple tables are specified with multiple -s switches; e.g.:
meryl -M add -s 1 -s 2 -s 3 -s 4 -o all
NOTE: It is NOT possible to specify more than one operation:
meryl -M add -s 1 -s 2 -sub -s 3
will NOT work.
-D: Dump the table (not all of these work).
-Dd Dump a histogram of the distance between the same mers.
-Dt Dump mers >= a threshold. Use -n to specify the threshold.
-Dc Count the number of mers, distinct mers and unique mers.
-Dh Dump (to stdout) a histogram of mer counts.
-s Read the count table from here (leave off the .mcdat or .mcidx).
