Archive Ensembl HomeArchive Ensembl Home
DnaFrag.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 =head1 NAME
00020 
00021 Bio::EnsEMBL::Compara::DnaFrag - Defines the DNA sequences used in the database.
00022 
00023 =head1 SYNOPSIS
00024 
00025   use Bio::EnsEMBL::Compara::DnaFrag; 
00026   my $dnafrag = new Bio::EnsEMBL::Compara::DnaFrag(
00027           -dbID => 1,
00028           -adaptor => $dnafrag_adaptor,
00029           -length => 256,
00030           -name => "19",
00031           -genome_db => $genome_db,
00032           -coord_system_name => "chromosome"
00033         );
00034 
00035 
00036 SET VALUES
00037   $dnafrag->dbID(1);
00038   $dnafrag->adaptor($dnafrag_adaptor);
00039   $dnafrag->length(256);
00040   $dnafrag->genome_db($genome_db);
00041   $dnafrag->genome_db_id(123);
00042   $dnafrag->coord_system_name("chromosome");
00043   $dnafrag->name("19");
00044 
00045 GET VALUES
00046   $dbID = $dnafrag->dbID;
00047   $dnafrag_adaptor = $dnafrag->adaptor;
00048   $length = $dnafrag->length;
00049   $genome_db = $dnafrag->genome_db;
00050   $genome_db_id = $dnafrag->genome_db_id;
00051   $coord_system_name = $dnafrag->coord_system_name;
00052   $name = $dnafrag->name;
00053 
00054 =head1 DESCRIPTION
00055 The DnaFrag object stores information on the toplevel sequences such as the name, coordinate system, length and species.
00056 
00057 =head1 OBJECT ATTRIBUTES
00058 
00059 =over
00060 
00061 =item dbID
00062 
00063 corresponds to dnafrag.dnafrag_id
00064 
00065 =item adaptor
00066 
00067 Bio::EnsEMBL::Compara::DBSQL::DnaFragAdaptor object to access DB
00068 
00069 =item length
00070 
00071 corresponds to dnafrag.length
00072 
00073 =item genome_db_id
00074 
00075 corresponds to dnafrag.genome_db_id
00076 
00077 =item genome_db
00078 
00079 Bio::EnsEMBL::Compara::GenomeDB object corresponding to genome_db_id
00080 
00081 =item coord_system_name
00082 
00083 corresponds to dnafrag.coord_system_name
00084 
00085 =item name
00086 
00087 corresponds to dnafrag.name
00088 
00089 =back
00090 
00091 =head1 APPENDIX
00092 
00093 The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _
00094 
00095 =cut
00096 
00097 
00098 # Let the code begin...
00099 
00100 
00101 package Bio::EnsEMBL::Compara::DnaFrag;
00102 
00103 use strict;
00104 use Bio::EnsEMBL::Utils::Exception qw(deprecate throw);
00105 use Bio::EnsEMBL::Utils::Argument;
00106 
00107 =head2 new
00108 
00109   Arg [-DBID] : (opt.) int $dbID (the database internal ID for this object)
00110   Arg [-ADAPTOR]
00111               : (opt.) Bio::EnsEMBL::Compara::DBSQL::DnaFragAdaptor $adaptor
00112                 (the adaptor for connecting to the database)
00113   Arg [-LENGTH]:(opt.) int $length (the length of this dnafrag)
00114   Arg [-NAME]:  (opt.) string $name (the name of this dnafrag)
00115   Arg [-GENOME_DB]
00116                :(opt.) Bio::EnsEMBL::Compara::GenomeDB $genome_db (the 
00117                 genome_db object representing the species of this dnafrag)
00118   Arg [-GENOME_DB_ID]
00119                :(opt.) int $genome_db_id (the database internal for the 
00120                  genome_db)
00121   Arg [-COORD_SYSTEM_NAME]
00122                :(opt.) string $coord_system_name (the name of the toplevel
00123                  coordinate system of the dnafrag eg 'chromosome', 'scaffold')
00124   Example : my $dnafrag = new Bio::EnsEMBL::Compara::DnaFrag(
00125                       -length 247249719,
00126                       -name "1",
00127                       -genome_db $genome_db,
00128                       -coord_system_name "chromosome");
00129   Example : my $dnafrag = new Bio::EnsEMBL::Compara::DnaFrag(
00130                       -length 247249719,
00131                       -name "1",
00132                       -genome_db_id 22,
00133                       -coord_system_name "chromosome");
00134   Description: Creates a new DnaFrag object
00135   Returntype : Bio::EnsEMBL::Compara::DnaFrag
00136   Exceptions : none
00137   Caller     : general
00138   Status     : Stable
00139 
00140 =cut
00141 
00142 
00143 sub new {
00144   my($class,@args) = @_;
00145 
00146   my $self = {};
00147 
00148   bless $self,$class;
00149 
00150 #   my ($name,$contig,$genomedb,$type,$adaptor,$dbID) =
00151 #     rearrange([qw(NAME CONTIG GENOMEDB TYPE ADAPTOR DBID)],@args);
00152 #    if ( defined $contig) {
00153 #      $self->contig($contig);
00154 #    }
00155 
00156   my ($dbID, $adaptor, $length, $name, $genome_db, $genome_db_id, $coord_system_name, $is_reference,
00157           $start, $end, $genomedb, $type
00158       ) =
00159     rearrange([qw(DBID ADAPTOR LENGTH NAME GENOME_DB GENOME_DB_ID COORD_SYSTEM_NAME IS_REFERENCE
00160             START END
00161         )],@args);
00162 
00163   $self->dbID($dbID) if (defined($dbID));
00164   $self->adaptor($adaptor) if (defined($adaptor));
00165   $self->length($length) if (defined($length));
00166   $self->name($name) if (defined($name));
00167   $self->genome_db($genome_db) if (defined($genome_db));
00168   $self->genome_db_id($genome_db_id) if (defined($genome_db_id));
00169   $self->coord_system_name($coord_system_name) if (defined($coord_system_name));
00170   $self->is_reference($is_reference) if (defined($is_reference));
00171 
00172   ###################################################################
00173   ## Support for backwards compatibility
00174   $self->start($start) if (defined($start));
00175   $self->end($end) if (defined($end));
00176   ##
00177   ###################################################################
00178 
00179   return $self;
00180 }
00181 
00182 =head2 new_fast
00183 
00184   Arg [1]    : hash reference $hashref
00185   Example    : none
00186   Description: This is an ultra fast constructor which requires knowledge of
00187                the objects internals to be used.
00188   Returntype :
00189   Exceptions : none
00190   Caller     :
00191   Status     : Stable
00192 
00193 =cut
00194 
00195 sub new_fast {
00196   my $class = shift;
00197   my $hashref = shift;
00198 
00199   return bless $hashref, $class;
00200 }
00201 
00202 =head2 dbID
00203 
00204  Arg [1]   : int $dbID
00205  Example   : $dbID = $dnafrag->dbID()
00206  Example   : $dnafrag->dbID(1)
00207  Function  : get/set dbID attribute.
00208  Returns   : integer
00209  Exeption  : none
00210  Caller    : $object->dbID
00211  Status    : Stable
00212 
00213 =cut
00214 
00215 sub dbID {
00216   my ($self, $dbID) = @_;
00217    
00218   if (defined($dbID)) {
00219     $self->{'dbID'} = $dbID;
00220   }
00221 
00222   return $self->{'dbID'};
00223 }
00224 
00225 
00226 =head2 adaptor
00227 
00228  Arg [1]   : Bio::EnsEMBL::Compara::DBSQL::DnaFragAdaptor $dnafrag_adaptor
00229  Example   : $dnafrag_adaptor = $dnafrag->adaptor()
00230  Example   : $dnafrag->adaptor($dnafrag_adaptor)
00231  Function  : get/set adaptor attribute.
00232  Returns   : Bio::EnsEMBL::Compara::DBSQL::DnaFragAdaptor object
00233  Exeption  : thrown if argument is not a Bio::EnsEMBL::Compara::DBSQL::DnaFragAdaptor
00234              object
00235  Caller    : $object->adaptor
00236  Status    : Stable
00237 
00238 =cut
00239 
00240 sub adaptor {
00241   my ($self, $adaptor) = @_;
00242    
00243   if (defined($adaptor)) {
00244     throw("[$adaptor] must be a Bio::EnsEMBL::Compara::DBSQL::DnaFragAdaptor object")
00245       unless ($adaptor->isa("Bio::EnsEMBL::Compara::DBSQL::DnaFragAdaptor"));
00246     $self->{'adaptor'} = $adaptor;
00247   }
00248 
00249   return $self->{'adaptor'};
00250 }
00251 
00252 
00253 =head2 length
00254 
00255  Arg [1]   : int $length
00256  Example   : $length = $dnafrag->length()
00257  Example   : $dnafrag->length(256)
00258  Function  : get/set length attribute. Use 0 as argument to reset this attribute.
00259  Returns   : integer
00260  Exeption  : none
00261  Caller    : $object->length
00262  Status    : Stable
00263 
00264 =cut
00265 
00266 sub length {
00267   my ($self, $length) = @_;
00268    
00269   if (defined($length)) {
00270     $self->{'length'} = ($length or undef);
00271   }
00272 
00273   return $self->{'length'};
00274 }
00275 
00276 
00277 =head2 name
00278 
00279  Arg [1]   : string $name
00280  Example   : $name = $dnafrag->name()
00281  Example   : $dnafrag->name("19")
00282  Function  : get/set name attribute. Use "" as argument to reset this attribute.
00283  Returns   : string
00284  Exeption  : none
00285  Caller    : $object->name
00286  Status    : Stable
00287 
00288 =cut
00289 
00290 sub name {
00291   my ($self, $name) = @_;
00292    
00293   if (defined($name)) {
00294     $self->{'name'} = ($name or undef);
00295   }
00296 
00297   return $self->{'name'};
00298 }
00299 
00300 
00301 =head2 genome_db
00302 
00303  Arg [1]   : Bio::EnsEMBL::Compara::GenomeDB $genome_db
00304  Example   : $genome_db = $dnafrag->genome_db()
00305  Example   : $dnafrag->genome_db($genome_db)
00306  Function  : get/set genome_db attribute. If no argument is given and the genome_db
00307              is not defined, it tries to get the data from other sources like the
00308              database using the genome_db_id.
00309  Returns   : Bio::EnsEMBL::Compara::GenomeDB object
00310  Exeption  : thrown if argument is not a Bio::EnsEMBL::Compara::GenomeDB
00311              object
00312  Caller    : $object->genome_db
00313  Status    : Stable
00314 
00315 =cut
00316 
00317 sub genome_db {
00318   my ($self, $genome_db) = @_;
00319    
00320   if (defined($genome_db)) {
00321     throw("[$genome_db] must be a Bio::EnsEMBL::Compara::GenomeDB object")
00322       unless ($genome_db and $genome_db->isa("Bio::EnsEMBL::Compara::GenomeDB"));
00323     if ($genome_db->dbID and defined($self->genome_db_id)) {
00324       throw("dbID of genome_db object does not match previously defined".
00325             " genome_db_id. If you want to override this".
00326             " Bio::EnsEMBL::Compara::GenomeDB object, you can reset the ".
00327             "genome_db_id using \$dnafrag->genome_db_id(0)")
00328           unless ($genome_db->dbID == $self->genome_db_id);
00329     }
00330     $self->{'genome_db'} = $genome_db;
00331   
00332   } elsif (!defined($self->{'genome_db'})) {
00333     # Try to get data from other sources
00334     if (defined($self->{'genome_db_id'}) and defined($self->{'adaptor'})) {
00335       $self->{'genome_db'} =
00336           $self->{'adaptor'}->db->get_GenomeDBAdaptor->fetch_by_dbID($self->{'genome_db_id'});
00337     }
00338   }
00339 
00340   return $self->{'genome_db'};
00341 }
00342 
00343 
00344 =head2 genome_db_id
00345 
00346  Arg [1]   : int $genome_db_id
00347  Example   : $genome_db_id = $dnafrag->genome_db_id()
00348  Example   : $dnafrag->genome_db_id(123)
00349  Function  : get/set genome_db_id attribute. If no argument is given and the genome_db_id
00350              is not defined, it tries to get the data from other sources like the
00351              corresponding Bio::EnsEMBL::Compara::GenomeDB object. Use 0 as argument to
00352              clear this attribute.
00353  Returns   : integer
00354  Exeption  : none
00355  Caller    : $object->genome_db_id
00356  Status    : Stable
00357 
00358 =cut
00359 
00360 sub genome_db_id {
00361   my ($self, $genome_db_id) = @_;
00362    
00363   if (defined($genome_db_id)) {
00364     if (defined($self->genome_db) and $genome_db_id) {
00365       if (defined($self->genome_db->dbID)) {
00366         throw("genome_db_id does not match previously defined".
00367               " dbID of genome_db object.")
00368             unless ($genome_db_id == $self->genome_db->dbID);
00369       } else {
00370         $self->genome_db->dbID($genome_db_id);
00371       }
00372     }
00373     $self->{'genome_db_id'} = ($genome_db_id or undef);
00374   
00375   } elsif (!defined($self->{'genome_db_id'})) {
00376     # Try to get data from other sources
00377     if (defined($self->{'genome_db'})) {
00378       # From the dbID of the corresponding Bio::EnsEMBL::Compara::GenomeDB object
00379       $self->{'genome_db_id'} = $self->{'genome_db'}->dbID;
00380     }
00381   }
00382 
00383   return $self->{'genome_db_id'};
00384 }
00385 
00386 
00387 =head2 coord_system_name
00388 
00389  Arg [1]   : string $coord_system_name
00390  Example   : $coord_system_name = $dnafrag->coord_system_name()
00391  Example   : $dnafrag->coord_system_name("chromosome")
00392  Function  : get/set coord_system_name attribute. Use "" or 0 as argument to
00393              clear this attribute.
00394  Returns   : string
00395  Exeption  : none
00396  Caller    : $object->coord_system_name
00397  Status    : Stable
00398 
00399 =cut
00400 
00401 sub coord_system_name {
00402   my ($self, $coord_system_name) = @_;
00403 
00404   if (defined($coord_system_name)) {
00405     $self->{'coord_system_name'} = ($coord_system_name or undef);
00406   }
00407 
00408   return $self->{'coord_system_name'};
00409 }
00410 
00411 
00412 =head2 is_reference
00413 
00414  Arg [1]   : bool $is_reference
00415  Example   : $is_reference = $dnafrag->is_reference()
00416  Example   : $dnafrag->is_reference(1)
00417  Function  : get/set is_reference attribute. The default value
00418              is 1 (TRUE).
00419  Returns   : bool
00420  Exeption  : none
00421  Caller    : $object->is_reference
00422  Status    : Stable
00423 
00424 =cut
00425 
00426 sub is_reference {
00427   my ($self, $is_reference) = @_;
00428 
00429   if (defined($is_reference)) {
00430     $self->{'is_reference'} = $is_reference;
00431   }
00432   if (!defined($self->{'is_reference'})) {
00433     $self->{'is_reference'} = 1;
00434   }
00435 
00436   return $self->{'is_reference'};
00437 }
00438 
00439 
00440 =head2 slice
00441 
00442  Arg 1      : -none-
00443  Example    : $slice = $dnafrag->slice;
00444  Description: Returns the Bio::EnsEMBL::Slice object corresponding to this
00445               Bio::EnsEMBL::Compara::DnaFrag object.
00446  Returntype : Bio::EnsEMBL::Slice object
00447  Exceptions : warns when the corresponding Bio::EnsEMBL::Compara::GenomeDB,
00448               coord_system_name, name or Bio::EnsEMBL::DBSQL::DBAdaptor
00449               cannot be retrieved and returns undef.
00450  Caller     : $object->methodname
00451  Status     : Stable
00452 
00453 =cut
00454 
00455 sub slice {
00456   my ($self) = @_;
00457   
00458   unless (defined $self->{'_slice'}) {
00459     if (!defined($self->genome_db)) {
00460       warn "Cannot get the Bio::EnsEMBL::Compara::GenomeDB object corresponding to [".$self."]";
00461       return undef;
00462     }
00463     if (!defined($self->coord_system_name)) {
00464       warn "Cannot get the coord_system_name corresponding to [".$self."]";
00465       return undef;
00466     }
00467     if (!defined($self->name)) {
00468       warn "Cannot get the name corresponding to [".$self."]";
00469       return undef;
00470     }
00471     my $dba = $self->genome_db->db_adaptor;
00472     if (!defined($dba)) {
00473       warn "Cannot get the Bio::EnsEMBL::DBSQL::DBAdaptor corresponding to [".$self->genome_db->name."]";
00474       return undef;
00475     }
00476 
00477     $self->{'_slice'} = $dba->get_SliceAdaptor->fetch_by_region($self->coord_system_name, $self->name);
00478   }
00479 
00480   return $self->{'_slice'};
00481 }
00482 
00483 
00484 =head2 display_id
00485 
00486   Args       : none
00487   Example    : my $id = $dnafrag->display_id;
00488   Description: returns string describing this chunk which can be used
00489                as display_id of a Bio::Seq object or in a fasta file.
00490                Uses dnafrag information in addition to start and end.
00491   Returntype : string
00492   Exceptions : none
00493   Caller     : general
00494   Status     : Stable
00495 
00496 =cut
00497 
00498 sub display_id {
00499   my $self = shift;
00500 
00501   return "" unless($self->genome_db);
00502   my $id = $self->genome_db->taxon_id. ".".
00503            $self->genome_db->dbID. ":".
00504            $self->coord_system_name.":".
00505            $self->name;
00506   return $id;
00507 }
00508 
00509 
00510 #####################################################################
00511 #####################################################################
00512 
00513 =head1 DEPRECATED METHODS
00514 
00515 Bio::EnsEMBL::Compara::DnaFrag::start and Bio::EnsEMBL::Compara::DnaFrag::end
00516 methods are no longer used. All Bio::EnsEMBL::Compara::DnaFrag objects start
00517 in 1. Start and end coordinates have been replaced by length attribute. Please,
00518 use Bio::EnsEMBL::Compara::DnaFrag::length method to access it.
00519 
00520 Bio::EnsEMBL::Compara::DnaFrag::genomedb has been renamed
00521 Bio::EnsEMBL::Compara::DnaFrag::genome_db.
00522 
00523 Bio::EnsEMBL::Compara::DnaFrag::type has been renamed
00524 Bio::EnsEMBL::Compara::DnaFrag::coord_system_name.
00525 
00526 =cut
00527 
00528 #####################################################################
00529 #####################################################################
00530 
00531 
00532 
00533 
00534 =head2 start [DEPRECATED]
00535  
00536   DEPRECATED! All Bio::EnsEMBL::Compara::DnaFrag objects start in 1
00537   
00538   Arg [1]    : int
00539   Example    : $dnafrag->start(1);
00540   Description: Getter/Setter for the start attribute
00541   Returntype : int
00542   Exceptions : thrown when trying to set a starting position different from 1
00543   Caller     : general
00544 
00545 =cut
00546  
00547 sub start {
00548   my ($self,$value) = @_;
00549 
00550   deprecate("All Bio::EnsEMBL::Compara::DnaFrag objects start in 1");
00551   if (defined($value) and ($value != 1)) {
00552     throw("Trying to set a start value different from 1!\n".
00553         "All Bio::EnsEMBL::Compara::DnaFrag objects start in 1");
00554   }
00555 
00556   return 1;
00557 }
00558 
00559 
00560 
00561 =head2 end [DEPRECATED]
00562  
00563   DEPRECATED! Use Bio::EnsEMBL::Compara::DnaFrag->length() method instead
00564 
00565   Arg [1]    : int $end
00566   Example    : $dnafrag->end(42);
00567   Description: Getter/Setter for the start attribute
00568   Returntype : int
00569   Exceptions : none
00570   Caller     : general
00571  
00572 =cut
00573 
00574 sub end {
00575   my ($self, $end) = @_;
00576   deprecate("Use Bio::EnsEMBL::Compara::DnaFrag->length() method instead");
00577 
00578   return $self->length($end);
00579 }
00580 
00581 
00582 1;
00583 
00584