Bio/Seq/TraceI.pm

   1 # BioPerl module for Bio::Seq::TraceI
   2 #
   3 # Cared for by Chad Matsalla <bioinformatics@dieselwurks.com
   4 #
   5 # Copyright Chad Matsalla
   6 #
   7 # You may distribute this module under the same terms as perl itself
   8
   9 # POD documentation - main docs before the code
  10
  11 =head1 NAME
  12
  13 Bio::Seq::TraceI - Interface definition for a Bio::Seq::Trace
  14
  15 =head1 SYNOPSIS
  16
  17     # get a Bio::Seq::Qual compliant object somehow
  18           $st = &get_object_somehow();
  19
  20     # to test this is a seq object
  21           $st->isa("Bio::Seq::TraceI")
  22                || $obj->throw("$obj does not implement the Bio::Seq::TraceI interface");
  23
  24           # set the trace for T to be @trace_points
  25      my $arrayref = $st->trace("T",\@trace_points);
  26           # get the trace points for "C"
  27      my $arrayref = $st->trace("C");
  28           # get a subtrace for "G" from 10 to 100
  29      $arrayref = $st->subtrace("G",10,100);
  30           # what is the trace value for "A" at position 355?
  31      my $trace_calue = $st->traceat("A",355);
  32           # create a false trace for "A" with $accuracy
  33      $arrayref = $st->false_trace("A",Bio::Seq::Quality, $accuracy);
  34           # does this trace have entries for each base?
  35      $bool = $st->is_complete();
  36           # how many entries are there in this trace?
  37      $length = $st->length();
  38
  39
  40
  41 =head1 DESCRIPTION
  42
  43 This object defines an abstract interface to basic trace information. This
  44 information may have come from an ABI- or scf- formatted file or may have been
  45 made up.
  46
  47 =head1 FEEDBACK
  48
  49 =head2 Mailing Lists
  50
  51 User feedback is an integral part of the evolution of this and other
  52 Bioperl modules. Send your comments and suggestions preferably to one
  53 of the Bioperl mailing lists.  Your participation is much appreciated.
  54
  55   bioperl-l@bioperl.org                  - General discussion
  56   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  57
  58 =head2 Reporting Bugs
  59
  60 Report bugs to the Bioperl bug tracking system to help us keep track
  61 the bugs and their resolution.  Bug reports can be submitted via the
  62 web:
  63
  64   http://bugzilla.open-bio.org/
  65
  66 =head1 AUTHOR - Chad Matsalla
  67
  68 Email bioinformatics@dieselwurks.com
  69
  70 =head1 APPENDIX
  71
  72 The rest of the documentation details each of the object methods.
  73 Internal methods are usually preceded with a _
  74
  75 =cut
  76
  77
  78 # Let the code begin...
  79
  80
  81 package Bio::Seq::TraceI;
  82 use strict;
  83 use Carp;
  84 use Dumpvalue;
  85 use Bio::Root::RootI;
  86
  87 =head1 Implementation Specific Functions
  88
  89 These functions are the ones that a specific implementation must
  90 define.
  91
  92 =head2 trace($base,\@new_values)
  93
  94  Title   : trace($base,\@new_values)
  95  Usage   : @trace_Values  = @{$obj->trace($base,\@new_values)};
  96  Function: Returns the trace values as a reference to an array containing the
  97      trace values. The individual elements of the trace array are not validated
  98      and can be any numeric value.
  99  Returns : A reference to an array.
 100  Status  :
 101 Arguments: $base : which color channel would you like the trace values for?
 102                - $base must be one of "A","T","G","C"
 103           \@new_values : a reference to an array of values containing trace
 104                data for this base
 105
 106 =cut
 107
 108 sub trace {
 109    my ($self) = @_;
 110    if( $self->can('throw') ) {
 111        $self->throw("Bio::Seq::TraceI definition of trace - implementing class did not provide this method");
 112    } else {
 113        confess("Bio::Seq::TraceI definition of trace - implementing class did not provide this method");
 114    }
 115 }
 116
 117 =head2 subtrace($base,$start,$end)
 118
 119  Title   : subtrace($base,$start,$end)
 120  Usage   : @subset_of_traces = @{$obj->subtrace("A",10,40)};
 121  Function: returns the trace values from $start to $end, where the
 122         first value is 1 and the number is inclusive, ie 1-2 are the first
 123         two trace values of this base. Start cannot be larger than end but can
 124         be equal.
 125  Returns : A reference to an array.
 126  Args    : $base: "A","T","G" or "C"
 127           $start: a start position
 128           $end  : an end position
 129
 130 =cut
 131
 132 sub subtrace {
 133    my ($self) = @_;
 134
 135    if( $self->can('throw') ) {
 136        $self->throw("Bio::Seq::TraceI definition of subtrace - implementing class did not provide this method");
 137    } else {
 138        confess("Bio::Seq::TraceI definition of subtrace - implementing class did not provide this method");
 139    }
 140
 141 }
 142
 143 =head2 can_call_new()
 144
 145  Title   : can_call_new()
 146  Usage   : if( $obj->can_call_new ) {
 147              $newobj = $obj->new( %param );
 148          }
 149  Function: can_call_new returns 1 or 0 depending on whether an
 150         implementation allows new constructor to be called. If a new
 151         constructor is allowed, then it should take the followed hashed
 152         constructor list.
 153            $myobject->new( -qual => $quality_as_string,
 154                            -display_id  => $id,
 155                            -accession_number => $accession,
 156                            );
 157  Example :
 158  Returns : 1 or 0
 159  Args    :
 160
 161
 162 =cut
 163
 164 sub can_call_new{
 165    my ($self,@args) = @_;
 166    # we default to 0 here
 167    return 0;
 168 }
 169
 170 =head2 traceat($channel,$position)
 171
 172  Title   : qualat($channel,$position)
 173  Usage   : $trace = $obj->traceat(500);
 174  Function: Return the trace value at the given location, where the
 175         first value is 1 and the number is inclusive, ie 1-2 are the first
 176         two bases of the sequence. Start cannot be larger than end but can
 177         be equal.
 178  Returns : A scalar.
 179  Args    : A base and a position.
 180
 181 =cut
 182
 183 sub traceat {
 184    my ($self,$value) = @_;
 185    if( $self->can('warn') ) {
 186        $self->warn("Bio::Seq::TraceI definition of traceat - implementing class did not provide this method");
 187    } else {
 188        warn("Bio::Seq::TraceI definition of traceat - implementing class did not provide this method");
 189    }
 190    return '';
 191 }
 192
 193 =head2 length()
 194
 195  Title   : length()
 196  Usage   : $length = $obj->length("A");
 197  Function: Return the length of the array holding the trace values for the "A"
 198      channel. A check should be done to make sure that this Trace object
 199      is_complete() before doing this to prevent hazardous results.
 200  Returns : A scalar (the number of elements in the quality array).
 201  Args    : If used, get the traces from that channel. Default to "A"
 202
 203 =cut
 204
 205 sub length {
 206    my ($self)= @_;
 207    if( $self->can('throw') ) {
 208        $self->throw("Bio::Seq::TraceI definition of length - implementing class did not provide this method");
 209    } else {
 210        confess("Bio::Seq::TraceI definition of length - implementing class did not provide this method");
 211    }
 212 }
 213
 214 =head2 trace_indices($new_indices)
 215
 216  Title   : trace_indices($new_indices)
 217  Usage   : $indices = $obj->trace_indices($new_indices);
 218  Function: Return the trace iindex points for this object.
 219  Returns : A scalar
 220  Args    : If used, the trace indices will be set to the provided value.
 221
 222 =cut
 223
 224 sub trace_indices {
 225    my ($self)= @_;
 226    if( $self->can('throw') ) {
 227        $self->throw("Bio::Seq::TraceI definition of trace_indices - implementing class did not provide this method");
 228    } else {
 229        confess("Bio::Seq::TraceI definition of trace_indices - implementing class did not provide this method");
 230    }
 231 }
 232
 233
 234
 235
 236 1;