| 1 | # | ||||||||||||||
| 2 | # BioPerl module for Bio::FeatureHolderI | ||||||||||||||
| 3 | # | ||||||||||||||
| 4 | # Please direct questions and support issues to <bioperl-l@bioperl.org> | ||||||||||||||
| 5 | # | ||||||||||||||
| 6 | # Cared for by Hilmar Lapp <hlapp at gmx.net> | ||||||||||||||
| 7 | # | ||||||||||||||
| 8 | # Copyright Hilmar Lapp | ||||||||||||||
| 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::FeatureHolderI - the base interface an object with features must implement | ||||||||||||||
| 17 | |||||||||||||||
| 18 | =head1 SYNOPSIS | ||||||||||||||
| 19 | |||||||||||||||
| 20 | use Bio::SeqIO; | ||||||||||||||
| 21 | # get a feature-holding object somehow: for example, Bio::SeqI objects | ||||||||||||||
| 22 | # have features | ||||||||||||||
| 23 | my $seqio = Bio::SeqIO->new(-fh => \*STDIN, -format => 'genbank'); | ||||||||||||||
| 24 | while (my $seq = $seqio->next_seq()) { | ||||||||||||||
| 25 | # $seq is-a Bio::FeatureHolderI, hence: | ||||||||||||||
| 26 | my @feas = $seq->get_SeqFeatures(); | ||||||||||||||
| 27 | # each element is-a Bio::SeqFeatureI | ||||||||||||||
| 28 | foreach my $fea (@feas) { | ||||||||||||||
| 29 | # do something with the feature objects | ||||||||||||||
| 30 | } | ||||||||||||||
| 31 | } | ||||||||||||||
| 32 | |||||||||||||||
| 33 | =head1 DESCRIPTION | ||||||||||||||
| 34 | |||||||||||||||
| 35 | This is the base interface that all feature-holding objects must | ||||||||||||||
| 36 | implement. | ||||||||||||||
| 37 | |||||||||||||||
| 38 | Popular feature-holders are for instance L<Bio::Seq> objects. Since | ||||||||||||||
| 39 | L<Bio::SeqFeatureI> defines a sub_SeqFeature() method, most | ||||||||||||||
| 40 | Bio::SeqFeatureI implementations like L<Bio::SeqFeature::Generic> will | ||||||||||||||
| 41 | implement the feature holder interface as well. | ||||||||||||||
| 42 | |||||||||||||||
| 43 | =head1 FEEDBACK | ||||||||||||||
| 44 | |||||||||||||||
| 45 | =head2 Mailing Lists | ||||||||||||||
| 46 | |||||||||||||||
| 47 | User feedback is an integral part of the evolution of this and other | ||||||||||||||
| 48 | Bioperl modules. Send your comments and suggestions preferably to | ||||||||||||||
| 49 | the Bioperl mailing list. Your participation is much appreciated. | ||||||||||||||
| 50 | |||||||||||||||
| 51 | bioperl-l@bioperl.org - General discussion | ||||||||||||||
| 52 | http://bioperl.org/wiki/Mailing_lists - About the mailing lists | ||||||||||||||
| 53 | |||||||||||||||
| 54 | =head2 Support | ||||||||||||||
| 55 | |||||||||||||||
| 56 | Please direct usage questions or support issues to the mailing list: | ||||||||||||||
| 57 | |||||||||||||||
| 58 | I<bioperl-l@bioperl.org> | ||||||||||||||
| 59 | |||||||||||||||
| 60 | rather than to the module maintainer directly. Many experienced and | ||||||||||||||
| 61 | reponsive experts will be able look at the problem and quickly | ||||||||||||||
| 62 | address it. Please include a thorough description of the problem | ||||||||||||||
| 63 | with code and data examples if at all possible. | ||||||||||||||
| 64 | |||||||||||||||
| 65 | =head2 Reporting Bugs | ||||||||||||||
| 66 | |||||||||||||||
| 67 | Report bugs to the Bioperl bug tracking system to help us keep track | ||||||||||||||
| 68 | of the bugs and their resolution. Bug reports can be submitted via the | ||||||||||||||
| 69 | web: | ||||||||||||||
| 70 | |||||||||||||||
| 71 | https://github.com/bioperl/bioperl-live/issues | ||||||||||||||
| 72 | |||||||||||||||
| 73 | =head1 AUTHOR - Hilmar Lapp | ||||||||||||||
| 74 | |||||||||||||||
| 75 | Email hlapp at gmx.net | ||||||||||||||
| 76 | |||||||||||||||
| 77 | =head1 CONTRIBUTORS | ||||||||||||||
| 78 | |||||||||||||||
| 79 | Steffen Grossmann [SG], grossman-at-molgen.mpg.de | ||||||||||||||
| 80 | Mark A. Jensen, maj -at- fortinbras -dot- us | ||||||||||||||
| 81 | |||||||||||||||
| 82 | =head1 APPENDIX | ||||||||||||||
| 83 | |||||||||||||||
| 84 | The rest of the documentation details each of the object methods. | ||||||||||||||
| 85 | Internal methods are usually preceded with a _ | ||||||||||||||
| 86 | |||||||||||||||
| 87 | =cut | ||||||||||||||
| 88 | |||||||||||||||
| 89 | |||||||||||||||
| 90 | # Let the code begin... | ||||||||||||||
| 91 | |||||||||||||||
| 92 | |||||||||||||||
| 93 | |||||||||||||||
| 94 | package Bio::FeatureHolderI; | ||||||||||||||
| 95 | 303 | $Bio::FeatureHolderI::VERSION = '1.7.8'; | |||||||||||||
| 96 | 303 | ▶ | use strict; | ||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||
| 97 | 303 | ▶ | use Carp; | ||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||
| 98 | |||||||||||||||
| 99 | 303 | ▶ | use base qw(Bio::Root::RootI); | ||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||
| 100 | |||||||||||||||
| 101 | =head2 get_SeqFeatures() | ||||||||||||||
| 102 | |||||||||||||||
| 103 | Usage : @feats = $obj->get_SeqFeatures() | ||||||||||||||
| 104 | Function: Get the feature objects held by this feature holder. | ||||||||||||||
| 105 | Example : | ||||||||||||||
| 106 | Returns : an array of Bio::SeqFeatureI implementing objects | ||||||||||||||
| 107 | if tag specified, return features having that tag | ||||||||||||||
| 108 | Args : [optional] scalar string (feature tag) | ||||||||||||||
| 109 | |||||||||||||||
| 110 | =cut | ||||||||||||||
| 111 | |||||||||||||||
| 112 | 0 | ▶ | sub get_SeqFeatures { | ||||||||||||
|
Subroutine
get_SeqFeatures: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||||||
| 113 | 0 | shift->throw_not_implemented(); | |||||||||||||
| 114 | } | ||||||||||||||
| 115 | |||||||||||||||
| 116 | =head2 add_SeqFeature() | ||||||||||||||
| 117 | |||||||||||||||
| 118 | Usage : $feat->add_SeqFeature($subfeat); | ||||||||||||||
| 119 | $feat->add_SeqFeature($subfeat,'EXPAND') | ||||||||||||||
| 120 | Function: Add a SeqFeature into the subSeqFeature array. | ||||||||||||||
| 121 | with no 'EXPAND' qualifer, subfeat will be tested | ||||||||||||||
| 122 | as to whether it lies inside the parent, and throw | ||||||||||||||
| 123 | an exception if not. | ||||||||||||||
| 124 | |||||||||||||||
| 125 | If EXPAND is used and the object implements Bio::RangeI | ||||||||||||||
| 126 | (which is not guaranteed), the parent''s start/end/strand | ||||||||||||||
| 127 | will be extended so that the new subFeature can be accomodated. | ||||||||||||||
| 128 | Example : | ||||||||||||||
| 129 | Returns : nothing | ||||||||||||||
| 130 | Args : a Bio::SeqFeatureI object | ||||||||||||||
| 131 | |||||||||||||||
| 132 | =cut | ||||||||||||||
| 133 | |||||||||||||||
| 134 | 0 | ▶ | sub add_SeqFeature { | ||||||||||||
|
Subroutine
add_SeqFeature: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||||||
| 135 | 0 | shift->throw_not_implemented(); | |||||||||||||
| 136 | } | ||||||||||||||
| 137 | |||||||||||||||
| 138 | |||||||||||||||
| 139 | =head2 remove_SeqFeatures() | ||||||||||||||
| 140 | |||||||||||||||
| 141 | Usage : $obj->remove_SeqFeatures | ||||||||||||||
| 142 | Function: Removes all sub SeqFeatures. If you want to remove only a subset, | ||||||||||||||
| 143 | remove that subset from the returned array, and add back the rest. | ||||||||||||||
| 144 | Returns : The array of Bio::SeqFeatureI implementing sub-features that was | ||||||||||||||
| 145 | deleted from this feature. | ||||||||||||||
| 146 | Args : none | ||||||||||||||
| 147 | |||||||||||||||
| 148 | =cut | ||||||||||||||
| 149 | |||||||||||||||
| 150 | 0 | ▶ | sub remove_SeqFeatures { | ||||||||||||
|
Subroutine
remove_SeqFeatures: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||||||
| 151 | 0 | shift->throw_not_implemented(); | |||||||||||||
| 152 | } | ||||||||||||||
| 153 | |||||||||||||||
| 154 | =head2 feature_count | ||||||||||||||
| 155 | |||||||||||||||
| 156 | Title : feature_count | ||||||||||||||
| 157 | Usage : $obj->feature_count() | ||||||||||||||
| 158 | Function: Return the number of SeqFeatures attached to a feature holder. | ||||||||||||||
| 159 | |||||||||||||||
| 160 | This is before flattening a possible sub-feature tree. | ||||||||||||||
| 161 | |||||||||||||||
| 162 | We provide a default implementation here that just counts | ||||||||||||||
| 163 | the number of objects returned by get_SeqFeatures(). | ||||||||||||||
| 164 | Implementors may want to override this with a more | ||||||||||||||
| 165 | efficient implementation. | ||||||||||||||
| 166 | |||||||||||||||
| 167 | Returns : integer representing the number of SeqFeatures | ||||||||||||||
| 168 | Args : None | ||||||||||||||
| 169 | |||||||||||||||
| 170 | At some day we may want to expand this method to allow for a feature | ||||||||||||||
| 171 | filter to be passed in. | ||||||||||||||
| 172 | |||||||||||||||
| 173 | Our default implementation allows for any number of additional | ||||||||||||||
| 174 | arguments and will pass them on to get_SeqFeatures(). I.e., in order to | ||||||||||||||
| 175 | support filter arguments, just support them in get_SeqFeatures(). | ||||||||||||||
| 176 | |||||||||||||||
| 177 | =cut | ||||||||||||||
| 178 | |||||||||||||||
| 179 | 0 | ▶ | sub feature_count { | ||||||||||||
|
Subroutine
feature_count: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||||||
| 180 | 0 | return scalar(shift->get_SeqFeatures(@_)); | |||||||||||||
| 181 | } | ||||||||||||||
| 182 | |||||||||||||||
| 183 | =head2 get_all_SeqFeatures | ||||||||||||||
| 184 | |||||||||||||||
| 185 | Title : get_all_SeqFeatures | ||||||||||||||
| 186 | Usage : | ||||||||||||||
| 187 | Function: Get the flattened tree of feature objects held by this | ||||||||||||||
| 188 | feature holder. The difference to get_SeqFeatures is that | ||||||||||||||
| 189 | the entire tree of sub-features will be flattened out. | ||||||||||||||
| 190 | |||||||||||||||
| 191 | We provide a default implementation here, so implementors | ||||||||||||||
| 192 | don''t necessarily need to implement this method. | ||||||||||||||
| 193 | |||||||||||||||
| 194 | Example : | ||||||||||||||
| 195 | Returns : an array of Bio::SeqFeatureI implementing objects | ||||||||||||||
| 196 | Args : none | ||||||||||||||
| 197 | |||||||||||||||
| 198 | At some day we may want to expand this method to allow for a feature | ||||||||||||||
| 199 | filter to be passed in. | ||||||||||||||
| 200 | |||||||||||||||
| 201 | Our default implementation allows for any number of additional | ||||||||||||||
| 202 | arguments and will pass them on to any invocation of | ||||||||||||||
| 203 | get_SeqFeatures(), wherever a component of the tree implements | ||||||||||||||
| 204 | FeatureHolderI. I.e., in order to support filter arguments, just | ||||||||||||||
| 205 | support them in get_SeqFeatures(). | ||||||||||||||
| 206 | |||||||||||||||
| 207 | =cut | ||||||||||||||
| 208 | |||||||||||||||
| 209 | 2069 | ▶ | sub get_all_SeqFeatures{ | ||||||||||||
|
Subroutine
get_all_SeqFeatures: called CC=4 SCAR=13.9
Pod
documented
| |||||||||||||||
| 210 | 2069 | my $self = shift; | |||||||||||||
| 211 | 2069 | my @flatarr; | |||||||||||||
| 212 | |||||||||||||||
| 213 | 2069 | foreach my $feat ( $self->get_SeqFeatures(@_) ){ | |||||||||||||
| 214 | 8767 | push(@flatarr,$feat); | |||||||||||||
| 215 | 8767 | &_add_flattened_SeqFeatures(\@flatarr,$feat,@_); | |||||||||||||
| 216 | } | ||||||||||||||
| 217 | |||||||||||||||
| 218 | # needed to deal with subfeatures which appear more than once in the hierarchy [SG] | ||||||||||||||
| 219 | 2069 | my %seen = (); | |||||||||||||
| 220 | 2069 | my @uniq_flatarr = (); | |||||||||||||
| 221 | 2069 | foreach my $feat (@flatarr) { | |||||||||||||
| 222 | 10782 | ▶ | push(@uniq_flatarr, $feat) unless $seen{$feat}++; | ||||||||||||
|
Branch: 1 branch
| |||||||||||||||
| 223 | } | ||||||||||||||
| 224 | 2069 | return @uniq_flatarr; | |||||||||||||
| 225 | } | ||||||||||||||
| 226 | |||||||||||||||
| 227 | 10782 | ▶ | sub _add_flattened_SeqFeatures { | ||||||||||||
|
Subroutine
_add_flattened_SeqFeatures: called CC=4 SCAR=15.9
| |||||||||||||||
| 228 | 10782 | my ($arrayref,$feat,@args) = @_; | |||||||||||||
| 229 | 10782 | my @subs = (); | |||||||||||||
| 230 | |||||||||||||||
| 231 | 10782 | ▶ | if($feat->isa("Bio::FeatureHolderI")) { | ||||||||||||
|
Branch: 2 branches
| |||||||||||||||
| 232 | 10782 | @subs = $feat->get_SeqFeatures(@args); | |||||||||||||
| 233 | } elsif($feat->isa("Bio::SeqFeatureI")) { | ||||||||||||||
| 234 | 0 | @subs = $feat->sub_SeqFeature(); | |||||||||||||
| 235 | } else { | ||||||||||||||
| 236 | 0 | confess ref($feat)." is neither a FeatureHolderI nor a SeqFeatureI. ". | |||||||||||||
| 237 | "Don't know how to flatten."; | ||||||||||||||
| 238 | } | ||||||||||||||
| 239 | 10782 | foreach my $sub (@subs) { | |||||||||||||
| 240 | 2015 | push(@$arrayref,$sub); | |||||||||||||
| 241 | 2015 | &_add_flattened_SeqFeatures($arrayref,$sub); | |||||||||||||
| 242 | } | ||||||||||||||
| 243 | |||||||||||||||
| 244 | } | ||||||||||||||
| 245 | |||||||||||||||
| 246 | 0 | ▶ | sub set_ParentIDs_from_hierarchy(){ | ||||||||||||
|
Subroutine
set_ParentIDs_from_hierarchy: not called CC=1 SCAR=6.9
Pod
undocumented
| |||||||||||||||
| 247 | # DEPRECATED - use IDHandler | ||||||||||||||
| 248 | 0 | my $self = shift; | |||||||||||||
| 249 | 0 | require "Bio/SeqFeature/Tools/IDHandler.pm"; | |||||||||||||
| 250 | 0 | Bio::SeqFeature::Tools::IDHandler->new->set_ParentIDs_from_hierarchy($self); | |||||||||||||
| 251 | } | ||||||||||||||
| 252 | |||||||||||||||
| 253 | 0 | ▶ | sub create_hierarchy_from_ParentIDs(){ | ||||||||||||
|
Subroutine
create_hierarchy_from_ParentIDs: not called CC=1 SCAR=6.9
Pod
undocumented
| |||||||||||||||
| 254 | # DEPRECATED - use IDHandler | ||||||||||||||
| 255 | 0 | my $self = shift; | |||||||||||||
| 256 | 0 | require "Bio/SeqFeature/Tools/IDHandler.pm"; | |||||||||||||
| 257 | 0 | Bio::SeqFeature::Tools::IDHandler->new->create_hierarchy_from_ParentIDs($self); | |||||||||||||
| 258 | } | ||||||||||||||
| 259 | |||||||||||||||
| 260 | |||||||||||||||
| 261 | |||||||||||||||
| 262 | 303 | 1; | |||||||||||||