.\"
.\" $Id: pfscale.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 PFSCALE 1 "August 2003" "pftools 2.3" "pftools"
.\" ------------------------------------------------
.\" Name section
.\" ------------------------------------------------
.SH NAME
pfscale \- fit parameters of an extreme-value distribution to a profile score list 
.\" ------------------------------------------------
.\" Synopsis section
.\" ------------------------------------------------
.SH SYNOPSIS
.TP 10
.B pfscale
[
.B \-hl
] [
.B \-L
.I log_base
] [
.B \-M
.I mode_nb
] [
.B \-N
.I db_size
] [
.B \-P
.I upper_limit
] [
.B \-Q
.I lower_limit
] [
.I score_list
|
.B \-
] [
.I profile
] [
.I parameters
]
.\" ------------------------------------------------
.\" Description section
.\" ------------------------------------------------
.SH DESCRIPTION
.B pfscale 
fits the two parameters of an extreme-value distribution to a
sorted score distribution obtained
by searching a sequence database with a profile. 
The file
.RI ' score_list '
is a sorted list of profile match scores generated by
.BR pfsearch .
If
.RB ' \- '
is specified instead of a filename, the score list is read from the
standard input. The result is written to the standard output.
.PP
If the original profile is given as the second argument, 
the normalization function with the lowest mode number or the lowest priority number
specified within the profile will be 
updated such as to produce -Log10 per-residue E-values. 
If the second argument is omitted, the output 
consists of a header line containing the normalization parameters
followed by a modified score list, 
showing
.IR "score rank" ,
.IR "original raw scores" ,
.I log-cumulative frequencies
and
corresponding
.I normalized scores
next to each other.
.PP
Note that this program implements the significance estimation procedure for profile
match scores described in Hofmann & Bucher (1995). 
It has been used for the calculation of the normalization parameters of 
all profiles in the
.SM PROSITE
database. 
.\" ------------------------------------------------
.\" Options section
.\" ------------------------------------------------
.SH OPTIONS 
.\" --- ms_file ---
.TP
.I score_list
Input score list.
.br
The file must contain a sorted list of scores. The first field
of each line is considered as being a score, all other fields on the same line are ignored.
The different fields of each line should be delimited by whitespaces.
If the filename is replaced by a
.RB ' \- ',
.B pfscale
will read the score list from
.BR stdin .
.\" --- profile ---
.TP
.I profile
Optional profile file.
.br
If a filename is specified, the profile will be parsed and
either the lowest priority mode or the mode number specified with option
.B \-M
will be scaled. All cut-off levels which use the specified mode number will also
be updated.
.\" --- 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. 
.\" --- L ---
.TP
.BI \-L\  log_base
Logarithmic base of the parameters of the estimated extreme-value 
distribution. 
The parameters reported by 
.B pfscale
are expressed as logarithms
and thus can be inserted directly into a linear normalization function
defined in a generalized profile.
.br
Default: 10
.\" --- M ---
.TP
.BI \-M\  mode_nb
Mode number to scale.
.br
Defines which mode number (and implicitly which cut-off level) of the
input
.SM PROSITE
profile should be scaled. This overrides the default behaviour of scaling
only the normalization mode with the lowest priority (or lowest mode number).
All cut-off levels defined in the profile as using this mode number (via the
.I MODE
keyword) will be updated as well.
.\" --- N ---
.TP
.BI \-N\  db_size
Size of the database from which the input score list was derived.
The searched database is typically a shuffled version
of a real protein or nucleotide sequence database.
.br
Default: 14147368 (size of
.SM SWISS-PROT
release 30 and shuffled derivatives of it).
.\" --- P ---
.TP
.BI \-P\  upper_limit
Upper threshold of the probability range to which the extreme-value
distribution will be fitted. 
For instance: if
.IR N =10'000'000
and 
.IR P =0.0001
then profile match scores below rank 1000
in the sorted input list
(corresponding to occurrence probabilities > 0.0001)
will be ignored.
.br
Default: 0.0001
.\" --- Q ---
.TP
.BI \-Q\  lower_limit
Lower threshold of the probability range to which the extreme-value
distribution will be fitted. 
For instance: if
.IR N =10'000'000
and
.IR Q =0.000001
then profile match scores above rank 10 in the sorted input list
(corresponding to occurrence probabilities < 0.000001)
will be ignored.
.br
Default: 0.000001
.\" ------------------------------------------------
.\" 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
L=#
Logarithmic base.
.br
Use option
.B \-L
instead.
.TP
M=#
Mode number.
.br
Use option
.B \-M
instead.
.TP
N=#
Database size.
.br
Use option
.B \-N
instead.
.TP
P=#
Upper probability threshold.
.br
Use option
.B \-P
instead.
.TP
Q=#
Lower probability threshold.
.br
Use option
.B \-Q
instead.
.\" ------------------------------------------------
.\" Examples section
.\" ------------------------------------------------
.SH EXAMPLES
.TP
(1)
.B pfsearch
\-fr \-C 200 sh3.prf shuffle20.seq |
.B sort
\-nr | 
.B pfscale
\-P 0.0001 \-Q 0.000001 \-
.IP
derives score-normalization parameters for the SH3 domain profile 
in file
.RB ' sh3.prf '. 
The file
.RB ' shuffle20.seq '
contains a window-shuffled derivative of 
.SM SWISS-PROT
release 30 in Pearson/Fasta format (window-size 20). 
Note that the implicit default of 
.I N
corresponds to the size of this database and thus 
needs not to be specified on the command line.
The cut-off value 200 for the
.BR pfsearch (1)
option
.B \-C
will produce about 2000 matches completely covering the range defined by
the command line parameters
.B \-P
and 
.B \-Q
of
.BR pfscale .
A suitable cut-off value has to be guessed in advance 
by computing a few optimal alignment scores for random sequences. 
.\" ------------------------------------------------
.\" Exit code section
.\" ------------------------------------------------
.SH EXIT CODE
.LP
On successful completion of its task,
.B pfscale
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.
.\" ------------------------------------------------
.\" Notes section
.\" ------------------------------------------------
.SH NOTES
.TP
(1)
The current version of
.B pfscale
does not yet support the
.BR xpsa (5)
output format produced by
.BR pfscan "(1) or " pfsearch (1).
The score list should therefore be generated without the
.BR pfscan "(1) and " pfsearch (1)
option
.BR \-k .
.\" ------------------------------------------------
.\" References section
.\" ------------------------------------------------
.SH REFERENCES
.LP
Hofmann K & Bucher P. (1995).
.I The FHA-domain: a nuclear signalling domain found in protein kinases and transcription factors. 
Trends Biochem. Sci.
.BR 20 :47-349. 
.\" ------------------------------------------------
.\" See also section
.\" ------------------------------------------------
.SH "SEE ALSO"
.BR pfsearch (1),
.BR pfscan (1),
.BR xpsa (5)
.\" ------------------------------------------------
.\" 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>.