PBSSCOREMATRIX(1)

💖 PBSSCOREMATRIX — bestie edition 💖

okay so this is the manual page for pbsScoreMatrix, section 1 (User Commands), and I need you to lock in because it's lowkey giving "math class but make it fashion". ✨

---

🌸 NAME 🌸

pbsScoreMatrix — Generate log-odds score matrices for use in alignment of

(yes bestie, the sentence just ends there, we don't make the rules, we just vibe with it 🙈)

---

✨ DESCRIPTION ✨

So the whole point: we generate log-odds score matrices for use in alignment of probabilistic biological sequences (PBSs, iykyk). By default it generates a matrix for every branch of the tree (as defined in tree.mod), but it can also generate a matrix for a given branch length (see --branch-length). For a code size of N, an N x N matrix is generated by default; --half-pbs will produce an N x 4 matrix, and --no-pbs will produce a 4 x 4 matrix (assuming a four-character nucleotide alphabet). 🧬

Two sequences are assumed to have evolved from a common ancestor by a reversible continuous-time Markov substitution process, and to be separated by a branch of length t. The conditional probability of a base j in one sequence given a base i in the other, P(j | i, t) is given by element (i, j) of the matrix

       P(t) = exp(Qt)

where Q is the rate matrix defining the substitution process, and element (i, j) of Q is the instantaneous rate at which base i changes to base j. 👑

Let S_t(i, j) be a log odds score for the alignment of two bases, i and j, based on P(t):

       S_t(i, j) = log P(i, j | t) / (pi(i) * pi(j))

              = log P(j | i, t) pi(i) / (pi(i) * pi(j))

              = log P(j | i, t) / pi(j)                         (1)

where pi(x) is the "equilibrium" or "background" probability of base x. Because of reversibility, S(i, j) = S(j, i), and the S(i, j) form a symmetric 4 x 4 matrix. That's the matrix that gets generated by pbsScoreMatrix with the --no-pbs option. 💅

If each "letter" in each sequence represents a probability distribution over bases, as in a PBS, then the score for two letters k and l can be shown to be

       S'_t(k, l) = log sum_i sum_j p_k(i) p_l(j) exp S_t(i, j) (2)

where the two sums are over the four bases, p_k(i) is the probability of base i under the distribution for k, and p_l(j) is the probability of base j under the distribution for l. 🦋

Notice that (2) reduces to (1) when p_k(i) = p_l(j) = 1 for some i and j and for all other i' and j' p_k(i') = p_l(j') = 0 (i.e., when all of the probability mass is on a single base in both distributions and the PBS reduces to an ordinary nucleotide sequence). The special case of p_l(j) = 1 only is also of interest when aligning a PBS and a nucleotide sequence:

       S''_t(k, j) = log sum_i p_k(i) exp S_t(i, j) (3)

This is the matrix generated by pbsScoreMatrix with the --half-pbs option. 🎀

⚠️ Note: all logs are base 2. no cap.

---

🔥 EXAMPLE 🔥

Generate an N x N matrix for every branch of the tree, using a code file "code" (generated by pbsTrain) and a tree model file "mytree.mod" (generated by phyloFit):

       pbsScoreMatrix mytree.mod code > matrices.dat

Generate an N x N matrix for a branch length of 0.2 expected substitutions per site.

       pbsScoreMatrix --branch-length 0.2 mytree.mod code > matrix.dat

Generate an N x 4 matrix:

       pbsScoreMatrix --branch-length 0.2 --half-pbs mytree.mod code >
       matrix.dat

Generate a 4 x 4 matrix:

       pbsScoreMatrix --branch-length 0.2 --no-pbs code mytree.mod >
       matrix.dat

(In this case, a code file is not needed.) 💀 iconic behavior honestly

---

🌈 OPTIONS 🌈

• --branch-length, -t <length> — Output a matrix for a branch of the specified length, rather than a matrix for every branch of the tree. The given length must be non-negative and in units of expected substitutions per site. 🍓
• --half-pbs, -H — Output an N x 4 matrix, as described above. ✨
• --no-pbs, -N — Output a 4 x 4 matrix, as described above. With this option, a code file is not needed. 🫶
• --help, -h — Show this help message. 💜

---

that's the whole page bestie, you ate it up 🧚

this was pbsScoreMatrix version 1.4, dated May 2016 — go forth and align, mwah 💅💖