.\" 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::Seq 3pm"
.TH Bio::Seq 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::Seq \- Sequence object, with features
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    # This is the main sequence object in Bioperl
\&
\&    # gets a sequence from a file
\&    $seqio  = Bio::SeqIO\->new( \*(Aq\-format\*(Aq => \*(Aqembl\*(Aq , \-file => \*(Aqmyfile.dat\*(Aq);
\&    $seqobj = $seqio\->next_seq();
\&
\&    # SeqIO can both read and write sequences; see Bio::SeqIO
\&    # for more information and examples
\&
\&    # get from database
\&    $db = Bio::DB::GenBank\->new();
\&    $seqobj = $db\->get_Seq_by_acc(\*(AqX78121\*(Aq);
\&
\&    # make from strings in script
\&    $seqobj = Bio::Seq\->new( \-display_id => \*(Aqmy_id\*(Aq,
\&                             \-seq => $sequence_as_string);
\&
\&    # gets sequence as a string from sequence object
\&    $seqstr   = $seqobj\->seq(); # actual sequence as a string
\&    $seqstr   = $seqobj\->subseq(10,50); # slice in biological coordinates
\&
\&    # retrieves information from the sequence
\&    # features must implement Bio::SeqFeatureI interface
\&
\&    @features = $seqobj\->get_SeqFeatures(); # just top level
\&    foreach my $feat ( @features ) {
\&        print "Feature ",$feat\->primary_tag," starts ",$feat\->start," ends ",
\&            $feat\->end," strand ",$feat\->strand,"\en";
\&
\&        # features retain link to underlying sequence object
\&        print "Feature sequence is ",$feat\->seq\->seq(),"\en"
\&    }
\&
\&    # sequences may have a species
\&
\&    if( defined $seq\->species ) {
\&        print "Sequence is from ",$species\->binomial," [",$species\->common_name,"]\en";
\&    }
\&
\&    # annotation objects are Bio::AnnotationCollectionI\*(Aqs
\&    $ann      = $seqobj\->annotation(); # annotation object
\&
\&    # references is one type of annotations to get. Also get
\&    # comment and dblink. Look at Bio::AnnotationCollection for
\&    # more information
\&
\&    foreach my $ref ( $ann\->get_Annotations(\*(Aqreference\*(Aq) ) {
\&        print "Reference ",$ref\->title,"\en";
\&    }
\&
\&    # you can get truncations, translations and reverse complements, these
\&    # all give back Bio::Seq objects themselves, though currently with no
\&    # features transferred
\&
\&    my $trunc = $seqobj\->trunc(100,200);
\&    my $rev   = $seqobj\->revcom();
\&
\&    # there are many options to translate \- check out the docs
\&    my $trans = $seqobj\->translate();
\&
\&    # these functions can be chained together
\&
\&    my $trans_trunc_rev = $seqobj\->trunc(100,200)\->revcom\->translate();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A Seq object is a sequence with sequence features placed on it. The
Seq object contains a PrimarySeq object for the actual sequence and
also implements its interface.
.PP
In Bioperl we have 3 main players that people are going to use frequently
.PP
.Vb 5
\&  Bio::PrimarySeq  \- just the sequence and its names, nothing else.
\&  Bio::SeqFeatureI \- a feature on a sequence, potentially with a sequence
\&                     and a location and annotation.
\&  Bio::Seq         \- A sequence and a collection of sequence features
\&                     (an aggregate) with its own annotation.
.Ve
.PP
Although Bioperl is not tied heavily to file formats these distinctions do
map to file formats sensibly and for some bioinformaticians this might help
.PP
.Vb 3
\&  Bio::PrimarySeq  \- Fasta file of a sequence
\&  Bio::SeqFeatureI \- A single entry in an EMBL/GenBank/DDBJ feature table
\&  Bio::Seq         \- A single EMBL/GenBank/DDBJ entry
.Ve
.PP
By having this split we avoid a lot of nasty circular references
(sequence features can hold a reference to a sequence without the sequence
holding a reference to the sequence feature). See Bio::PrimarySeq and
Bio::SeqFeatureI for more information.
.PP
Ian Korf really helped in the design of the Seq and SeqFeature system.
.SS "Examples"
.IX Subsection "Examples"
A simple and fundamental block of code:
.PP
.Vb 1
\&  use Bio::SeqIO;
\&
\&  my $seqIOobj = Bio::SeqIO\->new(\-file=>"1.fa"); # create a SeqIO object
\&  my $seqobj = $seqIOobj\->next_seq;              # get a Seq object
.Ve
.PP
With the Seq object in hand one has access to a powerful set of Bioperl
methods and related Bioperl objects. This next script will take a file of sequences
in \s-1EMBL\s0 format and create a file of the reverse-complemented sequences
in Fasta format using Seq objects. It also prints out details about the
exons it finds as sequence features in Genbank Flat File format.
.PP
.Vb 2
\&  use Bio::Seq;
\&  use Bio::SeqIO;
\&
\&  $seqin = Bio::SeqIO\->new( \-format => \*(AqEMBL\*(Aq , \-file => \*(Aqmyfile.dat\*(Aq);
\&  $seqout= Bio::SeqIO\->new( \-format => \*(AqFasta\*(Aq, \-file => \*(Aq>output.fa\*(Aq);
\&
\&  while((my $seqobj = $seqin\->next_seq())) {
\&      print "Seen sequence ",$seqobj\->display_id,", start of seq ",
\&            substr($seqobj\->seq,1,10),"\en";
\&      if( $seqobj\->alphabet eq \*(Aqdna\*(Aq) {
\&            $rev = $seqobj\->revcom;
\&            $id  = $seqobj\->display_id();
\&            $id  = "$id.rev";
\&            $rev\->display_id($id);
\&            $seqout\->write_seq($rev);
\&      }
\&
\&      foreach $feat ( $seqobj\->get_SeqFeatures() ) {
\&           if( $feat\->primary_tag eq \*(Aqexon\*(Aq ) {
\&              print STDOUT "Location ",$feat\->start,":",
\&                    $feat\->end," GFF[",$feat\->gff_string,"]\en";
\&           }
\&      }
\&  }
.Ve
.PP
Let's examine the script. The lines below import the Bioperl modules.
Seq is the main Bioperl sequence object and SeqIO is the Bioperl support
for reading sequences from files and to files
.PP
.Vb 2
\&  use Bio::Seq;
\&  use Bio::SeqIO;
.Ve
.PP
These two lines create two SeqIO streams: one for reading in sequences
and one for outputting sequences:
.PP
.Vb 2
\&  $seqin = Bio::SeqIO\->new( \-format => \*(AqEMBL\*(Aq , \-file => \*(Aqmyfile.dat\*(Aq);
\&  $seqout= Bio::SeqIO\->new( \-format => \*(AqFasta\*(Aq, \-file => \*(Aq>output.fa\*(Aq);
.Ve
.PP
Notice that in the \*(L"$seqout\*(R" case there is a greater-than sign,
indicating the file is being opened for writing.
.PP
Using the
.PP
.Vb 1
\&  \*(Aq\-argument\*(Aq => value
.Ve
.PP
syntax is common in Bioperl. The file argument is like an argument
to \fBopen()\fR . You can also pass in filehandles or FileHandle objects by
using the \-fh argument (see Bio::SeqIO documentation for details).
Many formats in Bioperl are handled, including Fasta, \s-1EMBL,\s0 GenBank,
Swissprot (swiss), \s-1PIR,\s0 and \s-1GCG.\s0
.PP
.Vb 2
\&  $seqin = Bio::SeqIO\->new( \-format => \*(AqEMBL\*(Aq , \-file => \*(Aqmyfile.dat\*(Aq);
\&  $seqout= Bio::SeqIO\->new( \-format => \*(AqFasta\*(Aq, \-file => \*(Aq>output.fa\*(Aq);
.Ve
.PP
This is the main loop which will loop progressively through sequences
in a file, and each call to \f(CW$seqio\fR\->\fBnext_seq()\fR provides a new Seq
object from the file:
.PP
.Vb 1
\&  while((my $seqobj = $seqio\->next_seq())) {
.Ve
.PP
This print line below accesses fields in the Seq object directly. The
\&\f(CW$seqobj\fR\->display_id is the way to access the display_id attribute
of the Seq object. The \f(CW$seqobj\fR\->seq method gets the actual
sequence out as string. Then you can do manipulation of this if
you want to (there are however easy ways of doing truncation,
reverse-complement and translation).
.PP
.Vb 2
\&  print "Seen sequence ",$seqobj\->display_id,", start of seq ",
\&               substr($seqobj\->seq,1,10),"\en";
.Ve
.PP
Bioperl has to guess the alphabet of the sequence, being either 'dna',
\&'rna', or 'protein'. The alphabet attribute is one of these three
possibilities.
.PP
.Vb 1
\&  if( $seqobj\->alphabet eq \*(Aqdna\*(Aq) {
.Ve
.PP
The \f(CW$seqobj\fR\->revcom method provides the reverse complement of the Seq
object as another Seq object. Thus, the \f(CW$rev\fR variable is a reference to
another Seq object. For example, one could repeat the above print line
for this Seq object (putting \f(CW$rev\fR in place of \f(CW$seqobj\fR). In this
case we are going to output the object into the file stream we built
earlier on.
.PP
.Vb 1
\&  $rev = $seqobj\->revcom;
.Ve
.PP
When we output it, we want the id of the outputted object
to be changed to \*(L"$id.rev\*(R", ie, with .rev on the end of the name. The
following lines retrieve the id of the sequence object, add .rev
to this and then set the display_id of the rev sequence object to
this. Notice that to set the display_id attribute you just need
call the same method, \fBdisplay_id()\fR, with the new value as an argument.
Getting and setting values with the same method is common in Bioperl.
.PP
.Vb 3
\&  $id  = $seqobj\->display_id();
\&  $id  = "$id.rev";
\&  $rev\->display_id($id);
.Ve
.PP
The write_seq method on the SeqIO output object, \f(CW$seqout\fR, writes the
\&\f(CW$rev\fR object to the filestream we built at the top of the script.
The filestream knows that it is outputting in fasta format, and
so it provides fasta output.
.PP
.Vb 1
\&  $seqout\->write_seq($rev);
.Ve
.PP
This block of code loops over sequence features in the sequence
object, trying to find ones who have been tagged as 'exon'.
Features have start and end attributes and can be outputted
in Genbank Flat File format, \s-1GFF,\s0 a standarized format for sequence
features.
.PP
.Vb 6
\&  foreach $feat ( $seqobj\->get_SeqFeatures() ) {
\&      if( $feat\->primary_tag eq \*(Aqexon\*(Aq ) {
\&          print STDOUT "Location ",$feat\->start,":",
\&             $feat\->end," GFF[",$feat\->gff_string,"]\en";
\&      }
\&  }
.Ve
.PP
The code above shows how a few Bio::Seq methods suffice to read, parse,
reformat and analyze sequences from a file. A full list of methods
available to Bio::Seq objects is shown below. Bear in mind that some of
these methods come from PrimarySeq objects, which are simpler
than Seq objects, stripped of features (see Bio::PrimarySeq for
more information).
.PP
.Vb 1
\&  # these methods return strings, and accept strings in some cases:
\&
\&  $seqobj\->seq();              # string of sequence
\&  $seqobj\->subseq(5,10);       # part of the sequence as a string
\&  $seqobj\->accession_number(); # when there, the accession number
\&  $seqobj\->alphabet();         # one of \*(Aqdna\*(Aq,\*(Aqrna\*(Aq,or \*(Aqprotein\*(Aq
\&  $seqobj\->version()           # when there, the version
\&  $seqobj\->keywords();         # when there, the Keywords line
\&  $seqobj\->length()            # length
\&  $seqobj\->desc();             # description
\&  $seqobj\->primary_id();       # a unique id for this sequence regardless
\&                               # of its display_id or accession number
\&  $seqobj\->display_id();       # the human readable id of the sequence
.Ve
.PP
Some of these values map to fields in common formats. For example, The
\&\fBdisplay_id()\fR method returns the \s-1LOCUS\s0 name of a Genbank entry,
the (\eS+) following the > character in a Fasta file, the \s-1ID\s0 from
a SwissProt file, and so on. The \fBdesc()\fR method will return the \s-1DEFINITION\s0
line of a Genbank file, the description following the display_id in a
Fasta file, and the \s-1DE\s0 field in a SwissProt file.
.PP
.Vb 2
\&  # the following methods return new Seq objects, but
\&  # do not transfer features across to the new object:
\&
\&  $seqobj\->trunc(5,10)  # truncation from 5 to 10 as new object
\&  $seqobj\->revcom       # reverse complements sequence
\&  $seqobj\->translate    # translation of the sequence
\&
\&  # if new() can be called this method returns 1, else 0
\&
\&  $seqobj\->can_call_new
\&
\&  # the following method determines if the given string will be accepted
\&  # by the seq() method \- if the string is acceptable then validate()
\&  # returns 1, or 0 if not
\&
\&  $seqobj\->validate_seq($string)
\&
\&  # the following method returns or accepts a Species object:
\&
\&  $seqobj\->species();
.Ve
.PP
Please see Bio::Species for more information on this object.
.PP
.Vb 3
\&  # the following method returns or accepts an Annotation object
\&  # which in turn allows access to Annotation::Reference
\&  # and Annotation::Comment objects:
\&
\&  $seqobj\->annotation();
.Ve
.PP
These annotations typically refer to entire sequences, unlike
features.  See Bio::AnnotationCollectionI,
Bio::Annotation::Collection, Bio::Annotation::Reference, and
Bio::Annotation::Comment for details.
.PP
It is also important to be able to describe defined portions of a
sequence. The combination of some description and the corresponding
sub-sequence is called a feature \- an exon and its coordinates within
a gene is an example of a feature, or a domain within a protein.
.PP
.Vb 1
\&  # the following methods return an array of SeqFeatureI objects:
\&
\&  $seqobj\->get_SeqFeatures # The \*(Aqtop level\*(Aq sequence features
\&  $seqobj\->get_all_SeqFeatures # All sequence features, including sub\-seq
\&                               # features, such as features in an exon
\&
\&  # to find out the number of features use:
\&
\&  $seqobj\->feature_count
.Ve
.PP
Here are just some of the methods available to SeqFeatureI objects:
.PP
.Vb 1
\&  # these methods return numbers:
\&
\&  $feat\->start          # start position (1 is the first base)
\&  $feat\->end            # end position (2 is the second base)
\&  $feat\->strand         # 1 means forward, \-1 reverse, 0 not relevant
\&
\&  # these methods return or accept strings:
\&
\&  $feat\->primary_tag    # the name of the sequence feature, eg
\&                        # \*(Aqexon\*(Aq, \*(Aqglycoslyation site\*(Aq, \*(AqTM domain\*(Aq
\&  $feat\->source_tag     # where the feature comes from, eg, \*(AqEMBL_GenBank\*(Aq,
\&                        # or \*(AqBLAST\*(Aq
\&
\&  # this method returns the more austere PrimarySeq object, not a
\&  # Seq object \- the main difference is that PrimarySeq objects do not
\&  # themselves contain sequence features
\&
\&  $feat\->seq            # the sequence between start,end on the
\&                        # correct strand of the sequence
.Ve
.PP
See Bio::PrimarySeq for more details on PrimarySeq objects.
.PP
.Vb 1
\&  # useful methods for feature comparisons, for start/end points
\&
\&  $feat\->overlaps($other)  # do $feat and $other overlap?
\&  $feat\->contains($other)  # is $other completely within $feat?
\&  $feat\->equals($other)    # do $feat and $other completely agree?
\&
\&  # one can also add features
\&
\&  $seqobj\->add_SeqFeature($feat)     # returns 1 if successful
\&
\&  # sub features. For complex join() statements, the feature
\&  # is one sequence feature with many sub SeqFeatures
\&
\&  $feat\->sub_SeqFeature  # returns array of sub seq features
.Ve
.PP
Please see Bio::SeqFeatureI and Bio::SeqFeature::Generic,
for more information on sequence features.
.PP
It is worth mentioning that one can also retrieve the start and end
positions of a feature using a Bio::LocationI object:
.PP
.Vb 3
\&  $location = $feat\->location # $location is a Bio::LocationI object
\&  $location\->start;           # start position
\&  $location\->end;             # end position
.Ve
.PP
This is useful because one needs a Bio::Location::SplitLocationI object
in order to retrieve the coordinates inside the Genbank or \s-1EMBL\s0 \fBjoin()\fR
statements (e.g. \*(L"\s-1CDS\s0    join(51..142,273..495,1346..1474)\*(R"):
.PP
.Vb 6
\&  if ( $feat\->location\->isa(\*(AqBio::Location::SplitLocationI\*(Aq) &&
\&               $feat\->primary_tag eq \*(AqCDS\*(Aq )  {
\&    foreach $loc ( $feat\->location\->sub_Location ) {
\&      print $loc\->start . ".." . $loc\->end . "\en";
\&    }
\&  }
.Ve
.PP
See Bio::LocationI and Bio::Location::SplitLocationI for more
information.
.SH "Implemented Interfaces"
.IX Header "Implemented Interfaces"
This class implements the following interfaces.
.IP "Bio::SeqI" 4
.IX Item "Bio::SeqI"
Note that this includes implementing Bio::PrimarySeqI.
.IP "Bio::IdentifiableI" 4
.IX Item "Bio::IdentifiableI"
.PD 0
.IP "Bio::DescribableI" 4
.IX Item "Bio::DescribableI"
.IP "Bio::AnnotatableI" 4
.IX Item "Bio::AnnotatableI"
.IP "Bio::FeatureHolderI" 4
.IX Item "Bio::FeatureHolderI"
.PD
.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 \- Ewan Birney, inspired by Ian Korf objects"
.IX Header "AUTHOR - Ewan Birney, inspired by Ian Korf objects"
Email birney@ebi.ac.uk
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
.Vb 2
\& Jason Stajich E<lt>jason@bioperl.orgE<gt>
\& Mark A. Jensen maj \-at\- fortinbras \-dot\- us
.Ve
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object
methods. Internal methods are usually preceded with a \*(L"_\*(R".
.SS "new"
.IX Subsection "new"
.Vb 5
\& Title   : new
\& Usage   : $seq = Bio::Seq\->new( \-seq => \*(AqATGGGGGTGGTGGTACCCT\*(Aq,
\&                                 \-id  => \*(Aqhuman_id\*(Aq,
\&                                 \-accession_number => \*(AqAL000012\*(Aq,
\&                               );
\&
\& Function: Returns a new Seq object from
\&           basic constructors, being a string for the sequence
\&           and strings for id and accession_number
\& Returns : a new Bio::Seq object
.Ve
.SH "PrimarySeq interface"
.IX Header "PrimarySeq interface"
The PrimarySeq interface provides the basic sequence getting
and setting methods for on all sequences.
.PP
These methods implement the Bio::PrimarySeq interface by delegating
to the primary_seq inside the object. This means that you
can use a Seq object wherever there is a PrimarySeq, and
of course, you are free to use these functions anyway.
.SS "seq"
.IX Subsection "seq"
.Vb 10
\& Title   : seq
\& Usage   : $string = $obj\->seq()
\& Function: Get/Set the sequence as a string of letters. The
\&           case of the letters is left up to the implementer.
\&           Suggested cases are upper case for proteins and lower case for
\&           DNA sequence (IUPAC standard),
\&           but implementations are suggested to keep an open mind about
\&           case (some users... want mixed case!)
\& Returns : A scalar
\& Args    : Optionally on set the new value (a string). An optional second
\&           argument presets the alphabet (otherwise it will be guessed).
\&           Both parameters may also be given in named parameter style
\&           with \-seq and \-alphabet being the names.
.Ve
.SS "validate_seq"
.IX Subsection "validate_seq"
.Vb 12
\& Title   : validate_seq
\& Usage   : if(! $seqobj\->validate_seq($seq_str) ) {
\&                print "sequence $seq_str is not valid for an object of
\&                alphabet ",$seqobj\->alphabet, "\en";
\&           }
\& Function: Test that the given sequence is valid, i.e. contains only valid
\&           characters. The allowed characters are all letters (A\-Z) and \*(Aq\-\*(Aq,\*(Aq.\*(Aq,
\&           \*(Aq*\*(Aq,\*(Aq?\*(Aq,\*(Aq=\*(Aq and \*(Aq~\*(Aq. Spaces are not valid. Note that this
\&           implementation does not take alphabet() into account.
\& Returns : 1 if the supplied sequence string is valid, 0 otherwise.
\& Args    : \- Sequence string to be validated
\&           \- Boolean to throw an error if the sequence is invalid
.Ve
.SS "length"
.IX Subsection "length"
.Vb 6
\& Title   : length
\& Usage   : $len = $seq\->length()
\& Function:
\& Example :
\& Returns : Integer representing the length of the sequence.
\& Args    : None
.Ve
.SH "Methods from the Bio::PrimarySeqI interface"
.IX Header "Methods from the Bio::PrimarySeqI interface"
.SS "subseq"
.IX Subsection "subseq"
.Vb 5
\& Title   : subseq
\& Usage   : $substring = $obj\->subseq(10,40);
\& Function: Returns the subseq from start to end, where the first base
\&           is 1 and the number is inclusive, ie 1\-2 are the first two
\&           bases of the sequence
\&
\&           Start cannot be larger than end but can be equal
\&
\& Returns : A string
\& Args    : 2 integers
.Ve
.SS "display_id"
.IX Subsection "display_id"
.Vb 4
\& Title   : display_id
\& Usage   : $id = $obj\->display_id or $obj\->display_id($newid);
\& Function: Gets or sets the display id, also known as the common name of
\&           the Seq object.
\&
\&           The semantics of this is that it is the most likely string
\&           to be used as an identifier of the sequence, and likely to
\&           have "human" readability.  The id is equivalent to the LOCUS
\&           field of the GenBank/EMBL databanks and the ID field of the
\&           Swissprot/sptrembl database. In fasta format, the >(\eS+) is
\&           presumed to be the id, though some people overload the id
\&           to embed other information. Bioperl does not use any
\&           embedded information in the ID field, and people are
\&           encouraged to use other mechanisms (accession field for
\&           example, or extending the sequence object) to solve this.
\&
\&           Notice that $seq\->id() maps to this function, mainly for
\&           legacy/convenience issues.
\& Returns : A string
\& Args    : None or a new id
.Ve
.SS "accession_number"
.IX Subsection "accession_number"
.Vb 8
\& Title   : accession_number
\& Usage   : $unique_biological_key = $obj\->accession_number;
\& Function: Returns the unique biological id for a sequence, commonly
\&           called the accession_number. For sequences from established
\&           databases, the implementors should try to use the correct
\&           accession number. Notice that primary_id() provides the
\&           unique id for the implementation, allowing multiple objects
\&           to have the same accession number in a particular implementation.
\&
\&           For sequences with no accession number, this method should return
\&           "unknown".
\&
\&           Can also be used to set the accession number.
\& Example : $key = $seq\->accession_number or $seq\->accession_number($key)
\& Returns : A string
\& Args    : None or an accession number
.Ve
.SS "desc"
.IX Subsection "desc"
.Vb 6
\& Title   : desc
\& Usage   : $seqobj\->desc($string) or $seqobj\->desc()
\& Function: Sets or gets the description of the sequence
\& Example :
\& Returns : The description
\& Args    : The description or none
.Ve
.SS "primary_id"
.IX Subsection "primary_id"
.Vb 6
\& Title   : primary_id
\& Usage   : $unique_implementation_key = $obj\->primary_id;
\& Function: Returns the unique id for this object in this
\&           implementation. This allows implementations to manage
\&           their own object ids in a way the implementation can control
\&           clients can expect one id to map to one object.
\&
\&           For sequences with no natural id, this method should return
\&           a stringified memory location.
\&
\&           Can also be used to set the primary_id (or unset to undef).
\&
\&           [Note this method name is likely to change in 1.3]
\&
\& Example : $id = $seq\->primary_id or $seq\->primary_id($id)
\& Returns : A string
\& Args    : None or an id, or undef to unset the primary id.
.Ve
.SS "can_call_new"
.IX Subsection "can_call_new"
.Vb 9
\& Title   : can_call_new
\& Usage   : if ( $obj\->can_call_new ) {
\&               $newobj = $obj\->new( %param );
\&           }
\& Function: can_call_new returns 1 or 0 depending
\&           on whether an implementation allows new
\&           constructor to be called. If a new constructor
\&           is allowed, then it should take the followed hashed
\&           constructor list.
\&
\&           $myobject\->new( \-seq => $sequence_as_string,
\&                           \-display_id  => $id
\&                           \-accession_number => $accession
\&                           \-alphabet => \*(Aqdna\*(Aq,
\&                         );
\& Example :
\& Returns : 1 or 0
\& Args    : None
.Ve
.SS "alphabet"
.IX Subsection "alphabet"
.Vb 4
\& Title   : alphabet
\& Usage   : if ( $obj\->alphabet eq \*(Aqdna\*(Aq ) { /Do Something/ }
\& Function: Get/Set the type of sequence being one of
\&           \*(Aqdna\*(Aq, \*(Aqrna\*(Aq or \*(Aqprotein\*(Aq. This is case sensitive.
\&
\&           This is not called <type> because this would cause
\&           upgrade problems from the 0.5 and earlier Seq objects.
\&
\& Returns : A string either \*(Aqdna\*(Aq,\*(Aqrna\*(Aq,\*(Aqprotein\*(Aq. NB \- the object must
\&           make a call of the type \- if there is no type specified it
\&           has to guess.
\& Args    : optional string to set : \*(Aqdna\*(Aq | \*(Aqrna\*(Aq | \*(Aqprotein\*(Aq
.Ve
.SS "is_circular"
.IX Subsection "is_circular"
.Vb 5
\& Title   : is_circular
\& Usage   : if( $obj\->is_circular) { /Do Something/ }
\& Function: Returns true if the molecule is circular
\& Returns : Boolean value
\& Args    : none
.Ve
.SH "Methods for Bio::IdentifiableI compliance"
.IX Header "Methods for Bio::IdentifiableI compliance"
.SS "object_id"
.IX Subsection "object_id"
.Vb 5
\& Title   : object_id
\& Usage   : $string    = $obj\->object_id()
\& Function: a string which represents the stable primary identifier
\&           in this namespace of this object. For DNA sequences this
\&           is its accession_number, similarly for protein sequences
\&
\&           This is aliased to accession_number().
\& Returns : A scalar
.Ve
.SS "version"
.IX Subsection "version"
.Vb 6
\& Title   : version
\& Usage   : $version    = $obj\->version()
\& Function: a number which differentiates between versions of
\&           the same object. Higher numbers are considered to be
\&           later and more relevant, but a single object described
\&           the same identifier should represent the same concept
\&
\& Returns : A number
.Ve
.SS "authority"
.IX Subsection "authority"
.Vb 5
\& Title   : authority
\& Usage   : $authority    = $obj\->authority()
\& Function: a string which represents the organisation which
\&           granted the namespace, written as the DNS name for
\&           organisation (eg, wormbase.org)
\&
\& Returns : A scalar
.Ve
.SS "namespace"
.IX Subsection "namespace"
.Vb 5
\& Title   : namespace
\& Usage   : $string    = $obj\->namespace()
\& Function: A string representing the name space this identifier
\&           is valid in, often the database name or the name
\&           describing the collection
\&
\& Returns : A scalar
.Ve
.SH "Methods for Bio::DescribableI compliance"
.IX Header "Methods for Bio::DescribableI compliance"
.SS "display_name"
.IX Subsection "display_name"
.Vb 7
\& Title   : display_name
\& Usage   : $string    = $obj\->display_name()
\& Function: A string which is what should be displayed to the user
\&           the string should have no spaces (ideally, though a cautious
\&           user of this interface would not assume this) and should be
\&           less than thirty characters (though again, double checking
\&           this is a good idea)
\&
\&           This is aliased to display_id().
\& Returns : A scalar
.Ve
.SS "description"
.IX Subsection "description"
.Vb 8
\& Title   : description
\& Usage   : $string    = $obj\->description()
\& Function: A text string suitable for displaying to the user a
\&           description. This string is likely to have spaces, but
\&           should not have any newlines or formatting \- just plain
\&           text. The string should not be greater than 255 characters
\&           and clients can feel justified at truncating strings at 255
\&           characters for the purposes of display
\&
\&           This is aliased to desc().
\& Returns : A scalar
.Ve
.SH "Methods for implementing Bio::AnnotatableI"
.IX Header "Methods for implementing Bio::AnnotatableI"
.SS "annotation"
.IX Subsection "annotation"
.Vb 6
\& Title   : annotation
\& Usage   : $ann = $seq\->annotation or 
\&           $seq\->annotation($ann)
\& Function: Gets or sets the annotation
\& Returns : Bio::AnnotationCollectionI object
\& Args    : None or Bio::AnnotationCollectionI object
.Ve
.PP
See Bio::AnnotationCollectionI and Bio::Annotation::Collection
for more information
.SH "Methods for delegating Bio::AnnotationCollectionI"
.IX Header "Methods for delegating Bio::AnnotationCollectionI"
.SS "\fBget_Annotations()\fP"
.IX Subsection "get_Annotations()"
.Vb 5
\& Usage   : my @annotations = $seq\->get_Annotations(\*(Aqkey\*(Aq)
\& Function: Retrieves all the Bio::AnnotationI objects for a specific key
\&           for this object
\& Returns : list of Bio::AnnotationI \- empty if no objects stored for a key
\& Args    : string which is key for annotations
.Ve
.SS "\fBadd_Annotation()\fP"
.IX Subsection "add_Annotation()"
.Vb 5
\& Usage   : $seq\->add_Annotation(\*(Aqreference\*(Aq,$object);
\&           $seq\->add_Annotation($object,\*(AqBio::MyInterface::DiseaseI\*(Aq);
\&           $seq\->add_Annotation($object);
\&           $seq\->add_Annotation(\*(Aqdisease\*(Aq,$object,\*(AqBio::MyInterface::DiseaseI\*(Aq);
\& Function: Adds an annotation for a specific key for this sequence object.
\&
\&           If the key is omitted, the object to be added must provide a value
\&           via its tagname().
\&
\&           If the archetype is provided, this and future objects added under
\&           that tag have to comply with the archetype and will be rejected
\&           otherwise.
\&
\& Returns : none
\& Args    : annotation key (\*(Aqdisease\*(Aq, \*(Aqdblink\*(Aq, ...)
\&           object to store (must be Bio::AnnotationI compliant)
\&           [optional] object archetype to map future storage of object
\&           of these types to
.Ve
.SS "\fBremove_Annotations()\fP"
.IX Subsection "remove_Annotations()"
.Vb 8
\& Usage   : $seq\->remove_Annotations()
\& Function: Remove the annotations for the specified key from this sequence 
\&           object
\& Returns : an list of Bio::AnnotationI compliant objects which were stored
\&           under the given key(s) for this sequence object
\& Args    : the key(s) (tag name(s), one or more strings) for which to
\&           remove annotations (optional; if none given, flushes all
\&           annotations)
.Ve
.SS "\fBget_num_of_annotations()\fP"
.IX Subsection "get_num_of_annotations()"
.Vb 6
\& Usage   : my $count = $seq\->get_num_of_annotations()
\& Alias   : num_Annotations
\& Function: Returns the count of all annotations stored for this sequence
\&           object      
\& Returns : integer
\& Args    : none
.Ve
.SH "Methods to implement Bio::FeatureHolderI"
.IX Header "Methods to implement Bio::FeatureHolderI"
This includes methods for retrieving, adding, and removing features.
.SS "get_SeqFeatures"
.IX Subsection "get_SeqFeatures"
.Vb 3
\& Title   : get_SeqFeatures
\& Usage   :
\& Function: Get the feature objects held by this feature holder.
\&
\&           Features which are not top\-level are subfeatures of one or
\&           more of the returned feature objects, which means that you
\&           must traverse the subfeature arrays of each top\-level
\&           feature object in order to traverse all features associated
\&           with this sequence.
\&
\&           Specific features can be obtained by primary tag, specified in 
\&           the argument.
\&
\&           Use get_all_SeqFeatures() if you want the feature tree
\&           flattened into one single array.
\&
\& Example : my @feats = $seq\->get_SeqFeatures or
\&           my @genefeats = $seq\->get_SeqFeatures(\*(Aqgene\*(Aq)
\& Returns : an array of Bio::SeqFeatureI implementing objects
\& Args    : [optional] string (feature tag)
.Ve
.SS "get_all_SeqFeatures"
.IX Subsection "get_all_SeqFeatures"
.Vb 7
\& Title   : get_all_SeqFeatures
\& Usage   : @feat_ary = $seq\->get_all_SeqFeatures();
\& Function: Returns the tree of feature objects attached to this
\&           sequence object flattened into one single array. Top\-level
\&           features will still contain their subfeature\-arrays, which
\&           means that you will encounter subfeatures twice if you
\&           traverse the subfeature tree of the returned objects.
\&
\&           Use get_SeqFeatures() if you want the array to contain only
\&           the top\-level features.
\&
\& Returns : An array of Bio::SeqFeatureI implementing objects.
\& Args    : None
.Ve
.SS "feature_count"
.IX Subsection "feature_count"
.Vb 5
\& Title   : feature_count
\& Usage   : $seq\->feature_count()
\& Function: Return the number of SeqFeatures attached to a sequence
\& Returns : integer representing the number of SeqFeatures
\& Args    : None
.Ve
.SS "add_SeqFeature"
.IX Subsection "add_SeqFeature"
.Vb 9
\& Title   : add_SeqFeature
\& Usage   : $seq\->add_SeqFeature($feat);
\& Function: Adds the given feature object to the feature array of this
\&           sequence. The object passed is required to implement the
\&           Bio::SeqFeatureI interface.
\&           The \*(AqEXPAND\*(Aq qualifier (see L<Bio::FeatureHolderI>) is supported, but
\&           has no effect,
\& Returns : 1 on success
\& Args    : A Bio::SeqFeatureI implementing object.
.Ve
.SS "remove_SeqFeatures"
.IX Subsection "remove_SeqFeatures"
.Vb 8
\& Title   : remove_SeqFeatures
\& Usage   : $seq\->remove_SeqFeatures();
\& Function: Removes all attached SeqFeatureI objects or those with the 
\&           specified primary tag
\& Example : my @gene_feats = $seq\->remove_seqFeatures(\*(Aqgene\*(Aq) or
\&           my @feats = $seq\->remove_seqFeatures()
\& Returns : The array of Bio::SeqFeatureI objects removed from the sequence
\& Args    : None, or a feature primary tag
.Ve
.SH "Methods provided in the Bio::PrimarySeqI interface"
.IX Header "Methods provided in the Bio::PrimarySeqI interface"
These methods are inherited from the PrimarySeq interface
and work as one expects, building new Bio::Seq objects
or other information as expected. See Bio::PrimarySeq
for more information.
.PP
Sequence Features are \fBnot\fR transferred to the new objects.
To reverse complement and include the features use
Bio::SeqUtils::revcom_with_features.
.SS "revcom"
.IX Subsection "revcom"
.Vb 6
\& Title   : revcom
\& Usage   : $rev = $seq\->revcom()
\& Function: Produces a new Bio::Seq object which
\&           is the reversed complement of the sequence. For protein
\&           sequences this throws an exception of "Sequence is a protein.
\&           Cannot revcom"
\&
\&           The id is the same id as the original sequence, and the
\&           accession number is also identical. If someone wants to track
\&           that this sequence has be reversed, it needs to define its own
\&           extensions
\&
\&           To do an in\-place edit of an object you can go:
\&
\&           $seq = $seq\->revcom();
\&
\&           This of course, causes Perl to handle the garbage collection of
\&           the old object, but it is roughly speaking as efficient as an
\&           in\-place edit.
\&
\& Returns : A new (fresh) Bio::Seq object
\& Args    : None
.Ve
.SS "trunc"
.IX Subsection "trunc"
.Vb 3
\& Title   : trunc
\& Usage   : $subseq = $myseq\->trunc(10,100);
\& Function: Provides a truncation of a sequence
\&
\& Example :
\& Returns : A fresh Seq object
\& Args    : A Seq object
.Ve
.SS "id"
.IX Subsection "id"
.Vb 5
\& Title   : id
\& Usage   : $id = $seq\->id()
\& Function: This is mapped on display_id
\& Returns : value of display_id()
\& Args    : [optional] value to update display_id
.Ve
.SH "Seq only methods"
.IX Header "Seq only methods"
These methods are specific to the Bio::Seq object, and not
found on the Bio::PrimarySeq object
.SS "primary_seq"
.IX Subsection "primary_seq"
.Vb 6
\& Title   : primary_seq
\& Usage   : $seq\->primary_seq or $seq\->primary_seq($newval)
\& Function: Get or set a PrimarySeq object
\& Example :
\& Returns : PrimarySeq object
\& Args    : None or PrimarySeq object
.Ve
.SS "species"
.IX Subsection "species"
.Vb 5
\& Title   : species
\& Usage   : $species = $seq\->species() or $seq\->species($species)
\& Function: Gets or sets the species
\& Returns : L<Bio::Species> object
\& Args    : None or L<Bio::Species> object
.Ve
.PP
See Bio::Species for more information