.\"
.\" $Id: ptof.1,v 1.2 2003/08/11 12:09:14 vflegel Exp $
.\" Copyright (c) 2003 SIB Swiss Institute of Bioinformatics <pftools@sib.swiss>
.\" Process this file with
.\" groff -man -Tascii <name>
.\" for ascii output or
.\" groff -man -Tps <name>
.\" for postscript output
.\"
.TH PTOF 1 "August 2003" "pftools 2.3" "pftools"
.\" ------------------------------------------------
.\" Name section
.\" ------------------------------------------------
.SH NAME
ptof \- convert a protein profile into a frame-search profile  
.\" ------------------------------------------------
.\" Synopsis section
.\" ------------------------------------------------
.SH SYNOPSIS
.TP 10
.B ptof
[
.B \-hlr
] [
.B \-B
.I init/term_score
] [
.B \-F
.I frameshift
] [
.B \-I
.I insert_multiplier
] [
.B \-X
.I stop_codon
] [
.B \-Y
.I intron_open
] [
.B \-Z
.I intron_extend
] [
.I protein_profile
|
.B \-
] [
.I parameters
]
.\" ------------------------------------------------
.\" Description section
.\" ------------------------------------------------
.SH DESCRIPTION
.B ptof
converts a protein profile (generated for instance by pftools
programs 
.BR pfmake (1), 
.BR gtop (1)
or
.BR htop (1))
into a so-called
.RI \(dq frame-search\ profile \(dq.
A frame-search profile is used to search an
.RI \(dq interleaved\ frame-translated \(dq
DNA sequence (generated by pftools program
.BR 2ft (1))
for occurrences of a protein sequence motif.
An
.RI \(dq interleaved\ frame-translated \(dq
DNA sequence is an amino acid sequence corresponding to the 
.I N-2
overlapping codons of a DNAsequence of length
.IR N .
Note that in such a sequence, the character
.RB ' O '
is used to represent stop codons.
.LP
The conversion procedure works as follows: The protein profile is 
expanded in length by a factor of three to accommodate three translated
codons per original match position.
Two dummy match positions are placed between two consecutive significant match positions
imported from the original profile. 
The original insert positions are placed between pairs of adjacent dummy match positions.
The initiation, termination, and transition scores of the original insert
positions are left unchanged; the
insert extension scores are divided by a factor of 3, or by the value of the command-line
option 
.BR \-I .  
The two insert positions flanking the significant match positions 
serve to accommodate frame-shift errors and introns, respectively.
The frame-shift insert position allows free insertion opening combined
with a high insert extension penalty (command-line option 
.BR \-F ) 
whereas the intron insertion position has high opening but low extension penalties
(command line options 
.B \-Y
and
.BR \-Z ).
The deletion opening and closing penalties next to the significant 
match positions are set to values that ensure that the total cost of a single-base
deletion is the same as the cost of  
a single base-insertion at a frame-shift insert position.
Furthermore, the alphabet of the original profile is extended by the stop codon symbol
.RB ' O ' 
which is assigned a constant negative value (command-line option
.BR \-X )
at significant match positions, and zero at dummy match positions. At insert positions,
it is set to the average of the other insert extension scores.
.\" ------------------------------------------------
.\" Options section
.\" ------------------------------------------------
.SH OPTIONS
.\" --- protein_profile ---
.TP
.I protein_profile
Input protein profile.
.br
The protein profile contained in this file will be converted into a frame-search profile.
If the filename is replaced by a
.RB ' \- ',
.B ptof
will read the profile from
.BR stdin .
.\" --- h ---
.TP
.B \-h
Display usage help text.
.\" --- l ---
.TP
.B \-l
Remove output line length limit. Individual lines of the output profile
can exceed a length of 132 characters, removing the need to wrap them over several lines. 
.\" --- r ---
.TP
.B \-r
Frame-search parameters are given in normalized score units. This option
will only be considered if a linear normalization function with
priority over all other normalization functions is specified 
in the profile. 
In this case, the frame-search scores specified on the command line will be 
divided by the slope
.RI ( R2
parameter) of the normalization function. 
This option is particularly useful for profiles which are 
already scaled in units that can be interpreted as \(miLog(P)-values, 
.I e.g.
bits.  
.\" --- B ---
.TP
.BI \-B\  init/term_score
Minimal initiation and termination score.
.br
All internal and external initiation and termination scores will be set to this 
value if the corresponding value in the original profile is lower than 
this value.
This parameter is used to impose a more
local alignment behavior on the frame-search profile in order to
deal with discontinuities in DNA sequences (long introns,
alternative splicing, chimeric clones, 
.IR etc. )
.br 
Default: \-50 (\-0.5 with option
.BR \-r )
.\" --- F ---
.TP
.BI \-F\  frameshift
Frame-shift error penalty.
.br
Default: \-100 (\-1.0 with option
.BR \-r ) 
.\" --- I ---
.TP
.BI \-I\  insert_multiplier
Insert score multiplier.
.br
The values of the original
insert extension scores will be multiplied by this
factor in order to compensate for the fact that 
a single amino acid corresponds to three overlapping
codon positions in the target sequence.
.br
Default: 1/3
.\" --- X ---
.TP
.BI \-X\  stop_codon
Stop codon penalty.
.br
Default: \-100 (\-1.0 with option
.BR -r )
.\" --- Y ---
.TP
.BI \-Y\  intron_open
Intron opening penalty.
.br
Default: \-300 (\-3.0 with option
.BR \-r ) 
.\" --- Z ---
.TP
.BI \-Z\  intron_extend
Intron extension penalty.
.br
Default: \-1 (\-0.01 with option
.BR \-r )
.\" ------------------------------------------------
.\" Parameters section
.\" ------------------------------------------------
.SH PARAMETERS
.TP
Note:
for backwards compatibility, release 2.3 of the
.B pftools
package will parse the version 2.2 style parameters, but these are
.I deprecated
and the corresponding option (refer to the
.I options
section) should be used instead.
.TP
B=#
Minimal initiation and termination score.
.br
Use option
.B \-B
instead.
.TP
F=#
Frame-shift error penalty.
.br
Use option
.B \-F
instead.
.TP
I=#
Insert score multiplier.
.br
Use option
.B \-I
instead.
.TP
X=#
Stop codon penalty.
.br
Use option
.B \-X
instead.
.TP
Y=#
Intron opening penalty.
.br
Use option
.B \-Y
instead.
.TP
Z=#
Intron extension penalty.
.br
Use option
.B \-Z
instead.
.\" ------------------------------------------------
.\" Examples section
.\" ------------------------------------------------
.SH EXAMPLES
.TP
(1)
.B ptof
\-r \-F -1.2 \-I 0.6 \-X -1.5 \-B -0.5 sh3.prf > sh3.fsp
.br
.B 2ft \-
< R76849.seq | 
.B pfsearch 
\-fy \-C 5.0 sh3.fsp \- 
.IP
The protein domain profile in 
.RI ' sh3.prf '
is first converted into a frame-search profile 
.RI ' sh3.fsp '.
Then both strands of the Fasta-formatted EST sequence in
.RI ' R76849.seq '
(GenBank/EMBL-accession: R76849) are converted into interleaved frame-translated
protein sequences and searched for SH3 domains with the frame-search profile 
generated in the preceding step.
.IP
The output may be compared to the result of a more conventional
search strategy using a protein profile in conjunction with a six-frame
translation of the same DNA sequence:
.IP
.B 6ft \-
< R76849.seq | 
.B pfsearch 
\-fy \-C 5.0 sh3.prf \-
.\" ------------------------------------------------
.\" Exit code section
.\" ------------------------------------------------
.SH EXIT CODE
.LP
On successful completion of its task,
.B ptof
will return an exit code of 0. If an error occurs, a diagnostic message will be
output on standard error and the exit code will be different from 0. When conflicting
options where passed to the program but the task could nevertheless be completed, warnings
will be issued on standard error.
.\" ------------------------------------------------
.\" See also section
.\" ------------------------------------------------
.SH "SEE ALSO"
.BR pfscan (1),
.BR pfsearch (1),
.BR 2ft (1),
.BR 6ft (1)
.\" ------------------------------------------------
.\" Author section
.\" ------------------------------------------------
.SH AUTHOR
The
.B pftools
package was developed by Philipp Bucher.
.br
Any comments or suggestions should be addressed to <pftools@sib.swiss>.