|
0
|
1 =head1 LICENSE
|
|
|
2
|
|
|
3 Copyright (c) 1999-2012 The European Bioinformatics Institute and
|
|
|
4 Genome Research Limited. All rights reserved.
|
|
|
5
|
|
|
6 This software is distributed under a modified Apache license.
|
|
|
7 For license details, please see
|
|
|
8
|
|
|
9 http://www.ensembl.org/info/about/code_licence.html
|
|
|
10
|
|
|
11 =head1 CONTACT
|
|
|
12
|
|
|
13 Please email comments or questions to the public Ensembl
|
|
|
14 developers list at <dev@ensembl.org>.
|
|
|
15
|
|
|
16 Questions may also be sent to the Ensembl help desk at
|
|
|
17 <helpdesk@ensembl.org>.
|
|
|
18
|
|
|
19 =cut
|
|
|
20
|
|
|
21 =head1 NAME
|
|
|
22
|
|
|
23 Bio::EnsEMBL::CoordSystem
|
|
|
24
|
|
|
25 =head1 SYNOPSIS
|
|
|
26
|
|
|
27 my $db = Bio::EnsEMBL::DBSQL::DBAdaptor->new(...);
|
|
|
28
|
|
|
29 my $csa = $db->get_CoordSystemAdaptor();
|
|
|
30
|
|
|
31 #
|
|
|
32 # Get all coord systems in the database:
|
|
|
33 #
|
|
|
34 foreach my $cs ( @{ $csa->fetch_all() } ) {
|
|
|
35 my $str = join ':', $cs->name(), $cs->version(), $cs->dbID();
|
|
|
36 print "$str\n";
|
|
|
37 }
|
|
|
38
|
|
|
39 =head1 DESCRIPTION
|
|
|
40
|
|
|
41 This is a simple object which contains a few coordinate system attributes:
|
|
|
42 name, internal identifier, version. A coordinate system is uniquely defined
|
|
|
43 by its name and version. A version of a coordinate system applies to all
|
|
|
44 sequences within a coordinate system. This should not be confused with
|
|
|
45 individual sequence versions.
|
|
|
46
|
|
|
47 Take for example the Human assembly. The version 'NCBI33' applies to
|
|
|
48 to all chromosomes in the NCBI33 assembly (that is the entire 'chromosome'
|
|
|
49 coordinate system). The 'clone' coordinate system in the same database would
|
|
|
50 have no version however. Although the clone sequences have their own sequence
|
|
|
51 versions, there is no version which applies to the entire set of clones.
|
|
|
52
|
|
|
53 Coordinate system objects are immutable. Their name and version, and other
|
|
|
54 attributes may not be altered after they are created.
|
|
|
55
|
|
|
56 =head1 METHODS
|
|
|
57
|
|
|
58 =cut
|
|
|
59
|
|
|
60
|
|
|
61 use strict;
|
|
|
62 use warnings;
|
|
|
63
|
|
|
64 package Bio::EnsEMBL::CoordSystem;
|
|
|
65
|
|
|
66 use Bio::EnsEMBL::Storable;
|
|
|
67
|
|
|
68 use Bio::EnsEMBL::Utils::Argument qw(rearrange);
|
|
|
69 use Bio::EnsEMBL::Utils::Exception qw(throw);
|
|
|
70
|
|
|
71 use vars qw(@ISA);
|
|
|
72
|
|
|
73 @ISA = qw(Bio::EnsEMBL::Storable);
|
|
|
74
|
|
|
75
|
|
|
76 =head2 new
|
|
|
77
|
|
|
78 Arg [..] : List of named arguments:
|
|
|
79 -NAME - The name of the coordinate system
|
|
|
80 -VERSION - (optional) The version of the coordinate system.
|
|
|
81 Note that if the version passed in is undefined,
|
|
|
82 it will be set to the empty string in the
|
|
|
83 resulting CoordSystem object.
|
|
|
84 -RANK - The rank of the coordinate system. The highest
|
|
|
85 level coordinate system should have rank 1, the
|
|
|
86 second highest rank 2 and so on. An example of
|
|
|
87 a high level coordinate system is 'chromosome' an
|
|
|
88 example of a lower level coordinate system is
|
|
|
89 'clone'.
|
|
|
90 -TOP_LEVEL - (optional) Sets whether this is a top-level coord
|
|
|
91 system. Default = 0. This should only be set to
|
|
|
92 true if you are creating an artificial toplevel
|
|
|
93 coordsystem by the name of 'toplevel'
|
|
|
94 -SEQUENCE_LEVEL - (optional) Sets whether this is a sequence
|
|
|
95 level coordinate system. Default = 0
|
|
|
96 -DEFAULT - (optional)
|
|
|
97 Whether this is the default version of the
|
|
|
98 coordinate systems of this name. Default = 0
|
|
|
99 -DBID - (optional) The internal identifier of this
|
|
|
100 coordinate system
|
|
|
101 -ADAPTOR - (optional) The adaptor which provides database
|
|
|
102 interaction for this object
|
|
|
103 Example : $cs = Bio::EnsEMBL::CoordSystem->new(-NAME => 'chromosome',
|
|
|
104 -VERSION => 'NCBI33',
|
|
|
105 -RANK => 1,
|
|
|
106 -DBID => 1,
|
|
|
107 -ADAPTOR => adaptor,
|
|
|
108 -DEFAULT => 1,
|
|
|
109 -SEQUENCE_LEVEL => 0);
|
|
|
110 Description: Creates a new CoordSystem object representing a coordinate
|
|
|
111 system.
|
|
|
112 Returntype : Bio::EnsEMBL::CoordSystem
|
|
|
113 Exceptions : none
|
|
|
114 Caller : general
|
|
|
115 Status : Stable
|
|
|
116
|
|
|
117 =cut
|
|
|
118
|
|
|
119 sub new {
|
|
|
120 my $caller = shift;
|
|
|
121 my $class = ref($caller) || $caller;
|
|
|
122
|
|
|
123 my $self = $class->SUPER::new(@_);
|
|
|
124
|
|
|
125 my ( $name, $version, $top_level, $sequence_level, $default, $rank ) =
|
|
|
126 rearrange( [ 'NAME', 'VERSION',
|
|
|
127 'TOP_LEVEL', 'SEQUENCE_LEVEL',
|
|
|
128 'DEFAULT', 'RANK' ],
|
|
|
129 @_ );
|
|
|
130
|
|
|
131 $version = '' if ( !defined($version) );
|
|
|
132
|
|
|
133 $top_level = ($top_level) ? 1 : 0;
|
|
|
134 $sequence_level = ($sequence_level) ? 1 : 0;
|
|
|
135 $default = ($default) ? 1 : 0;
|
|
|
136 $rank ||= 0;
|
|
|
137
|
|
|
138 if ( $top_level == 1 ) {
|
|
|
139 if ( $rank != 0 ) {
|
|
|
140 throw('RANK argument must be 0 if TOP_LEVEL is 1');
|
|
|
141 }
|
|
|
142
|
|
|
143 if ( defined($name) ) {
|
|
|
144 if ( $name ne 'toplevel' ) {
|
|
|
145 throw('The NAME argument must be "toplevel" if TOP_LEVEL is 1');
|
|
|
146 }
|
|
|
147 } else {
|
|
|
148 $name = 'toplevel';
|
|
|
149 }
|
|
|
150
|
|
|
151 if ( $sequence_level == 1 ) {
|
|
|
152 throw("SEQUENCE_LEVEL argument must be 0 if TOP_LEVEL is 1");
|
|
|
153 }
|
|
|
154
|
|
|
155 $default = 0;
|
|
|
156
|
|
|
157 } else {
|
|
|
158
|
|
|
159 if ( $rank == 0 ) {
|
|
|
160 throw("RANK argument must be non-zero unless TOP_LEVEL is 1");
|
|
|
161 }
|
|
|
162
|
|
|
163 if ( !defined($name) ) {
|
|
|
164 throw('The NAME argument is required');
|
|
|
165 } elsif ( $name eq 'toplevel' ) {
|
|
|
166 throw( "Cannot name coord system 'toplevel' "
|
|
|
167 . "unless TOP_LEVEL is 1" );
|
|
|
168 }
|
|
|
169
|
|
|
170 }
|
|
|
171
|
|
|
172 if ( $rank !~ /^\d+$/ ) {
|
|
|
173 throw('The RANK argument must be a positive integer');
|
|
|
174 }
|
|
|
175
|
|
|
176 $self->{'version'} = $version;
|
|
|
177 $self->{'name'} = $name;
|
|
|
178 $self->{'top_level'} = $top_level;
|
|
|
179 $self->{'sequence_level'} = $sequence_level;
|
|
|
180 $self->{'default'} = $default;
|
|
|
181 $self->{'rank'} = $rank;
|
|
|
182
|
|
|
183 return $self;
|
|
|
184 } ## end sub new
|
|
|
185
|
|
|
186
|
|
|
187 =head2 name
|
|
|
188
|
|
|
189 Arg [1] : (optional) string $name
|
|
|
190 Example : print $coord_system->name();
|
|
|
191 Description: Getter for the name of this coordinate system
|
|
|
192 Returntype : string
|
|
|
193 Exceptions : none
|
|
|
194 Caller : general
|
|
|
195 Status : Stable
|
|
|
196
|
|
|
197 =cut
|
|
|
198
|
|
|
199 sub name {
|
|
|
200 my $self = shift;
|
|
|
201 return $self->{'name'};
|
|
|
202 }
|
|
|
203
|
|
|
204
|
|
|
205
|
|
|
206 =head2 version
|
|
|
207
|
|
|
208 Arg [1] : none
|
|
|
209 Example : print $coord->version();
|
|
|
210 Description: Getter for the version of this coordinate system. This
|
|
|
211 will return an empty string if no version is defined for this
|
|
|
212 coordinate system.
|
|
|
213 Returntype : string
|
|
|
214 Exceptions : none
|
|
|
215 Caller : general
|
|
|
216 Status : Stable
|
|
|
217
|
|
|
218 =cut
|
|
|
219
|
|
|
220 sub version {
|
|
|
221 my $self = shift;
|
|
|
222 return $self->{'version'};
|
|
|
223 }
|
|
|
224
|
|
|
225
|
|
|
226
|
|
|
227 =head2 species
|
|
|
228
|
|
|
229 Arg [1] : none
|
|
|
230 Example : print $coord->species();
|
|
|
231 Description: Shortcut method to get the species this CoordSystem refers to.
|
|
|
232 Returntype : string
|
|
|
233 Exceptions : none
|
|
|
234 Caller : general
|
|
|
235 Status : Stable
|
|
|
236
|
|
|
237 =cut
|
|
|
238
|
|
|
239 sub species {
|
|
|
240 my $self = shift;
|
|
|
241 return $self->adaptor->db->species;
|
|
|
242 }
|
|
|
243
|
|
|
244
|
|
|
245
|
|
|
246 =head2 equals
|
|
|
247
|
|
|
248 Arg [1] : Bio::EnsEMBL::CoordSystem $cs
|
|
|
249 The coord system to compare to for equality.
|
|
|
250 Example : if($coord_sys->equals($other_coord_sys)) { ... }
|
|
|
251 Description: Compares 2 coordinate systems and returns true if they are
|
|
|
252 equivalent. The definition of equivalent is sharing the same
|
|
|
253 name and version.
|
|
|
254 Returntype : string
|
|
|
255 Exceptions : none
|
|
|
256 Caller : general
|
|
|
257 Status : Stable
|
|
|
258
|
|
|
259 =cut
|
|
|
260
|
|
|
261 sub equals {
|
|
|
262 my $self = shift;
|
|
|
263 my $cs = shift;
|
|
|
264
|
|
|
265 if(!$cs || !ref($cs) || !$cs->isa('Bio::EnsEMBL::CoordSystem')) {
|
|
|
266 if ($cs->isa('Bio::EnsEMBL::ExternalData::DAS::CoordSystem')) {
|
|
|
267 return $cs->equals($self);
|
|
|
268 }
|
|
|
269 throw('Argument must be a CoordSystem');
|
|
|
270 }
|
|
|
271
|
|
|
272 if($self->{'version'} eq $cs->version() && $self->{'name'} eq $cs->name()) {
|
|
|
273 return 1;
|
|
|
274 }
|
|
|
275
|
|
|
276 return 0;
|
|
|
277 }
|
|
|
278
|
|
|
279
|
|
|
280
|
|
|
281
|
|
|
282 =head2 is_top_level
|
|
|
283
|
|
|
284 Arg [1] : none
|
|
|
285 Example : if($coord_sys->is_top_level()) { ... }
|
|
|
286 Description: Returns true if this is the toplevel pseudo coordinate system.
|
|
|
287 The toplevel coordinate system is not a real coordinate system
|
|
|
288 which is stored in the database, but it is a placeholder that
|
|
|
289 can be used to request transformations or retrievals to/from
|
|
|
290 the highest defined coordinate system in a given region.
|
|
|
291 Returntype : 1 or 0
|
|
|
292 Exceptions : none
|
|
|
293 Caller : general
|
|
|
294 Status : Stable
|
|
|
295
|
|
|
296 =cut
|
|
|
297
|
|
|
298 sub is_top_level {
|
|
|
299 my $self = shift;
|
|
|
300 return $self->{'top_level'};
|
|
|
301 }
|
|
|
302
|
|
|
303
|
|
|
304 =head2 is_sequence_level
|
|
|
305
|
|
|
306 Arg [1] : none
|
|
|
307 Example : if($coord_sys->is_sequence_level()) { ... }
|
|
|
308 Description: Returns true if this is a sequence level coordinate system
|
|
|
309 Returntype : 1 or 0
|
|
|
310 Exceptions : none
|
|
|
311 Caller : general
|
|
|
312 Status : Stable
|
|
|
313
|
|
|
314 =cut
|
|
|
315
|
|
|
316 sub is_sequence_level {
|
|
|
317 my $self = shift;
|
|
|
318 return $self->{'sequence_level'};
|
|
|
319 }
|
|
|
320
|
|
|
321
|
|
|
322 =head2 is_default
|
|
|
323
|
|
|
324 Arg [1] : none
|
|
|
325 Example : if($coord_sys->is_default()) { ... }
|
|
|
326 Description: Returns true if this coordinate system is the default
|
|
|
327 version of the coordinate system of this name.
|
|
|
328 Returntype : 1 or 0
|
|
|
329 Exceptions : none
|
|
|
330 Caller : general
|
|
|
331 Status : Stable
|
|
|
332
|
|
|
333 =cut
|
|
|
334
|
|
|
335 sub is_default {
|
|
|
336 my $self = shift;
|
|
|
337 return $self->{'default'};
|
|
|
338 }
|
|
|
339
|
|
|
340
|
|
|
341
|
|
|
342
|
|
|
343 =head2 rank
|
|
|
344
|
|
|
345 Arg [1] : none
|
|
|
346 Example : if($cs1->rank() < $cs2->rank()) {
|
|
|
347 print $cs1->name(), " is a higher level coord system than",
|
|
|
348 $cs2->name(), "\n";
|
|
|
349 }
|
|
|
350 Description: Returns the rank of this coordinate system. A lower number
|
|
|
351 is a higher coordinate system. The highest level coordinate
|
|
|
352 system has a rank of 1 (e.g. 'chromosome'). The toplevel
|
|
|
353 pseudo coordinate system has a rank of 0.
|
|
|
354 Returntype : int
|
|
|
355 Exceptions : none
|
|
|
356 Caller : general
|
|
|
357 Status : Stable
|
|
|
358
|
|
|
359 =cut
|
|
|
360
|
|
|
361 sub rank {
|
|
|
362 my $self = shift;
|
|
|
363 return $self->{'rank'};
|
|
|
364 }
|
|
|
365
|
|
|
366 1;
|
