|
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 # Ensembl module for Bio::EnsEMBL::Variation::Population
|
|
|
22 #
|
|
|
23 # Copyright (c) 2004 Ensembl
|
|
|
24 #
|
|
|
25
|
|
|
26
|
|
|
27 =head1 NAME
|
|
|
28
|
|
|
29 Bio::EnsEMBL::Variation::Population - A population represents a phenotypic
|
|
|
30 group, ethnic group, set of individuals used in an assay, etc.
|
|
|
31
|
|
|
32 =head1 SYNOPSIS
|
|
|
33
|
|
|
34 # Population
|
|
|
35 $pop = Bio::EnsEMBL::Variation::Population->new
|
|
|
36 (-name => 'WEST AFRICA',
|
|
|
37 -description => 'Sub-Saharan Nations bordering Atlantic north' .
|
|
|
38 ' of Congo River, and Central/Southern Atlantic' .
|
|
|
39 ' Island Nations.');
|
|
|
40
|
|
|
41 ...
|
|
|
42
|
|
|
43 # print out all sub populations of a population
|
|
|
44 # same could work for super populations
|
|
|
45
|
|
|
46 print_sub_pops($pop);
|
|
|
47
|
|
|
48 sub print_sub_pops {
|
|
|
49 my $pop = shift;
|
|
|
50 my $level = shift || 0;
|
|
|
51
|
|
|
52 my $sub_pops = $pop->get_all_sub_Populations();
|
|
|
53
|
|
|
54 foreach my $sp (@$sub_pops) {
|
|
|
55 print ' ' x $level++,
|
|
|
56 'name: ', $sp->name(),
|
|
|
57 'desc: ', $sp->description(),
|
|
|
58 'size: ', $sp->size(),"\n";
|
|
|
59 print_sub_pops($sp, $level);
|
|
|
60 }
|
|
|
61 }
|
|
|
62
|
|
|
63
|
|
|
64
|
|
|
65 =head1 DESCRIPTION
|
|
|
66
|
|
|
67 This is a class representing a population. A population may consist of any
|
|
|
68 grouping of individuals, including phenotypic groups (e.g. people with
|
|
|
69 diabetes), ethnic groups (e.g. caucasians), individuals used in an assay
|
|
|
70 (e.g. subjects in experiment X), etc.
|
|
|
71
|
|
|
72 Populations may be arranged into an arbitrary hierarchy of sub and super
|
|
|
73 populations.
|
|
|
74
|
|
|
75 =head1 METHODS
|
|
|
76
|
|
|
77 =cut
|
|
|
78
|
|
|
79 use strict;
|
|
|
80 use warnings;
|
|
|
81
|
|
|
82 package Bio::EnsEMBL::Variation::Population;
|
|
|
83
|
|
|
84 use Bio::EnsEMBL::Variation::Sample;
|
|
|
85 use Bio::EnsEMBL::Utils::Argument qw(rearrange);
|
|
|
86 use Bio::EnsEMBL::Utils::Exception qw(throw);
|
|
|
87
|
|
|
88 our @ISA = ('Bio::EnsEMBL::Variation::Sample');
|
|
|
89
|
|
|
90
|
|
|
91 =head2 new
|
|
|
92
|
|
|
93 Arg [-dbID]: int - unique internal identifier of the sample
|
|
|
94 Arg [-ADAPTOR]: Bio::EnsEMBL::PopulationAdaptor
|
|
|
95 Arg [-NAME]: string - name of the population
|
|
|
96 Arg [-DESCRIPTION]: string - description of the population
|
|
|
97 Arg [-SIZE]: int - the size of the population
|
|
|
98 Arg [-SUB_POPULATIONS]: listref of Bio::EnsEMBL::Population objects
|
|
|
99 Example : $pop = Bio::EnsEMBL::Variation::Population->new
|
|
|
100 (-name => 'WEST AFRICA',
|
|
|
101 -description => 'Sub-Saharan Nations bordering Atlantic north' .
|
|
|
102 ' of Congo River, and Central/Southern Atlantic' .
|
|
|
103 ' Island Nations.'
|
|
|
104 -sub_populations => \@sub_pops);
|
|
|
105 Description: Constructor. Instantiates a new Population object
|
|
|
106 Returntype : Bio::EnsEMBL::Variation::Population
|
|
|
107 Exceptions : none
|
|
|
108 Caller : general
|
|
|
109 Status : At Risk
|
|
|
110
|
|
|
111 =cut
|
|
|
112
|
|
|
113 sub new {
|
|
|
114 my $caller = shift;
|
|
|
115
|
|
|
116 my $class = ref($caller) || $caller;
|
|
|
117
|
|
|
118 my ($dbID, $adaptor, $name, $desc, $size, $is_strain, $sub_pops) =
|
|
|
119 rearrange(['DBID','ADAPTOR','NAME', 'DESCRIPTION', 'SIZE',
|
|
|
120 'SUB_POPULATIONS'], @_);
|
|
|
121
|
|
|
122 return bless {'dbID' => $dbID,
|
|
|
123 'adaptor' => $adaptor,
|
|
|
124 'name' => $name,
|
|
|
125 'description' => $desc,
|
|
|
126 'size' => $size,
|
|
|
127 'sub_populations' => $sub_pops}, $class;
|
|
|
128 }
|
|
|
129
|
|
|
130
|
|
|
131
|
|
|
132 =head2 get_all_sub_Populations
|
|
|
133
|
|
|
134 Arg [1] : none
|
|
|
135 Example : foreach my $sub_pop (@{$pop->get_all_sub_Populations}) {
|
|
|
136 my $sub_sub_pops = $sub_pop->get_all_sub_Populations();
|
|
|
137 }
|
|
|
138 Description: Retrieves all populations which are conceptually a sub set
|
|
|
139 of this population.
|
|
|
140 Returntype : reference to list of Bio::EnsEMBL::Variation::Population objects
|
|
|
141 Exceptions : none
|
|
|
142 Caller : general
|
|
|
143 Status : At Risk
|
|
|
144
|
|
|
145 =cut
|
|
|
146
|
|
|
147 sub get_all_sub_Populations {
|
|
|
148 my $self = shift;
|
|
|
149
|
|
|
150 if(!defined($self->{'sub_populations'}) && $self->{'adaptor'}) {
|
|
|
151 # lazy-load from database
|
|
|
152 $self->{'sub_populations'} =
|
|
|
153 $self->{'adaptor'}->fetch_all_by_super_Population($self);
|
|
|
154 }
|
|
|
155 return $self->{'sub_populations'} || [];
|
|
|
156 }
|
|
|
157
|
|
|
158
|
|
|
159
|
|
|
160 =head2 get_all_super_Populations
|
|
|
161
|
|
|
162 Arg [1] : none
|
|
|
163 Example : foreach my $sup_pop (@{$pop->get_all_super_Populations}) {
|
|
|
164 my $sup_sup_pops = $sup_pop->get_all_super_Populations();
|
|
|
165 }
|
|
|
166 Description: Retrieves all populations which this population is a part of
|
|
|
167 from the database.
|
|
|
168 Super populations may not be directly added in order to avoid
|
|
|
169 circular references and memory leaks. You must add
|
|
|
170 sub_Populations instead and store this in the database.
|
|
|
171 Returntype : reference to list of Bio::EnsEMBL::Variation::Population objects
|
|
|
172 Exceptions : none
|
|
|
173 Caller : general
|
|
|
174 Status : At Risk
|
|
|
175
|
|
|
176 =cut
|
|
|
177
|
|
|
178 sub get_all_super_Populations {
|
|
|
179 my $self = shift;
|
|
|
180
|
|
|
181 return [] if(!$self->{'adaptor'});
|
|
|
182
|
|
|
183 # load from database - do not cache to avoid circular references (mem leak)!
|
|
|
184 return $self->{'adaptor'}->fetch_all_by_sub_Population($self);
|
|
|
185 }
|
|
|
186
|
|
|
187
|
|
|
188
|
|
|
189 =head2 add_sub_Population
|
|
|
190
|
|
|
191 Arg [1] : Bio::EnsEMBL::Variation::Population $pop
|
|
|
192 Example : $pop->add_sub_Population($sub_pop);
|
|
|
193 $sub_pop->add_super_Population($pop);
|
|
|
194 Description: Adds a sub population to this population.
|
|
|
195 Returntype : none
|
|
|
196 Exceptions : throw on incorrect argument
|
|
|
197 Caller : general
|
|
|
198 Status : At Risk
|
|
|
199
|
|
|
200 =cut
|
|
|
201
|
|
|
202 sub add_sub_Population {
|
|
|
203 my $self = shift;
|
|
|
204 my $pop = shift;
|
|
|
205
|
|
|
206 if(!ref($pop) || !$pop->isa('Bio::EnsEMBL::Variation::Population')) {
|
|
|
207 throw('Bio::EnsEMBL::Variation::Population argument expected.');
|
|
|
208 }
|
|
|
209
|
|
|
210 if($pop == $self) {
|
|
|
211 throw("Cannot add self as sub population.");
|
|
|
212 }
|
|
|
213
|
|
|
214 $self->{'sub_populations'} ||= [];
|
|
|
215 push @{$self->{'sub_populations'}}, $pop;
|
|
|
216
|
|
|
217 return $pop;
|
|
|
218 }
|
|
|
219
|
|
|
220 =head2 get_all_synonyms
|
|
|
221
|
|
|
222 Arg [1] : (optional) string $source - the source of the synonyms to
|
|
|
223 return.
|
|
|
224 Example : @dbsnp_syns = @{$p->get_all_synonyms('dbSNP')};
|
|
|
225 @all_syns = @{$p->get_all_synonyms()};
|
|
|
226 Description: Retrieves synonyms for this Population. If a source argument
|
|
|
227 is provided all synonyms from that source are returned,
|
|
|
228 otherwise all synonyms are returned.
|
|
|
229 Returntype : reference to list of strings
|
|
|
230 Exceptions : none
|
|
|
231 Caller : general
|
|
|
232 Status : At Risk
|
|
|
233
|
|
|
234 =cut
|
|
|
235
|
|
|
236 sub get_all_synonyms {
|
|
|
237 my $self = shift;
|
|
|
238 my $source = shift;
|
|
|
239
|
|
|
240 return [] if(!$self->adaptor()); #if there is no adaptor, return empty string
|
|
|
241
|
|
|
242 return $self->adaptor()->fetch_synonyms($self->dbID(),$source);
|
|
|
243
|
|
|
244 }
|
|
|
245
|
|
|
246 =head2 get_all_Individuals
|
|
|
247
|
|
|
248 Arg [1] : none
|
|
|
249 Example : @individuals = @{$p->get_all_individuals()};
|
|
|
250 Description: Retrieves all Individuals belonging to this Population.
|
|
|
251 Returntype : reference to list of Bio::EnsEMBL::Variation::Individual objects
|
|
|
252 Exceptions : none
|
|
|
253 Caller : general
|
|
|
254 Status : At Risk
|
|
|
255
|
|
|
256 =cut
|
|
|
257
|
|
|
258 sub get_all_Individuals {
|
|
|
259 my $self = shift;
|
|
|
260
|
|
|
261 my $ia = $self->adaptor->db->get_IndividualAdaptor;
|
|
|
262
|
|
|
263 return (defined $ia ? $ia->fetch_all_by_Population($self) : []);
|
|
|
264 }
|
|
|
265
|
|
|
266 1;
|
