Archive Ensembl HomeArchive Ensembl Home
CoordSystem.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::CoordSystem
00024 
00025 =head1 SYNOPSIS
00026 
00027   my $db = Bio::EnsEMBL::DBSQL::DBAdaptor->new(...);
00028 
00029   my $csa = $db->get_CoordSystemAdaptor();
00030 
00031   #
00032   # Get all coord systems in the database:
00033   #
00034   foreach my $cs ( @{ $csa->fetch_all() } ) {
00035     my $str = join ':', $cs->name(), $cs->version(), $cs->dbID();
00036     print "$str\n";
00037   }
00038 
00039 =head1 DESCRIPTION
00040 
00041 This is a simple object which contains a few coordinate system attributes:
00042 name, internal identifier, version.  A coordinate system is uniquely defined
00043 by its name and version.  A version of a coordinate system applies to all
00044 sequences within a coordinate system.  This should not be confused with
00045 individual sequence versions.
00046 
00047 Take for example the Human assembly.  The version 'NCBI33' applies to
00048 to all chromosomes in the NCBI33 assembly (that is the entire 'chromosome'
00049 coordinate system).  The 'clone' coordinate system in the same database would
00050 have no version however.  Although the clone sequences have their own sequence
00051 versions, there is no version which applies to the entire set of clones.
00052 
00053 Coordinate system objects are immutable. Their name and version, and other
00054 attributes may not be altered after they are created.
00055 
00056 =head1 METHODS
00057 
00058 =cut
00059 
00060 
00061 use strict;
00062 use warnings;
00063 
00064 package Bio::EnsEMBL::CoordSystem;
00065 
00066 use Bio::EnsEMBL::Storable;
00067 
00068 use Bio::EnsEMBL::Utils::Argument  qw(rearrange);
00069 use Bio::EnsEMBL::Utils::Exception qw(throw);
00070 
00071 use vars qw(@ISA);
00072 
00073 @ISA = qw(Bio::EnsEMBL::Storable);
00074 
00075 
00076 =head2 new
00077 
00078   Arg [..]   : List of named arguments:
00079                -NAME      - The name of the coordinate system
00080                -VERSION   - (optional) The version of the coordinate system.
00081                             Note that if the version passed in is undefined,
00082                             it will be set to the empty string in the
00083                             resulting CoordSystem object.
00084                -RANK      - The rank of the coordinate system. The highest
00085                             level coordinate system should have rank 1, the
00086                             second highest rank 2 and so on.  An example of
00087                             a high level coordinate system is 'chromosome' an
00088                             example of a lower level coordinate system is
00089                             'clone'.
00090                -TOP_LEVEL - (optional) Sets whether this is a top-level coord
00091                             system. Default = 0. This should only be set to
00092                             true if you are creating an artificial toplevel
00093                             coordsystem by the name of 'toplevel'
00094                -SEQUENCE_LEVEL - (optional) Sets whether this is a sequence
00095                             level coordinate system. Default = 0
00096                -DEFAULT   - (optional)
00097                             Whether this is the default version of the 
00098                             coordinate systems of this name. Default = 0
00099                -DBID      - (optional) The internal identifier of this
00100                              coordinate system
00101                -ADAPTOR   - (optional) The adaptor which provides database
00102                             interaction for this object
00103   Example    : $cs = Bio::EnsEMBL::CoordSystem->new(-NAME    => 'chromosome',
00104                                                     -VERSION => 'NCBI33',
00105                                                     -RANK    => 1,
00106                                                     -DBID    => 1,
00107                                                     -ADAPTOR => adaptor,
00108                                                     -DEFAULT => 1,
00109                                                     -SEQUENCE_LEVEL => 0);
00110   Description: Creates a new CoordSystem object representing a coordinate
00111                system.
00112   Returntype : Bio::EnsEMBL::CoordSystem
00113   Exceptions : none
00114   Caller     : general
00115   Status     : Stable
00116 
00117 =cut
00118 
00119 sub new {
00120   my $caller = shift;
00121   my $class = ref($caller) || $caller;
00122 
00123   my $self = $class->SUPER::new(@_);
00124 
00125   my ( $name, $version, $top_level, $sequence_level, $default, $rank ) =
00126     rearrange( [ 'NAME',      'VERSION',
00127                  'TOP_LEVEL', 'SEQUENCE_LEVEL',
00128                  'DEFAULT',   'RANK' ],
00129                @_ );
00130 
00131   $version = '' if ( !defined($version) );
00132 
00133   $top_level      = ($top_level)      ? 1 : 0;
00134   $sequence_level = ($sequence_level) ? 1 : 0;
00135   $default        = ($default)        ? 1 : 0;
00136   $rank ||= 0;
00137 
00138   if ( $top_level == 1 ) {
00139     if ( $rank != 0 ) {
00140       throw('RANK argument must be 0 if TOP_LEVEL is 1');
00141     }
00142 
00143     if ( defined($name) ) {
00144       if ( $name ne 'toplevel' ) {
00145         throw('The NAME argument must be "toplevel" if TOP_LEVEL is 1');
00146       }
00147     } else {
00148       $name = 'toplevel';
00149     }
00150 
00151     if ( $sequence_level == 1 ) {
00152       throw("SEQUENCE_LEVEL argument must be 0 if TOP_LEVEL is 1");
00153     }
00154 
00155     $default = 0;
00156 
00157   } else {
00158 
00159     if ( $rank == 0 ) {
00160       throw("RANK argument must be non-zero unless TOP_LEVEL is 1");
00161     }
00162 
00163     if ( !defined($name) ) {
00164       throw('The NAME argument is required');
00165     } elsif ( $name eq 'toplevel' ) {
00166       throw(   "Cannot name coord system 'toplevel' "
00167              . "unless TOP_LEVEL is 1" );
00168     }
00169 
00170   }
00171 
00172   if ( $rank !~ /^\d+$/ ) {
00173     throw('The RANK argument must be a positive integer');
00174   }
00175 
00176   $self->{'version'}        = $version;
00177   $self->{'name'}           = $name;
00178   $self->{'top_level'}      = $top_level;
00179   $self->{'sequence_level'} = $sequence_level;
00180   $self->{'default'}        = $default;
00181   $self->{'rank'}           = $rank;
00182 
00183   return $self;
00184 } ## end sub new
00185 
00186 
00187 =head2 name
00188 
00189   Arg [1]    : (optional) string $name
00190   Example    : print $coord_system->name();
00191   Description: Getter for the name of this coordinate system
00192   Returntype : string
00193   Exceptions : none
00194   Caller     : general
00195   Status     : Stable
00196 
00197 =cut
00198 
00199 sub name {
00200   my $self = shift;
00201   return $self->{'name'};
00202 }
00203 
00204 
00205 
00206 =head2 version
00207 
00208   Arg [1]    : none
00209   Example    : print $coord->version();
00210   Description: Getter for the version of this coordinate system.  This
00211                will return an empty string if no version is defined for this
00212                coordinate system.
00213   Returntype : string
00214   Exceptions : none
00215   Caller     : general
00216   Status     : Stable
00217 
00218 =cut
00219 
00220 sub version {
00221   my $self = shift;
00222   return $self->{'version'};
00223 }
00224 
00225 
00226 
00227 =head2 species
00228 
00229   Arg [1]    : none
00230   Example    : print $coord->species();
00231   Description: Shortcut method to get the species this CoordSystem refers to.
00232   Returntype : string
00233   Exceptions : none
00234   Caller     : general
00235   Status     : Stable
00236 
00237 =cut
00238 
00239 sub species {
00240   my $self = shift;
00241   return $self->adaptor->db->species;
00242 }
00243 
00244 
00245 
00246 =head2 equals
00247 
00248   Arg [1]    : Bio::EnsEMBL::CoordSystem $cs
00249                The coord system to compare to for equality.
00250   Example    : if($coord_sys->equals($other_coord_sys)) { ... }
00251   Description: Compares 2 coordinate systems and returns true if they are
00252                equivalent.  The definition of equivalent is sharing the same
00253                name and version.
00254   Returntype : string
00255   Exceptions : none
00256   Caller     : general
00257   Status     : Stable
00258 
00259 =cut
00260 
00261 sub equals {
00262   my $self = shift;
00263   my $cs = shift;
00264 
00265   if(!$cs || !ref($cs) || !$cs->isa('Bio::EnsEMBL::CoordSystem')) {
00266     if ($cs->isa('Bio::EnsEMBL::ExternalData::DAS::CoordSystem')) {
00267       return $cs->equals($self);
00268     }
00269     throw('Argument must be a CoordSystem');
00270   }
00271 
00272   if($self->{'version'} eq $cs->version() && $self->{'name'} eq $cs->name()) {
00273     return 1;
00274   }
00275 
00276   return 0;
00277 }
00278 
00279 
00280 
00281 
00282 =head2 is_top_level
00283 
00284   Arg [1]    : none
00285   Example    : if($coord_sys->is_top_level()) { ... }
00286   Description: Returns true if this is the toplevel pseudo coordinate system.
00287                The toplevel coordinate system is not a real coordinate system
00288                which is stored in the database, but it is a placeholder that
00289                can be used to request transformations or retrievals to/from
00290                the highest defined coordinate system in a given region.
00291   Returntype : 0 or 1
00292   Exceptions : none
00293   Caller     : general
00294   Status     : Stable
00295 
00296 =cut
00297 
00298 sub is_top_level {
00299   my $self = shift;
00300   return $self->{'top_level'};
00301 }
00302 
00303 
00304 =head2 is_sequence_level
00305 
00306   Arg [1]    : none
00307   Example    : if($coord_sys->is_sequence_level()) { ... }
00308   Description: Returns true if this is a sequence level coordinate system
00309   Returntype : 0 or 1
00310   Exceptions : none
00311   Caller     : general
00312   Status     : Stable
00313 
00314 =cut
00315 
00316 sub is_sequence_level {
00317   my $self = shift;
00318   return $self->{'sequence_level'};
00319 }
00320 
00321 
00322 =head2 is_default
00323 
00324   Arg [1]    : none
00325   Example    : if($coord_sys->is_default()) { ... }
00326   Description: Returns true if this coordinate system is the default
00327                version of the coordinate system of this name.
00328   Returntype : 0 or 1
00329   Exceptions : none
00330   Caller     : general
00331   Status     : Stable
00332 
00333 =cut
00334 
00335 sub is_default {
00336   my $self = shift;
00337   return $self->{'default'};
00338 }
00339 
00340 
00341 
00342 
00343 =head2 rank
00344 
00345   Arg [1]    : none
00346   Example    : if($cs1->rank() < $cs2->rank()) {
00347                  print $cs1->name(), " is a higher level coord system than",
00348                        $cs2->name(), "\n";
00349                }
00350   Description: Returns the rank of this coordinate system.  A lower number
00351                is a higher coordinate system.  The highest level coordinate
00352                system has a rank of 1 (e.g. 'chromosome').  The toplevel
00353                pseudo coordinate system has a rank of 0.
00354   Returntype : int
00355   Exceptions : none
00356   Caller     : general
00357   Status     : Stable
00358 
00359 =cut
00360 
00361 sub rank {
00362   my $self = shift;
00363   return $self->{'rank'};
00364 }
00365 
00366 1;