| 1 | package Bio::Graphics::Feature; | ||
| 2 | |||
| 3 | =head1 NAME | ||
| 4 | |||
| 5 | Bio::Graphics::Feature - A simple feature object for use with Bio::Graphics::Panel | ||
| 6 | |||
| 7 | =head1 SYNOPSIS | ||
| 8 | |||
| 9 | use Bio::Graphics::Feature; | ||
| 10 | |||
| 11 | # create a simple feature with no internal structure | ||
| 12 | $f = Bio::Graphics::Feature->new(-start => 1000, | ||
| 13 | -stop => 2000, | ||
| 14 | -type => 'transcript', | ||
| 15 | -name => 'alpha-1 antitrypsin', | ||
| 16 | -desc => 'an enzyme inhibitor', | ||
| 17 | ); | ||
| 18 | |||
| 19 | # create a feature composed of multiple segments, all of type "similarity" | ||
| 20 | $f = Bio::Graphics::Feature->new(-segments => [[1000,1100],[1500,1550],[1800,2000]], | ||
| 21 | -name => 'ABC-3', | ||
| 22 | -type => 'gapped_alignment', | ||
| 23 | -subtype => 'similarity'); | ||
| 24 | |||
| 25 | # build up a gene exon by exon | ||
| 26 | $e1 = Bio::Graphics::Feature->new(-start=>1,-stop=>100,-type=>'exon'); | ||
| 27 | $e2 = Bio::Graphics::Feature->new(-start=>150,-stop=>200,-type=>'exon'); | ||
| 28 | $e3 = Bio::Graphics::Feature->new(-start=>300,-stop=>500,-type=>'exon'); | ||
| 29 | $f = Bio::Graphics::Feature->new(-segments=>[$e1,$e2,$e3],-type=>'gene'); | ||
| 30 | |||
| 31 | =head1 DESCRIPTION | ||
| 32 | |||
| 33 | This is a simple Bio::SeqFeatureI-compliant object that is compatible | ||
| 34 | with Bio::Graphics::Panel. With it you can create lightweight feature | ||
| 35 | objects for drawing. | ||
| 36 | |||
| 37 | All methods are as described in L<Bio::SeqFeatureI> with the following additions: | ||
| 38 | |||
| 39 | =head2 The new() Constructor | ||
| 40 | |||
| 41 | $feature = Bio::Graphics::Feature->new(@args); | ||
| 42 | |||
| 43 | This method creates a new feature object. You can create a simple | ||
| 44 | feature that contains no subfeatures, or a hierarchically nested object. | ||
| 45 | |||
| 46 | Arguments are as follows: | ||
| 47 | |||
| 48 | -seq_id the reference sequence | ||
| 49 | -start the start position of the feature | ||
| 50 | -end the stop position of the feature | ||
| 51 | -stop an alias for end | ||
| 52 | -name the feature name (returned by seqname()) | ||
| 53 | -type the feature type (returned by primary_tag()) | ||
| 54 | -primary_tag the same as -type | ||
| 55 | -source the source tag | ||
| 56 | -score the feature score (for GFF compatibility) | ||
| 57 | -desc a description of the feature | ||
| 58 | -segments a list of subfeatures (see below) | ||
| 59 | -subtype the type to use when creating subfeatures | ||
| 60 | -strand the strand of the feature (one of -1, 0 or +1) | ||
| 61 | -phase the phase of the feature (0..2) | ||
| 62 | -id an alias for -name | ||
| 63 | -seqname an alias for -name | ||
| 64 | -display_id an alias for -name | ||
| 65 | -display_name an alias for -name (do you get the idea the API has changed?) | ||
| 66 | -primary_id unique database ID | ||
| 67 | -url a URL to link to when rendered with Bio::Graphics | ||
| 68 | -configurator an object (like a Bio::Graphics::FeatureFile) that knows how | ||
| 69 | to configure the graphical representation of the object based | ||
| 70 | on its type. | ||
| 71 | -attributes a hashref of tag value attributes, in which the key is the tag | ||
| 72 | and the value is an array reference of values | ||
| 73 | -factory a reference to a feature factory, used for compatibility with | ||
| 74 | more obscure parts of Bio::DB::GFF | ||
| 75 | |||
| 76 | The subfeatures passed in -segments may be an array of | ||
| 77 | Bio::Graphics::Feature objects, or an array of [$start,$stop] | ||
| 78 | pairs. Each pair should be a two-element array reference. In the | ||
| 79 | latter case, the feature type passed in -subtype will be used when | ||
| 80 | creating the subfeatures. | ||
| 81 | |||
| 82 | If no feature type is passed, then it defaults to "feature". | ||
| 83 | |||
| 84 | =head2 Non-SeqFeatureI methods | ||
| 85 | |||
| 86 | A number of new methods are provided for compatibility with | ||
| 87 | Ace::Sequence, which has a slightly different API from SeqFeatureI: | ||
| 88 | |||
| 89 | =over 4 | ||
| 90 | |||
| 91 | =item attributes() | ||
| 92 | |||
| 93 | An alternative interface to get_tag_values. Pass the name of an | ||
| 94 | attribute to get the value(s) of that attribute: | ||
| 95 | |||
| 96 | $expression_level = $gene->attributes('expression'); | ||
| 97 | |||
| 98 | Call attributes() without any arguments to get a hash of all | ||
| 99 | attributes: | ||
| 100 | |||
| 101 | %attributes = $gene->attributes; | ||
| 102 | |||
| 103 | =item url() | ||
| 104 | |||
| 105 | Get/set the URL that the graphical rendering of this feature will link to. | ||
| 106 | |||
| 107 | =item add_segment(@segments) | ||
| 108 | |||
| 109 | Add one or more segments (a subfeature). Segments can either be | ||
| 110 | Feature objects, or [start,stop] arrays, as in the -segments argument | ||
| 111 | to new(). The feature endpoints are automatically adjusted. | ||
| 112 | |||
| 113 | =item my @features = get_SeqFeatures('type1','type2','type3'...) | ||
| 114 | |||
| 115 | Get the subfeatures of this feature. If an optional list of types is | ||
| 116 | provided, then only returns subfeatures with the indicated | ||
| 117 | primary_tag. (This is an extension of the Bio::SeqFeatureI interface). | ||
| 118 | |||
| 119 | =item $feature->add_hit($hit) | ||
| 120 | |||
| 121 | For nucleotide alignments, add a feature that is a "hit" on the feature. | ||
| 122 | |||
| 123 | =item $hit = $feature->hit | ||
| 124 | |||
| 125 | Return the hit. | ||
| 126 | |||
| 127 | =cut | ||
| 128 | |||
| 129 | sub add_hit { | ||
| 130 | my $self = shift; | ||
| 131 | my $hit = shift; | ||
| 132 | $self->{_hit} = $hit; | ||
| 133 | } | ||
| 134 | |||
| 135 | sub hit { shift->{_hit} } | ||
| 136 | |||
| 137 | sub get_SeqFeatures { | ||
| 138 | my $self = shift; | ||
| 139 | my %filter = map {$_=>1} @_; | ||
| 140 | my @pieces = %filter ? grep {$filter{$_->primary_tag}} | ||
| 141 | $self->SUPER::get_SeqFeatures() | ||
| 142 | : $self->SUPER::get_SeqFeatures; | ||
| 143 | return @pieces; | ||
| 144 | } | ||
| 145 | |||
| 146 | sub each_tag_value { | ||
| 147 | my $self = shift; | ||
| 148 | my $tag = shift; | ||
| 149 | my $value = $self->{attributes}{$tag} or return; | ||
| 150 | my $ref = CORE::ref $value; | ||
| 151 | return $ref && $ref eq 'ARRAY' ? @{$self->{attributes}{$tag}} | ||
| 152 | : $self->{attributes}{$tag}; | ||
| 153 | } | ||
| 154 | |||
| 155 | |||
| 156 | |||
| 157 | =item segments() | ||
| 158 | |||
| 159 | An alias for get_SeqFeatures(). | ||
| 160 | |||
| 161 | =item get_all_SeqFeatures() | ||
| 162 | |||
| 163 | Alias for get_SeqFeatures() | ||
| 164 | |||
| 165 | =item merged_segments() | ||
| 166 | |||
| 167 | Another alias for sub_SeqFeature(). | ||
| 168 | |||
| 169 | =item stop() | ||
| 170 | |||
| 171 | An alias for end(). | ||
| 172 | |||
| 173 | =item name() | ||
| 174 | |||
| 175 | An alias for seqname(). | ||
| 176 | |||
| 177 | =item exons() | ||
| 178 | |||
| 179 | An alias for sub_SeqFeature() (you don't want to know why!) | ||
| 180 | |||
| 181 | =item configurator() | ||
| 182 | |||
| 183 | Get/set the configurator that knows how to adjust the graphical | ||
| 184 | representation of this feature based on its type. Currently the only | ||
| 185 | configurator that will work is Bio::Graphics::FeatureFile. | ||
| 186 | |||
| 187 | =back | ||
| 188 | |||
| 189 | =cut | ||
| 190 | |||
| 191 | use strict; | ||
| 192 | use base 'Bio::SeqFeature::Lite'; | ||
| 193 | |||
| 194 | # usage: | ||
| 195 | # Bio::Graphics::Feature->new( | ||
| 196 | # -start => 1, | ||
| 197 | # -end => 100, | ||
| 198 | # -name => 'fred feature', | ||
| 199 | # -strand => +1); | ||
| 200 | # | ||
| 201 | # Alternatively, use -segments => [ [start,stop],[start,stop]...] | ||
| 202 | # to create a multisegmented feature. | ||
| 203 | sub new { | ||
| 204 | my $self = shift->SUPER::new(@_); | ||
| 205 | |||
| 206 | my %arg = @_; | ||
| 207 | for my $option (qw(factory configurator)) { | ||
| 208 | $self->{$option} = $arg{"-$option"} if exists $arg{"-$option"}; | ||
| 209 | } | ||
| 210 | $self; | ||
| 211 | } | ||
| 212 | |||
| 213 | =head2 factory | ||
| 214 | |||
| 215 | Title : factory | ||
| 216 | Usage : $factory = $obj->factory([$new_factory]) | ||
| 217 | Function: Returns the feature factory from which this feature was generated. | ||
| 218 | Mostly for compatibility with weird dependencies in gbrowse. | ||
| 219 | Returns : A feature factory | ||
| 220 | Args : None | ||
| 221 | |||
| 222 | =cut | ||
| 223 | |||
| 224 | sub factory { | ||
| 225 | my $self = shift; | ||
| 226 | my $d = $self->{factory}; | ||
| 227 | $self->{factory} = shift if @_; | ||
| 228 | $d; | ||
| 229 | } | ||
| 230 | |||
| 231 | =head2 display_name | ||
| 232 | |||
| 233 | Title : display_name | ||
| 234 | Usage : $id = $obj->display_name or $obj->display_name($newid); | ||
| 235 | Function: Gets or sets the display id, also known as the common name of | ||
| 236 | the Seq object. | ||
| 237 | |||
| 238 | The semantics of this is that it is the most likely string | ||
| 239 | to be used as an identifier of the sequence, and likely to | ||
| 240 | have "human" readability. The id is equivalent to the LOCUS | ||
| 241 | field of the GenBank/EMBL databanks and the ID field of the | ||
| 242 | Swissprot/sptrembl database. In fasta format, the >(\S+) is | ||
| 243 | presumed to be the id, though some people overload the id | ||
| 244 | to embed other information. Bioperl does not use any | ||
| 245 | embedded information in the ID field, and people are | ||
| 246 | encouraged to use other mechanisms (accession field for | ||
| 247 | example, or extending the sequence object) to solve this. | ||
| 248 | |||
| 249 | Notice that $seq->id() maps to this function, mainly for | ||
| 250 | legacy/convenience issues. | ||
| 251 | Returns : A string | ||
| 252 | Args : None or a new id | ||
| 253 | |||
| 254 | |||
| 255 | =head2 accession_number | ||
| 256 | |||
| 257 | Title : accession_number | ||
| 258 | Usage : $unique_biological_key = $obj->accession_number; | ||
| 259 | Function: Returns the unique biological id for a sequence, commonly | ||
| 260 | called the accession_number. For sequences from established | ||
| 261 | databases, the implementors should try to use the correct | ||
| 262 | accession number. Notice that primary_id() provides the | ||
| 263 | unique id for the implemetation, allowing multiple objects | ||
| 264 | to have the same accession number in a particular implementation. | ||
| 265 | |||
| 266 | For sequences with no accession number, this method should return | ||
| 267 | "unknown". | ||
| 268 | Returns : A string | ||
| 269 | Args : None | ||
| 270 | |||
| 271 | =head2 alphabet | ||
| 272 | |||
| 273 | Title : alphabet | ||
| 274 | Usage : if( $obj->alphabet eq 'dna' ) { /Do Something/ } | ||
| 275 | Function: Returns the type of sequence being one of | ||
| 276 | 'dna', 'rna' or 'protein'. This is case sensitive. | ||
| 277 | |||
| 278 | This is not called <type> because this would cause | ||
| 279 | upgrade problems from the 0.5 and earlier Seq objects. | ||
| 280 | |||
| 281 | Returns : a string either 'dna','rna','protein'. NB - the object must | ||
| 282 | make a call of the type - if there is no type specified it | ||
| 283 | has to guess. | ||
| 284 | Args : none | ||
| 285 | Status : Virtual | ||
| 286 | |||
| 287 | =head2 desc | ||
| 288 | |||
| 289 | Title : desc | ||
| 290 | Usage : $seqobj->desc($string) or $seqobj->desc() | ||
| 291 | Function: Sets or gets the description of the sequence | ||
| 292 | Example : | ||
| 293 | Returns : The description | ||
| 294 | Args : The description or none | ||
| 295 | |||
| 296 | =head2 location | ||
| 297 | |||
| 298 | Title : location | ||
| 299 | Usage : my $location = $seqfeature->location() | ||
| 300 | Function: returns a location object suitable for identifying location | ||
| 301 | of feature on sequence or parent feature | ||
| 302 | Returns : Bio::LocationI object | ||
| 303 | Args : none | ||
| 304 | |||
| 305 | |||
| 306 | =head2 location_string | ||
| 307 | |||
| 308 | Title : location_string | ||
| 309 | Usage : my $string = $seqfeature->location_string() | ||
| 310 | Function: Returns a location string in a format recognized by gbrowse | ||
| 311 | Returns : a string | ||
| 312 | Args : none | ||
| 313 | |||
| 314 | This is a convenience function used by the generic genome browser. It | ||
| 315 | returns the location of the feature and its subfeatures in the compact | ||
| 316 | form "start1..end1,start2..end2,...". Use | ||
| 317 | $seqfeature-E<gt>location()-E<gt>toFTString() to obtain a standard | ||
| 318 | GenBank/EMBL location representation. | ||
| 319 | |||
| 320 | =head2 configurator | ||
| 321 | |||
| 322 | Title : configurator | ||
| 323 | Usage : my $configurator = $seqfeature->configurator([$new_configurator]) | ||
| 324 | Function: Get/set an object that provides configuration information for this feature | ||
| 325 | Returns : configurator object | ||
| 326 | Args : new configurator object (optional) | ||
| 327 | |||
| 328 | A configurator object provides hints to the Bio::Graphics::Feature as | ||
| 329 | to how to display itself on a canvas. Currently this stores the | ||
| 330 | Bio::Graphics::FeatureFile and descendents. | ||
| 331 | |||
| 332 | =cut | ||
| 333 | |||
| 334 | |||
| 335 | # get/set the configurator (Bio::Graphics::FeatureFile) for this feature | ||
| 336 | sub configurator { | ||
| 337 | my $self = shift; | ||
| 338 | my $d = $self->{configurator}; | ||
| 339 | $self->{configurator} = shift if @_; | ||
| 340 | $d; | ||
| 341 | } | ||
| 342 | |||
| 343 | =head2 url | ||
| 344 | |||
| 345 | Title : url | ||
| 346 | Usage : my $url = $seqfeature->url([$new_url]) | ||
| 347 | Function: Get/set the URL associated with this feature | ||
| 348 | Returns : a URL string | ||
| 349 | Args : new URL (optional) | ||
| 350 | |||
| 351 | Features link to URLs when displayed as a clickable image map. This | ||
| 352 | field holds that information. | ||
| 353 | |||
| 354 | =cut | ||
| 355 | |||
| 356 | |||
| 357 | # get/set the url for this feature | ||
| 358 | sub url { | ||
| 359 | my $self = shift; | ||
| 360 | my $d = $self->{url}; | ||
| 361 | $self->{url} = shift if @_; | ||
| 362 | $d; | ||
| 363 | } | ||
| 364 | |||
| 365 | =head2 make_link | ||
| 366 | |||
| 367 | Title : make_link | ||
| 368 | Usage : my $url = $seqfeature->make_link() | ||
| 369 | Function: Create a URL for the feature | ||
| 370 | Returns : a URL string | ||
| 371 | Args : none | ||
| 372 | |||
| 373 | This method will invoke the configurator in order to turn the feature | ||
| 374 | into a link. Used by Bio::Graphics::Panel to create imagemaps. | ||
| 375 | |||
| 376 | =cut | ||
| 377 | |||
| 378 | # make a link | ||
| 379 | sub make_link { | ||
| 380 | my $self = shift; | ||
| 381 | |||
| 382 | if (my $url = $self->url) { | ||
| 383 | return $url; | ||
| 384 | } | ||
| 385 | |||
| 386 | elsif (my $configurator = $self->configurator) { | ||
| 387 | return $configurator->make_link($self) if $configurator->can('make_link'); | ||
| 388 | } | ||
| 389 | |||
| 390 | else { | ||
| 391 | return; | ||
| 392 | } | ||
| 393 | } | ||
| 394 | |||
| 395 | |||
| 396 | |||
| 397 | 1; | ||
| 398 | |||
| 399 | __END__ |