Bio/DasI.pm

filter: Statementstmt 35.4% 11 / 31 Branchbran 0.0% 0 / 6 Conditioncond 0.0% 0 / 6 MC/DCmcdc 0.0% 0 / 4 Subroutinesub 18.7% 3 / 16 Podpod 92.3% 12 / 13 totaltotal 34.2% 26 / 76 CC 6 SCAR 25.9
CC
6
Cov
26%
parse_types
42.0
new
2.0
types
2.0
CRAP 13.3
« Bio/Search/GenericDatabase.pm ↑ Summary Bio/Matrix/Generic.pm »
1 #
2 # BioPerl module for Bio::DasI
3 #
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
5 #
6 # Cared for by Lincoln Stein <lstein@cshl.org>
7 #
8 # Copyright Lincoln Stein
9 #
10 # You may distribute this module under the same terms as perl itself
11  
12 # POD documentation - main docs before the code
13  
14 =head1 NAME
15  
16 Bio::DasI - DAS-style access to a feature database
17  
18 =head1 SYNOPSIS
19  
20 # Open up a feature database somehow...
21 $db = Bio::DasI->new(@args);
22  
23 @segments = $db->segment(-name => 'NT_29921.4',
24 -start => 1,
25 -end => 1000000);
26  
27 # segments are Bio::Das::SegmentI - compliant objects
28  
29 # fetch a list of features
30 @features = $db->features(-type=>['type1','type2','type3']);
31  
32 # invoke a callback over features
33 $db->features(-type=>['type1','type2','type3'],
34 -callback => sub { ... }
35 );
36  
37 $stream = $db->get_seq_stream(-type=>['type1','type2','type3']);
38 while (my $feature = $stream->next_seq) {
39 # each feature is a Bio::SeqFeatureI-compliant object
40 }
41  
42 # get all feature types
43 @types = $db->types;
44  
45 # count types
46 %types = $db->types(-enumerate=>1);
47  
48 @feature = $db->get_feature_by_name($class=>$name);
49 @feature = $db->get_feature_by_target($target_name);
50 @feature = $db->get_feature_by_attribute($att1=>$value1,$att2=>$value2);
51 $feature = $db->get_feature_by_id($id);
52  
53 $error = $db->error;
54  
55 =head1 DESCRIPTION
56  
57 Bio::DasI is a simplified alternative interface to sequence annotation
58 databases used by the distributed annotation system (see
59 L<Bio::Das>). In this scheme, the genome is represented as a series of
60 features, a subset of which are named. Named features can be used as
61 reference points for retrieving "segments" (see L<Bio::Das::SegmentI>),
62 and these can, in turn, be used as the basis for exploring the genome
63 further.
64  
65 In addition to a name, each feature has a "class", which is
66 essentially a namespace qualifier and a "type", which describes what
67 type of feature it is. Das uses the GO consortium's ontology of
68 feature types, and so the type is actually an object of class
69 Bio::Das::FeatureTypeI (see L<Bio::Das::FeatureTypeI>). Bio::DasI
70 provides methods for interrogating the database for the types it
71 contains and the counts of each type.
72  
73 =head1 FEEDBACK
74  
75 =head2 Mailing Lists
76  
77 User feedback is an integral part of the evolution of this and other
78 Bioperl modules. Send your comments and suggestions preferably to one
79 of the Bioperl mailing lists. Your participation is much appreciated.
80  
81 bioperl-l@bioperl.org
82  
83 =head2 Support
84  
85 Please direct usage questions or support issues to the mailing list:
86  
87 I<bioperl-l@bioperl.org>
88  
89 rather than to the module maintainer directly. Many experienced and
90 reponsive experts will be able look at the problem and quickly
91 address it. Please include a thorough description of the problem
92 with code and data examples if at all possible.
93  
94 =head2 Reporting Bugs
95  
96 Report bugs to the Bioperl bug tracking system to help us keep track
97 the bugs and their resolution. Bug reports can be submitted via the web:
98  
99 https://github.com/bioperl/bioperl-live/issues
100  
101 =head1 AUTHOR - Lincoln Stein
102  
103 Email lstein@cshl.org
104  
105 =head1 APPENDIX
106  
107 The rest of the documentation details each of the object
108 methods. Internal methods are usually preceded with a _
109  
110 =cut
111  
112 #'
113 # Let the code begin...
114  
115 package Bio::DasI;
116 1 $Bio::DasI::VERSION = '1.7.8';
117 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
118  
119 1 ▶use Bio::Das::SegmentI;
Subroutine BEGIN: called CC=1 SCAR=0.0
120 # Object preamble - inherits from Bio::Root::Root;
121 1 ▶use base qw(Bio::Root::RootI Bio::SeqFeature::CollectionI);
Subroutine BEGIN: called CC=1 SCAR=0.0
122  
123 =head2 new
124  
125 Title : new
126 Usage : Bio::DasI->new(@args)
127 Function: Create new Bio::DasI object
128 Returns : a Bio::DasI object
129 Args : see below
130  
131 The new() method creates a new object. The argument list is either a
132 single argument consisting of a connection string, or the following
133 list of -name=E<gt>value arguments:
134  
135 Argument Description
136 -------- -----------
137  
138 -dsn Connection string for database
139 -adaptor Name of an adaptor class to use when connecting
140 -aggregator Array ref containing list of aggregators
141 "semantic mappers" to apply to database
142 -user Authentication username
143 -pass Authentication password
144  
145 Implementors of DasI may add other arguments.
146  
147 =cut
148  
149 0 ▶sub new {shift->throw_not_implemented}
Subroutine new: not called CC=1 SCAR=6.9
Pod documented
150  
151 =head2 types
152  
153 Title : types
154 Usage : $db->types(@args)
155 Function: return list of feature types in database
156 Returns : a list of Bio::Das::FeatureTypeI objects
157 Args : see below
158  
159 This routine returns a list of feature types known to the database. It
160 is also possible to find out how many times each feature occurs.
161  
162 Arguments are -option=E<gt>value pairs as follows:
163  
164 -enumerate if true, count the features
165  
166 The returned value will be a list of Bio::Das::FeatureTypeI objects
167 (see L<Bio::Das::FeatureTypeI>.
168  
169 If -enumerate is true, then the function returns a hash (not a hash
170 reference) in which the keys are the stringified versions of
171 Bio::Das::FeatureTypeI and the values are the number of times each
172 feature appears in the database.
173  
174 =cut
175  
176 0 ▶sub types { shift->throw_not_implemented; }
Subroutine types: not called CC=1 SCAR=6.9
Pod documented
177  
178 =head2 parse_types
179  
180 Title : parse_types
181 Usage : $db->parse_types(@args)
182 Function: parses list of types
183 Returns : an array ref containing ['method','source'] pairs
184 Args : a list of types in 'method:source' form
185 Status : internal
186  
187 This method takes an array of type names in the format "method:source"
188 and returns an array reference of ['method','source'] pairs. It will
189 also accept a single argument consisting of an array reference with
190 the list of type names.
191  
192 =cut
193  
194 # turn feature types in the format "method:source" into a list of [method,source] refs
195 0 ▶sub parse_types {
Subroutine parse_types: not called CC=6 SCAR=37.4
Pod documented
196 0 my $self = shift;
197 0 ▶ return [] if !@_ or !defined($_[0]);
Branch: 1 branch
BranchTrueFalseTotal
unless @_ and defined $_[0] 0 0 0
Condition0%0/3
@_ and defined $_[0]
!ll&&!rl&&r
000
MC/DC0%0/2
@_ and defined $_[0]
@_ defined $_[0]
Truth table0%0/3
A and B
A= @_B= defined $_[0]
ABresult
0X0
100
111
198 0 ▶ return $_[0] if ref $_[0] eq 'ARRAY' && ref $_[0][0];
Branch: 1 branch
BranchTrueFalseTotal
if ref $_[0] eq "ARRAY" and ref $_[0][0] 0 0 0
Condition0%0/3
ref $_[0] eq "ARRAY" and ref $_[0][0]
!ll&&!rl&&r
000
MC/DC0%0/2
ref $_[0] eq "ARRAY" and ref $_[0][0]
ref $_[0] eq "ARRAY" ref $_[0][0]
Truth table0%0/3
A and B
A= ref $_[0] eq "ARRAY"B= ref $_[0][0]
ABresult
0X0
100
111
199 0 ▶ my @types = ref($_[0]) ? @{$_[0]} : @_;
Branch: 1 branch
BranchTrueFalseTotal
ref $_[0] ? : 0 0 0
200 0 my @type_list = map { [split(':',$_,2)] } @types;
201 0 return \@type_list;
202 }
203  
204 =head2 segment
205  
206 Title : segment
207 Usage : $db->segment(@args);
208 Function: create a segment object
209 Returns : segment object(s)
210 Args : see below
211  
212 This method generates a Bio::Das::SegmentI object (see
213 L<Bio::Das::SegmentI>). The segment can be used to find overlapping
214 features and the raw sequence.
215  
216 When making the segment() call, you specify the ID of a sequence
217 landmark (e.g. an accession number, a clone or contig), and a
218 positional range relative to the landmark. If no range is specified,
219 then the entire region spanned by the landmark is used to generate the
220 segment.
221  
222 Arguments are -option=E<gt>value pairs as follows:
223  
224 -name ID of the landmark sequence.
225  
226 -class A namespace qualifier. It is not necessary for the
227 database to honor namespace qualifiers, but if it
228 does, this is where the qualifier is indicated.
229  
230 -version Version number of the landmark. It is not necessary for
231 the database to honor versions, but if it does, this is
232 where the version is indicated.
233  
234 -start Start of the segment relative to landmark. Positions
235 follow standard 1-based sequence rules. If not specified,
236 defaults to the beginning of the landmark.
237  
238 -end End of the segment relative to the landmark. If not specified,
239 defaults to the end of the landmark.
240  
241 The return value is a list of Bio::Das::SegmentI objects. If the method
242 is called in a scalar context and there are no more than one segments
243 that satisfy the request, then it is allowed to return the segment.
244 Otherwise, the method must throw a "multiple segment exception".
245  
246 =cut
247  
248 #'
249  
250 0 ▶sub segment { shift->throw_not_implemented }
Subroutine segment: not called CC=1 SCAR=6.9
Pod documented
251  
252 =head2 features
253  
254 Title : features
255 Usage : $db->features(@args)
256 Function: get all features, possibly filtered by type
257 Returns : a list of Bio::SeqFeatureI objects
258 Args : see below
259 Status : public
260  
261 This routine will retrieve features in the database regardless of
262 position. It can be used to return all features, or a subset based on
263 their type
264  
265 Arguments are -option=E<gt>value pairs as follows:
266  
267 -types List of feature types to return. Argument is an array
268 of Bio::Das::FeatureTypeI objects or a set of strings
269 that can be converted into FeatureTypeI objects.
270  
271 -callback A callback to invoke on each feature. The subroutine
272 will be passed each Bio::SeqFeatureI object in turn.
273  
274 -attributes A hash reference containing attributes to match.
275  
276 The -attributes argument is a hashref containing one or more attributes
277 to match against:
278  
279 -attributes => { Gene => 'abc-1',
280 Note => 'confirmed' }
281  
282 Attribute matching is simple exact string matching, and multiple
283 attributes are ANDed together. See L<Bio::DB::ConstraintsI> for a
284 more sophisticated take on this.
285  
286 If one provides a callback, it will be invoked on each feature in
287 turn. If the callback returns a false value, iteration will be
288 interrupted. When a callback is provided, the method returns undef.
289  
290 =cut
291  
292 0 ▶sub features { shift->throw_not_implemented }
Subroutine features: not called CC=1 SCAR=6.9
Pod documented
293  
294 =head2 get_feature_by_name
295  
296 Title : get_feature_by_name
297 Usage : $db->get_feature_by_name(-class=>$class,-name=>$name)
298 Function: fetch features by their name
299 Returns : a list of Bio::SeqFeatureI objects
300 Args : the class and name of the desired feature
301 Status : public
302  
303 This method can be used to fetch named feature(s) from the database.
304 The -class and -name arguments have the same meaning as in segment(),
305 and the method also accepts the following short-cut forms:
306  
307 1) one argument: the argument is treated as the feature name
308 2) two arguments: the arguments are treated as the class and name
309 (note: this uses _rearrange() so the first argument must not
310 begin with a hyphen or it will be interpreted as a named
311 argument).
312  
313 This method may return zero, one, or several Bio::SeqFeatureI objects.
314 The implementor may allow the name to contain wildcards, in which case
315 standard C-shell glob semantics are expected.
316  
317 =cut
318  
319 0 ▶sub get_feature_by_name {
Subroutine get_feature_by_name: not called CC=1 SCAR=6.9
Pod documented
320 0 shift->throw_not_implemented();
321 }
322  
323 =head2 get_feature_by_target
324  
325 Title : get_feature_by_target
326 Usage : $db->get_feature_by_target($class => $name)
327 Function: fetch features by their similarity target
328 Returns : a list of Bio::SeqFeatureI objects
329 Args : the class and name of the desired feature
330 Status : public
331  
332 This method can be used to fetch a named feature from the database
333 based on its similarity hit. The arguments are the same as
334 get_feature_by_name(). If this is not implemented, the interface
335 defaults to using get_feature_by_name().
336  
337 =cut
338  
339 0 ▶sub get_feature_by_target {
Subroutine get_feature_by_target: not called CC=1 SCAR=6.9
Pod documented
340 0 shift->get_feature_by_name(@_);
341 }
342  
343 =head2 get_feature_by_id
344  
345 Title : get_feature_by_id
346 Usage : $db->get_feature_by_target($id)
347 Function: fetch a feature by its ID
348 Returns : a Bio::SeqFeatureI objects
349 Args : the ID of the feature
350 Status : public
351  
352 If the database provides unique feature IDs, this can be used to
353 retrieve a single feature from the database. If not overridden, this
354 interface calls get_feature_by_name() and returns the first element.
355  
356 =cut
357  
358 0 ▶sub get_feature_by_id {
Subroutine get_feature_by_id: not called CC=1 SCAR=6.9
Pod documented
359 0 (shift->get_feature_by_name(@_))[0];
360 }
361  
362 =head2 get_feature_by_attribute
363  
364 Title : get_feature_by_attribute
365 Usage : $db->get_feature_by_attribute(attribute1=>value1,attribute2=>value2)
366 Function: fetch features by combinations of attribute values
367 Returns : a list of Bio::SeqFeatureI objects
368 Args : the class and name of the desired feature
369 Status : public
370  
371 This method can be used to fetch a set of features from the database.
372 Attributes are a list of name=E<gt>value pairs. They will be
373 logically ANDed together. If an attribute value is an array
374 reference, the list of values in the array is treated as an
375 alternative set of values to be ORed together.
376  
377 =cut
378  
379 0 ▶sub get_feature_by_attribute {
Subroutine get_feature_by_attribute: not called CC=1 SCAR=6.9
Pod documented
380 0 shift->throw_not_implemented();
381 }
382  
383  
384 =head2 search_notes
385  
386 Title : search_notes
387 Usage : $db->search_notes($search_term,$max_results)
388 Function: full-text search on features, ENSEMBL-style
389 Returns : an array of [$name,$description,$score]
390 Args : see below
391 Status : public
392  
393 This routine performs a full-text search on feature attributes (which
394 attributes depend on implementation) and returns a list of
395 [$name,$description,$score], where $name is the feature ID,
396 $description is a human-readable description such as a locus line, and
397 $score is the match strength.
398  
399 Since this is a decidedly non-standard thing to do (but the generic
400 genome browser uses it), the default method returns an empty list.
401 You do not have to implement it.
402  
403 =cut
404  
405 0 ▶sub search_notes { return }
Subroutine search_notes: not called CC=1 SCAR=6.9
Pod documented
406  
407 =head2 get_seq_stream
408  
409 Title : get_seq_stream
410 Usage : $seqio = $db->get_seq_stream(@args)
411 Function: Performs a query and returns an iterator over it
412 Returns : a Bio::SeqIO stream capable of returning Bio::SeqFeatureI objects
413 Args : As in features()
414 Status : public
415  
416 This routine takes the same arguments as features(), but returns a
417 Bio::SeqIO::Stream-compliant object. Use it like this:
418  
419 $stream = $db->get_seq_stream('exon');
420 while (my $exon = $stream->next_seq) {
421 print $exon,"\n";
422 }
423  
424 NOTE: In the interface this method is aliased to get_feature_stream(),
425 as the name is more descriptive.
426  
427 =cut
428  
429 0 ▶sub get_seq_stream { shift->throw_not_implemented }
Subroutine get_seq_stream: not called CC=1 SCAR=6.9
Pod documented
430 0 ▶sub get_feature_stream {shift->get_seq_stream(@_) }
Subroutine get_feature_stream: not called CC=1 SCAR=6.9
Pod undocumented
431  
432 =head2 refclass
433  
434 Title : refclass
435 Usage : $class = $db->refclass
436 Function: returns the default class to use for segment() calls
437 Returns : a string
438 Args : none
439 Status : public
440  
441 For data sources which use namespaces to distinguish reference
442 sequence accessions, this returns the default namespace (or "class")
443 to use. This interface defines a default of "Accession".
444  
445 =cut
446  
447 0 ▶sub refclass { "Accession" }
Subroutine refclass: not called CC=1 SCAR=6.9
Pod documented
448  
449 1 1;
« Bio/Search/GenericDatabase.pm ↑ Summary Bio/Matrix/Generic.pm »