Bio::LiveSeq::SeqI - Abstract sequence interface class for LiveSeq # documentation needed This class implements BioPerl PrimarySeqI interface for Live Seq objects. One of the main difference in LiveSequence compared to traditional "string" sequences is that coordinate systems are flexible. Typically gene nucleotide numbering starts from 1 at the first character of the initiator codon (A in ATG). This means that negative positions are possible and common! Secondly, the sequence manipulation methods do not return a new sequence object but change the current object. The current status can be written out to BioPerl sequence objects.

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 lists

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 email or the web: bioperl-bugs@bioperl.org http://bio.perl.org/bioperl-bugs/ Email: Insana@ebi.ac.uk, jinsana@gmx.net Address: EMBL Outstation, European Bioinformatics Institute Wellcome Trust Genome Campus, Hinxton Cambs. CB10 1SD, United Kingdom The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _ Some note on the terminology/notation of method names: label: a unique pointer to a single nucleotide position: the position of a nucleotide according to a particular coordinate system (e.g. counting downstream from a particular label taken as number 1) base: the one letter code for a nucleotide (i.e.: "a" "t" "c" "g") a base is the "value" that an "element" of a "chain" can assume (see documentation on the Chain datastructure if interested)

seq
Title : seq Usage : $string = $obj->seq() Function: Returns the complete sequence of an object as a string of letters. Suggested cases are upper case for proteins and lower case for DNA sequence (IUPAC standard), Returns : a string

all_labels
Title : all_labels Usage : @labels = $obj->all_labels() Function: all the labels of every nucleotide an object is composed of Returns : an array of labels Args : none

labelsubseq
Title : labelsubseq Usage : $dna->labelsubseq(); : $dna->labelsubseq($startlabel); : $dna->labelsubseq($startlabel,$length); : $dna->labelsubseq($startlabel,undef,$endlabel); e.g. : $dna->labelsubseq(4,undef,8); Function: prints the sequence as string. The difference between labelsubseq and normal subseq is that it uses /labels/ as arguments, instead than positions. This allows for faster and more efficient lookup, skipping the (usually) lengthy conversion of positions into labels. This is expecially useful for manipulating with high power LiveSeq objects, knowing the labels and exploiting their usefulness. Returns : a string Errorcode -1 Args : without arguments it returns the entire sequence with a startlabel it returns the sequence downstream that label if a length is specified, it returns only that number of bases if an endlabel is specified, it overrides the length argument and prints instead up to that label (included) Defaults: $startlabel defaults to the beginning of the entire sequence $endlabel defaults to the end of the entire sequence

subseq
Title : subseq Usage : $substring = $obj->subseq(10,40); : $substring = $obj->subseq(10,undef,4); 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. Allows for negative numbers $obj->subseq(-10,-1). By definition, there is no 0! -5 -1 1 5 gctagcgcccaac atggctcgctg This allows to retrieve sequences upstream from given position. The precedence is from left to right: if END is given LENGTH is ignored. Examples: $obj->subseq(-10,undef,10) returns 10 elements before position 1 $obj->subseq(4,8) returns elements from the 4th to the 8th, inclusive Returns : a string Errorcode: -1 Args : start, integer, defaults to start of the sequence end, integer, '' or undef, defaults to end of the sequence length, integer, '' or undef an optional strand (1 or -1) 4th argument if strand argument is not given, it will default to the object argment. This argument is useful when a call is issued from a child of a parent object containing the subseq method

length
Title : length Usage : $seq->length(); Function: returns the number of nucleotides (or the number of aminoacids) in the entire sequence Returns : an integer Errorcode -1 Args : none

display_id
Title : display_id Usage : $id_string = $obj->display_id(); Function: returns the display id, alias the common name of the 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. See also: accession_number Returns : a string Args : none

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. 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 objects with no accession_number this method returns "unknown". Returns : a string Args : none

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 implementation can control. Clients can expect one id to map to one object. For sequences with no primary_id, this method returns a stringified memory location. Returns : A string Args : None

change
Title : change Usage : $substring = $obj->change('AA', 10); Function: changes, modifies, mutates the LiveSequence Examples: $obj->change('', 10); delete nucleotide #10 $obj->change('', 10, 2); delete two nucleotides starting from #10 $obj->change('G', 10); change nuc #10 to 'G' $obj->change('GA', 10, 4); replace #10 and 3 following with 'GA' $obj->change('GA', 10, 2)); is same as $obj->change('GA', 10); $obj->change('GA', 10, 0 ); insert 'GA' before nucleotide at #10 $obj->change('GA', 10, 1); GA inserted before #10, #10 deleted $obj->change('GATC', 10, 2); GATC inserted before #10, #10&#11 deleted $obj->change('GATC', 10, 6); GATC inserted before #10, #10-#15 deleted Returns : a string of deleted bases (if any) or 1 (everything OK) Errorcode: -1 Args : seq, string, or '' ('' = undef = 0 = deletion) start, integer length, integer (optional)

positionchange
Title : positionchange Function: Exactly like change. I.e. change() defaults to positionchange()

labelchange
Title : labelchange Function: Exactly like change but uses a /label/ instead than a position as second argument. This allows for multiple changes in a LiveSeq without the burden of recomputing positions. I.e. for a multiple change in two different points of the LiveSeq, the approach would be the following: fetch the correct labels out of the two different positions (method: label($position)) and then use the labelchange() method to modify the sequence using those labels instead than relying on the positions (that would have modified after the first change).

valid
Title : valid Usage : $boolean = $obj->valid($label) Function: tests if a label exists inside the object Returns : boolean Args : label

start
Title : start Usage : $startlabel=$obj->start() Function: returns the label of the first nucleotide of the object (exon, CDS) Returns : label Args : none

end
Title : end Usage : $endlabel=$obj->end() Function: returns the label of the last nucleotide of the object (exon, CDS) Returns : label Args : none

strand
Title : strand Usage : $strand=$obj->strand() $obj->strand($strand) Function: gets or sets strand information, being 1 or -1 (forward or reverse) Returns : -1 or 1 Args : none OR -1 or 1

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. Returns : a string either 'dna','rna','protein'. Args : none Note : "circular dna" is set as dna

coordinate_start
Title : coordinate_start Usage : $coordstartlabel=$obj->coordinate_start() : $coordstartlabel=$obj->coordinate_start($label) Function: returns and optionally sets the first label of the coordinate system used For some objects only labels inside the object or in frame (for Translation objects) will be allowed to get set as coordinate start Returns : label. It returns 0 if label not found. Errorcode -1 Args : an optional reference $label that is position 1

label
Title : label Usage : $seq->label($position) : $seq->label($position,$firstlabel) Examples: $nextlabel=$seq->label(2,$label) -> retrieves the following label : $prevlabel=$seq->label(-1,$label) -> retrieves the preceding label Function: returns the label of the nucleotide at $position from current coordinate start Returns : a label. It returns 0 if label not found. Errorcode -1 Args : a position, an optional reference $firstlabel that is to be used as position 1 an optional strand (1 or -1) argument if strand argument is not given, it will default to the object argument. This argument is useful when a call is issued from a child of a parent object containing the subseq method

position
Title : position Usage : $seq->position($label) : $seq->position($label,$firstlabel) Function: returns the position of nucleotide at $label Returns : the position of the label from current coordinate start Errorcode 0 Args : a label pointing to a certain nucleotide (e.g. start of exon) an optional "firstlabel" as reference to count from an optional strand (1 or -1) argument if strand argument is not given, it will default to the object argument. This argument is useful when a call is issued from a child of a parent object containing the subseq method

follows
Title : follows Usage : $seq->follows($firstlabel,$secondlabel) : $seq->follows($firstlabel,$secondlabel,$strand) Function: checks if SECONDlabel follows FIRSTlabel, undependent of the strand i.e. it checks downstream for forward strand and upstream for reverse strand Returns : 1 or 0 Errorcode -1 Args : two labels an optional strand (1 or -1) argument if strand argument is not given, it will default to the object argument. This argument is useful when a call is issued from a child of a parent object containing the subseq method

translate
Title : translate Usage : $protein_seq = $obj->translate Function: Provides the translation of the DNA sequence using full IUPAC ambiguities in DNA/RNA and amino acid codes. The resulting translation is identical to EMBL/TREMBL database translations. Returns : a string Args : character for terminator (optional) defaults to '*' character for unknown amino acid (optional) defaults to 'X' frame (optional) valid values 0, 1, 3, defaults to 0 codon table id (optional) defaults to 1

translate_string
Title : translate_string Usage : $protein_seq = $obj->translate_string("attcgtgttgatcgatta"); Function: Like translate, but can be used to translate subsequences after having retrieved them as string. Args : 1st argument is a string. Optional following arguments: like in the translate method

gene
Title : gene Usage : my $gene=$obj->gene; Function: Gets or sets the reference to the LiveSeq::Gene object. Objects that are features of a LiveSeq Gene will have this attribute set automatically. Returns : reference to an object of class Gene Note : if Gene object is not set, this method will return 0; Args : none or reference to object of class Bio::LiveSeq::Gene

obj_valid
Title : obj_valid Usage : if ($obj->obj_valid) {do something;} Function: Checks if start and end labels are still valid for the ojbect, i.e. tests if the LiveSeq object is still valid Returns : boolean Args : none

name
Title : name Usage : $name = $obj->name; : $name = $obj->name("ABCD"); Function: Returns or sets the name of the object. If there is no name, it will return "unknown"; Returns : A string Args : None

description
Title : description Usage : $description = $obj->description; : $description = $obj->description("ABCD"); Function: Returns or sets the description of the object. If there is no description, it will return "unknown"; Returns : A string Args : None

source
Title : source Usage : $name = $obj->source; : $name = $obj->source("Homo sapiens"); Function: Returns or sets the organism that is source of the object. If there is no source, it will return "unknown"; Returns : A string Args : None

verbose
Title : verbose Usage : $self->verbose(0) Function: Sets verbose level for how ->warn behaves -1 = silent: no warning 0 = reduced: minimal warnings 1 = default: all warnings 2 = extended: all warnings + stack trace dump 3 = paranoid: a warning becomes a throw and the program dies Note: a quick way to set all LiveSeq objects at the same verbosity level is to change the DNA level object, since they all look to that one if their verbosity_level attribute is not set. But the method offers fine tuning possibility by changing the verbose level of each object in a different way. So for example, after $loader= and $gene= have been retrieved by a program, the command $gene->verbose(0); would set the default verbosity level to 0 for all objects. Returns : the current verbosity level Args : -1,0,1,2 or 3

warn
Title : warn Usage : $object->warn("Warning message",$ignorable); Function: Places a warning. What happens now is down to the verbosity of the object (value of $obj->verbose) -1 = silent: no warning 0 = reduced: minimal warnings 1 = default: all warnings 2 = extended: all warnings + stack trace dump 3 = paranoid: a warning becomes a throw and the program dies If a second argument is given and is 1, then the warning becomes a relatively ignorable one. I.e. it means that warning is one the program can cope with, so at verbose level "0", it wouldn't be printed. At verbose level >1 it will be printed with the rest. Example : $obj->warn("Label not found"); Example : $obj->warn("Starting position not specified, using default start",1); Returns : nothing Args : string, boolean

throw
Title : throw Usage : $obj->throw("throwing exception message") Function: Throws an exception, which, if not caught with an eval brace will print the error message, a stack trace dump, and die. Returns : nothing Args : A string giving a descriptive error message

stack_trace
Title : stack_trace Usage : @stack_array_ref= $self->stack_trace Function: gives an array to a reference of arrays with stack trace info each coming from the caller(stack_number) call Returns : array containing a reference of arrays Args : none