---
name: "pbsScoreMatrix"
section: "1"
platform: "linux"
package: "phast"
version: "1.7+dfsg-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/pbsScoreMatrix"
---

# pbsScoreMatrix(1)

Generate log-odds score matrices for use in alignment of

## NAME

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

## DESCRIPTION

Generate log-odds score matrices for use in alignment of probabilistic biological sequences (PBSs).  By default, generates a matrix for every branch of the tree (as defined in tree.mod), but 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.  This is the matrix that is 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.

## 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.)

## 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.