NAME
Bio::Seq - Sequence object, with features
SYNOPSIS
$seqio = Bio::SeqIO->new ( '-format' => 'embl' , -file => 'myfile.dat');
$seqobj = $seqio->next_seq();
# features must implement Bio::SeqFeatureI
@features = $seqobj->top_SeqFeatures(); # just top level
@features = $seqobj->all_SeqFeatures(); # descend into sub features
$seq = $seqobj->seq(); # actual sequence as a string
$seqstr = $seqobj->subseq(10,50);
$ann = $seqobj->annotation(); # annotation objectDESCRIPTION
A Seq object is a sequence with sequence features placed on them. The Seq object contains a PrimarySeq object for the actual sequence and also implements its interface.
In bioperl we have 3 main players that people are going to use
Bio::PrimarySeq - just the sequence and its names, nothing else.
Bio::SeqFeatureI - a location on a sequence, potentially with a sequence.
and annotation
Bio::Seq - A sequence and a collection of seqfeatures (an aggregate) with
its own annotation.Although bioperl is not tied to file formats heavily, these distinctions do map to file formats sensibly and for some bioinformaticians this might help you:
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 entryBy having this split we avoid alot of nasty ciricular references (seqfeatures can hold a reference to a sequence without the sequence holding a reference to the seqfeature).
Ian Korf really helped in the design of the Seq and SeqFeature system.
FEEDBACK
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.
bioperl-l@bioperl.org - General discussion
http://bio.perl.org/MailList.html - About the mailing listsReporting 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 email or the web:
bioperl-bugs@bioperl.org
http://bio.perl.org/bioperl-bugs/AUTHOR - Ewan Birney, inspired by Ian Korf objects
Email birney@sanger.ac.uk
Describe contact details here
APPENDIX
The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _
new
Title : new
Usage : $seq = Bio::Seq->new( -seq => 'ATGGGGGTGGTGGTACCCT',
-id => 'human_id',
-accession_number => 'AL000012',
);
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 objectPrimarySeq interface
The primaryseq interface is the basic sequence getting and setting methods found on all sequences.
These methods implement the 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.
seq
Title : seq
Usage : $string = $obj->seq()
Function: Returns 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 scalarlength
Title : length
Usage : $len = $seq->length()
Function:
Example :
Returns : integer representing the length of the sequence.
Args :subseq
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 :display_id
Title : display_id
Usage : $id_string = $obj->display_id($newid);
Function: returns or sets the display id, aka the common name of the
Sequence 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 ID
field of the GenBank/EMBL databanks and the id field of the
Swissprot/sptrembl database. In fasta format, the >(\S+) 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/convience issues
Returns : A string
Args : newid (optional)accession_number
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 implemetation, allowing multiple objects
to have the same accession number in a particular implementation.
For sequences with no accession number, this method should return
"unknown".
Returns : A string
Args : Nonedesc
Title : desc
Usage : $seqobj->desc()
Function: Sets/Gets the description of the sequnce
Example :
Returns :
Args :primary_id
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 implementaiton 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.
Also notice that this method is B<not> delegated to the
internal PrimarySeq object
Returns : A string
Args : Nonecan_call_new
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
-moltype => 'dna',
);
Example :
Returns : 1 or 0
Args :moltype
Title : moltype
Usage : if( $obj->moltype eq 'dna' ) { /Do Something/ }
Function: Returns the type of sequence being one of
'dna', 'rna' or 'protein'. 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 'dna','rna','protein'. NB - the object must
make a call of the type - if there is no type specified it
has to guess.
Args : noneMethods 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.
Sequence Features are not transfered to the new objects. This is possibly a mistake. Anyone who feels the urge in dealing with this is welcome to give it a go.
revcom
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 orginal sequence, and the accession number
is also indentical. If someone wants to track that this sequence has be
reversed, it needs to define its own extensions
To do an inplace 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 inplace edit.
Returns : A new (fresh) Bio::Seq object
Args : nonetrunc
Title : trunc
Usage : $subseq = $myseq->trunc(10,100);
Function: Provides a truncation of a sequence,
Example :
Returns : a fresh Bio::Seq object
Args :id
Title : id
Usage : $id = $seq->id()
Function: This is mapped on display_id
Example :
Returns :
Args :Seq only methods
These methods are specific to the Bio::Seq object, and not found on the Bio::PrimarySeq object
primary_seq
Title : primary_seq
Usage : $obj->primary_seq($newval)
Function:
Example :
Returns : value of primary_seq
Args : newvalue (optional)annotation
Title : annotation
Usage : $obj->annotation($seq_obj)
Function:
Example :
Returns : value of annotation
Args : newvalue (optional)add_SeqFeature
Title : add_SeqFeature
Usage : $seq->add_SeqFeature($feat);
$seq->add_SeqFeature(@feat);
Function: Adds the given feature object (or each of an array of feature
objects to the feature array of this
sequence. The object passed is required to implement the
Bio::SeqFeatureI interface.
Example :
Returns : TRUE on success
Args : A Bio::SeqFeatureI implementing object, or an array of such objects.top_SeqFeatures
Title : top_SeqFeatures
Usage : @feat_ary = $seq->top_SeqFeatures();
Function: Returns the array of top-level features for this sequence object.
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.
Use all_SeqFeatures() if you want the feature tree flattened into
one single array.
Example :
Returns : An array of Bio::SeqFeatureI implementing objects.
Args :all_SeqFeatures
Title : all_SeqFeatures
Usage : @feat_ary = $seq->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 top_SeqFeatures() if you want the array to contain only the
top-level features.
Example :
Returns : An array of Bio::SeqFeatureI implementing objects.
Args :feature_count
Title : feature_count
Usage : $seq->feature_count()
Function: Return the number of SeqFeatures attached to a sequence
Example :
Returns : number of SeqFeatures
Args : nonespecies
Title : species
Usage :
Function: Gets or sets the species
Example : $species = $self->species();
Returns : Bio::Species object
Args : Bio::Species object or none;