MURASAKI(1)

📦 version 1.68.6, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 MURASAKI 💖

okay bestie, welcome to the murasaki manual page (that's the MURASAKI(1) one, user contributed Perl documentation, iykyk) — it computes anchors between multiple sequences and honestly? it's giving main character energy. buckle up, this is part one of three, so don't go anywhere. 🦋

✨ NAME ✨

murasaki — compute anchors between multiple sequences

🌸 SYNOPSIS 🌸

murasaki [OPTIONS] -p[pattern] seq1.fa seq2.gbk [seq3.raw ...] #compute anchors between seq1.fa and seq2.gbk using [pattern]
mpirun murasaki [OPTIONS] -p[pattern] seq1.fa seq2.gbk [seq3.raw ...] #compute anchors between seq1.fa and seq2.gbk using [pattern] in parallel via MPI

🎀 DESCRIPTION 🎀

okay so here's the tea ☕ — Murasaki generates anchors based on all the sequences you hand it, using the pattern you supply plus hash tables. Basically, every single base of every single sequence gets masked by the pattern, which forms a seed, and that seed gets used to generate a hash. The location of the seed? Stored in the hash table, obviously. 💅

Once all the seeds have been hashed and stored, Murasaki scans the hash table and generates anchors for all the matching seeds. An anchor is a set of intervals across a subset of the input sequences — no cap. These live in name.anchors files, and they're described in "FILE FORMATS".

By default, anchors are maximally extended until their minimum pairwise ungapped alignment score drops below a threshold — same fashion as the X-drop parameter in BLAST and BLAST-like searches. literally the same vibe. 🔥

🧬 PATTERNS 🧬

Murasaki uses spaced seed patterns when it's considering seeds. A spaced seed pattern is typically written as a string of 1s and 0s, and it necessarily starts and ends with a 1 (that part is not optional bestie, it's the rules).

1s mean this base is considered part of the seed.
bases sitting at 0 positions are not.

For example, with a pattern "1011", the sequence "ACGT" would match "AGGT" and "ATGT" but not "ACTT". slay.

The number of 1s in the pattern is called the "weight" of the pattern, and the number of 1s and 0s combined is the "length" of the pattern. Murasaki lets you use any arbitrary pattern expressed as a string of 1s and 0s, and it also interprets patterns of the form "x:y" to mean a "random pattern of weight x and length y."

The choice of pattern obviously has an impact on sensitivity and specificity, but whether one pattern is "better" than another depends on the application and the input sequences under consideration. Calculating "maximally sensitive spaced seed patterns" is a computationally difficult problem, and there are a number of research papers describing various methods for approximation (peep "RELATED READING"). In general though? "Heavier" spaced seed patterns are less sensitive but more specific than lighter seeds. Anecdotally we find that seeds with weights approximately 60% to 75% (with lengths around 24 for bacteria, and 36 to 48 for mammals) are good for most applications. Extremely similar species (for example human and chimp) benefit from longer, heavier seeds. ✨

🔐 HASH FUNCTIONS 🔐

Hash functions (and hash parameters too) are generated automatically, based on the system environment and the input sequences. There are essentially two types of hash functions available in Murasaki: adaptive and cryptographic hashes.

The adaptive hashes are XOR combinations of various bitwise shifts of the seed, designed by analyzing the spaced seed pattern to maximize the entropy of the resulting hash.
The cryptographic hashes are available via the CryptoPP library and use the entire spaced seed pattern to generate a hash using one of the common cryptographic hashes like MD5 or SHA-1.

The adaptive hash functions are almost always faster and more efficient than MD5 and SHA-1, but the cryptographic functions are available for reference and may be useful as an alternative in the unlikely event you're dealing with an environment where the adaptive hasher is unsuitable (for example a sequence consisting of only A and T (leaving 1 out of every 2 bits uninitialized)). 💀

🧠 MEMORY SCALING 🧠

Murasaki can take a lot of memory. Storing the location of each seed in the hash table is the most costly part of the operation, requiring approximately ceil(log_2(N)) bits per seed where N is the total sequence length. Locations are, by default, stored in a bitpacked format to approach theoretical minimum. so efficient, we love her. 🫶

The second most costly element is the hash table structure, where each bucket carries a small overhead and unused [buckets] are simply wasted space. More hash table buckets (i.e. a longer hash table) decreases the expected number of collisions, leading to faster execution time. Therefore Murasaki tries to use as many buckets as possible by inspecting the available system memory and using as much as it can while still storing all the seed locations.

If this automatic scaling is ineffective, setting the hash table size directly via the --hashbits|-b options can force a specific hash table size. And if the memory of one computer is insufficient to store the desired hash table, PARALLELIZATION can be used to distribute the hash table across multiple computers. 👑

🌈 PARALLELIZATION 🌈

Murasaki is designed to run in parallel using MPI. Consult the documentation for the specific variations of your MPI implementation, however in general the execution method looks like:

mpirun [MPI options] murasaki [murasaki options] -p[pattern] [seq1 ...]

Murasaki in parallel divides the number of processors available (NP) into two groups: hasher nodes and storage nodes.

The storage nodes divide the hash table between themselves, each one being responsible for a different part of the table.
The hasher nodes divide the input sequence between themselves, each hashing a separate portion of the input sequence, and passing the seed location to the appropriate storage node for storage.

When all the hasher nodes are finished hashing, the storage nodes scan their portion of the hash table and pass matching sets of seeds to a hasher node, where they're assembled into anchors and extended. Finally, all the hasher nodes combine their independent anchor sets into one final set in ceil(log_2(H)) iterations (where H is the number of hasher nodes), with each hasher node number 2h passing its anchors to hasher number 2h-1 at each iteration. 🌟

Because almost none of the parallelization steps require communication between all nodes, and each seed and each anchor can be processed in parallel, Murasaki scales very well in parallel — running approximately twice as fast when twice as many nodes are available. fr fr. Furthermore, the hash table is automatically grown to take advantage of the combined memory from multiple machines. iconic behavior honestly. 💜

✨ OPTIONS ✨

okay so here's the thing bestie: most options can be written out in their long form — like --directory out or --directory=out — or you can go short, like -dout. both work, pick your vibe 💅

and there's a little alphabet soup for the value types, so let's decode it:

<S> — wants a string
<D> — wants an integer
<F> — wants a float
 — wants a boolean: yes/on/true/1 for true, no/off/false/0 for false

and the booleans? most of them can just omit the value entirely and they'll flip from whatever they were to the opposite. toggling queen 👑

murasaki has… a lot of options. like, a lot a lot. so they're sorted into categories here to help you tell what each one's actually for. but heads up: in certain situations certain option choices may have unforeseen consequences, and obviously if the output you asked for is huge, the runtime is gonna be long. it is a mistake to think that everything outside the "tuning options" in the Performance section has no bearing on performance. no cap. 🫶

these ones shape what even counts as an "anchor".

--pattern|-p <S> — sets the seed pattern (eg. 11101001010011011). if you use the format [<w>:<l>] it automatically generates a random pattern of weight <w> and length <l> ✨
--repeatmask|-r  — skip repeat masked data (ie: lowercase atgc). just be aware that some sequence files are distributed purely in lower case, so… vibe check your input first 😭
--seedfilter|-f <D> — skip seeds that occur more than N times. exceptionally slow. see --hashfilter for a faster approximation.
--hashfilter|-m <D> — like --seedfilter but it works on hash keys instead of seeds. may cause some collateral damage to otherwise unique seeds, but it's faster. tradeoffs, bestie 💀
--skipfwd|-F  — don't hash/match the forward strands.
--skiprev|-R  — don't hash/match the reverse complement strands.
--skip1to1|-1  — skip matches along the 1:1 line (good for comparing to self 👀).
--hashonly|-Q  — Hash Only. no anchor output, just statistics.
--hashskip|-S <D> — hashes every n bases. default is 1 (i.e. hashing all positions). not supplying any argument increments the skip amount by 1.
--join|-j <D> — join anchors within n bases of each other (default: 0). specifying a negative D implies -D*patternLength.
--bitscore|-B  — toggles computation of a bitscore for all anchors (default is on).
--seedterms|-T  — toggles retention of seed terms (defaults to off). these are necessary for computing TF-IDF scores).
--sectime|-e  — always display times in seconds as opposed to human readable "1d 3h 45m 5s" style times.
--mergefilter|-Y <D> — filter out matches which would cause more than D many anchors to be generated from 1 seed (default -Y100). use -Y0 to disable.
--scorefilter <D> — set a minimum ungapped score for seeds.
--rifts|-/ <D> — allow anchors to skip D sequences (default 0).
--islands|-% <D> — same as --rifts=S-D (where S is number of input seqs).
--fuzzyextend|-z  — enable (default) or disable fuzzy extension (i.e. ungapped alignment) of anchors.
--fuzzyextendlosslimit|-Z <D> — set the cutoff at which to stop extending fuzzy hits (ie. the BLAST X parameter).
--gappedanchors  — use gapped (true) or ungapped (false (default)) anchors.
--scorebyminimumpair  — do anchor scoring by minimum pair when appropriate (default). the alternative is arithmetic mean (seldom useful, but theoretically faster).

🌸 Output options

these are the ones that mostly decide what data goes where.

--directory|-d <S> — output directory (default: output)
--name|-n <S> — alignment name (default: test)
--repeatmap|-i  — toggles keeping of a repeat map when --mergefilter is used (defaults to yes).
--histogram|-H <D> — histogram computation level (-H alone implies -H1):
- 0 - no histogram (default)
- 1 - basic bucketsize/bucketcount histogram data
- 2 - bucket-based scores to anchors.detils
- 3 - perbucket count data
- 4 - perbucket + perpattern count data any values above 2 are purely explorartory and can result in massive output files. like, unhinged file sizes. be careful 💀
--tfidf|-k  — perform accurate tfidf scoring from within murasaki (requires extra memory at anchor generation time). default is no.

🔥 Performance/tuning options

these mostly affect performance, and don't (in general) impact output. in general, okay, don't @ me.

--quickhash|-q <D> — specify a hashing function:
- 0 - adaptive with S-boxes (default when there's plenty of hash table to spare)
- 1 - don't pack bits to make hash (use first word only)
- 2 - naively use the first hashbits worth of pattern
- 3 - adaptivevely find a good hash (default)
- experimental CryptoPP hashes
- 4 - MD5
- 5 - SHA1
- 6 - Whirlpool
- 7 - CRC-32
- 8 - Adler-32

Note: 3 and 0 are the only "recommended" hash functions, and the only ones automatically selected. the others are provided merely for reference. 1, 7, and 8 aren't even expected to utilize the entire hash space. 🙈

--hashbits|-b <D> — use D bit hashes (for n's of 1 to WORDSIZE. default 26)
--hashtype|-t <S> — select hash table data structure to use:
- OpenHash - open sub-word packing of hashbits (default when there's plenty of hash table to spare)
- EcoHash - chained sub-word packing of hashbits (default)
- ArrayHash - malloc/realloc (fast but fragmentation-prone)
- MSetHash - memory exorbanant, almost pointless.
--probing <D> — 0 - linear, 1 - quadratic (default). only applicable for --hashtype=OpenHash.
--hitfilter|-h <D> — minimum number of hits to be outputted as an anchor (default 1). in PatternHunter this is 2.
--rseed|-s <D> — random number seed for non-deterministic algorithms (ie: adative hash function generation). if you're doing any performance comparisons, it's probably imperative that you use the same seed for each run of the same settings. default is obtained from time() (ie: seconds since 1970).
--memory|-M [<F>|<S>] — set the target amount of total memory (either in gb or as % total memory).
--reverseotf|-o  — generate reverse complement on the fly (defaults to on). turning this off precomputes all the reverse complement strands and stores them in memory, which rarely provides a measurable performance improvement.
--binaryseq  — enable (default) or disable binary sequence read/write

performance options related to adaptive hash function generation.

--hasherFairEntropy  — use more balanced entropy estimation (default: yes).
--hasherCorrelationAdjust  — adjust entropy estimates for nearby sources assuming some correlation (default: yes).
--hasherTargetGACycles <D> — adaptive hash function generation genetic algorithm cycle cutoff.
--hasherEntropyAgro <F> — how aggressive to be about pursuing maximum entropy hash functions (takes a real. default is 1).

💜 MPI Specific

--hashers|-A [<F>|<D>] — specify the number of processes to be used as hashers (only applies to MPI. if a number between 0 and 1 it refers to a ratio of np).
--localhash|-K  — perform hashing locally on each storage node rather than sending it over the network (helpful for slow networks).
--mpidistro|-L  — toggles use of MPI to distribute sequence data over (if the sequence is available on local disk on each node then turning this off may potentially accerlate the initial sequence loading).
--waittoanchor|-w  — postpone actual anchor computation until all location sets have been received (as opposed to trying to work between receiving seed packets).
--buffers|-u <D> — maximum number of unfinished buffers to allow while message passing (0 means unlimited). default is set based on the number of nodes participating.

MPI can crash or perform very poorly if this value is too high. ⚠️

--nobuffers|-U  — same as --buffers=1.
--bigfirst|-I  — assign hashers to large memory nodes first.
--hostbalance|-l  — if yes (default): spread out hashers evenly among all nodes. if no: ignore host name when assigning jobs.
--memorybalance|-a  — if yes (default): balance hash storage between nodes based on the amount of available ram. if no: distribute storage evently. this more likely to achieve optimal run times, but might not utilize memory as efficiently.
--distmerge|-<  — if yes (default): during the merge step, storage nodes send seeds to any available hasher. if no: send all seeds to one node only.
--distcollect|->  — if yes (default): collect anchor data from all hashers. if no: send all seeds to the final assembly node only.
--mpiredirectoutput  — if yes (default): each rank redirects its stdout/stderr to a separate file (murasaki-mpiout-N). if no: do what comes naturally (ie: managed by mpirun (for OpenMPI see --output-filename and --tag-output in mpirun(1))).
--keepstdoe  — don't erase the murasaki-mpiout files on success.
--sysvipc|-V  — use System V IPC to negotiate shared memory regions (saves memory when one host runs multiple nodes). default is true.

⭐ Universal options

--verbose|-v — increases verbosity.
--version|-V — prints version information and quits.
--help|-? — prints a help message and quits.

📂 FILE FORMATS 📂

Murasaki drops a whole array of output files, and honestly bestie, most of the formats are designed to just ~make sense~ on sight. Every output file gets prefixed with whatever you gave to the --name parameter, okay? The big ones are described right here. Unless it says otherwise, files are line based and tab delimited. 💖

🧬 `.seqs`

The .seqs file shows which sequences got used as input — one per line, periodt. Various programs use this file together with the .anchors file, so it's generally important that the contents actually reflect the correct sequence files. 👑

Heads up: if you move anchor results between computers, the paths might change and you'll have to update the .seqs file yourself. An alternative that lowkey fixes this: always use relative paths. 🫶

⚓ `.anchors` files

These are 1 anchor per line, with a 3-tuple per sequence. Each tuple = the start and stop coordinates plus the strand of the anchored interval on that sequence. The sequence order matches the order in the .seqs file. 🌸

Coordinates are structured so that 1 is the first base in the sequence, 2 is the second, etc. Negative values refer to the reverse complement sequence, where -1 is the last base of the reverse complement sequence (ie: the complement first base in the forward sequence). The "strand" element is a '+' or '-' that merely matches the sign of the coordinates — yes, that's redundant info, but it's kept around to make parsing or filtering simpler. 💅

For examle:

 1       18     +       -1      -18       -

This line describes an anchor where the first 18 bases of the first sequence match the first 18 bases of the reverse complement of the second sequence. Slay. ✨

📜 `.anchors.details`

This is an antiquated file format, ngl, but GMV uses it to calculate statistics like TF-IDF scores, so it's been kept around for that reason. The .anchors.details file has the same format and information as the .anchors file — except after the anchor tuples come two more terms: a score, and a comma (,) delimited list of term and count pairs (written "term:count"). The score and count data might be varied depending on the --histogram option choices. 🎀

🧮 `.anchors.bitscore`

The term "bitscore" here is a misnomer, but it's maintained for historical reasons. In reality this file contains the mean number of matching bases and the length of each anchor (corresponding line by line to the .anchors file). 💀

📊 `.stats.tfidf`

Contains anchor TF-IDF scores (corresponding line by line to the .anchors file). Cute, simple, iconic. 💜

📈 `.histogram`

Contains a simple histogram of the hash table usage. First field = the bucket size, second field = the frequency. So for example, a .histogram file like this:

 1  24
 2  1

Would indicate that there were 24 hash buckets that stored only 1 location (i.e. 24 unique seeds), and 1 hash bucket stored 2 locations (i.e. 1 seed that matched 2 locations (or 2 non-matching seeds that resulted in a hash collision)). 🌈

⚙️ `.options`

Maintains a record of the options used when running Murasaki. Receipts, basically. 🧾

🔁 `.repeats`

The .repeats file stores a record of "repeats" as defined by the --mergefilter option (i.e. seeds that would have have induced more anchors than permitted). In this file, each repeat record is separated by a blank line. A repeat record looks like this:

 R: G.GCCTTT.T.ACT.CACAA..AT
 0: 2145540494 -425039256 -113794380 1998323403
 1: 2480929222 -1874514626 2543723555 -2550045172

The first line (always prefixed "R:") shows the repeating seed itself (where the . are the bases masked by the pattern). The subsequent lines show where these seeds occurred in the input sequences (in the first (0) and second (1) sequences). Note that if there are no hits in a particular sequence, it doesn't include a blank line for that sequence. For example:

 R: G.GCCTTT.T.ACT.CACAA..AT
 0: 2145540494 -425039256 -113794380 1998323403
 2: 2480929222 -1874514626 2543723555 -2550045172

is also a valid .repeats file. 🦋

📄 LICENSE 📄

GNU General Public License, version 3 (GPLv3). Free as in bestie. 💖

🌐 AVAILABILITY 🌐

<http://murasaki.sourceforge.net>

👑 AUTHOR 👑

Kris Popendorf <krisp@dna.bio.keio.ac.jp>

👀 SEE ALSO 👀

mbfa(1), geneparse(1)

M. Csuros and B. Ma, "Rapid Homology Search with Two-Stage Extension and Daughter Seeds" (2005).
F. P. Preparata and L. Zhang and K. W. Choi, "Quick, practical selection of effective seeds for homology search" (2005).
KP Choi, et. al., "Good spaced seeds for homology search" (2004).

And that's a wrap, bestie!! 🎀 This page is perl v5.10.1, dated 2010-05-31, and it's the man page for MURASAKI(1) — go forth and align some sequences, you absolute icon. 💅✨

📦 where this page comes from

debian bookworm: murasaki 1.68.6-13+b3 · GPL-3.0-or-later
debian trixie: murasaki 1.68.6-14+b1 · GPL-3.0-or-later
ubuntu jammy: murasaki 1.68.6-13build1 · GPL-3.0-or-later
ubuntu noble: murasaki 1.68.6-13build6 · GPL-3.0-or-later
ubuntu questing: murasaki 1.68.6-15
ubuntu resolute: murasaki 1.68.6-17 · GPL-3.0-or-later
ubuntu stonking: murasaki 1.68.6-18 · GPL-3.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms