Archive Ensembl HomeArchive Ensembl Home
StableIdEvent.pm
Go to the documentation of this file.
00001 =head1 LICENSE
00002 
00003   Copyright (c) 1999-2012 The European Bioinformatics Institute and
00004   Genome Research Limited.  All rights reserved.
00005 
00006   This software is distributed under a modified Apache license.
00007   For license details, please see
00008 
00009     http://www.ensembl.org/info/about/code_licence.html
00010 
00011 =head1 CONTACT
00012 
00013   Please email comments or questions to the public Ensembl
00014   developers list at <dev@ensembl.org>.
00015 
00016   Questions may also be sent to the Ensembl help desk at
00017   <helpdesk@ensembl.org>.
00018 
00019 =cut
00020 
00021 =head1 NAME
00022 
00023 Bio::EnsEMBL::StableIdEvent- object representing a stable ID mapping event
00024 
00025 =head1 SYNOPSIS
00026 
00027   my $old_id = Bio::EnsEMBL::ArchiveStableId->new(
00028     -stable_id => 'ENSG001',
00029     -version   => 1,
00030     -type      => 'Gene',
00031   );
00032 
00033   my $new_id = Bio::EnsEMBL::ArchiveStableId->new(
00034     -stable_id => 'ENSG001',
00035     -version   => 2,
00036     -type      => 'Gene',
00037   );
00038 
00039   my $event = Bio::EnsEMBL::StableIdEvent->new(
00040     -old_id => $old_id,
00041     -new_id => $new_id,
00042     -score  => 0.997
00043   );
00044 
00045   # directly access attributes in old and new ArchiveStableId
00046   my $old_stable_id = $event->get_attribute( 'old', 'stable_id' );
00047 
00048 =head1 DESCRIPTION
00049 
00050 This object represents a stable ID mapping event. Such an event links two
00051 ArchiveStableIds with a mapping score.
00052 
00053 =head1 METHODS
00054 
00055   new
00056   old_ArchiveStableId
00057   new_ArchiveStableId
00058   score
00059   get_attribute
00060   ident_string
00061 
00062 =head1 RELATED MODULES
00063 
00064   Bio::EnsEMBL::ArchiveStableId
00065   Bio::EnsEMBL::DBSQL::ArchiveStableIdAdaptor
00066   Bio::EnsEMBL::StableIdHistoryTree
00067 
00068 =cut
00069 
00070 package Bio::EnsEMBL::StableIdEvent;
00071 
00072 use strict;
00073 use warnings;
00074 no warnings 'uninitialized';
00075 
00076 use Bio::EnsEMBL::Utils::Exception qw(throw warning);
00077 use Bio::EnsEMBL::Utils::Argument qw(rearrange);
00078 
00079 
00080 =head2 new
00081 
00082   Arg[1]      : Bio::EnsEMBL::ArchiveStableId $old_id
00083                 The old ArchiveStableId in the mapping event
00084   Arg[2]      : Bio::EnsEMBL::ArchiveStableId $new_id
00085                 The new ArchiveStableId in the mapping event
00086   Arg[3]      : (optional) float $score - score of this mapping event
00087   Example     : my $event = Bio::EnsEMBL::StableIdEvent->new(
00088                   $arch_id1, $arch_id2, 0.977);
00089   Description : object constructor
00090   Return type : Bio::EnsEMBL::StableIdEvent
00091   Exceptions  : thrown on wrong argument types
00092   Caller      : Bio::EnsEMBL::DBSQL::ArchiveStableIdAdaptor::fetch_history_tree_by_stable_id, general
00093   Status      : At Risk
00094               : under development
00095 
00096 =cut
00097 
00098 sub new {
00099   my $caller = shift;
00100   my $class = ref($caller) || $caller;
00101 
00102   my ($old_id, $new_id, $score) = rearrange([qw(OLD_ID NEW_ID SCORE)], @_);
00103 
00104   throw("Need old or new Bio::EnsEMBL::ArchiveStableId to create StableIdEvent")
00105     unless ($old_id || $new_id);
00106 
00107   my $self = {};
00108   bless $self, $class;
00109 
00110   # initialise object
00111   $self->old_ArchiveStableId($old_id);
00112   $self->new_ArchiveStableId($new_id);
00113   $self->score($score);
00114   
00115   return $self;
00116 }
00117 
00118 
00119 =head2 old_ArchiveStableId
00120 
00121   Arg[1]      : (optional) Bio::EnsEMBL::ArchiveStableId $archive_id, or undef
00122                 The old ArchiveStableId to set for this mapping event
00123   Example     : # getter
00124                 my $archive_id = $event->old_ArchiveStableId;
00125                 
00126                 # setter
00127                 $event->old_ArchiveStableId($archive_id);
00128   Description : Getter/setter for old ArchiveStableId in this mapping event.
00129   Return type : Bio::EnsEMBL::ArchiveStableId
00130   Exceptions  : thrown on wrong argument type
00131   Caller      : general
00132   Status      : At Risk
00133               : under development
00134 
00135 =cut
00136 
00137 sub old_ArchiveStableId {
00138   my $self = shift;
00139   
00140   # setter
00141   if (@_) {
00142     my $archive_id = shift;
00143 
00144     # if argument is defined, check type. undef is also legal as an argument.
00145     if (defined($archive_id)) {
00146       throw("Need a Bio::EnsEMBL::ArchiveStableId.") unless
00147         (ref($archive_id) && $archive_id->isa('Bio::EnsEMBL::ArchiveStableId'));
00148     }
00149 
00150     $self->{'old_id'} = $archive_id;
00151   }
00152 
00153   # getter
00154   return $self->{'old_id'};
00155 }
00156 
00157 
00158 =head2 new_ArchiveStableId
00159 
00160   Arg[1]      : (optional) Bio::EnsEMBL::ArchiveStableId $archive_id, or undef
00161                 The new ArchiveStableId to set for this mapping event
00162   Example     : # getter
00163                 my $archive_id = $event->new_ArchiveStableId;
00164                 
00165                 # setter
00166                 $event->new_ArchiveStableId($archive_id);
00167   Description : Getter/setter for new ArchiveStableId in this mapping event.
00168   Return type : Bio::EnsEMBL::ArchiveStableId
00169   Exceptions  : thrown on wrong argument type
00170   Caller      : general
00171   Status      : At Risk
00172               : under development
00173 
00174 =cut
00175 
00176 sub new_ArchiveStableId {
00177   my $self = shift;
00178   
00179   # setter
00180   if (@_) {
00181     my $archive_id = shift;
00182 
00183     # if argument is defined, check type. undef is also legal as an argument.
00184     if (defined($archive_id)) {
00185       throw("Need a Bio::EnsEMBL::ArchiveStableId.") unless
00186         (ref($archive_id) && $archive_id->isa('Bio::EnsEMBL::ArchiveStableId'));
00187     }
00188 
00189     $self->{'new_id'} = $archive_id;
00190   }
00191 
00192   # getter
00193   return $self->{'new_id'};
00194 }
00195 
00196 
00197 =head2 score
00198 
00199   Arg[1]      : (optional) float $score - the score to set
00200   Example     : my $score = $event->score;
00201   Description : Getter/setter for mapping event score.
00202   Return type : float or undef
00203   Exceptions  : none
00204   Caller      : general
00205   Status      : At Risk
00206               : under development
00207 
00208 =cut
00209 
00210 sub score {
00211   my $self = shift;
00212   $self->{'score'} = shift if (@_);
00213   return $self->{'score'};
00214 }
00215 
00216 
00217 =head2 get_attribute
00218 
00219   Arg[1]      : String $type - determines whether to get attribute from 'old'
00220                 or 'new' ArchiveStableId
00221   Arg[2]      : String $attr - ArchiveStableId attribute to fetch
00222   Example     : my $old_stable_id = $event->get_attribute('old', 'stable_id');
00223   Description : Accessor to attributes of the ArchiveStableIds attached to this
00224                 event. Convenience method that does the check for undef old
00225                 and/or new ArchiveStableId for you.
00226   Return type : same as respective method in Bio::EnsEMBL::ArchiveStableId, or
00227                 undef
00228   Exceptions  : thrown on wrong arguments
00229   Caller      : general
00230   Status      : At Risk
00231               : under development
00232 
00233 =cut
00234 
00235 sub get_attribute {
00236   my ($self, $type, $attr) = @_;
00237 
00238   throw("First argument passed to this function has to be 'old' or 'new'.")
00239     unless ($type eq 'old' or $type eq 'new');
00240 
00241   my %allowed_attribs = map { $_ => 1 }
00242     qw(stable_id version db_name release assembly);
00243 
00244   throw("Attribute $attr not allowed.") unless $allowed_attribs{$attr};
00245 
00246   my $call = $type.'_ArchiveStableId';
00247 
00248   if (my $id = $self->$call) {
00249     return $id->$attr;
00250   } else {
00251     return undef;
00252   }
00253 }
00254 
00255 
00256 =head2 ident_string
00257 
00258   Example     : print $event->ident_string, "\n";
00259   Description : Returns a string that can be used to identify your StableIdEvent.
00260                 Useful in debug warnings.
00261   Return type : String
00262   Exceptions  : none
00263   Caller      : general
00264   Status      : At Risk
00265               : under development
00266 
00267 =cut
00268 
00269 sub ident_string {
00270   my $self = shift;
00271 
00272   my $old_id = $self->old_ArchiveStableId;
00273   my $new_id = $self->new_ArchiveStableId;
00274 
00275   my $str;
00276 
00277   if ($old_id) {
00278     $str = $old_id->stable_id.'.'.$old_id->version.' ('.
00279       $old_id->release.')';
00280   } else {
00281     $str = 'null';
00282   }
00283 
00284   $str .= ' -> ';
00285 
00286   if ($new_id) {
00287     $str .= $new_id->stable_id.'.'.$new_id->version.' ('.
00288       $new_id->release.')';
00289   } else {
00290     $str .= 'null';
00291   }
00292 
00293   $str .= ' ['.$self->score.']';
00294   
00295   return $str;
00296 }
00297 
00298 
00299 1;
00300