.\"
.\" $Id: pfscan.1,v 1.5 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 PFSCAN  1 "July 2003" "pftools 2.3" "pftools"
.\" ------------------------------------------------
.\" Name section
.\" ------------------------------------------------
.SH NAME
pfscan \- scan a protein or DNA sequence with a profile library 
.\" ------------------------------------------------
.\" Synopsis section
.\" ------------------------------------------------
.SH SYNOPSIS
.TP 10
.B pfscan
[
.B \-abdfhlLmruksvxyz
] [
.B \-C
.I cut_off
] [
.B \-M
.I mode_nb
] [
.B \-W
.I width
] [
.I sequence
|
.B \-
] [
.I profile_library
|
.B \-
] [
.I parameters
]
.\" ------------------------------------------------
.\" Description section
.\" ------------------------------------------------
.SH DESCRIPTION
.B pfscan 
compares a protein or nucleic acid sequence against a profile library. 
The result is an unsorted list of profile-sequence matches written to
the standard output.
A variety of output formats containing different information can be specified
via the options
.BR \-l , \ \-L , \ \-r , \ \-k , \ \-s , \ \-x , \ \-y
and 
.BR \-z .
The file
.RI ' sequence '
contains a sequence in
.SM EMBL/SWISS-PROT
format (assumed by default) or in Pearson/Fasta
format (indicated by option 
.BR \-f ).
The
.RI ' profile_library '
file contains a library of profiles in
.SM PROSITE
format. 
If
.RB ' \- '
is specified instead of one of the filenames, the corresponding data is read
from the standard input.
.\" ------------------------------------------------
.\" Options section
.\" ------------------------------------------------
.SH OPTIONS 
.\" --- sequence ---
.TP
.I sequence
Input query sequence.
.br
This DNA or protein sequence will be used to search for matches to
a library of
.SM PROSITE
profiles.
.br
The content of the file must be either in
.SM EMBL/SWISS-PROT
(default) or in Pearson/Fasta format (option
.BR \-f ).
If the filename is replaced by a
.RB ' \- ',
.B pfscan
will read the input sequence from
.BR stdin .
.\" --- profile_library ---
.TP
.I profile_library
Library of
.SM PROSITE
profiles.
.br
This file should contain one or several
.SM PROSITE
profiles, against which the query sequence will be matched.
Each entry in this library should be separated from the next by
a line containing only the
.RB ' // '
code.
If the filename is replaced by a
.RB ' \- ',
.B pfscan
will read the profile library from
.BR stdin .
.\" --- a ---
.TP
.B \-a
Report optimal alignment scores for 
all profiles regardless of the cut-off value. 
This option simultaneously forces 
.IR DISJOINT = UNIQUE .   
.\" --- b ---
.TP
.B \-b
Search the complementary strand of the DNA sequence as well.
.\" --- f ---
.TP
.B \-f
Input sequence is in Pearson/Fasta format.
.\" --- h ---
.TP
.B \-h
Display usage help text.
.\" --- l ---
.TP
.B \-l
Indicate the value of the highest cut-off level exceeded by the match score
in the output list. 
.\" --- L ---
.TP
.B \-L
Indicate by character string the highest cut-off level exceeded by the match score
in the output list.
.br
.RS
.TP
Note:
The generalized profile format includes a text
string field to specify a name for a cut-off level. The
.B \-L
option causes the program to display the first two characters of this text string
(usually something like
.RI ' ! ',\ ' ? ',\ ' ?? ',
etc.) at the beginning of each match description.
.RE
.\" --- m ---
.TP
.B \-m
Report individual matches for circular profiles.
.br
If the profile is circular, each match between a sequence and a profile can be composed
of a stretch of individual matches of the profile. By default,
.B pfscan
reports only the total matched region. When this option is set, detailed information for 
each individual match will be output as well.
.RS
.TP
Note:
The scoring system for most circular profiles has been optimized to find
total matches, therefore the normalized scores of individual matches of a circular profile
to a sequence should be considered with caution.
.RE
.\" --- r ---
.TP
.B \-r
Use raw scores rather than normalized 
scores for match selection.  The normalized score is not printed.
.\" --- u ---
.TP
.B \-u
Forces
.IR DISJOINT = UNIQUE . 
.\" --- C ---
.TP
.BI \-C\  cut_off
Cut-off level to be used for match selection.
.br
The value of
.RI ' cut_off '
should be the numerical identifier of a cut-off level defined in the profile.
The raw or normalized score of this level will then be used to include profile to
sequence matches in the output list.
.br
If the specified level does not exist in the profile, the next higher (if 
.I cut_off
is negative) or next lower (if
.I cut_off
is positive) level defined is used instead.
.br
Type: integer
.br
Default: 0
.\" --- M ---
.TP
.BI \-M\  mode_nb
Normalization mode to use for score computation.
.br
The
.RI ' mode_nb '
specifies which normalization mode defined in the profile should be used
to compute the normalized scores for profile to sequence matches. This
option will override the profile's
.I PRIORITY
parameter.
.br
If the specified normalization mode does not exist in the profile, an error
message will be output to standard error and the search is interrupted.
.br
Type: integer
.br
Default: lowest priority mode defined in the profile
.\" ------------------------------------------------
.\" Output modifiers subsection
.\" ------------------------------------------------
.SS Output modifiers
.\" --- d ---
.TP
.B \-d
Limit profile description length.
.br
If this option is set, the description of the profile on the header line
will be limited in length. If the match information is longer than
the output width specified using option
.BR \-W ,
the profile description will not be printed. Else the description will be truncated
to fit the
.B \-W
value.
.br
By default, the profile description is not truncated. This option can not be used
when option
.B \-k
is set.
.\" --- k ---
.TP
.B \-k
Use
.BR xpsa (5)
headers for output.
.br
When this option is set, all output types 
.RI ( see
below) will use
an
.BR xpsa (5)
style header line. This format uses
.IR keyword = value
pairs to output alignment parameters. It is useful to transfer information between
different sequence alignment tools.
.\" --- s ---
.TP
.B \-s
List the sequences of the matched regions as well. 
The output will be a Pearson/Fasta-formatted sequence
library.
.\" --- v ---
.TP
.B \-v
Suppress sequence/profile parsing warnings.
If this option is set no warning messages will be printed on
.IR stderr .
Only fatal errors will be reported. This option should be used
with caution.
.\" --- x ---
.TP
.B \-x
List profile-sequence alignments 
in
.BR psa (5)
format. Please refer to the corresponding man page for more information. 
.\" --- y ---
.TP
.B \-y
Display alignments between the profile and the matched sequence regions in 
a human-friendly pairwise alignment format.   
.\" --- z ---
.TP
.B \-z
Indicate starting and ending position of the matched profile range. The latter
position will be given as a negative offset from the end of the profile. Thus
the range [    1,    -1] means entire profile.
.\" --- W ---
.TP
.BI \-W\  width
Set alignment output width.
.br
The value of
.RI ' width '
specifies how many residues will be output on one line when any of the
.BR \-s ,\  \-x \ or\  \-y
options is set.
.br
Type: integer
.br
Default: 60
.\" ------------------------------------------------
.\" 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=#
Cut-off level.
.br
Use option
.B \-C
instead, not
.BR \-L .
.TP
W=#
Output width.
.br
Use option
.B \-W
instead.
.\" ------------------------------------------------
.\" Examples section
.\" ------------------------------------------------
.SH EXAMPLES
.TP
(1)
.B pfscan
\-s GTPA_HUMAN prosite13.prf
.IP
Scans the human GAP protein for matches to profiles in
.SM PROSITE 
release 13. 
The file
.RI ' GTPA_HUMAN ' 
contains the 
.SM SWISS-PROT
entry P20936|GTPA_HUMAN.
The profile library file
.RI ' prosite13.prf ' 
contains all profile entries of
.SM PROSITE
release 13.  
The output is a Pearson/Fasta-formatted sequence library containing 
all sequence regions of the input sequence matching a profile in the 
profile library. 
.TP
(2)
.B pfscan
\-by \-C 2 CVPBR322 ecp.prf
.IP
Scans both strands of plasmid PBR322 for high-scoring (level 2) 
.I E. coli
promoter matches.   
The sequence file
.RI ' CVPBR322 '
contains
.SM EMBL
entry J01749|CVPBR322.
The profile library file
.RI ' ecp.prf '
contains a profile for
.I E. coli  
promoters.
The output includes profile-sequence alignments in a human-friendly
format. 
.\" ------------------------------------------------
.\" Exit code section
.\" ------------------------------------------------
.SH EXIT CODE
.LP
On successful completion of its task,
.B pfscan
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.
.\" ------------------------------------------------
.\" Bugs section
.\" ------------------------------------------------
.SH "BUGS"
If the match selection is based on normalized scores 
.RI ( i.e.
option
.B \-r
is not set), rounding errors can lead to the exclusion of some matches even if
the raw score is above or equal to the specified cut-off level score.
.\" ------------------------------------------------
.\" See also section
.\" ------------------------------------------------
.SH "SEE ALSO"
.BR pfsearch (1),
.BR pfmake (1),
.BR psa (5),
.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>.