← Back to branch summary

~ubuntu-branches/ubuntu/saucy/bioperl/saucy-proposed

« back to all changes in this revision

Viewing changes to Bio/DB/SeqFeature/Store.pm

  • Committer: Bazaar Package Importer
  • Author(s): Charles Plessy
  • Date: 2009-03-10 07:19:11 UTC
  • mfrom: (1.2.3 upstream)
  • Revision ID: james.westby@ubuntu.com-20090310071911-fukqzw54pyb1f0bd
Tags: 1.6.0-2
https://launchpad.net/bugs/324001
* Removed patch system (not used):
  - removed instuctions in debian/rules;
  - removed quilt from Build-Depends in debian/control.
* Re-enabled tests:
  - uncommented test command in debian/rules;
  - uncommented previously missing build-dependencies in debian/control.
  - Re-enabled tests and uncommented build-dependencies accordingly.
* Removed libmodule-build-perl and libtest-harness-perl from
  Build-Depends-Indep (provided by perl-modules).
* Better cleaning of empty directories using find -type d -empty -delete
  instead of rmdir in debian/rules (LP: #324001).

Show diffs side-by-side

added added

removed removed

Lines of Context:
Bio/DB/SeqFeature/Store.pm
1
1
package Bio::DB::SeqFeature::Store;
2
2
 
3
 
# $Id: Store.pm,v 1.21.4.4 2006/10/07 12:54:33 lstein Exp $
 
3
# $Id: Store.pm 15137 2008-12-10 18:26:31Z lstein $
4
4
 
5
5
=head1 NAME
6
6
 
13
13
  # Open the feature database
14
14
  my $db      = Bio::DB::SeqFeature::Store->new( -adaptor => 'DBI::mysql',
15
15
                                                 -dsn     => 'dbi:mysql:test',
16
 
                                                 -write   => 1 );
 
16
                                                 -create  => 1 );
17
17
 
18
18
  # get a feature from somewhere
19
19
  my $feature = Bio::SeqFeature::Generic->new(...);
43
43
  @features = $db->get_features_by_alias('sma-3');
44
44
 
45
45
  # ...by type
46
 
  @features = $db->get_features_by_name('gene');
 
46
  @features = $db->get_features_by_type('gene');
47
47
 
48
48
  # ...by location
49
49
  @features = $db->get_features_by_location(-seq_id=>'Chr1',-start=>4000,-end=>600000);
51
51
  # ...by attribute
52
52
  @features = $db->get_features_by_attribute({description => 'protein kinase'})
53
53
 
 
54
  # ...by primary id
 
55
  @features = $db->get_feature_by_primary_id(42); # note no plural!!!
 
56
 
54
57
  # ...by the GFF "Note" field
55
58
  @result_list = $db->search_notes('kinase');
56
59
 
83
86
  $db->insert_sequence('Chr1','GATCCCCCGGGATTCCAAAA...');
84
87
  my $sequence = $db->fetch_sequence('Chr1',5000=>6000);
85
88
 
 
89
  # what feature types are defined in the database?
 
90
  my @types    = $db->types;
 
91
 
86
92
  # create a new feature in the database
87
93
  my $feature = $db->new_feature(-primary_tag => 'mRNA',
88
94
                                 -seq_id      => 'chr3',
148
154
 
149
155
=over 4
150
156
 
 
157
=item memory
 
158
 
 
159
An implementation that stores all data in memory. This is useful for
 
160
small data sets of no more than 10,000 features (more or less,
 
161
depending on system memory).
 
162
 
151
163
=item DBI::mysql
152
164
 
153
165
A full-featured implementation on top of the MySQL relational database
154
166
system.
155
167
 
156
 
=item bdb
157
 
 
158
 
A partial implementation that runs on top of the BerkeleyDB
159
 
database. The fetch() and store() methods are implemented, but the
160
 
various search functions (e.g. get_features_by_name()) are not.
 
168
=item berkeleydb
 
169
 
 
170
A full-feature implementation that runs on top of the BerkeleyDB
 
171
database. See L<Bio::DB::SeqFeature::Store::berkeleydb>.
 
172
 
161
173
 
162
174
=back
163
175
 
227
239
*dna = *get_dna = *get_sequence = \&fetch_sequence;
228
240
*get_SeqFeatures = \&fetch_SeqFeatures;
229
241
 
 
242
# local version
 
243
sub api_version { 1.2 }
 
244
 
230
245
=head1 Methods for Connecting and Initializating a Database
231
246
 
232
247
=head2 new
249
264
 -serializer        The name of the serializer class (default Storable)
250
265
 
251
266
 -index_subfeatures Whether or not to make subfeatures searchable
252
 
                    (default true)
 
267
                    (default false)
253
268
 
254
269
 -cache             Activate LRU caching feature -- size of cache
255
270
 
256
271
 -compress          Compresses features before storing them in database
257
272
                    using Compress::Zlib
258
273
 
 
274
 -create            (Re)initialize the database.
 
275
 
259
276
The B<-index_subfeatures> argument, if true, tells the module to
260
277
create indexes for a feature and all its subfeatures (and its
261
278
subfeatues' subfeatures). Indexing subfeatures means that you will be
280
297
compressed before storing it. This will make the database somewhat
281
298
smaller at the cost of decreasing performance.
282
299
 
 
300
The B<-create> argument, if true, will either initialize or
 
301
reinitialize the database. It is needed the first time a database is
 
302
used.
 
303
 
283
304
The new() method of individual adaptors recognize additional
284
305
arguments. The default DBI::mysql adaptor recognizes the following
285
306
ones:
303
324
                    L<Bio::DB::SeqFeature::Store::GFF3Loader> for a
304
325
                    description of this. Default is the current
305
326
                    directory.
 
327
 -write             Make the database writeable (implied by -create)
306
328
 
307
329
=cut
308
330
 
354
376
 Args    : (optional) flag to erase current data
355
377
 Status  : public
356
378
 
357
 
Call this after Bio::DB::SeqFeature::Store-E<gt>new() to initialize a new
358
 
database. In the case of a DBI database, this method installs the
 
379
Call this after Bio::DB::SeqFeature::Store-E<gt>new() to initialize a
 
380
new database. In the case of a DBI database, this method installs the
359
381
schema but does B<not> create the database. You have to do this
360
382
offline using the appropriate command-line tool. In the case of the
361
 
"bdb" BerkeleyDB adaptor, this creates an empty BTREE database.
 
383
"berkeleydb" adaptor, this creates an empty BTREE database.
362
384
 
363
385
If there is any data already in the database, init_database() called
364
386
with no arguments will have no effect. To permanently erase the data
462
484
  $self->store_and_cache(0,@_);
463
485
}
464
486
 
 
487
=head2 no_blobs
 
488
 
 
489
 Title   : no_blobs
 
490
 Usage   : $db->no_blobs(1);
 
491
 Function: decide if objects should be stored in the database as blobs.
 
492
 Returns : boolean (default false)
 
493
 Args    : boolean (true to no longer store objects; when the corresponding
 
494
           feature is retrieved it will instead be a minimal representation of
 
495
           the object that was stored, as some simple Bio::SeqFeatureI object)
 
496
 Status  : dubious (new)
 
497
 
 
498
This method saves lots of space in the database, which may in turn lead to large
 
499
performance increases in extreme cases (over 7 million features in the db).
 
500
 
 
501
Currently only applies to the mysql implementation.
 
502
 
 
503
=cut
 
504
 
 
505
sub no_blobs {
 
506
    my $self = shift;
 
507
    if (@_) { $self->{no_blobs} = shift }
 
508
    return $self->{no_blobs} || 0;
 
509
}
 
510
 
465
511
=head2 new_feature
466
512
 
467
513
 Title   : new_feature
555
601
  $success;
556
602
}
557
603
 
 
604
=head2 get_feature_by_id
 
605
 
 
606
 Title   : get_feature_by_id
 
607
 Usage   : $feature = $db->get_feature_by_id($primary_id)
 
608
 Function: fetch a feature from the database using its primary ID
 
609
 Returns : a feature
 
610
 Args    : primary ID of desired feature
 
611
 Status  : public
 
612
 
 
613
This method returns a previously-stored feature from the database
 
614
using its primary ID. If the primary ID is invalid, it returns undef.
 
615
 
 
616
=cut
 
617
 
 
618
sub get_feature_by_id {
 
619
    my $self = shift;
 
620
    $self->fetch(@_);
 
621
}
 
622
 
558
623
=head2 fetch
559
624
 
560
625
 Title   : fetch
564
629
 Args    : primary ID of desired feature
565
630
 Status  : public
566
631
 
567
 
This method returns a previously-stored feature from the database
568
 
using its primary ID. If the primary ID is invalid, it returns undef.
 
632
This is an alias for get_feature_by_id().
569
633
 
570
634
=cut
571
635
 
587
651
  }
588
652
}
589
653
 
 
654
=head2 get_feature_by_primary_id
 
655
 
 
656
 Title   : get_feature_by_primary_id
 
657
 Usage   : $feature = $db->get_feature_by_primary_id($primary_id)
 
658
 Function: fetch a feature from the database using its primary ID
 
659
 Returns : a feature
 
660
 Args    : primary ID of desired feature
 
661
 Status  : public
 
662
 
 
663
This method returns a previously-stored feature from the database
 
664
using its primary ID. If the primary ID is invalid, it returns
 
665
undef. This method is identical to fetch().
 
666
 
 
667
=cut
 
668
 
 
669
sub get_feature_by_primary_id {
 
670
    shift->fetch(@_);
 
671
}
 
672
 
590
673
=head2 fetch_many
591
674
 
592
675
 Title   : fetch_many
667
750
 
668
751
=cut
669
752
 
670
 
# backward compatibility for gbrowse
671
 
sub get_feature_by_name { shift->get_features_by_name(@_) }
672
 
 
673
753
###
674
754
# get_feature_by_name() return 0 or more features using a name lookup
675
755
# uses the Bio::DB::GFF API
690
770
  $self->_features(-name=>$name,-class=>$class,-aliases=>$allow_alias,-type=>$types);
691
771
}
692
772
 
 
773
=head2 get_feature_by_name
 
774
 
 
775
 Title   : get_feature_by_name
 
776
 Usage   : @features = $db->get_feature_by_name($name)
 
777
 Function: looks up features by their display_name
 
778
 Returns : a list of matching features
 
779
 Args    : the desired name
 
780
 Status  : Use get_features_by_name instead.
 
781
 
 
782
This method is provided for backward compatibility with gbrowse.
 
783
 
 
784
=cut
 
785
 
 
786
sub get_feature_by_name { shift->get_features_by_name(@_) }
 
787
 
693
788
=head2 get_features_by_alias
694
789
 
695
790
 Title   : get_features_by_alias
1007
1102
  column 1     The display name of the feature
1008
1103
  column 2     The text of the note
1009
1104
  column 3     A relevance score.
 
1105
  column 4     The feature type
 
1106
  column 5     The unique ID of the feature
1010
1107
 
1011
1108
NOTE: This search will fail to find features that do not have a display name!
1012
1109
 
 
1110
You can use fetch() or fetch_many() with the returned IDs to get to
 
1111
the features themselves.
 
1112
 
1013
1113
=cut
1014
1114
 
1015
1115
sub search_attributes {
1036
1136
  column 1     The display_name of the feature, suitable for passing to get_feature_by_name()
1037
1137
  column 2     The text of the note
1038
1138
  column 3     A relevance score.
 
1139
  column 4     The type
1039
1140
 
1040
1141
NOTE: This is equivalent to $db-E<gt>search_attributes('full text search
1041
1142
string','Note',$limit). This search will fail to find features that do
1052
1153
  return $self->_search_attributes($search_string,['Note'],$limit);
1053
1154
}
1054
1155
 
 
1156
=head2 types
 
1157
 
 
1158
 Title   : types
 
1159
 Usage   : @type_list = $db->types
 
1160
 Function: Get all the types in the database
 
1161
 Returns : array of Bio::DB::GFF::Typename objects
 
1162
 Args    : none
 
1163
 Status  : public
 
1164
 
 
1165
=cut
 
1166
 
 
1167
sub types {
 
1168
    shift->throw_not_implemented;
 
1169
}
 
1170
 
1055
1171
=head2 insert_sequence
1056
1172
 
1057
1173
 Title   : insert_sequence
1120
1236
#
1121
1237
sub fetch_sequence {
1122
1238
  my $self = shift;
1123
 
  my ($seqid,$start,$end,$class,$bioseq) = rearrange([['NAME','SEQID','SEQ_ID'],'START',['END','STOP'],'CLASS','BIOSEQ'],@_);
 
1239
  my ($seqid,$start,$end,$class,$bioseq) = rearrange([['NAME','SEQID','SEQ_ID'],
 
1240
                                                      'START',['END','STOP'],'CLASS','BIOSEQ'],@_);
1124
1241
  $seqid = "$seqid:$class" if defined $class;
1125
1242
  my $seq = $self->_fetch_sequence($seqid,$start,$end);
1126
1243
  return $seq unless $bioseq;
1133
1250
=head2 segment
1134
1251
 
1135
1252
 Title   : segment
1136
 
 Usage   : $segment = $db->segment($seq_id [,$start] [,$end])
 
1253
 Usage   : $segment = $db->segment($seq_id [,$start] [,$end] [,$absolute])
1137
1254
 Function: restrict the database to a sequence range
1138
1255
 Returns : a Bio::DB::SeqFeature::Segment object
1139
1256
 Args    : sequence id, start and end ranges (optional)
1158
1275
a get_features_by_name() internally and then transform the feature
1159
1276
into the appropriate coordinates.
1160
1277
 
 
1278
If $absolute is a true value, then the specified coordinates are
 
1279
relative to the reference (absolute) coordinates.
 
1280
 
1161
1281
=cut
1162
1282
 
1163
1283
###
1181
1301
Either call in a list context or narrow your search using the -types or -class arguments
1182
1302
END
1183
1303
  }
1184
 
  my ($rel_start,$rel_end) = rearrange(['START',['STOP','END']],@args);
 
1304
  my ($rel_start,$rel_end,$abs) = rearrange(['START',['STOP','END'],'ABSOLUTE'],@args);
1185
1305
  $rel_start = 1 unless defined $rel_start;
1186
1306
 
1187
1307
  my @segments;
1189
1309
    my $seqid  = $f->seq_id;
1190
1310
    my $strand = $f->strand;
1191
1311
    my ($start,$end);
1192
 
    my $re = defined $rel_end ? $rel_end : $f->end - $f->start + 1;
1193
 
 
1194
 
    if ($strand >= 0) {
1195
 
      $start = $f->start + $rel_start - 1;
1196
 
      $end   = $f->start + $re   - 1;
 
1312
    if ($abs) {
 
1313
      $start = $rel_start;
 
1314
      $end   = defined $rel_end ? $rel_end : $start + $f->length - 1;
1197
1315
    }
1198
1316
    else {
1199
 
      $start = $f->end - $re   + 1;
1200
 
      $end   = $f->end - $rel_start + 1;
 
1317
      my $re = defined $rel_end ? $rel_end : $f->end - $f->start + 1;
 
1318
 
 
1319
      if ($strand >= 0) {
 
1320
        $start = $f->start + $rel_start - 1;
 
1321
        $end   = $f->start + $re   - 1;
 
1322
      }
 
1323
      else {
 
1324
        $start = $f->end - $re   + 1;
 
1325
        $end   = $f->end - $rel_start + 1;
 
1326
      }
1201
1327
    }
1202
1328
    push @segments,Bio::DB::SeqFeature::Segment->new($self,$seqid,$start,$end,$strand);
1203
1329
  }
1270
1396
  $self->_end_reindexing;
1271
1397
}
1272
1398
 
 
1399
=head2 attributes
 
1400
 
 
1401
 Title   : attributes
 
1402
 Usage   : @a = $db->attributes
 
1403
 Function: Returns list of all known attributes
 
1404
 Returns : Returns list of all known attributes
 
1405
 Args    : nothing
 
1406
 Status  : public
 
1407
 
 
1408
=cut
 
1409
 
 
1410
sub attributes {
 
1411
    my $self = shift;
 
1412
    shift->throw_not_implemented;
 
1413
}
 
1414
 
 
1415
 
1273
1416
=head2 start_bulk_update,finish_bulk_update
1274
1417
 
1275
1418
 Title   : start_bulk_update,finish_bulk_update
1447
1590
  $d;
1448
1591
}
1449
1592
 
 
1593
=head2 clone
 
1594
 
 
1595
The clone() method should be used when you want to pass the
 
1596
Bio::DB::SeqFeature::Store object to a child process across a
 
1597
fork(). The child must call clone() before making any queries.
 
1598
 
 
1599
The default behavior is to do nothing, but adaptors that use the DBI
 
1600
interface may need to implement this in order to avoid database handle
 
1601
errors. See the dbi adaptor for an example.
 
1602
 
 
1603
=cut
 
1604
 
 
1605
sub clone { }
 
1606
 
1450
1607
################################# TIE interface ####################
1451
1608
 
1452
1609
=head1 TIE Interface
2338
2495
L<Bio::DB::SeqFeature::Store::GFF3Loader>,
2339
2496
L<Bio::DB::SeqFeature::Segment>,
2340
2497
L<Bio::DB::SeqFeature::Store::DBI::mysql>,
2341
 
L<Bio::DB::SeqFeature::Store::bdb>
 
2498
L<Bio::DB::SeqFeature::Store::berkeleydb>
 
2499
L<Bio::DB::SeqFeature::Store::memory>
2342
2500
 
2343
2501
=head1 AUTHOR
2344
2502