Archive Ensembl HomeArchive Ensembl Home
MiscFeature.pm
Go to the documentation of this file.
00001 =head1 LICENSE
00002 
00003   Copyright (c) 1999-2012 The European Bioinformatics Institute and
00004   Genome Research Limited.  All rights reserved.
00005 
00006   This software is distributed under a modified Apache license.
00007   For license details, please see
00008 
00009     http://www.ensembl.org/info/about/code_licence.html
00010 
00011 =head1 CONTACT
00012 
00013   Please email comments or questions to the public Ensembl
00014   developers list at <dev@ensembl.org>.
00015 
00016   Questions may also be sent to the Ensembl help desk at
00017   <helpdesk@ensembl.org>.
00018 
00019 =cut
00020 
00021 =head1 NAME
00022 
00023 Bio::EnsEMBL::MiscFeature - A miscelaneous feature with arbitrary features and
00024 associations.
00025 
00026 =head1 SYNOPSIS
00027 
00028   use Bio::EnsEMBL::MiscFeature;
00029   use Bio::EnsEMBL::MiscSet;
00030   use Bio::EnsEMBL::Attribute;
00031 
00032   my $mfeat = Bio::EnsEMBL::MiscFeature->new(
00033     -START  => 1200,
00034     -END    => 100_000,
00035     -STRAND => 1,
00036     -SLICE  => $slice
00037   );
00038 
00039   # Can add attributes to the misc feature and associate with various
00040   # sets
00041   my $clone_set = Bio::EnsEMBL::MiscSet->new(
00042     -CODE        => 'clone',
00043     -NAME        => '1MB clone set',
00044     -DESCRIPTION => '1MB CloneSet'
00045   );
00046 
00047   my $tiling_path_set = Bio::EnsEMBL::MiscSet->new(
00048     -CODE => 'tilingpath',
00049     -NAME => 'tiling path set'
00050   );
00051 
00052   my $attrib1 = Bio::EnsEMBL::Attribute->new(
00053     -VALUE => 'RLX12451',
00054     -CODE  => 'name',
00055     -NAME  => 'name'
00056   );
00057 
00058   my $attrib2 = Bio::EnsEMBL::Attribute->new(
00059     -VALUE => '4',
00060     -CODE  => 'version',
00061     -NAME  => 'version'
00062   );
00063 
00064   my $attrib3 = Bio::EnsEMBL::Attribute->new(
00065     -VALUE => 'AL42131.4',
00066     -CODE  => 'synonym',
00067     -NAME  => 'synonym'
00068   );
00069 
00070   # can associate a misc feature with any number of sets
00071 
00072   $mfeat->add_MiscSet($clone_set);
00073   $mfeat->add_MiscSet($tiling_path_set);
00074 
00075   # can add arbitrary attributes to a misc feature
00076 
00077   $mfeat->add_Attribute($attrib1);
00078   $mfeat->add_Attribute($attrib2);
00079   $mfeat->add_Attribute($attrib3);
00080 
00081   my ($name_attrib) = @{ $mfeat->get_all_Attributes('name') };
00082   my @all_attribs = @{ $mfeat->get_all_Attributes() };
00083 
00084   my @all_sets = @{ $mfeat->get_all_MiscSets() };
00085   my ($clone_set) = @{ $mfeat->get_all_CloneSets('clone') };
00086 
00087 
00088   # Can do normal feature operations as well
00089   $mfeat = $mfeat->transform('supercontig');
00090   print $mfeat->slice->seq_region_name, ' ', $mfeat->start, '-',
00091     $mfeat->end;
00092 
00093 
00094 =head1 DESCRIPTION
00095 
00096 MiscFeatures are extremely general features with a location, and an
00097 arbitrary group of attributes.  They are grouped with other features of
00098 the same 'type' through the use of MiscSets (see Bio::EnsEMBL::MiscSet).
00099 Attributes are attached in the fom of Bio::EnsEMBL::Attribute objects.
00100 See Bio::EnsEMBL::DBSQL::MiscFeatureAdaptor for ways to fetch or store
00101 MiscFeatures.
00102 
00103 =cut
00104 
00105 
00106 package Bio::EnsEMBL::MiscFeature;
00107 
00108 use strict;
00109 use warnings;
00110 
00111 use Bio::EnsEMBL::Feature;
00112 use Bio::EnsEMBL::Utils::Exception qw(throw);
00113 use Scalar::Util qw(weaken isweak);
00114 
00115 use vars qw(@ISA);
00116 
00117 @ISA = qw(Bio::EnsEMBL::Feature);
00118 
00119 =head2 new
00120 
00121   Arg [-SLICE]: Bio::EnsEMBL::SLice - Represents the sequence that this
00122                 feature is on. The coordinates of the created feature are
00123                 relative to the start of the slice.
00124   Arg [-START]: The start coordinate of this feature relative to the start
00125                 of the slice it is sitting on.  Coordinates start at 1 and
00126                 are inclusive.
00127   Arg [-END]  : The end coordinate of this feature relative to the start of
00128                 the slice it is sitting on.  Coordinates start at 1 and are
00129                 inclusive.
00130   Arg [-STRAND]: The orientation of this feature.  Valid values are 1,-1,0.
00131   Arg [-SEQNAME] : A seqname to be used instead of the default name of the
00132                 of the slice.  Useful for features that do not have an
00133                 attached slice such as protein features.
00134   Arg [-dbID]   : (optional) internal database id
00135   Arg [-ADAPTOR]: (optional) Bio::EnsEMBL::DBSQL::BaseAdaptor
00136   Example    : $feature = Bio::EnsEMBL::MiscFeature->new(-start    => 1,
00137                                                      -end      => 100,
00138                                                      -strand   => 1,
00139                                                      -slice    => $slice,
00140                                                      -analysis => $analysis);
00141   Description: Constructs a new Bio::EnsEMBL::Feature.  Generally subclasses
00142                of this method are instantiated, rather than this class itself.
00143   Returntype : Bio::EnsEMBL::MiscFeature
00144   Exceptions : Thrown on invalid -SLICE, -ANALYSIS, -STRAND ,-ADAPTOR arguments
00145   Caller     : general, subclass constructors
00146   Status     : Stable
00147 
00148 =cut
00149 
00150 
00151 sub new {
00152   my $class = shift;
00153 
00154   my $self = $class->SUPER::new(@_);
00155 
00156   $self->{'attributes'} = [];
00157 
00158   return $self;
00159 }
00160 
00161 
00162 =head2 new_fast
00163 
00164   Arg [...]  : hashref to bless as new MiscFeature
00165   Example    : $miscfeature = Bio::EnsEMBL::MiscFeature->new_fast();
00166   Description: Creates a new Miscfeature.
00167   Returntype : Bio::EnsEMBL::MiscFeature
00168   Exceptions : none
00169   Caller     : general
00170   Status     : Stable
00171 
00172 =cut
00173 
00174 
00175 sub new_fast {
00176   my $class = shift;
00177   my $hashref = shift;
00178 
00179   $hashref->{'attributes'} ||= [];
00180 
00181   my $self = bless $hashref, $class;
00182   weaken($self->{adaptor})  if ( ! isweak($self->{adaptor}) );
00183   return $self;
00184 }
00185 
00186 
00187 
00188 =head2 add_Attribute
00189 
00190   Arg [1]    : Bio::EnsEMBL::Attribute $attribute
00191   Example    : $misc_feature->add_attribute($attribute);
00192   Description: Adds an attribute to this misc. feature
00193   Returntype : none
00194   Exceptions : throw on wrong argument type
00195   Caller     : general
00196   Status     : Stable
00197 
00198 =cut
00199 
00200 sub add_Attribute {
00201   my ($self, $attrib) = @_;
00202 
00203   if( ! defined $attrib || ! $attrib->isa( "Bio::EnsEMBL::Attribute" )) {
00204     throw( "You have to provide a Bio::EnsEMBL::Attribute, not a [$attrib]" );
00205   }
00206 
00207   $self->{'attributes'} ||= [];
00208   push @{$self->{'attributes'}}, $attrib
00209 }
00210 
00211 
00212 
00213 =head2 add_MiscSet
00214 
00215   Arg [1]    : Bio::EnsEMBL::MiscSet $set
00216                The set to add
00217   Example    : $misc_feature->add_MiscSet(Bio::EnsEMBL::MiscSet->new(...));
00218   Description: Associates this MiscFeature with a given Set.
00219   Returntype : none
00220   Exceptions : throw if the set arg is not provided,
00221                throw if the set to be added does not have a code
00222   Caller     : general
00223   Status     : Stable
00224 
00225 =cut
00226 
00227 
00228 sub add_MiscSet {
00229   my $self = shift;
00230   my $miscSet = shift;
00231 
00232   if(!$miscSet || !ref($miscSet) || !$miscSet->isa('Bio::EnsEMBL::MiscSet')) {
00233     throw('Set argument must be a Bio::EnsEMBL::MiscSet');
00234   }
00235 
00236   $self->{'miscSets'} ||= [];
00237 
00238   push( @{$self->{'miscSets'}}, $miscSet );
00239 }
00240 
00241 
00242 
00243 =head2 get_all_MiscSets
00244 
00245   Arg [1]    : optional string $code
00246                The code of the set to retrieve
00247   Example    : $set = $misc_feature->get_all_MiscSets($code);
00248   Description: Retrieves a set that this feature is associated with via its
00249                code. Can return empty lists. Usually returns about one elements lists.
00250   Returntype : listref of Bio::EnsEMBL::MiscSet
00251   Exceptions : throw if the code arg is not provided
00252   Caller     : general
00253   Status     : Stable
00254 
00255 =cut
00256 
00257 
00258 sub get_all_MiscSets {
00259   my $self = shift;
00260   my $code = shift;
00261 
00262   $self->{'miscSets'} ||= [];
00263   if( defined $code ) {
00264     my @results = grep { uc($_->code())eq uc( $code ) } @{$self->{'miscSets'}};
00265     return \@results;
00266   } else {
00267     return $self->{'miscSets'};
00268   }
00269 }
00270 
00271 
00272 =head2 get_all_Attributes
00273 
00274   Arg [1]    : optional string $code
00275                The code of the Attribute objects to retrieve
00276   Example    : @attributes = @{ $misc_feature->get_all_Attributes('name') };
00277   Description: Retrieves a list of Attribute objects for given code or all
00278                of the associated Attributes.
00279   Returntype : listref of Bio::EnsEMBL::Attribute
00280   Exceptions : 
00281   Caller     : general
00282   Status     : Stable
00283 
00284 =cut
00285 
00286 sub get_all_Attributes {
00287   my $self = shift;
00288   my $code = shift;
00289 
00290   my @results;
00291   my $result;
00292 
00293   if( defined $code ) {
00294     @results = grep { uc( $_->code() ) eq uc( $code )} @{$self->{'attributes'}};
00295     return \@results;
00296   } else {
00297     return $self->{'attributes'};
00298   }
00299 }
00300 
00301 =head2 get_all_attribute_values
00302 
00303   Arg [1]    : string $code
00304                The code of the Attribute object values to retrieve
00305   Example    : @attributes_vals = @{$misc_feature->get_all_attribute_values('name')};
00306   Description: Retrieves a list of Attribute object values for given code or all
00307                of the associated Attributes.
00308   Returntype : listref of values
00309   Exceptions : 
00310   Caller     : general
00311   Status     : Stable
00312 
00313 =cut
00314 
00315 sub get_all_attribute_values {
00316   my $self = shift;
00317   my $code = shift;
00318   my @results = map { uc( $_->code() ) eq uc( $code ) ? $_->value : () } 
00319                 @{$self->{'attributes'}};
00320   return \@results;
00321 }
00322 
00323 =head2 get_scalar_attribute
00324 
00325   Arg [1]    : string $code
00326                The code of the Attribute object values to retrieve
00327   Example    : $vals = $misc_feature->get_scalar_attribute('name');
00328   Description: Retrieves a value for given code or all
00329                of the associated Attributes.
00330   Returntype : scalar value
00331   Exceptions : 
00332   Caller     : general
00333   Status     : Stable
00334 
00335 
00336 =cut
00337   
00338 
00339 sub get_scalar_attribute {
00340   my $self = shift;
00341   my $code = shift;
00342   my @results = grep { uc( $_->code() ) eq uc( $code )} @{$self->{'attributes'}};
00343   return @results ? $results[0]->value() : '';
00344 }
00345 
00346 sub get_first_scalar_attribute {
00347   my $self = shift;
00348   foreach my $code ( @_ ) {
00349     my @results = grep { uc( $_->code() ) eq uc( $code )} @{$self->{'attributes'}};
00350     return $results[0]->value() if @results;
00351   }
00352   return '';
00353 }
00354 =head2 display_id
00355 
00356   Arg [1]    : none
00357   Example    : print $kb->display_id();
00358   Description: This method returns a string that is considered to be
00359                the 'display' identifier.  For misc_features this is the first
00360                name or synonym attribute or '' if neither are defined.
00361   Returntype : string
00362   Exceptions : none
00363   Caller     : web drawing code
00364   Status     : Stable
00365 
00366 =cut
00367 
00368 sub display_id {
00369   my $self = shift;
00370   my ($attrib) = @{$self->get_all_Attributes('name')};
00371   ($attrib) =  @{$self->get_all_Attributes('synonym')} if(!$attrib);
00372   if( defined $attrib ) {
00373     return $attrib->value();
00374   } else {
00375     return '';
00376   }
00377 }
00378 
00379 
00380 
00381 
00382 1;