Bio/Seq/TraceI.pm

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