Provided by: phast_1.5+dfsg-1_amd64 
NAME
pbsTrain - Estimate a discrete encoding scheme for probabilistic biological
DESCRIPTION
Estimate a discrete encoding scheme for probabilistic biological sequences (PBSs) based on training data.
Input file should be a table of probability vectors, with a row for each distinct vector, and a column of
counts (positive integers) followed by d columns for the elements of the d-dimensional probability
vectors (see example below). It may be produced with 'prequel' using the --suff-stats option. Output is
a code file that can be used with pbsEncode, pbsDecode, etc. By default, a code of size 255 is created,
so that encoded PBSs can be represented with one byte per position (the 256th letter in the code is
reserved for gaps). The --nbytes option allows larger codes to be created, if desired.
The code is estimated by a two-part procedure designed to minimize the "training error" (defined as the
total KL divergence) of the encoded training data with respect to the original training data. 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 is
given the largest possible value such that the number of simplex regions is no larger than the target
code size, but smaller values of n can be specified using --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) 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. (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.)
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, on each step, the simplex
region with the largest contribution to the total error is identified, and the next letter in the code is
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.
EXAMPLE
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).
OPTIONS
--nrows, -n <n> Number of "rows" per dimension in the simplex grid. Default is 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 -- 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.