Archive Ensembl HomeArchive Ensembl Home
Operon.pm
Go to the documentation of this file.
00001 
00002 =head1 LICENSE
00003 
00004   Copyright (c) 1999-2012 The European Bioinformatics Institute and
00005   Genome Research Limited.  All rights reserved.
00006 
00007   This software is distributed under a modified Apache license.
00008   For license details, please see
00009 
00010     http://www.ensembl.org/info/about/code_licence.html
00011 
00012 =head1 CONTACT
00013 
00014   Please email comments or questions to the public Ensembl
00015   developers list at <dev@ensembl.org>.
00016 
00017   Questions may also be sent to the Ensembl help desk at
00018   <helpdesk@ensembl.org>.
00019 
00020 =cut
00021 
00022 =head1 NAME
00023 
00024 Bio::EnsEMBL::Operon - Object representing an operon
00025 
00026 =head1 SYNOPSIS
00027 
00028   my $operon = Bio::EnsEMBL::Operon->new(
00029     -START  => 123,
00030     -END    => 1045,
00031     -STRAND => 1,
00032     -SLICE  => $slice,
00033     -DISPLAY_LABEL   => $name
00034   );
00035 
00036   # print operon information
00037   print("operon start:end:strand is "
00038       . join( ":", map { $operon->$_ } qw(start end strand) )
00039       . "\n" );
00040 
00041 =head1 DESCRIPTION
00042 
00043 A representation of an Operon within the Ensembl system. 
00044 An operon is a collection of one or more polycistronic transcripts which contain one or more genes.
00045 
00046 =head1 METHODS
00047 
00048 =cut
00049 
00050 package Bio::EnsEMBL::Operon;
00051 
00052 use strict;
00053 use warnings;
00054 
00055 use Bio::EnsEMBL::Feature;
00056 use Bio::EnsEMBL::Utils::Argument qw(rearrange);
00057 use Bio::EnsEMBL::Utils::Exception qw(throw warning deprecate);
00058 use Bio::EnsEMBL::Utils::Scalar qw(assert_ref);
00059 
00060 use vars qw(@ISA);
00061 @ISA = qw(Bio::EnsEMBL::Feature);
00062 
00063 =head2 new
00064 
00065   Arg [-START]  : 
00066        int - start postion of the operon
00067   Arg [-END]    : 
00068        int - end position of the operon
00069   Arg [-STRAND] : 
00070        int - 1,-1 the strand the operon is on
00071   Arg [-SLICE]  : 
00072        Bio::EnsEMBL::Slice - the slice the operon is on
00073   Arg [-STABLE_ID] :
00074         string - the stable identifier of this operon
00075   Arg [-VERSION] :
00076         int - the version of the stable identifier of this operon
00077   Arg [-DISPLAY_LABEL]:
00078         A name/label for this operon
00079   Arg [-CREATED_DATE]:
00080         string - the date the operon was created
00081   Arg [-MODIFIED_DATE]:
00082         string - the date the operon was last modified
00083 
00084   Example    : $gene = Bio::EnsEMBL::Operon->new(...);
00085   Description: Creates a new operon object
00086   Returntype : Bio::EnsEMBL::Operon
00087   Exceptions : none
00088   Caller     : general
00089   Status     : Stable
00090 
00091 =cut
00092 
00093 sub new {
00094     my $caller = shift;
00095 
00096     my $class = ref($caller) || $caller;
00097     my $self = $class->SUPER::new(@_);
00098     my ( $stable_id, $version, $created_date, $modified_date,$display_label) =
00099       rearrange( [  'STABLE_ID',    'VERSION',
00100                     'CREATED_DATE', 'MODIFIED_DATE',
00101                     'DISPLAY_LABEL' ],
00102                  @_ );
00103 
00104     $self->stable_id($stable_id);
00105     $self->version($version);
00106     $self->{'created_date'}  = $created_date;
00107     $self->{'modified_date'} = $modified_date;
00108     $self->display_label($display_label);
00109 
00110     return $self;
00111 }
00112 
00113 =head2 created_date
00114 
00115   Arg [1]    : (optional) String - created date to set (as a UNIX time int)
00116   Example    : $gene->created_date('1141948800');
00117   Description: Getter/setter for attribute created_date
00118   Returntype : String
00119   Exceptions : none
00120   Caller     : general
00121   Status     : Stable
00122 
00123 =cut
00124 
00125 sub created_date {
00126   my $self = shift;
00127   $self->{'created_date'} = shift if ( @_ );
00128   return $self->{'created_date'};
00129 }
00130 
00131 
00132 =head2 modified_date
00133 
00134   Arg [1]    : (optional) String - modified date to set (as a UNIX time int)
00135   Example    : $gene->modified_date('1141948800');
00136   Description: Getter/setter for attribute modified_date
00137   Returntype : String
00138   Exceptions : none
00139   Caller     : general
00140   Status     : Stable
00141 
00142 =cut
00143 
00144 sub modified_date {
00145   my $self = shift;
00146   $self->{'modified_date'} = shift if ( @_ );
00147   return $self->{'modified_date'};
00148 }
00149 
00150 
00151 =head2 display_label
00152 
00153   Arg [1]    : (optional) String - the name/label to set
00154   Example    : $operon->name('accBCD');
00155   Description: Getter/setter for attribute name.
00156   Returntype : String or undef
00157   Exceptions : none
00158   Caller     : general
00159   Status     : Stable
00160 
00161 =cut
00162 
00163 sub display_label {
00164     my $self = shift;
00165     $self->{'display_label'} = shift if (@_);
00166     return $self->{'display_label'};
00167 }
00168 
00169 =head2 stable_id
00170 
00171   Arg [1]    : (optional) String - the stable ID to set
00172   Example    : $operon->stable_id("accR2");
00173   Description: Getter/setter for stable id for this operon.
00174   Returntype : String
00175   Exceptions : none
00176   Caller     : general
00177   Status     : Stable
00178 
00179 =cut
00180 
00181 sub stable_id {
00182     my $self = shift;
00183     $self->{'stable_id'} = shift if (@_);
00184     return $self->{'stable_id'};
00185 }
00186 
00187 =head2 version
00188 
00189   Arg [1]    : (optional) Int - the stable ID version to set
00190   Example    : $operon->version(1);
00191   Description: Getter/setter for stable id version for this operon.
00192   Returntype : Int
00193   Exceptions : none
00194   Caller     : general
00195   Status     : Stable
00196 
00197 =cut
00198 sub version {
00199   my $self = shift;
00200   $self->{'version'} = shift if(@_);
00201   return $self->{'version'};
00202 }
00203 
00204 =head2 get_all_OperonTranscripts
00205 
00206   Example    : my $ots = $operon->get_all_OperonTranscripts();
00207   Description: Retrieve all operon transcripts belonging to this operon
00208   Returntype : Arrayref of Bio::EnsEMBL::OperonTranscript
00209   Exceptions : none
00210   Caller     : general
00211   Status     : Stable
00212 
00213 =cut
00214 sub get_all_OperonTranscripts {
00215     my $self = shift;
00216     if ( !exists $self->{'_operon_transcript_array'} ) {
00217         if ( defined $self->adaptor() ) {
00218             my $ta = $self->adaptor()->db()->get_OperonTranscriptAdaptor();
00219             my $transcripts = $ta->fetch_all_by_Operon($self);
00220             $self->{'_operon_transcript_array'} = $transcripts;
00221         }
00222     }
00223     return $self->{'_operon_transcript_array'};
00224 }
00225 
00226 =head2 add_OperonTranscript
00227 
00228   Arg [1]    : Bio::EnsEMBL::OperonTranscript - operon transcript to attach to this operon
00229   Example    : $operon->add_OperonTranscript($ot);
00230   Description: Attach a polycistronic operon transcript to this operon
00231   Exceptions : if argument is not Bio::EnsEMBL::OperonTranscript
00232   Caller     : general
00233   Status     : Stable
00234 
00235 =cut
00236 sub add_OperonTranscript {
00237     my ( $self, $trans ) = @_;
00238 
00239     assert_ref($trans,"Bio::EnsEMBL::OperonTranscript");
00240 
00241     $self->{'_operon_transcript_array'} ||= [];
00242     push( @{ $self->{'_operon_transcript_array'} }, $trans );
00243 
00244     #$self->recalculate_coordinates();
00245     return;
00246 }
00247 
00248 =head2 add_DBEntry
00249 
00250   Arg [1]    : Bio::EnsEMBL::DBEntry $dbe
00251                The dbEntry to be added
00252   Example    : my $dbe = Bio::EnsEMBL::DBEntery->new(...);
00253                $operon->add_DBEntry($dbe);
00254   Description: Associates a DBEntry with this operon. Note that adding DBEntries
00255                will prevent future lazy-loading of DBEntries for this operon
00256                (see get_all_DBEntries).
00257   Returntype : none
00258   Exceptions : thrown on incorrect argument type
00259   Caller     : general
00260   Status     : Stable
00261 
00262 =cut
00263 
00264 sub add_DBEntry {
00265   my $self = shift;
00266   my $dbe = shift;
00267 
00268   unless($dbe && ref($dbe) && $dbe->isa('Bio::EnsEMBL::DBEntry')) {
00269     throw('Expected DBEntry argument');
00270   }
00271 
00272   $self->{'dbentries'} ||= [];
00273   push @{$self->{'dbentries'}}, $dbe;
00274 }
00275 
00276 
00277 =head2 get_all_Attributes
00278 
00279   Arg [1]    : (optional) String $attrib_code
00280                The code of the attribute type to retrieve values for
00281   Example    : my ($author) = @{ $operon->get_all_Attributes('author') };
00282                my @operon_attributes = @{ $operon->get_all_Attributes };
00283   Description: Gets a list of Attributes of this operon.
00284                Optionally just get Attributes for given code.
00285   Returntype : Listref of Bio::EnsEMBL::Attribute
00286   Exceptions : warning if gene does not have attached adaptor and attempts lazy
00287                load.
00288   Caller     : general
00289   Status     : Stable
00290 
00291 =cut
00292 
00293 sub get_all_Attributes {
00294     my $self        = shift;
00295     my $attrib_code = shift;
00296 
00297     if ( !exists $self->{'attributes'} ) {
00298         if ( !$self->adaptor() ) {
00299             return [];
00300         }
00301 
00302         my $attribute_adaptor = $self->adaptor->db->get_AttributeAdaptor();
00303         $self->{'attributes'} = $attribute_adaptor->fetch_all_by_Operon($self);
00304     }
00305 
00306     if ( defined $attrib_code ) {
00307         my @results =
00308           grep { uc( $_->code() ) eq uc($attrib_code) }
00309           @{ $self->{'attributes'} };
00310         return \@results;
00311     } else {
00312         return $self->{'attributes'};
00313     }
00314 }
00315 
00316 =head2 get_all_DBEntries
00317 
00318   Arg [1]    : (optional) String, external database name
00319 
00320   Arg [2]    : (optional) String, external_db type
00321 
00322   Example    : @dbentries = @{ $gene->get_all_DBEntries() };
00323 
00324   Description: Retrieves DBEntries (xrefs) for this operon.  This does
00325                *not* include DBEntries that are associated with the
00326                transcripts and corresponding translations of this
00327                gene (see get_all_DBLinks()).
00328 
00329                This method will attempt to lazy-load DBEntries
00330                from a database if an adaptor is available and no
00331                DBEntries are present on the gene (i.e. they have not
00332                already been added or loaded).
00333 
00334   Return type: Listref of Bio::EnsEMBL::DBEntry objects
00335   Exceptions : none
00336   Caller     : get_all_DBLinks, OperonAdaptor::store
00337   Status     : Stable
00338 
00339 =cut
00340 
00341 sub get_all_DBEntries {
00342     my ( $self, $db_name_exp, $ex_db_type ) = @_;
00343 
00344     my $cache_name = 'dbentries';
00345 
00346     if ( defined($db_name_exp) ) {
00347         $cache_name .= $db_name_exp;
00348     }
00349 
00350     if ( defined($ex_db_type) ) {
00351         $cache_name .= $ex_db_type;
00352     }
00353 
00354     # if not cached, retrieve all of the xrefs for this gene
00355     if ( !defined( $self->{$cache_name} ) && defined( $self->adaptor() ) ) {
00356         $self->{$cache_name} =
00357           $self->adaptor()->db()->get_DBEntryAdaptor()
00358           ->fetch_all_by_Operon( $self, $db_name_exp, $ex_db_type );
00359     }
00360 
00361     $self->{$cache_name} ||= [];
00362 
00363     return $self->{$cache_name};
00364 }
00365 
00366 1;
00367