.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bio::SeqIO::swiss 3pm"
.TH Bio::SeqIO::swiss 3pm "2020-10-28" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::SeqIO::swiss \- Swissprot sequence input/output stream
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
It is probably best not to use this object directly, but
rather go through the SeqIO handler system:
.PP
.Vb 1
\&    use Bio::SeqIO;
\&
\&    $stream = Bio::SeqIO\->new(\-file => $filename,
\&                              \-format => \*(Aqswiss\*(Aq);
\&
\&    while ( my $seq = $stream\->next_seq() ) {
\&       # do something with $seq
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This object can transform Bio::Seq objects to and from Swiss-Pprot flat
file databases.
.PP
There is a lot of flexibility here about how to dump things which needs
to be documented.
.SS "\s-1GN\s0 (Gene name) line management details"
.IX Subsection "GN (Gene name) line management details"
A Uniprot/Swiss\-Prot entry holds information on one protein
sequence. If that sequence is identical across genes and species, they
are all merged into one entry. This creates complex needs for several
annotation fields in swiss-prot format.
.PP
The latest syntax for \s-1GN\s0 line is described in the user manual:
.PP
.Vb 1
\&  http://www.expasy.ch/sprot/userman.html#GN_line
.Ve
.PP
Each of the possibly multiple genes in an entry can have Name,
Synonyms (only if there is a name), OrderedLocusNames (names from
genomic sequences) and ORFNames (temporary or cosmid names). \*(L"Name\*(R"
here really means \*(L"symbol\*(R". This complexity is now dealt with the
following way:
.PP
A new Bio::AnnotationI class was created in order to store the
data in tag-value pairs.  This class (Bio::Annotation::TagTree)
is stored in the Bio::Annotation::Collection object and is
accessed like all other annotations. The tag name is 'gene_name'.
.PP
There is a single Bio::Annotation::TagTree per sequence record, which
corresponds to the original class that stored this data
(Bio::Annotation::StructuredValue).  Depending on how we progress
this may change to represent each group of gene names.
.PP
For now, to access the gene name tree annotation, one uses the below method:
.PP
.Vb 1
\&   my ($gene) = $seq\->annotation\->get_Annotations(\*(Aqgene_name\*(Aq);
.Ve
.PP
If you are only interested in displaying the values, \fBvalue()\fR returns a
string with similar formatting.
.PP
There are several ways to get directly at the information you want if you
know the element (tag) for the data.  For gene names all data is stored with
the element-tag pairs:
.PP
.Vb 1
\&  "element1=tag1, tag2, tag3; element2=tag4, tag5;"
.Ve
.PP
This normally means the element will be 'Name', 'Synonyms', etc. and the
gene names the values.  Using \fBfindval()\fR, you can do the following:
.PP
.Vb 2
\&  # grab a flattened list of all gene names
\&  my @names = $ann\->findval(\*(AqName\*(Aq);
\&
\&  # or iterated through the nodes and grab the name for each group
\&  for my $node ($ann\->findnode(\*(Aqgene_name\*(Aq)) {
\&     my @names = $node\->findval(\*(AqName\*(Aq);
\&  }
.Ve
.PP
The current method for parsing gene name data (and reconstructing gene name
output) is very generic. This is somewhat preemptive if, for instance, UniProt
decides to update and add another element name to the current ones using the
same formatting layout. Under those circumstances, one can iterate through the
tag tree in a safe way and retrieve all node data like so.
.PP
.Vb 2
\&  # retrieve the gene name nodes (groups like names, synonyms, etc).
\&  for my $ann ($seq\->annotation\->get_Annotations(\*(Aqgene_name\*(Aq)) {
\&
\&      # each gene name group
\&      for my $node ($ann\->findnode(\*(Aqgene_name\*(Aq)) {
\&          print "Gene name:\en";
\&
\&          # each gene name node (tag => value pair)
\&          for my $n ($node\->children) {
\&              print "\et".$n\->element.": ".$n\->children."\en";
\&          }
\&      }
\&  }
.Ve
.PP
For more uses see Bio::Annotation::TagTree.
.PP
Since Uniprot/Swiss\-Prot format have been around for quite some time, the
parser is also able to read in the older \s-1GN\s0 line syntax where genes
are separated by \s-1AND\s0 and various symbols by \s-1OR.\s0 The first symbol is
taken to be the 'Name' and the remaining ones are stored as 'Synonyms'.
.PP
Also, for UniProt output we support using other Bio::AnnotationI, but in this
case we only use the stringified version of the annotation. This is to allow for
backwards compatibility with code that previously used
Bio::Annotation::SimpleValue or other Bio::AnnotationI classes.
.SS "Optional functions"
.IX Subsection "Optional functions"
.IP "\fB_show_dna()\fR" 3
.IX Item "_show_dna()"
(output only) shows the dna or not
.IP "\fB_post_sort()\fR" 3
.IX Item "_post_sort()"
(output only) provides a sorting func which is applied to the FTHelpers
before printing
.IP "\fB_id_generation_func()\fR" 3
.IX Item "_id_generation_func()"
This is function which is called as
.Sp
.Vb 1
\&   print "ID   ", $func($seq), "\en";
.Ve
.Sp
To generate the \s-1ID\s0 line. If it is not there, it generates a sensible \s-1ID\s0
line using a number of tools.
.Sp
If you want to output annotations in Swissprot format they need to be
stored in a Bio::Annotation::Collection object which is accessible
through the Bio::SeqI interface method \fBannotation()\fR.
.Sp
The following are the names of the keys which are polled from a
Bio::Annotation::Collection object.
.Sp
.Vb 4
\& reference   \- Should contain Bio::Annotation::Reference objects
\& comment     \- Should contain Bio::Annotation::Comment objects
\& dblink      \- Should contain Bio::Annotation::DBLink objects
\& gene_name   \- Should contain Bio::Annotation::SimpleValue object
.Ve
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "Mailing Lists"
User feedback is an integral part of the evolution of this
and other Bioperl modules. Send your comments and suggestions,
preferably to one of the Bioperl mailing lists.
Your participation is much appreciated.
.PP
.Vb 2
\&  bioperl\-l@bioperl.org                  \- General discussion
\&  http://bioperl.org/wiki/Mailing_lists  \- About the mailing lists
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
rather than to the module maintainer directly. Many experienced and 
reponsive experts will be able look at the problem and quickly 
address it. Please include a thorough description of the problem 
with code and data examples if at all possible.
.SS "Reporting Bugs"
.IX Subsection "Reporting Bugs"
Report bugs to the Bioperl bug tracking system to help us keep track
the bugs and their resolution.
Bug reports can be submitted via the web:
.PP
.Vb 1
\&  https://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "AUTHOR \- Elia Stupka"
.IX Header "AUTHOR - Elia Stupka"
Email elia@tll.org.sg
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object methods.
Internal methods are usually preceded with a _
.SS "next_seq"
.IX Subsection "next_seq"
.Vb 5
\& Title   : next_seq
\& Usage   : $seq = $stream\->next_seq()
\& Function: returns the next sequence in the stream
\& Returns : Bio::Seq object
\& Args    :
.Ve
.SS "write_seq"
.IX Subsection "write_seq"
.Vb 5
\& Title   : write_seq
\& Usage   : $stream\->write_seq($seq)
\& Function: writes the $seq object (must be seq) to the stream
\& Returns : 1 for success and 0 for error
\& Args    : array of 1 to n Bio::SeqI objects
.Ve
.SS "_generateCRCTable"
.IX Subsection "_generateCRCTable"
.Vb 6
\& Title   : _generateCRCTable
\& Usage   :
\& Function:
\& Example :
\& Returns :
\& Args    :
.Ve
.SS "_crc32"
.IX Subsection "_crc32"
.Vb 6
\& Title   : _crc32
\& Usage   :
\& Function:
\& Example :
\& Returns :
\& Args    :
.Ve
.SS "_crc64"
.IX Subsection "_crc64"
.Vb 6
\& Title   : _crc64
\& Usage   :
\& Function:
\& Example :
\& Returns :
\& Args    :
.Ve
.SS "_print_swissprot_FTHelper"
.IX Subsection "_print_swissprot_FTHelper"
.Vb 6
\& Title   : _print_swissprot_FTHelper
\& Usage   :
\& Function:
\& Example :
\& Returns :
\& Args    :
.Ve
.SS "_read_swissprot_References"
.IX Subsection "_read_swissprot_References"
.Vb 6
\& Title   : _read_swissprot_References
\& Usage   :
\& Function: Reads references from swissprot format. Internal function really
\& Example :
\& Returns :
\& Args    :
.Ve
.SS "_read_swissprot_Species"
.IX Subsection "_read_swissprot_Species"
.Vb 9
\& Title   : _read_swissprot_Species
\& Usage   :
\& Function: Reads the swissprot Organism species and classification
\&           lines.
\&             Able to deal with unconventional species names.
\& Example : OS Unknown prokaryotic organism
\&             $genus = undef ; $species = Unknown prokaryotic organism
\& Returns : A Bio::Species object
\& Args    :
.Ve
.SS "_filehandle"
.IX Subsection "_filehandle"
.Vb 6
\& Title   : _filehandle
\& Usage   : $obj\->_filehandle($newval)
\& Function:
\& Example :
\& Returns : value of _filehandle
\& Args    : newvalue (optional)
.Ve
.SS "_read_FTHelper_swissprot"
.IX Subsection "_read_FTHelper_swissprot"
.Vb 6
\& Title   : _read_FTHelper_swissprot
\& Usage   : _read_FTHelper_swissprot(\e$buffer)
\& Function: reads the next FT key line
\& Example :
\& Returns : Bio::SeqIO::FTHelper object
\& Args    :
.Ve
.SS "_write_line_swissprot"
.IX Subsection "_write_line_swissprot"
.Vb 6
\& Title   : _write_line_swissprot
\& Usage   :
\& Function: internal function
\& Example :
\& Returns :
\& Args    :
.Ve
.SS "_write_line_swissprot_regex"
.IX Subsection "_write_line_swissprot_regex"
.Vb 9
\& Title   : _write_line_swissprot_regex
\& Usage   :
\& Function: internal function for writing lines of specified
\&           length, with different first and the next line
\&           left hand headers and split at specific points in the
\&           text
\& Example :
\& Returns : nothing
\& Args    : file handle, first header, second header, text\-line, regex for line breaks, total line length
.Ve
.SS "_post_sort"
.IX Subsection "_post_sort"
.Vb 5
\& Title   : _post_sort
\& Usage   : $obj\->_post_sort($newval)
\& Function:
\& Returns : value of _post_sort
\& Args    : newvalue (optional)
.Ve
.SS "_show_dna"
.IX Subsection "_show_dna"
.Vb 5
\& Title   : _show_dna
\& Usage   : $obj\->_show_dna($newval)
\& Function:
\& Returns : value of _show_dna
\& Args    : newvalue (optional)
.Ve
.SS "_id_generation_func"
.IX Subsection "_id_generation_func"
.Vb 5
\& Title   : _id_generation_func
\& Usage   : $obj\->_id_generation_func($newval)
\& Function:
\& Returns : value of _id_generation_func
\& Args    : newvalue (optional)
.Ve
.SS "_ac_generation_func"
.IX Subsection "_ac_generation_func"
.Vb 5
\& Title   : _ac_generation_func
\& Usage   : $obj\->_ac_generation_func($newval)
\& Function:
\& Returns : value of _ac_generation_func
\& Args    : newvalue (optional)
.Ve
.SS "_sv_generation_func"
.IX Subsection "_sv_generation_func"
.Vb 5
\& Title   : _sv_generation_func
\& Usage   : $obj\->_sv_generation_func($newval)
\& Function:
\& Returns : value of _sv_generation_func
\& Args    : newvalue (optional)
.Ve
.SS "_kw_generation_func"
.IX Subsection "_kw_generation_func"
.Vb 5
\& Title   : _kw_generation_func
\& Usage   : $obj\->_kw_generation_func($newval)
\& Function:
\& Returns : value of _kw_generation_func
\& Args    : newvalue (optional)
.Ve