Bio/Symbol/Symbol.pm

   1 #
   2 # BioPerl module for Bio::Symbol::Symbol
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Jason Stajich <jason@bioperl.org>
   7 #
   8 # Copyright Jason Stajich
   9 #
  10 # You may distribute this module under the same terms as perl itself
  11
  12 # POD documentation - main docs before the code
  13
  14 =head1 NAME
  15
  16 Bio::Symbol::Symbol - A biological symbol
  17
  18 =head1 SYNOPSIS
  19
  20     use Bio::Symbol::Symbol;
  21     my $thymine = Bio::Symbol::Symbol->new(-name => 'Thy',
  22                                           -token=> 'T');
  23     my $a = Bio::Symbol::Symbol->new(-token => 'A' );
  24     my $u = Bio::Symbol::Symbol->new(-token => 'U' );
  25     my $g = Bio::Symbol::Symbol->new(-token => 'G' );
  26
  27     my $M = Bio::Symbol::Symbol->new(-name  => 'Met',
  28                                     -token => 'M',
  29                                     -symbols => [ $a, $u, $g ]);
  30
  31     my ($name,$token) = ($a->name, $a->token);
  32     my @symbols       = $a->symbols;
  33     my $matches       = $a->matches;
  34
  35 =head1 DESCRIPTION
  36
  37 Symbol represents a single token in the sequence. Symbol can have
  38 multiple synonyms or matches within the same Alphabet, which
  39 makes possible to represent ambiguity codes and gaps.
  40
  41 Symbols can be also composed from ordered list other symbols. For
  42 example, codons can be represented by single Symbol using a
  43 compound Alphabet made from three DNA Alphabets.
  44
  45 This module was implemented for the purposes of meeting the
  46 BSANE/BioCORBA spec 0.3 only.
  47
  48 =head1 FEEDBACK
  49
  50 =head2 Mailing Lists
  51
  52 User feedback is an integral part of the evolution of this and other
  53 Bioperl modules. Send your comments and suggestions preferably to
  54 the Bioperl mailing list.  Your participation is much appreciated.
  55
  56   bioperl-l@bioperl.org                  - General discussion
  57   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  58
  59 =head2 Support
  60
  61 Please direct usage questions or support issues to the mailing list:
  62
  63 I<bioperl-l@bioperl.org>
  64
  65 rather than to the module maintainer directly. Many experienced and
  66 reponsive experts will be able look at the problem and quickly
  67 address it. Please include a thorough description of the problem
  68 with code and data examples if at all possible.
  69
  70 =head2 Reporting Bugs
  71
  72 Report bugs to the Bioperl bug tracking system to help us keep track
  73 of the bugs and their resolution. Bug reports can be submitted via the
  74 web:
  75
  76   https://github.com/bioperl/bioperl-live/issues
  77
  78 =head1 AUTHOR - Jason Stajich
  79
  80 Email jason@bioperl.org
  81
  82 =head1 APPENDIX
  83
  84 The rest of the documentation details each of the object methods.
  85 Internal methods are usually preceded with a _
  86
  87 =cut
  88
  89
  90 # Let the code begin...
  91
  92
  93 package Bio::Symbol::Symbol;
  94 use strict;
  95
  96 # Object preamble - inherits from Bio::Root::Root
  97
  98 use Bio::Symbol::Alphabet;
  99
 100 use base qw(Bio::Root::Root Bio::Symbol::SymbolI);
 101
 102 =head2 new
 103
 104  Title   : new
 105  Usage   : my $obj = Bio::Symbol::Symbol->new();
 106  Function: Builds a new Bio::Symbol::Symbol object
 107  Returns : Bio::Symbol::Symbol
 108  Args    : -name    => descriptive name (string) [e.g. Met]
 109            -token   => Shorthand token (string)  [e.g. M]
 110            -symbols => Symbols that make up this symbol (array) [e.g. AUG]
 111            -matches => Alphabet in the event symbol is an ambiguity
 112                        code.
 113
 114 =cut
 115
 116 sub new {
 117   my($class,@args) = @_;
 118   my $self = $class->SUPER::new(@args);
 119   $self->{'_symbols'} = [];
 120
 121   my ($name, $token, $symbols,
 122       $matches) = $self->_rearrange([qw(NAME TOKEN SYMBOLS
 123                                         MATCHES)],
 124                                     @args);
 125   $token && $self->token($token);
 126   $name && $self->name($name);
 127   $symbols && ref($symbols) =~ /array/i && $self->symbols(@$symbols);
 128   $matches && $self->matches($matches);
 129   return $self;
 130 }
 131
 132 =head2 name
 133
 134  Title   : name
 135  Usage   : my $name = $symbol->name();
 136  Function: Get/Set Descriptive name for Symbol
 137  Returns : string
 138  Args    : (optional) string
 139
 140 =cut
 141
 142 sub name {
 143    my ($self,$value) = @_;
 144    if( $value ) {
 145        $self->{'_name'} = $value;
 146    }
 147    return $self->{'_name'} || '';
 148 }
 149
 150 =head2 token
 151
 152  Title   : token
 153  Usage   : my $token = $self->token();
 154  Function: Get/Set token for this symbol
 155  Example : Letter A,C,G,or T for a DNA alphabet Symbol
 156  Returns : string
 157  Args    : (optional) string
 158
 159 =cut
 160
 161 sub token{
 162    my ($self,$value) = @_;
 163    if( $value ) {
 164        $self->{'_token'} = $value;
 165    }
 166    return $self->{'_token'} || '';
 167 }
 168
 169 =head2 symbols
 170
 171  Title   : symbols
 172  Usage   : my @symbols = $self->symbols();
 173  Function: Get/Set Symbols this Symbol is composed from
 174  Example : Ambiguity symbols are made up > 1 base symbol
 175  Returns : Array of Bio::Symbol::SymbolI objects
 176  Args    : (optional) Array of Bio::Symbol::SymbolI objects
 177
 178
 179 =cut
 180
 181 sub symbols{
 182    my ($self,@args) = @_;
 183    if( @args ) {
 184        $self->{'_symbols'} = [@args];
 185    }
 186    return @{$self->{'_symbols'}};
 187 }
 188
 189 =head2 matches
 190
 191  Title   : matches
 192  Usage   : my $matchalphabet = $symbol->matches();
 193  Function: Get/Set (Sub) alphabet of symbols matched by this symbol
 194            including the symbol itself (i.e. if symbol is DNA
 195            ambiguity code W then the matches contains symbols for W
 196            and T)
 197  Returns : Bio::Symbol::AlphabetI
 198  Args    : (optional) Bio::Symbol::AlphabetI
 199
 200 =cut
 201
 202 sub matches{
 203    my ($self,$matches) = @_;
 204
 205    if( $matches ) {
 206        if( ! $matches->isa('Bio::Symbol::AlphabetI') ) {
 207            $self->warn("Must pass in a Bio::Symbol::AlphabetI object to matches function");
 208            # stick with previous value
 209        } else {
 210            $self->{'_matches'} = $matches;
 211        }
 212    }
 213    return $self->{'_matches'};
 214 }
 215
 216 =head2 equals
 217
 218  Title   : equals
 219  Usage   : if( $symbol->equals($symbol2) ) { }
 220  Function: Tests if a symbol is equal to another
 221  Returns : Boolean
 222  Args    : Bio::Symbol::SymbolI
 223
 224 =cut
 225
 226 sub equals{
 227    my ($self,$symbol2) = @_;
 228    # Let's just test based on Tokens for now
 229    # Doesn't handle DNA vs PROTEIN accidential comparisons
 230    return  $self->token eq $symbol2->token;
 231 }
 232
 233
 234 1;