Archive Ensembl HomeArchive Ensembl Home
Gene.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::Gene - Object representing a genes
00024 
00025 =head1 SYNOPSIS
00026 
00027   my $gene = Bio::EnsEMBL::Gene->new(
00028     -START  => 123,
00029     -END    => 1045,
00030     -STRAND => 1,
00031     -SLICE  => $slice
00032   );
00033 
00034   # print gene information
00035   print("gene start:end:strand is "
00036       . join( ":", map { $gene->$_ } qw(start end strand) )
00037       . "\n" );
00038 
00039   # set some additional attributes
00040   $gene->stable_id('ENSG000001');
00041   $gene->description('This is the gene description');
00042 
00043 =head1 DESCRIPTION
00044 
00045 A representation of a Gene within the Ensembl system. A gene is a set of one or
00046 more alternative transcripts.
00047 
00048 =head1 METHODS
00049 
00050 =cut
00051 
00052 package Bio::EnsEMBL::Gene;
00053 
00054 use strict;
00055 
00056 use POSIX;
00057 use Bio::EnsEMBL::Feature;
00058 use Bio::EnsEMBL::Utils::Argument qw(rearrange);
00059 use Bio::EnsEMBL::Utils::Exception qw(throw warning deprecate);
00060 use Bio::EnsEMBL::Utils::Scalar qw(assert_ref);
00061 
00062 use vars qw(@ISA);
00063 @ISA = qw(Bio::EnsEMBL::Feature);
00064 
00065 
00066 =head2 new
00067 
00068   Arg [-START]  : 
00069        int - start postion of the gene
00070   Arg [-END]    : 
00071        int - end position of the gene
00072   Arg [-STRAND] : 
00073        int - 1,-1 tehe strand the gene is on
00074   Arg [-SLICE]  : 
00075        Bio::EnsEMBL::Slice - the slice the gene is on
00076   Arg [-STABLE_ID] :
00077         string - the stable identifier of this gene
00078   Arg [-VERSION] :
00079         int - the version of the stable identifier of this gene
00080   Arg [-EXTERNAL_NAME] :
00081         string - the external database name associated with this gene
00082   Arg [-EXTERNAL_DB] :
00083         string - the name of the database the external name is from
00084   Arg [-EXTERNAL_STATUS]:
00085         string - the status of the external identifier
00086   Arg [-DISPLAY_XREF]:
00087         Bio::EnsEMBL::DBEntry - The external database entry that is used
00088         to label this gene when it is displayed.
00089   Arg [-TRANSCRIPTS]:
00090         Listref of Bio::EnsEMBL::Transcripts - this gene's transcripts
00091   Arg [-CREATED_DATE]:
00092         string - the date the gene was created
00093   Arg [-MODIFIED_DATE]:
00094         string - the date the gene was last modified
00095   Arg [-DESCRIPTION]:
00096         string - the genes description
00097   Arg [-BIOTYPE]:
00098         string - the biotype e.g. "protein_coding"
00099   Arg [-STATUS]:
00100         string - the gene status i.e. "KNOWN","NOVEL"
00101   Arg [-SOURCE]:
00102         string - the genes source, e.g. "ensembl"
00103   Arg [-IS_CURRENT]:
00104         Boolean - specifies if this is the current version of the gene
00105   Arg [-CANONICAL_TRANSCRIPT]:
00106         Bio::EnsEMBL::Transcript - the canonical transcript of this gene
00107   Arg [-CANONICAL_TRANSCRIPT_ID]:
00108         integer - the canonical transcript dbID of this gene, if the
00109         transcript object itself is not available.
00110   Arg [-CANONICAL_ANNOTATION]:
00111         string - canonical annotation
00112 
00113   Example    : $gene = Bio::EnsEMBL::Gene->new(...);
00114   Description: Creates a new gene object
00115   Returntype : Bio::EnsEMBL::Gene
00116   Exceptions : none
00117   Caller     : general
00118   Status     : Stable
00119 
00120 =cut
00121 
00122 sub new {
00123   my $caller = shift;
00124 
00125   my $class = ref($caller) || $caller;
00126   my $self = $class->SUPER::new(@_);
00127   my (
00128     $stable_id,               $version,
00129     $external_name,           $type,
00130     $external_db,             $external_status,
00131     $display_xref,            $description,
00132     $transcripts,             $created_date,
00133     $modified_date,           $confidence,
00134     $biotype,                 $source,
00135     $status,                  $is_current,
00136     $canonical_transcript_id, $canonical_transcript,
00137     $canonical_annotation
00138     )
00139     = rearrange( [
00140       'STABLE_ID',               'VERSION',
00141       'EXTERNAL_NAME',           'TYPE',
00142       'EXTERNAL_DB',             'EXTERNAL_STATUS',
00143       'DISPLAY_XREF',            'DESCRIPTION',
00144       'TRANSCRIPTS',             'CREATED_DATE',
00145       'MODIFIED_DATE',           'CONFIDENCE',
00146       'BIOTYPE',                 'SOURCE',
00147       'STATUS',                  'IS_CURRENT',
00148       'CANONICAL_TRANSCRIPT_ID', 'CANONICAL_TRANSCRIPT',
00149       'CANONICAL_ANNOTATION'
00150     ],
00151     @_
00152     );
00153 
00154 
00155   if ($transcripts) {
00156     $self->{'_transcript_array'} = $transcripts;
00157     $self->recalculate_coordinates();
00158   }
00159 
00160   $self->stable_id($stable_id);
00161   $self->version($version);
00162   $self->{'created_date'}  = $created_date;
00163   $self->{'modified_date'} = $modified_date;
00164 
00165   $self->external_name($external_name) if ( defined $external_name );
00166   $self->external_db($external_db)     if ( defined $external_db );
00167   $self->external_status($external_status)
00168     if ( defined $external_status );
00169   $self->display_xref($display_xref) if ( defined $display_xref );
00170   $self->biotype($type)              if ( defined $type );
00171   $self->biotype($biotype)           if ( defined $biotype );
00172   $self->description($description);
00173   $self->status($confidence);    # incase old naming is used.
00174       # kept to ensure routine is backwards compatible.
00175   $self->status($status);    # add new naming
00176   $self->source($source);
00177 
00178   # default to is_current
00179   $is_current = 1 unless (defined($is_current));
00180   $self->{'is_current'} = $is_current;
00181 
00182   # Add the canonical transcript if we were given one, otherwise add the
00183   # canonical transcript internal ID if we were given one.
00184   if ( defined($canonical_transcript) ) {
00185     $self->canonical_transcript($canonical_transcript);
00186   } elsif ( defined($canonical_transcript_id) ) {
00187     $self->{'canonical_transcript_id'} = $canonical_transcript_id;
00188   }
00189 
00190   $self->canonical_annotation($canonical_annotation)
00191     if ( defined $canonical_annotation );
00192 
00193   return $self;
00194 }
00195 
00196 
00197 =head2 is_known
00198 
00199   Example    : print "Gene ".$gene->stable_id." is KNOWN\n" if $gene->is_known;
00200   Description: Returns TRUE if this gene has a status of 'KNOWN'
00201   Returntype : TRUE if known, FALSE otherwise
00202   Exceptions : none
00203   Caller     : general
00204   Status     : Stable
00205 
00206 =cut
00207 
00208 
00209 sub is_known{
00210   my $self = shift;
00211   return ( $self->{'status'} eq "KNOWN" || $self->{'status'} eq "KNOWN_BY_PROJECTION" );
00212 }
00213 
00214 
00215 =head2 external_name
00216 
00217   Arg [1]    : (optional) String - the external name to set
00218   Example    : $gene->external_name('BRCA2');
00219   Description: Getter/setter for attribute external_name.
00220   Returntype : String or undef
00221   Exceptions : none
00222   Caller     : general
00223   Status     : Stable
00224 
00225 =cut
00226 
00227 sub external_name {
00228   my  $self  = shift;
00229 
00230   $self->{'external_name'} = shift if (@_);
00231 
00232   if (defined $self->{'external_name'}) {
00233     return $self->{'external_name'};
00234   }
00235 
00236   my $display_xref = $self->display_xref();
00237 
00238   if (defined $display_xref) {
00239     return $display_xref->display_id();
00240   } else {
00241     return undef;
00242   }
00243 }
00244 
00245 
00246 =head2 status
00247 
00248   Arg [1]    : (optional) String - status to set
00249   Example    : $gene->status('KNOWN');
00250   Description: Getter/setter for attribute status
00251   Returntype : String
00252   Exceptions : none
00253   Caller     : general
00254   Status     : Medium Risk
00255 
00256 =cut
00257 
00258 sub status {
00259    my $self = shift;
00260   $self->{'status'} = shift if( @_ );
00261   return $self->{'status'};
00262 }
00263 
00264 
00265 =head2 source
00266 
00267   Arg [1]    : (optional) String - the source to set
00268   Example    : $gene->source('ensembl');
00269   Description: Getter/setter for attribute source
00270   Returntype : String
00271   Exceptions : none
00272   Caller     : general
00273   Status     : Stable
00274 
00275 =cut
00276 
00277 sub source {
00278   my $self = shift;
00279   $self->{'source'} = shift if( @_ );
00280   return ( $self->{'source'} || "ensembl" );
00281 }
00282 
00283 
00284 =head2 external_db  
00285 
00286   Arg [1]    : (optional) String - name of external db to set
00287   Example    : $gene->external_db('HGNC');
00288   Description: Getter/setter for attribute external_db. The db is the one that 
00289                belongs to the external_name.  
00290   Returntype : String
00291   Exceptions : none
00292   Caller     : general
00293   Status     : Stable
00294 
00295 =cut
00296 
00297 sub external_db {
00298   my $self = shift;
00299 
00300   $self->{'external_db'} = shift if( @_ );
00301 
00302   if( exists $self->{'external_db'} ) {
00303     return $self->{'external_db'};
00304   }
00305 
00306   my $display_xref = $self->display_xref();
00307 
00308   if( defined $display_xref ) {
00309     return $display_xref->dbname()
00310   } else {
00311     return undef;
00312   }
00313 }
00314 
00315 
00316 =head2 external_status
00317 
00318   Arg [1]    : (optional) String - status of the external db
00319   Example    : $gene->external_status('KNOWNXREF');
00320   Description: Getter/setter for attribute external_status. The status of
00321                the external db of the one that belongs to the external_name.
00322   Returntype : String
00323   Exceptions : none
00324   Caller     : general
00325   Status     : Stable
00326 
00327 =cut
00328 
00329 sub external_status {
00330   my $self = shift;
00331 
00332   $self->{'_ext_status'} = shift if ( @_ );
00333   return $self->{'_ext_status'} if exists $self->{'_ext_status'};
00334 
00335   my $display_xref = $self->display_xref();
00336 
00337   if( defined $display_xref ) {
00338     return $display_xref->status()
00339   } else {
00340     return undef;
00341   }
00342 }
00343 
00344 
00345 =head2 description
00346 
00347   Arg [1]    : (optional) String - the description to set
00348   Example    : $gene->description('This is the gene\'s description');
00349   Description: Getter/setter for gene description
00350   Returntype : String
00351   Exceptions : none
00352   Caller     : general
00353   Status     : Stable
00354 
00355 =cut
00356 
00357 sub description {
00358     my $self = shift;
00359     $self->{'description'} = shift if( @_ );
00360     return $self->{'description'};
00361 }
00362 
00363 
00364 =head2 equals
00365 
00366   Arg [1]       : Bio::EnsEMBL::Gene gene
00367   Example       : if ($geneA->equals($geneB)) { ... }
00368   Description   : Compares two genes for equality.
00369                   The test for eqality goes through the following list
00370                   and terminates at the first true match:
00371 
00372                   1. If Bio::EnsEMBL::Feature::equals() returns false,
00373                      then the genes are *not* equal.
00374                   2. If the biotypes differ, then the genes are *not*
00375                      equal.
00376                   3. If both genes have stable IDs: if these are the
00377                      same, the genes are equal, otherwise not.
00378                   4. If both genes have the same number of transcripts
00379                      and if these are (when compared pair-wise sorted by
00380                      start-position and length) the same, then they are
00381                      equal, otherwise not.
00382 
00383   Return type   : Boolean (0, 1)
00384 
00385   Exceptions    : Thrown if a non-gene is passed as the argument.
00386 
00387 =cut
00388 
00389 sub equals {
00390   my ( $self, $gene ) = @_;
00391 
00392   if ( !defined($gene) ) { return 0 }
00393   if ( $self eq $gene ) { return 1 }
00394 
00395   assert_ref( $gene, 'Bio::EnsEMBL::Gene' );
00396 
00397   my $feature_equals = $self->SUPER::equals($gene);
00398   if ( defined($feature_equals) && $feature_equals == 0 ) {
00399     return 0;
00400   }
00401 
00402   if ( $self->biotype() ne $gene->biotype() ) {
00403     return 0;
00404   }
00405 
00406   if ( defined( $self->stable_id() ) && defined( $gene->stable_id() ) )
00407   {
00408     if   ( $self->stable_id() eq $gene->stable_id() ) { return 1 }
00409     else                                              { return 0 }
00410   }
00411 
00412   my @self_transcripts = sort {
00413     $a->start() <=> $b->start() ||
00414       $a->length() <=> $b->length()
00415   } @{ $self->get_all_Transcripts() };
00416   my @gene_transcripts = sort {
00417     $a->start() <=> $b->start() ||
00418       $a->length() <=> $b->length()
00419   } @{ $gene->get_all_Transcripts() };
00420 
00421   if ( scalar(@self_transcripts) != scalar(@gene_transcripts) ) {
00422     return 0;
00423   }
00424 
00425   while (@self_transcripts) {
00426     my $self_transcript = shift(@self_transcripts);
00427     my $gene_transcript = shift(@gene_transcripts);
00428 
00429     if ( !$self_transcript->equals($gene_transcript) ) {
00430       return 0;
00431     }
00432   }
00433 
00434   return 1;
00435 } ## end sub equals
00436 
00437 =head2 canonical_transcript
00438 
00439   Arg [1]    : (optional) Bio::EnsEMBL::Transcipt - canonical_transcript object
00440   Example    : $gene->canonical_transcript($canonical_transcript);
00441   Description: Getter/setter for the canonical_transcript
00442   Returntype : Bio::EnsEMBL::Transcript
00443   Exceptions : Throws if argument is not a transcript object.
00444   Caller     : general
00445   Status     : Stable
00446 
00447 =cut
00448 
00449 sub canonical_transcript {
00450   my ( $self, $transcript ) = @_;
00451 
00452   if ( defined($transcript) ) {
00453     # We're attaching a new canonical transcript.
00454 
00455     assert_ref( $transcript, 'Bio::EnsEMBL::Transcript' );
00456 
00457     # If there's already a canonical transcript, make sure it doesn't
00458     # think it's still canonical.
00459     if ( defined( $self->{'canonical_transcript'} ) ) {
00460       $self->{'canonical_transcript'}->is_canonical(0);
00461     }
00462 
00463     $self->{'canonical_transcript'}    = $transcript;
00464     $self->{'canonical_transcript_id'} = $transcript->dbID();
00465 
00466     $transcript->is_canonical(1);
00467 
00468   } elsif (   !defined( $self->{'canonical_transcript'} )
00469             && defined( $self->{'canonical_transcript_id'} )
00470             && $self->{'canonical_transcript_id'} != 0 )
00471   {
00472     # We have not attached a canoncical transcript, but we have the dbID
00473     # of one.
00474 
00475     if ( defined( $self->adaptor() ) ) {
00476       my $transcript_adaptor =
00477         $self->adaptor()->db()->get_TranscriptAdaptor();
00478 
00479       my $canonical_transcript =
00480         $transcript_adaptor->fetch_by_dbID(
00481                                    $self->{'canonical_transcript_id'} );
00482 
00483       if ( defined($canonical_transcript) ) {
00484         # Recusive call...
00485         $self->canonical_transcript($canonical_transcript);
00486       }
00487 
00488     } else {
00489       warning(   "Gene has no adaptor "
00490                . "when trying to fetch canonical transcript." );
00491     }
00492 
00493   } ## end elsif ( !defined( $self->...))
00494 
00495   return $self->{'canonical_transcript'};
00496 } ## end sub canonical_transcript
00497 
00498 
00499 =head2 canonical_annotation
00500 
00501   Arg [1]    : (optional) String - canonical_annotation
00502   Example    : $gene->canonical_annotation('This is the canonical_annotation');
00503   Description: Getter/setter for the canonical_annotation
00504   Returntype : String
00505   Exceptions : none
00506   Caller     : general
00507   Status     : Stable
00508 
00509 =cut
00510 
00511 sub canonical_annotation {
00512     my $self = shift;
00513     $self->{'canonical_annotation'} = shift if( @_ );
00514     return $self->{'canonical_annotation'};
00515 }
00516 
00517 =head2 get_all_Attributes
00518 
00519   Arg [1]    : (optional) String $attrib_code
00520                The code of the attribute type to retrieve values for
00521   Example    : my ($author) = @{ $gene->get_all_Attributes('author') };
00522                my @gene_attributes = @{ $gene->get_all_Attributes };
00523   Description: Gets a list of Attributes of this gene.
00524                Optionally just get Attributes for given code.
00525   Returntype : Listref of Bio::EnsEMBL::Attribute
00526   Exceptions : warning if gene does not have attached adaptor and attempts lazy
00527                load.
00528   Caller     : general
00529   Status     : Stable
00530 
00531 =cut
00532 
00533 sub get_all_Attributes {
00534   my $self = shift;
00535   my $attrib_code = shift;
00536 
00537   if ( ! exists $self->{'attributes' } ) {
00538     if (!$self->adaptor() ) {
00539       return [];
00540     }
00541 
00542     my $attribute_adaptor = $self->adaptor->db->get_AttributeAdaptor();
00543     $self->{'attributes'} = $attribute_adaptor->fetch_all_by_Gene($self);
00544   }
00545 
00546   if ( defined $attrib_code ) {
00547     my @results = grep { uc($_->code()) eq uc($attrib_code) }
00548     @{$self->{'attributes'}};
00549     return \@results;
00550   } else {
00551     return $self->{'attributes'};
00552   }
00553 }
00554 
00555 
00556 =head2 add_Attributes
00557 
00558   Arg [1-N]  : list of Bio::EnsEMBL::Attribute's @attribs
00559                Attribute(s) to add
00560   Example    : my $attrib = Bio::EnsEMBL::Attribute->new(...);
00561                $gene->add_Attributes($attrib);
00562   Description: Adds an Attribute to the Gene. If you add an attribute before
00563                you retrieve any from database, lazy loading will be disabled.
00564   Returntype : none
00565   Exceptions : throw on incorrect arguments
00566   Caller     : general
00567   Status     : Stable
00568 
00569 =cut
00570 
00571 sub add_Attributes {
00572   my $self = shift;
00573   my @attribs = @_;
00574 
00575   if( ! exists $self->{'attributes'} ) {
00576     $self->{'attributes'} = [];
00577   }
00578 
00579   for my $attrib ( @attribs ) {
00580     if( ! $attrib->isa( "Bio::EnsEMBL::Attribute" )) {
00581      throw( "Argument to add_Attribute has to be an Bio::EnsEMBL::Attribute" );
00582     }
00583     push( @{$self->{'attributes'}}, $attrib );
00584   }
00585 
00586   return;
00587 }
00588 
00589 
00590 =head2 add_DBEntry
00591 
00592   Arg [1]    : Bio::EnsEMBL::DBEntry $dbe
00593                The dbEntry to be added
00594   Example    : my $dbe = Bio::EnsEMBL::DBEntery->new(...);
00595                $gene->add_DBEntry($dbe);
00596   Description: Associates a DBEntry with this gene. Note that adding DBEntries
00597                will prevent future lazy-loading of DBEntries for this gene
00598                (see get_all_DBEntries).
00599   Returntype : none
00600   Exceptions : thrown on incorrect argument type
00601   Caller     : general
00602   Status     : Stable
00603 
00604 =cut
00605 
00606 sub add_DBEntry {
00607   my $self = shift;
00608   my $dbe = shift;
00609 
00610   unless($dbe && ref($dbe) && $dbe->isa('Bio::EnsEMBL::DBEntry')) {
00611     throw('Expected DBEntry argument');
00612   }
00613 
00614   $self->{'dbentries'} ||= [];
00615   push @{$self->{'dbentries'}}, $dbe;
00616 }
00617 
00618 
00619 =head2 get_all_DBEntries
00620 
00621   Arg [1]    : (optional) String, external database name
00622 
00623   Arg [2]    : (optional) String, external_db type
00624 
00625   Example    : @dbentries = @{ $gene->get_all_DBEntries() };
00626 
00627   Description: Retrieves DBEntries (xrefs) for this gene.  This does
00628                *not* include DBEntries that are associated with the
00629                transcripts and corresponding translations of this
00630                gene (see get_all_DBLinks()).
00631 
00632                This method will attempt to lazy-load DBEntries
00633                from a database if an adaptor is available and no
00634                DBEntries are present on the gene (i.e. they have not
00635                already been added or loaded).
00636 
00637   Return type: Listref of Bio::EnsEMBL::DBEntry objects
00638   Exceptions : none
00639   Caller     : get_all_DBLinks, GeneAdaptor::store
00640   Status     : Stable
00641 
00642 =cut
00643 
00644 sub get_all_DBEntries {
00645   my ( $self, $db_name_exp, $ex_db_type ) = @_;
00646 
00647   my $cache_name = 'dbentries';
00648 
00649   if ( defined($db_name_exp) ) {
00650     $cache_name .= $db_name_exp;
00651   }
00652 
00653   if ( defined($ex_db_type) ) {
00654     $cache_name .= $ex_db_type;
00655   }
00656 
00657   # if not cached, retrieve all of the xrefs for this gene
00658   if ( !defined( $self->{$cache_name} ) && defined( $self->adaptor() ) )
00659   {
00660     $self->{$cache_name} =
00661       $self->adaptor()->db()->get_DBEntryAdaptor()
00662       ->fetch_all_by_Gene( $self, $db_name_exp, $ex_db_type );
00663   }
00664 
00665   $self->{$cache_name} ||= [];
00666 
00667   return $self->{$cache_name};
00668 } ## end sub get_all_DBEntries
00669 
00670 =head2 get_all_object_xrefs
00671 
00672   Arg [1]    : (optional) String, external database name
00673 
00674   Arg [2]    : (optional) String, external_db type
00675 
00676   Example    : @oxrefs = @{ $gene->get_all_object_xrefs() };
00677 
00678   Description: Retrieves xrefs for this gene.  This does *not*
00679                include xrefs that are associated with the
00680                transcripts or corresponding translations of this
00681                gene (see get_all_xrefs()).
00682 
00683                This method will attempt to lazy-load xrefs from a
00684                database if an adaptor is available and no xrefs are
00685                present on the gene (i.e. they have not already been
00686                added or loaded).
00687 
00688                 NB: This method is an alias for the
00689                     get_all_DBentries() method.
00690 
00691   Return type: Listref of Bio::EnsEMBL::DBEntry objects
00692 
00693   Status     : Stable
00694 
00695 =cut
00696 
00697 sub get_all_object_xrefs {
00698   my $self = shift;
00699   return $self->get_all_DBEntries(@_);
00700 }
00701 
00702 =head2 get_all_DBLinks
00703 
00704   Arg [1]    : String database name (optional)
00705                SQL wildcard characters (_ and %) can be used to
00706                specify patterns.
00707 
00708   Example    : @dblinks = @{ $gene->get_all_DBLinks() };
00709                @dblinks = @{ $gene->get_all_DBLinks('Uniprot%') };
00710 
00711   Description: Retrieves *all* related DBEntries for this gene. This
00712                includes all DBEntries that are associated with the
00713                transcripts and corresponding translations of this
00714                gene.
00715 
00716                If you only want to retrieve the DBEntries
00717                associated with the gene (and not the transcript
00718                and translations) then you should use the
00719                get_all_DBEntries() call instead.
00720 
00721                Note: Each entry may be listed more than once.  No
00722                uniqueness checks are done.  Also if you put in an
00723                incorrect external database name no checks are done
00724                to see if this exists, you will just get an empty
00725                list.
00726 
00727   Return type: Listref of Bio::EnsEMBL::DBEntry objects
00728   Exceptions : none
00729   Caller     : general
00730   Status     : Stable
00731 
00732 =cut
00733 
00734 sub get_all_DBLinks {
00735   my ( $self, $db_name_exp, $ex_db_type ) = @_;
00736 
00737   my @links =
00738     @{ $self->get_all_DBEntries( $db_name_exp, $ex_db_type ) };
00739 
00740   # Add all of the transcript and translation xrefs to the return list.
00741   foreach my $transcript ( @{ $self->get_all_Transcripts() } ) {
00742     push( @links,
00743           @{$transcript->get_all_DBLinks( $db_name_exp, $ex_db_type ) }
00744     );
00745   }
00746 
00747   return \@links;
00748 }
00749 
00750 =head2 get_all_xrefs
00751 
00752   Arg [1]    : String database name (optional)
00753                SQL wildcard characters (_ and %) can be used to
00754                specify patterns.
00755 
00756   Example    : @xrefs = @{ $gene->get_all_xrefs() };
00757                @xrefs = @{ $gene->get_all_xrefs('Uniprot%') };
00758 
00759   Description: Retrieves *all* related xrefs for this gene.  This
00760                includes all xrefs that are associated with the
00761                transcripts and corresponding translations of this
00762                gene.
00763 
00764                If you want to retrieve the xrefs associated
00765                with only the gene (and not the transcript
00766                or translations) then you should use the
00767                get_all_object_xrefs() method instead.
00768 
00769                Note: Each entry may be listed more than once.  No
00770                uniqueness checks are done.  Also if you put in an
00771                incorrect external database name no checks are done
00772                to see if this exists, you will just get an empty
00773                list.
00774 
00775                 NB: This method is an alias for the
00776                     get_all_DBLinks() method.
00777 
00778   Return type: Listref of Bio::EnsEMBL::DBEntry objects
00779 
00780   Status     : Stable
00781 
00782 =cut
00783 
00784 sub get_all_xrefs {
00785   my $self = shift;
00786   return $self->get_all_DBLinks(@_);
00787 }
00788 
00789 =head2 get_all_Exons
00790 
00791   Example    : my @exons = @{ $gene->get_all_Exons };
00792   Description: Returns a set of all the exons associated with this gene.
00793   Returntype : Listref of Bio::EnsEMBL::Exon objects
00794   Exceptions : none
00795   Caller     : general
00796   Status     : Stable
00797 
00798 =cut
00799 
00800 
00801 sub get_all_Exons {
00802   my $self = shift;
00803 
00804   my %h;
00805   my @out = ();
00806 
00807   foreach my $trans ( @{$self->get_all_Transcripts} ) {
00808     foreach my $e ( @{$trans->get_all_Exons} ) {
00809       $h{$e->start()."-".$e->end()."-".$e->strand()."-".$e->phase()."-".$e->end_phase()} = $e;
00810     }
00811   }
00812 
00813   push @out, values %h;
00814 
00815   return \@out;
00816 }
00817 
00818 
00819 =head2 get_all_homologous_Genes
00820 
00821   Description: Queries the Ensembl Compara database and retrieves all
00822                Genes from other species that are orthologous.
00823                REQUIRES properly setup Registry conf file. Meaning that
00824                one of the aliases for each core db has to be "Genus species"
00825                e.g. "Homo sapiens" (as in the name column in genome_db table
00826                in the compara database).
00827   Returntype : listref [
00828                         Bio::EnsEMBL::Gene,
00829                         Bio::EnsEMBL::Compara::Homology,
00830                         string $species # needed as cannot get spp from Gene 
00831                        ]
00832   Exceptions : none
00833   Caller     : general
00834   Status     : Stable
00835 
00836 =cut
00837 
00838 sub get_all_homologous_Genes {
00839   my $self = shift;
00840 
00841   if( exists( $self->{'homologues'} ) ){
00842     return $self->{'homologues'};
00843   }
00844   $self->{'homologues'} = [];
00845 
00846   # TODO: Find a robust way of retrieving compara dba directly.
00847   # For now look through all DBAs
00848   my $compara_dba;
00849   foreach my $dba( @{Bio::EnsEMBL::Registry->get_all_DBAdaptors} ){
00850     if( $dba->isa('Bio::EnsEMBL::Compara::DBSQL::DBAdaptor') ){
00851       $compara_dba = $dba;
00852       last;
00853     }
00854   }
00855   unless( $compara_dba ){
00856     warning("No compara in Bio::EnsEMBL::Registry");
00857     return $self->{'homologues'};
00858   }
00859 
00860   # Get the compara 'member' corresponding to self
00861   my $member_adaptor   = $compara_dba->get_adaptor('Member');
00862   my $query_member = $member_adaptor->fetch_by_source_stable_id
00863       ("ENSEMBLGENE",$self->stable_id);
00864   unless( $query_member ){ return $self->{'homologues'} };
00865 
00866   # Get the compara 'homologies' corresponding to 'member'
00867   my $homology_adaptor = $compara_dba->get_adaptor('Homology');
00868   my @homolos = @{$homology_adaptor->fetch_all_by_Member($query_member)};
00869   unless( scalar(@homolos) ){ return $self->{'homologues'} };
00870 
00871   # Get the ensembl 'genes' corresponding to 'homologies'
00872   foreach my $homolo( @homolos ){
00873     foreach my $member_attrib( @{$homolo->get_all_Member_Attribute} ){
00874       my ($member, $attrib) = @{$member_attrib};
00875       my $hstable_id = $member->stable_id;
00876       next if ($hstable_id eq $query_member->stable_id); # Ignore self     
00877       my $hgene = undef;
00878       eval { $hgene = $member->get_Gene;} ;
00879       unless( $hgene ){
00880         # Something up with DB. Create a new gene is best we can do
00881         $hgene = Bio::EnsEMBL::Gene->new
00882             ( -stable_id=>$hstable_id,
00883               -description=>$member->description, );
00884       }
00885       my $hspecies = $member->genome_db->name;
00886       push @{$self->{'homologues'}}, [$hgene,$homolo,$hspecies];
00887     }
00888   }
00889   return $self->{'homologues'};
00890 }
00891 
00892 
00893 =head2 biotype
00894 
00895   Arg [1]    : (optional) String - the biotype to set
00896   Example    : $gene->biotype("protein_coding");
00897   Description: Getter/setter for the attribute biotype
00898   Returntype : String
00899   Exceptions : none
00900   Caller     : general
00901   Status     : Stable
00902 
00903 =cut
00904 
00905 sub biotype {
00906   my $self = shift;
00907 
00908   $self->{'biotype'} = shift if( @_ );
00909   return ( $self->{'biotype'} || "protein_coding" );
00910 }
00911 
00912 
00913 =head2 add_Transcript
00914 
00915   Arg [1]    : Bio::EnsEMBL::Transcript $trans
00916                The transcript to add to the gene
00917   Example    : my $transcript = Bio::EnsEMBL::Transcript->new(...);
00918                $gene->add_Transcript($transcript);
00919   Description: Adds another Transcript to the set of alternatively
00920                spliced Transcripts of this gene. If it shares exons 
00921                with another Transcript, these should be object-identical.
00922   Returntype : none
00923   Exceptions : none
00924   Caller     : general
00925   Status     : Stable
00926 
00927 =cut
00928 
00929 sub add_Transcript {
00930    my ($self, $trans) = @_;
00931 
00932    if( !ref $trans || ! $trans->isa("Bio::EnsEMBL::Transcript") ) {
00933        throw("$trans is not a Bio::EnsEMBL::Transcript!");
00934    }
00935 
00936    $self->{'_transcript_array'} ||= [];
00937    push(@{$self->{'_transcript_array'}},$trans);
00938 
00939    $self->recalculate_coordinates();
00940 }
00941 
00942 
00943 =head2 get_all_Transcripts
00944 
00945   Example    : my @transcripts = @{ $gene->get_all_Transcripts };
00946   Description: Returns the Transcripts in this gene.
00947   Returntype : Listref of Bio::EnsEMBL::Transcript objects
00948   Exceptions : none
00949   Caller     : general
00950   Status     : Stable
00951 
00952 =cut
00953 
00954 sub get_all_Transcripts {
00955   my $self = shift;
00956 
00957   if( ! exists $self->{'_transcript_array'} ) {
00958     if( defined $self->adaptor() ) {
00959       my $ta = $self->adaptor()->db()->get_TranscriptAdaptor();
00960       my $transcripts = $ta->fetch_all_by_Gene( $self );
00961       $self->{'_transcript_array'} = $transcripts;
00962     }
00963   }
00964   return $self->{'_transcript_array'};
00965 }
00966 
00967 
00968 =head2 get_all_alt_alleles
00969 
00970   Example    : my @alt_genes = @{ $gene->get_all_alt_alleles };
00971                foreach my $alt_gene (@alt_genes) {
00972                  print "Alternate allele: " . $alt_gene->stable_id() . "\n";
00973                }
00974   Description: Returns a listref of Gene objects that represent this Gene on
00975                an alternative haplotype. Empty list if there is no such
00976                Gene (eg there is no overlapping haplotype).
00977   Returntype : listref of Bio::EnsEMBL::Gene objects
00978   Exceptions : none
00979   Caller     : general
00980   Status     : Stable
00981 
00982 =cut
00983 
00984 sub get_all_alt_alleles {
00985   my $self = shift;
00986   my $result = $self->adaptor()->fetch_all_alt_alleles( $self );
00987   return $result;
00988 }
00989 
00990 
00991 =head2 version
00992 
00993   Arg [1]    : (optional) Int
00994                A version number for the stable_id
00995   Example    : $gene->version(2);
00996   Description: Getter/setter for version number
00997   Returntype : Int
00998   Exceptions : none
00999   Caller     : general
01000   Status     : Stable
01001 
01002 =cut
01003 
01004 sub version {
01005   my $self = shift;
01006   $self->{'version'} = shift if(@_);
01007   return $self->{'version'};
01008 }
01009 
01010 
01011 =head2 stable_id
01012 
01013   Arg [1]    : (optional) String - the stable ID to set
01014   Example    : $gene->stable_id("ENSG0000000001");
01015   Description: Getter/setter for stable id for this gene.
01016   Returntype : String
01017   Exceptions : none
01018   Caller     : general
01019   Status     : Stable
01020 
01021 =cut
01022 
01023 sub stable_id {
01024   my $self = shift;
01025   $self->{'stable_id'} = shift if(@_);
01026   return $self->{'stable_id'};
01027 }
01028 
01029 
01030 =head2 is_current
01031 
01032   Arg [1]    : Boolean $is_current
01033   Example    : $gene->is_current(1)
01034   Description: Getter/setter for is_current state of this gene.
01035   Returntype : Int
01036   Exceptions : none
01037   Caller     : general
01038   Status     : Stable
01039 
01040 =cut
01041 
01042 sub is_current {
01043   my $self = shift;
01044   $self->{'is_current'} = shift if (@_);
01045   return $self->{'is_current'};
01046 }
01047 
01048 
01049 =head2 created_date
01050 
01051   Arg [1]    : (optional) String - created date to set (as a UNIX time int)
01052   Example    : $gene->created_date('1141948800');
01053   Description: Getter/setter for attribute created_date
01054   Returntype : String
01055   Exceptions : none
01056   Caller     : general
01057   Status     : Stable
01058 
01059 =cut
01060 
01061 sub created_date {
01062   my $self = shift;
01063   $self->{'created_date'} = shift if ( @_ );
01064   return $self->{'created_date'};
01065 }
01066 
01067 
01068 =head2 modified_date
01069 
01070   Arg [1]    : (optional) String - modified date to set (as a UNIX time int)
01071   Example    : $gene->modified_date('1141948800');
01072   Description: Getter/setter for attribute modified_date
01073   Returntype : String
01074   Exceptions : none
01075   Caller     : general
01076   Status     : Stable
01077 
01078 =cut
01079 
01080 sub modified_date {
01081   my $self = shift;
01082   $self->{'modified_date'} = shift if ( @_ );
01083   return $self->{'modified_date'};
01084 }
01085 
01086 
01087 =head2 transform
01088 
01089   Arg [1]    : String - coordinate system name to transform to
01090   Arg [2]    : String - coordinate system version
01091   Example    : my $new_gene = $gene->transform('supercontig');
01092   Description: Moves this gene to the given coordinate system. If this gene has
01093                Transcripts attached, they move as well.
01094   Returntype : Bio::EnsEMBL::Gene
01095   Exceptions : throw on wrong parameters
01096   Caller     : general
01097   Status     : Stable
01098 
01099 =cut
01100 
01101 sub transform {
01102   my $self = shift;
01103 
01104   # catch for old style transform calls
01105   if( !@_  || ( ref $_[0] && ($_[0]->isa( "Bio::EnsEMBL::Slice" ) or $_[0]->isa( "Bio::EnsEMBL::LRGSlice" )) )) {
01106     deprecate('Calling transform without a coord system name is deprecated.');
01107     return $self->_deprecated_transform(@_);
01108   }
01109 
01110   my $new_gene = $self->SUPER::transform(@_);
01111 
01112   if ( !defined($new_gene) ) {
01113     # check if this gene projects at all to requested coord system,
01114     #  if not we are done.
01115     my @segments = @{ $self->project(@_) };
01116     if ( !@segments ) {
01117       return undef;
01118     }
01119   }
01120 
01121   #
01122   # If you are transforming the gene then make sure the transcripts and exons are loaded
01123   #
01124 
01125   foreach my $tran (@{$self->get_all_Transcripts}){
01126     $tran->get_all_Exons();
01127   }
01128 
01129   if( exists $self->{'_transcript_array'} ) {
01130     my @new_transcripts;
01131     my ( $strand, $slice );
01132     my $low_start = POSIX::INT_MAX;
01133     my $hi_end = POSIX::INT_MIN;
01134     for my $old_transcript ( @{$self->{'_transcript_array'}} ) {
01135       my $new_transcript = $old_transcript->transform( @_ );
01136       # this can fail if gene transform failed  
01137       
01138       return undef unless $new_transcript;
01139 
01140       if( ! defined $new_gene ) {
01141     if( $new_transcript->start() < $low_start ) {
01142       $low_start = $new_transcript->start();
01143     }
01144     if( $new_transcript->end() > $hi_end ) {
01145       $hi_end = $new_transcript->end();
01146     }
01147     $slice = $new_transcript->slice();
01148     $strand = $new_transcript->strand();
01149       }
01150       push( @new_transcripts, $new_transcript );
01151     }
01152 
01153     if( ! defined $new_gene ) {
01154       %$new_gene = %$self;
01155       bless $new_gene, ref( $self );
01156 
01157       $new_gene->start( $low_start );
01158       $new_gene->end( $hi_end );
01159       $new_gene->strand( $strand );
01160       $new_gene->slice( $slice );
01161     }
01162 
01163     $new_gene->{'_transcript_array'} = \@new_transcripts;
01164   }
01165   return $new_gene;
01166 }
01167 
01168 
01169 =head2 transfer
01170 
01171   Arg [1]    : Bio::EnsEMBL::Slice $destination_slice
01172   Example    : my $new_gene = $gene->transfer($slice);
01173   Description: Moves this Gene to given target slice coordinates. If Transcripts
01174                are attached they are moved as well. Returns a new gene.
01175   Returntype : Bio::EnsEMBL::Gene
01176   Exceptions : none
01177   Caller     : general
01178   Status     : Stable
01179 
01180 =cut
01181 
01182 sub transfer {
01183   my $self  = shift;
01184   
01185   my $new_gene = $self->SUPER::transfer( @_ );
01186   return undef unless $new_gene;
01187 
01188   if( exists $self->{'_transcript_array'} ) {
01189     my @new_transcripts;
01190     for my $old_transcript ( @{$self->{'_transcript_array'}} ) {
01191       my $new_transcript = $old_transcript->transfer( @_ );
01192       push( @new_transcripts, $new_transcript );
01193     }
01194     $new_gene->{'_transcript_array'} = \@new_transcripts;
01195   }
01196   return $new_gene;
01197 }
01198 
01199 
01200 =head2 display_xref
01201 
01202   Arg [1]    : (optional) Bio::EnsEMBL::DBEntry - the display xref to set
01203   Example    : $gene->display_xref($db_entry);
01204   Description: Getter/setter display_xref for this gene.
01205   Returntype : Bio::EnsEMBL::DBEntry
01206   Exceptions : none
01207   Caller     : general
01208   Status     : Stable
01209 
01210 =cut
01211 
01212 sub display_xref {
01213   my $self = shift;
01214   $self->{'display_xref'} = shift if(@_);
01215   return $self->{'display_xref'};
01216 }
01217 
01218 
01219 =head2 display_id
01220 
01221   Example    : print $gene->display_id();
01222   Description: This method returns a string that is considered to be
01223                the 'display' identifier. For genes this is (depending on
01224                availability and in this order) the stable Id, the dbID or an
01225                empty string.
01226   Returntype : String
01227   Exceptions : none
01228   Caller     : web drawing code
01229   Status     : Stable
01230 
01231 =cut
01232 
01233 sub display_id {
01234   my $self = shift;
01235   return $self->{'stable_id'} || $self->dbID || '';
01236 }
01237 
01238 
01239 =head2 recalculate_coordinates
01240 
01241   Example    : $gene->recalculate_coordinates;
01242   Description: Called when transcript added to the gene, tries to adapt the
01243                coords for the gene.
01244   Returntype : none
01245   Exceptions : none
01246   Caller     : internal
01247   Status     : Stable
01248 
01249 =cut
01250 
01251 sub recalculate_coordinates {
01252   my $self = shift;
01253 
01254   my $transcripts = $self->get_all_Transcripts();
01255 
01256   return if(!$transcripts || !@$transcripts);
01257 
01258   my ( $slice, $start, $end, $strand );
01259   $slice = $transcripts->[0]->slice();
01260   $strand = $transcripts->[0]->strand();
01261   $start = $transcripts->[0]->start();
01262   $end = $transcripts->[0]->end();
01263 
01264   my $transsplicing = 0;
01265 
01266   for my $t ( @$transcripts ) {
01267     if( $t->start() < $start ) {
01268       $start = $t->start();
01269     }
01270 
01271     if( $t->end() > $end ) {
01272       $end = $t->end();
01273     }
01274 
01275     if( $t->slice()->name() ne $slice->name() ) {
01276       throw( "Transcripts with different slices not allowed on one Gene" );
01277     }
01278 
01279     if( $t->strand() != $strand ) {
01280       $transsplicing = 1;
01281     }
01282   }
01283   if( $transsplicing ) {
01284     warning( "Gene contained trans splicing event" );
01285   }
01286 
01287   $self->start( $start );
01288   $self->end( $end );
01289   $self->strand( $strand );
01290   $self->slice( $slice );
01291 }
01292 
01293 
01294 =head2 get_all_DASFactories
01295 
01296   Example    : $dasref = $prot->get_all_DASFactories
01297   Description: Retrieves a listref of registered DAS objects
01298               TODO: Abstract to a DBLinkContainer obj
01299   Returntype : [ DAS_objects ]
01300   Exceptions : none
01301   Caller     : general
01302   Status     : Stable
01303 
01304 =cut
01305 
01306 sub get_all_DASFactories {
01307    my $self = shift;
01308    return [ $self->adaptor()->db()->_each_DASFeatureFactory ];
01309 }
01310 
01311 
01312 =head2 get_all_DAS_Features
01313 
01314   Example    : $features = $prot->get_all_DAS_Features;
01315   Description: Retreives a hash reference to a hash of DAS feature
01316                sets, keyed by the DNS, NOTE the values of this hash
01317                are an anonymous array containing:
01318                 (1) a pointer to an array of features
01319                 (2) a pointer to the DAS stylesheet
01320   Returntype : hashref of Bio::SeqFeatures
01321   Exceptions : none
01322   Caller     : webcode
01323   Status     : Stable
01324 
01325 =cut
01326 
01327 sub get_all_DAS_Features{
01328   my ($self, @args) = @_;
01329   my $slice = $self->feature_Slice;
01330   return $self->SUPER::get_all_DAS_Features($slice);
01331 }
01332 
01333 
01334 
01335 
01336 =head2 add_unconventional_transcript_association
01337 
01338   Arg [1]    : Bio::EnsEMBL::Transcript $trans
01339                The transcript to associate with the gene, in an unconventional manner.
01340   Arg [2]    : String $type
01341                The type of association between this gene and this transcript, e.g.
01342                "antisense","sense_intronic","sense_overlaping_exonic","chimeric_sense_exonic"
01343   Example    : my $transcript = Bio::EnsEMBL::Transcript->new(...);
01344                $gene->add_unconventional_transcript_association($transcript, "antisense");
01345   Description: Associate a transcript with this gene in a way that is
01346                non-conventional.
01347   Returntype : none
01348   Exceptions : none
01349   Caller     : general
01350   Status     : At Risk.
01351 
01352 =cut
01353 
01354 sub add_unconventional_transcript_association {
01355 
01356    my ($self, $transcript, $type) = @_;
01357 
01358    if( !ref $transcript || ! $transcript->isa("Bio::EnsEMBL::Transcript") ) {
01359        throw("$transcript is not a Bio::EnsEMBL::Transcript!");
01360    }
01361 
01362    my $uta = Bio::EnsEMBL::UnconventionalTranscriptAssociation->new($transcript, $self, $type);
01363    $self->{'_unconventional_transcript_array'} ||= [];
01364    push(@{$self->{'_unconventional_transcript_array'}}, $uta);
01365 
01366 }
01367 
01368 
01369 =head2 get_all_unconventional_transcript_associations
01370 
01371   Arg [1]    : (optional) String - Only get transcripts where the association
01372                between this gene and the transcripts is of a certain type.
01373   Example    : my @transcripts = @{ $gene->get_all_unconventional_transcript_associations, "antisense" };
01374   Description: Returns the unconventional transcripts associated with this gene.
01375   Returntype : Listref of Bio::EnsEMBL::UnconventionalTranscriptAssociation objects
01376   Exceptions : none
01377   Caller     : general
01378   Status     : At risk.
01379 
01380 =cut
01381 
01382 sub get_all_unconventional_transcript_associations {
01383 
01384   my ($self, $type) = @_;
01385 
01386   if( ! exists $self->{'_unconventional_transcript_array'} ) {
01387     $self->{'_unconventional_transcript_array'} = [];
01388     if( defined $self->adaptor() ) {
01389       my $utaa = $self->adaptor()->db()->get_UnconventionalTranscriptAssociationAdaptor();
01390       my $utas = $utaa->fetch_all_by_gene( $self, $type );
01391       $self->{'_unconventional_transcript_array'} = $utas;
01392     }
01393   }
01394 
01395   return $self->{'_unconventional_transcript_array'};
01396 }
01397 
01398 =head2 remove_unconventional_transcript_associations
01399 
01400   Args       : None
01401   Example    : $gene->remove_unconventional_transcript_associations();
01402   Description: Returns the unconventional transcripts associated with this gene.
01403   Returntype : Listref of Bio::EnsEMBL::UnconventionalTranscriptAssociation objects
01404   Exceptions : none
01405   Caller     : general
01406   Status     : At risk.
01407 
01408 =cut
01409 
01410 sub remove_unconventional_transcript_associations {
01411 
01412   my $self = shift;
01413 
01414   $self->{'_unconventional_transcript_array'} = [];
01415 
01416 }
01417 
01418 =head2 load
01419 
01420   Arg [1]       : Boolean $load_xrefs
01421                   Load (or don't load) xrefs.  Default is to load xrefs.
01422   Example       : $gene->load();
01423   Description   : The Ensembl API makes extensive use of
01424                   lazy-loading.  Under some circumstances (e.g.,
01425                   when copying genes between databases), all data of
01426                   an object needs to be fully loaded.  This method
01427                   loads the parts of the object that are usually
01428                   lazy-loaded.  It will also call the equivalent
01429                   method on all the transcripts of the gene.
01430   Returns       : 
01431 
01432 =cut
01433 
01434 sub load {
01435   my ( $self, $load_xrefs ) = @_;
01436 
01437   if ( !defined($load_xrefs) ) { $load_xrefs = 1 }
01438 
01439   foreach my $transcript ( @{ $self->get_all_Transcripts() } ) {
01440     $transcript->load($load_xrefs);
01441   }
01442 
01443   $self->analysis();
01444   $self->get_all_Attributes();
01445   $self->stable_id();
01446   $self->canonical_transcript();
01447 
01448   if ($load_xrefs) {
01449     $self->get_all_DBEntries();
01450   }
01451 }
01452 
01453 =head2 is_ref
01454 
01455   Description: getter setter for the gene attribute is_ref
01456   Arg [1]    : (optional) 1 or 0
01457   return     : boolean
01458 
01459 =cut
01460 
01461 sub is_reference{
01462   my ( $self, $is_ref) = @_;
01463 
01464   if(defined($is_ref)){
01465     $self->{'is_ref'} = $is_ref;
01466   }
01467   else{
01468     $self->{'is_ref'} = $self->adaptor->is_ref($self->dbID);
01469   } 
01470   return $self->{'is_ref'};
01471 }
01472 
01473 =head2 summary_as_hash
01474 
01475   Example       : $gene_summary = $gene->summary_as_hash();
01476   Description   : Extends Feature::summary_as_hash
01477                   Retrieves a summary of this Gene object.
01478                       
01479   Returns       : hashref of arrays of descriptive strings
01480   Status        : Intended for internal use
01481 =cut
01482 
01483 sub summary_as_hash {
01484   my $self = shift;
01485   my $summary_ref = $self->SUPER::summary_as_hash;
01486   $summary_ref->{'description'} = $self->description;
01487   $summary_ref->{'biotype'} = $self->biotype;
01488   $summary_ref->{'external_name'} = $self->external_name;
01489   return $summary_ref;
01490 }
01491 
01492 
01493 ###########################
01494 # DEPRECATED METHODS FOLLOW
01495 ###########################
01496 
01497 =head2 DEPRECATED add_DBLink
01498 
01499   Description: DEPRECATED This method has been deprecated in favour of the
01500                add_DBEntry method.  Objects are responible for holding only
01501                xrefs directly associated with themselves now.
01502 
01503 =cut
01504 
01505 
01506 sub add_DBLink{
01507   my ($self,$value) = @_;
01508 
01509   throw("add_DBLink is deprecated.  You probably want add_DBEntry.");
01510 
01511   #  unless(defined $value && ref $value 
01512   #  && $value->isa('Bio::Annotation::DBLink') ) {
01513   #    throw("This [$value] is not a DBLink");
01514   #  }
01515     
01516   #  if( !defined $self->{'_db_link'} ) {
01517   #    $self->{'_db_link'} = [];
01518   #  }
01519 
01520   #  push(@{$self->{'_db_link'}},$value);
01521 }
01522 
01523 
01524 =head2 temporary_id
01525 
01526  Function: DEPRECATED:  Use dbID or stable_id or something else instead
01527 
01528 =cut
01529 
01530 sub temporary_id {
01531    my ($obj,$value) = @_;
01532    deprecate( "I cant see what a temporary_id is good for, please use " .
01533                "dbID or stableID or\n try without an id." );
01534    if( defined $value) {
01535       $obj->{'temporary_id'} = $value;
01536     }
01537     return $obj->{'temporary_id'};
01538 }
01539 
01540 
01541 =head2 chr_name
01542 
01543   Description: DEPRECATED.  Use project, tranform, or transfer to obtain this
01544                gene in another coord system.  Use $gene->slice->seq_region_name
01545                to get the name of the underlying coord system. Or
01546                $gene->slice->name().
01547 
01548 =cut
01549 
01550 sub chr_name {
01551   my $self = shift;
01552 
01553   deprecate( "Use project() to obtain other coordinate systems" );
01554 
01555   my $gene_slice = $self->slice();
01556   if( $gene_slice->coord_system()->name eq "chromosome" ) {
01557     return $gene_slice->seq_region_name();
01558   }
01559 
01560   my $coords = $self->project( "toplevel" );
01561 
01562   if( @$coords ) {
01563     return $coords->[0]->[2]->seq_region_name();
01564   }
01565 }
01566 
01567 
01568 =head2 fetch_coded_for_regulatory_factors
01569 
01570   Arg [1]    : none
01571   Example    : $gene->fetch_coded_for_regualtory_factors()
01572   Description: DEPRECATED: Fetches any regulatory_factors that are coded for by
01573                this gene.
01574   Returntype : Listref of Bio::Ensembl::RegulatoryFactor
01575   Exceptions :
01576   Caller     : ?
01577   Status     : At Risk
01578              : under development
01579 
01580 =cut
01581 
01582 sub fetch_coded_for_regulatory_factors {
01583 
01584   my ($self) = @_;
01585 
01586   my $rfa = $self->adaptor->db->get_RegulatoryFactorAdaptor();
01587 
01588   return $rfa->fetch_factors_coded_for_by_gene($self);
01589 
01590 }
01591 
01592 
01593 =head2 type
01594 
01595   Description: DEPRECATED. Use biotype() instead.
01596 
01597 =cut
01598 
01599 sub type {
01600   deprecate("Use biotype() instead");
01601   biotype(@_);
01602 }
01603 
01604 
01605 =head2 confidence
01606 
01607   Description: DEPRECATED. Use status() instead.
01608 
01609 =cut
01610 
01611 sub confidence {
01612   deprecate("Use status() instead");
01613   status(@_);
01614 }
01615 
01616 
01617 1;
01618