PATMAN(1)

👑 PATMAN(1) — the patman manual, bestie edition 👑

okay so you found your way to the patman man page and honestly? iconic. this is a User Manual situation, and the whole thing lives under the name PatMaN. buckle up, we're searching for approximate patterns in DNA libraries and it's gonna be a whole vibe 🧬✨

---

✨ NAME ✨

PatMaN — search for approximate patterns in DNA libraries 🦋

---

🌸 SYNOPSIS 🌸

patman [ option | file ... ]

---

💖 DESCRIPTION 💖

So PatMaN goes looking for (small) patterns inside (huge) DNA databases, and it's totally chill with a few mismatches and, if you want, some gaps too. 🫶

Patterns and databases get read from one or more fasta(5) files that you list as non-option arguments — and which is which depends on whether -D or -P was the last one to show up before them, iykyk — and then they get matched against each other.

The output of PatMaN is a table with one line per match, and the fields are tab-separated:

• name of database sequence,
• name of pattern,
• position of first matched base in database sequence, the sequence's beginning has position 1,
• position of last matched base in database sequence,
• strand (+ for literal match, - for reverse complement),
• edit distance (number of mismatches plus number of gaps).

---

🎀 OPTIONS 🎀

• -V, --version — print the version number and dip. bye 💅
• -e num, --edits num — let there be up to num mismatches and/or gaps per match.
• -g num, --gaps num — allow up to num gaps per match. heads up bestie: gaps count as mismatches too, so you should always set -e at least as high as -g. and letting lots of gaps happen can cost you a considerable amount of compute. 😭
• -D, --databases — treat the files that follow as database. databases have to be in fasta(5) format. you can give multiple database files, and - means standard input — they get read in turn. 🗂️
• -P, --patterns — treat the files that follow as patterns. pattern files have to be in fasta(5) format too. multiple pattern files are allowed, - means standard input, and they are all read before we even touch the databases. 💖
• -o file, --output file — send the output to file. the file name - makes output go to stdout, which is also the default.
• -a, --ambicodes — turn on interpretation of ambiguity codes in patterns. what happens is any pattern with ambiguity codes gets expanded into multiple patterns, and those can match independently. compare the Unknown Nucleotides bit below. 🌈
• -s, --singlestrand — turn off reverse-complement matching. normally PatMaN tries to match patterns both literally and after reverse-complementing them; with this set, only straight-forward matches get considered. ✨
• -p num, --prefetch num — prefetch num pointers in advance. this can boost performance if PatMaN was compiled for a processor architecture that supports prefetching. the optimum value for your particular setup has to be figured out empirically, but the default should be reasonably good. 🧚
• -l len, --min-length len — only consider patterns that are at least len long. use this when your pattern collection has short sequences and you don't want a ton of possible matches reported for them. 🙈
• -x num, --chop3 num — cut num bases off the 3' end of each pattern. use this for patterns with damaged, edited, etc. 3' ends that should be ignored. the chopped bases are neither matched nor included in the reported match regions. 🍓
• -X num, --chop5 num — cut num bases off the 5' end of each pattern. use this for patterns with damaged, edited, etc. 5' ends that should be ignored. the chopped bases are neither matched nor included in the reported match regions. 🍓
• -A, --adenine-hack — let adenine be ignored in patterns. this is basically equivalent to not counting gaps in the database, as long as it was an A that got gapped. using -A can be computationally extremely expensive, in both memory and time. 💀
• -q, --quiet — suppress warnings (about unrecognized characters in input sequences, or missing input files). even without -q, at most one such warning is given per run. 🤫
• -v, --verbose — prints extra progress information to stderr.
• -d flags, --debug flags — sets debugging flags to flags. flags may be the logical OR of any of the values below, and each of them makes some output appear on stderr. some of the values may only work if PatMaN has been compiled in debug mode. the default value is 1. 🔥
  1. print warnings. equivalent to not setting -q.
  2. print progress information. equivalent to setting -v.
  4. dump the suffix trie of the patterns. only available in debug build.
  8. count number of visited nodes and print that number in each iteration. only available in debug build.
  16. print total number of nodes fetched from memory after completing all databases.
  32. output database sequence while it is being matched.

---

💜 NOTES 💜

📁 Non-Option Arguments

Non-option arguments (bare filenames) are treated as either database or pattern files, depending on whether the -D or -P option was the last one that occurred before the filename. if neither -D nor -P was given, file names get treated as pattern files. if no database was given, it's read from standard input instead. standard input can be explicitly given as either a database or a pattern file by using the filename -.

a warning is given if standard input is selected implicitly as database, and an error message is given if no pattern files have been named at all. 🫶

🕳️ Gapped Matching

Allowing gaps often causes overlapping matches of single patterns at almost the same position. PatMaN makes no attempt to filter these redundant matches. also note that allowing many gaps — and especially allowing an arbitrary amount of gaps through the -A hack — can slow down PatMaN considerably and cause it to produce enormous amounts of output. the use of some sorty of post-processor to filter these is highly recommended. 😭

❓ Unknown Nucleotides

Unknown nucleotides are most often encoded by the letter N. if the --ambicodes option is not given, Ns in patterns are interpreted as unknown nucleotides and can never match without penalty. if --ambicodes is given, Ns in patterns are expanded just like the other amibuguity codes, and effectively work as wildcards. unknown nucleotides can still be encoded by an X and will never match anything.

the database is treated differently: anything other than A, C, G, T and U, including ambiguity codes, is treated as unknown and can never match without penalty. 💅

---

🗄️ FILES 🗄️

• /etc/popt — the system wide configuration file for popt(3). PatMaN identifies itself as patman to popt.
• ~/.popt — per user configuration file for popt(3).

---

💀 BUGS 💀

None known. (bestie is literally flawless, no cap 😌)

---

👑 AUTHOR 👑

Kay Pruefer <pruefer@eva.mpg.de> Udo Stenzel <udo_stenzel@eva.mpg.de>

---

🌈 SEE ALSO 🌈

popt(3), fasta(5)

---

and that's the whole page, bestie — this was the Applications manual, dated JANUARY 2008, and it ate. periodt. 💖✨🎀