1 #-------------------------------------------------------------------------------
3 # BioPerl module Bio::Restriction::EnzymeCollection
5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
7 # Cared for by Rob Edwards <redwards@utmem.edu>
9 # You may distribute this module under the same terms as perl itself
10 #-------------------------------------------------------------------------------
16 Bio::Restriction::EnzymeCollection - Set of restriction endonucleases
20 use Bio::Restriction::EnzymeCollection;
22 # Create a collection with the default enzymes.
23 my $default_collection = Bio::Restriction::EnzymeCollection->new();
25 # Or create a collection from a REBASE 'withrefm' file obtained from
26 # ftp://ftp.neb.com/pub/rebase/. (See Bio::Restriction::IO for more
28 my $rebase = Bio::Restriction::IO->new(
29 -file => 'withrefm.610',
30 -format => 'withrefm' );
31 my $rebase_collection = $rebase->read();
33 # Or create an empty collection and set the enzymes later. See
34 # 'CUSTOM COLLECTIONS' below for more information.
35 my $empty_collection =
36 Bio::Restriction::EnzymeCollection->new( -empty => 1 );
38 # Get an array of Bio::Restriction::Enzyme objects from the collection.
39 my @enzymes = $default_collection->each_enzyme();
41 # Get a Bio::Restriction::Enzyme object for a particular enzyme by name.
42 my $enz = $default_collection->get_enzyme( 'EcoRI' );
44 # Get a Bio::Restriction::EnzymeCollection object containing the enzymes
45 # that have the equivalent of 6-bp recognition sequences.
46 my $six_cutters = $default_collection->cutters( 6 );
48 # Get a Bio::Restriction::EnzymeCollection object containing the enzymes
49 # that are rare cutters.
50 my $rare_cutters = $default_collection->cutters( -start => 6, -end => 8 );
52 # Get a Bio::Restriction::EnzymeCollection object that contains enzymes
53 # that generate blunt ends:
54 my $blunt_cutters = $default_collection->blunt_enzymes();
56 # See 'CUSTOM COLLECTIONS' below for an example of creating a
57 # Bio::Restriction::EnzymeCollection object with a specified subset of
58 # enzymes using methods provided by the Bio::RestrictionEnzyme class.
62 Bio::Restriction::EnzymeCollection represents a collection of
65 If you create a new collection directly rather than from a REBASE
66 file using L<Bio::Restriction::IO>, it will be populated by a
67 default set of enzymes with site and cut information
70 Use L<Bio::Restriction::Analysis> to figure out which enzymes are
71 available and where they cut your sequence.
73 =head1 CUSTOM COLLECTIONS
75 Note that the underlying L<Bio::Restriction::Enzyme> objects have a rich
76 variety of methods that allow more complicated selections than the methods
77 that are defined by Bio::Restriction::EnzymeCollection.
79 For example, the way to create a custom collection of Type II enzymes
82 my $complete_collection =
83 Bio::Restriction::EnzymeCollection->new();
84 my $type_ii_collection =
85 Bio::Restriction::EnzymeCollection->new( -empty => 1 );
86 $type_ii_collection->enzymes(
87 grep { $_->type() eq 'II' } $complete_collection->each_enzyme() );
91 L<Bio::Restriction::IO> - read in enzymes from REBASE files
93 L<Bio::Restriction::Analysis> - figure out what enzymes cut a sequence
95 L<Bio::Restriction::Enzyme> - define a single restriction enzyme
101 User feedback is an integral part of the evolution of this and other
102 Bioperl modules. Send your comments and suggestions preferably to one
103 of the Bioperl mailing lists. Your participation is much appreciated.
105 bioperl-l@bioperl.org - General discussion
106 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
110 Please direct usage questions or support issues to the mailing list:
112 I<bioperl-l@bioperl.org>
114 rather than to the module maintainer directly. Many experienced and
115 reponsive experts will be able look at the problem and quickly
116 address it. Please include a thorough description of the problem
117 with code and data examples if at all possible.
119 =head2 Reporting Bugs
121 Report bugs to the Bioperl bug tracking system to help us keep track
122 the bugs and their resolution. Bug reports can be submitted via the
125 https://github.com/bioperl/bioperl-live/issues
129 Rob Edwards, redwards@utmem.edu
133 Heikki Lehvaslaiho, heikki-at-bioperl-dot-org
137 Copyright (c) 2003 Rob Edwards.
139 Some of this work is Copyright (c) 1997-2002 Steve A. Chervitz. All
142 This module is free software; you can redistribute it and/or modify it
143 under the same terms as Perl itself.
147 Methods beginning with a leading underscore are considered private and
148 are intended for internal use by this module. They are not considered
149 part of the public interface and are described here for documentation
155 package Bio
::Restriction
::EnzymeCollection
;
158 use Bio
::Restriction
::Enzyme
;
159 use Bio
::Restriction
::IO
;
163 use base
qw(Bio::Root::Root);
168 Function : Initializes the Restriction::EnzymeCollection object
169 Returns : The Restriction::EnzymeCollection object
170 Arguments : optional named parameter -empty
172 Set parameter -empty to true if you do NOT want the collection be
173 populated by the default set of prototype type II enzymes.
175 Alternatively, pass an array of enzymes to -enzymes parameter.
180 my($class, @args) = @_;
181 my $self = $class->SUPER::new
(@args);
183 my ($empty, $enzymes) =
184 $self->_rearrange([qw(
189 $self->{'_all_enzymes'} = [];
190 $self->{'_enzymes'} = {};
192 return $self if $empty;
196 # as advertised in pod/maj
197 $self->throw( "Arg to -enzymes must be an arrayref to Bio::Restriction::Enzyme objects") unless ref($enzymes) eq 'ARRAY';
198 $self->enzymes(@
$enzymes);
202 # the default set of enzymes
203 my $in = Bio
::Restriction
::IO
->new(-verbose
=> $self->verbose);
208 =head2 Manipulate the enzymes within the collection
215 Function : add/get method for enzymes and enzyme collections
216 Returns : object itself
217 Arguments : array of Bio::Restriction::Enzyme and
218 Bio::Restriction::EnzymeCollection objects
223 my ($self, @enzs)=@_;
224 foreach my $e (@enzs) {
228 elsif ($e->isa('Bio::Restriction::EnzymeI')) {
229 push(@
{$self->{'_all_enzymes'}},$e);
230 $self->{'_enzymes'}->{$e->name} = $e;
232 elsif ($e->isa('Bio::Restriction::EnzymeCollection')) {
233 $self->enzymes($e->each_enzyme);
236 $self->warn("EnzymeCollection can not deal with ".
244 # method to remove duplicates?
250 Function : get an array of enzymes
251 Returns : array of Bio::Restriction::Enzyme objects
258 return @
{$self->{'_all_enzymes'}};
264 Function : Gets a Bio::Restriction::Enzyme object for the enzyme name
265 Returns : A Bio::Restriction::Enzyme object or undef
266 Arguments : An enzyme name that is in the collection
271 my ($self, $name)=@_;
272 return $self->{'_enzymes'}->{$name};
276 =head2 available_list
278 Title : available_list
279 Function : Gets a list of all the enzymes that we know about
280 Returns : A reference to an array with all the enzyme names
281 that we have defined or 0 if none are defined
283 Comments : Note, I maintain this for backwards compatibility,
284 but I don't like the name as it is very ambiguous
289 my ($self, $size)=@_;
290 my @keys = sort keys %{$self->{'_enzymes'}};
294 =head2 longest_cutter
296 Title : longest_cutter
297 Function : Gets the enzyme with the longest recognition site
298 Returns : A Bio::Restriction::Enzyme object
300 Comments : Note, this is used by Bio::Restriction::Analysis
301 to figure out what to do with circular sequences
307 my $longest=0; my $longest_enz='.';
308 foreach my $enz ($self->each_enzyme) {
309 my $len=$enz->recognition_length;
310 if ($len > $longest) {$longest=$len; $longest_enz=$enz}
315 =head2 Filter enzymes
321 Title : blunt_enzymes
322 Function : Gets a list of all the enzymes that are blunt cutters
323 Returns : A reference to an array with all the enzyme names that
324 are blunt cutters or 0 if none are defined
328 This is an example of the kind of filtering better done by the scripts
329 using the rich collection of methods in Bio::Restriction::Enzyme.
335 my $bs = Bio
::Restriction
::EnzymeCollection
->new(-empty
=> 1);
336 return $bs->enzymes( grep { $_->overhang eq 'blunt' } $self->each_enzyme );
343 Function : Gets a list of all the enzymes that recognize a
344 certain size, e.g. 6-cutters
345 Usage : $cutters = $collection->cutters(6);
346 Returns : A reference to an array with all the enzyme names
347 that are x cutters or 0 if none are defined
348 Arguments : A positive number for the size of cutters to return
350 A range: (-start => 6, -end => 8,
351 -inclusive => 1, -exclusive = 0 )
353 The default for a range is 'inclusive'
361 return unless @_; # no argument
363 if (scalar @_ == 1 ) {
366 (ref $size eq 'ARRAY') ?
push @sizes, @
{$size} : push @sizes, $size;
367 my $bs = Bio
::Restriction
::EnzymeCollection
->new(-empty
=> 1);
368 for my $size (@sizes) {
369 $self->throw("Need a positive number [$size]")
370 unless $size =~ /[+]?[\d\.]+/;
371 foreach my $e ($self->each_enzyme) {
372 ##print $e->name, ": ", $e->cutter, "\n" if $e->cutter == $size;
373 $bs->enzymes($e) if $e->cutter == $size;
378 } else { # named arguments
380 my ($start, $end, $inclusive, $exclusive ) =
381 $self->_rearrange([qw(
388 $self->throw("Start needs a positive number [$start]")
389 unless $start =~ /[+]?[\d\.]+/;
390 $self->throw("End needs a positive number [$end]")
391 unless $end =~ /[+]?[\d\.]+/;
394 $inclusive = 1 if $inclusive or not $exclusive;
395 $inclusive = 0 if $exclusive;
397 my $bs = Bio
::Restriction
::EnzymeCollection
->new(-empty
=> 1);
399 foreach my $e ($self->each_enzyme) {
400 $bs->enzymes($e) if $e->cutter >= $start and $e->cutter <= $end;
403 foreach my $e ($self->each_enzyme) {
404 $bs->enzymes($e) if $e->cutter > $start and $e->cutter < $end;