PBSTRAIN(1)

💖 NAME 💖

ok so pbsTrain — bestie she estimates a discrete encoding scheme for probabilistic biological sequences (PBSs). that's the whole job. iconic of her honestly 🦋

---

✨ DESCRIPTION ✨

okay so here's the tea ☕: pbsTrain estimates a discrete encoding scheme for probabilistic biological sequences (PBSs) based on training data. no cap, that's the vibe.

Your input file needs to be a table of probability vectors, and like, here's the layout bestie:

• one row for each distinct vector,
• a column of counts (positive integers) coming first,
• then d columns for the elements of the d-dimensional probability vectors.

(peep the example down below if you're confused, it's giving very clear ✨)

you can literally make this file with prequel using the --suff-stats option, so slay.

The output is a code file that plays nice with pbsEncode, pbsDecode, etc. 💅 and by default a code of size 255 gets created, so that encoded PBSs can be represented with one byte per position (the 256th letter in the code is reserved for gaps, periodt). but if you want bigger codes, the --nbytes option has you covered 🫶

---

ok so the code is estimated by a two-part procedure designed to minimize the "training error" (which is defined as the total KL divergence) of the encoded training data with respect to the original training data. let's break it down:

part one 🎀 — first, a "grid" is defined for the probability simplex, partitioning it into regions that intersect "cells" (hypercubes) in a matrix in d-dimensional space. this grid has n "rows" per dimension. by default, n gets the largest possible value such that the number of simplex regions is no larger than the target code size — but you can specify smaller values of n with --nrows. Each simplex region is assigned a letter in the code, and the representative point for that letter is set equal to the mean (weighted by the counts, iykyk) of all vectors in the training data that fall in that region. this can be shown to minimize the training error for this initial encoding scheme, no cap. (and if no vectors fall in a region, then the representative point is set equal to the centroid of the region, which can be shown to minimize the expected KL divergence of points uniformly distributed in the region. math girlies stay winning 💅)

part two 🌸 — in the second part of the estimation procedure, the remaining letters in the code are defined by a greedy algorithm, which attempts to further minimize the training error. briefly (because bestie this is a lot):

• on each step, the simplex region with the largest contribution to the total error is identified,
• and the next letter in the code gets assigned to that region.

in this new encoding there are multiple letters, hence multiple representative points, per region. the representative point for a given vector is taken to be the closest, in terms of KL divergence, of the representative points associated with the simplex region in which that vector falls. when a new representative point is added to a region, all representative points for that region are reoptimized using a k-means type algorithm. this procedure is repeated, letter by letter, until the number of code letters equals the target code size. ate. 🔥

---

🦋 EXAMPLE 🦋

first step bestie: generate training data using prequel:

prequel --suff-stats mammals.fa mytree.mod training

a file called "training.stats" will be generated ✨ it will look something like this:

#count
p(A)    p(C)    p(G)    p(T)
170085
0.043485        0.797886        0.029534        0.129096
158006
0.191119        0.046081        0.695205        0.067595
221937
0.047309        0.122834        0.043852        0.786004
221585
0.781156        0.044520        0.126179        0.048146
159472
0.067254        0.697947        0.045959        0.188840
...

now estimate a code from the training data:

pbsTrain training.stats > mammals.code

the code file contains some metadata followed by a list of code indices and representative points, e.g.:

##NROWS = 7
##DIMENSION = 4
##NBYTES = 1
##CODESIZE = 255
# Code generated by pbsTrain, with argument(s) "training.stats"
# acs, Mon Jul 18 23:29:07 2005
# Average training error = 0.001298 bits

each index of the code is shown below with its representative probability vector (p1, p2, ..., pd) 👑

#code_index p1 p2 ...
0       0.107143        0.107143        0.107143        0.678571
1       0.033226        0.093854        0.031987        0.840933
2       0.000059        0.001645        0.000111        0.998185
3       0.139270        0.021059        0.278993        0.560678
...

the reported "average training error" is the training error divided by the number of data points (the sum of the counts). math checks out bestie, trust 💜

---

🌈 OPTIONS 🌈

• --nrows, -n <n> — number of "rows" per dimension in the simplex grid. default is the maximum possible for code size ✨
• --nbytes, -b <b> — number of bytes per encoded probabilistic base (default 1). the size of the code will be 256^b - 1 (one letter in the code is reserved for gaps). values as large as 4 are allowed for b, but in the current implementation, performance considerations effectively limit it to 2 or 3. 💀
• --no-greedy, -G — skip greedy optimization entirely 🚫 — just assign a single representative point to each region of the probability simplex, equal to the (weighted) mean of all vectors from the training data that fall in that region.
• --no-train, -x <dim> — ignore the data entirely; just use the centroid of each simplex partition. the dimension of the simplex must be given (<dim>) but no data file is required 🙈
• --log, -l <file> — write log of optimization procedure to specified file 📝
• --help, -h* — print this help message 🫶

---

and that's the whole thing bestie!! this was pbsTrain version 1.4, dated May 2016 — go forth and encode, you're the main character of this probability simplex now 👑💖✨