Bio::Graphics::Feature - A simple feature object for use with Bio::Graphics::Panel

- NAME
- SYNOPSIS
- DESCRIPTION

- The `new()` Constructor
- Non-SeqFeatureI methods
- factory
- display_name
- accession_number
- alphabet
- desc
- location
- location_string
- configurator
- url
- make_link

- SEE ALSO
- AUTHOR

# NAME

Bio::Graphics::Feature - A simple feature object for use with Bio::Graphics::Panel

# SYNOPSIS

     use Bio::Graphics::Feature;

     # create a simple feature with no internal structure
     $f = Bio::Graphics::Feature->new(-start => 1000,
                                      -stop  => 2000,
                                      -type  => 'transcript',
                                      -name  => 'alpha-1 antitrypsin',
                                      -desc  => 'an enzyme inhibitor',
                                     );

     # create a feature composed of multiple segments, all of type "similarity"
     $f = Bio::Graphics::Feature->new(-segments => [[1000,1100],[1500,1550],[1800,2000]],
                                      -name     => 'ABC-3',
                                      -type     => 'gapped_alignment',
                                      -subtype  => 'similarity');

     # build up a gene exon by exon
     $e1 = Bio::Graphics::Feature->new(-start=>1,-stop=>100,-type=>'exon');
     $e2 = Bio::Graphics::Feature->new(-start=>150,-stop=>200,-type=>'exon');
     $e3 = Bio::Graphics::Feature->new(-start=>300,-stop=>500,-type=>'exon');
     $f  = Bio::Graphics::Feature->new(-segments=>[$e1,$e2,$e3],-type=>'gene');

# DESCRIPTION

This is a simple Bio::SeqFeatureI-compliant object that is compatible with Bio::Graphics::Panel. With it you can create lightweight feature objects for drawing.

All methods are as described in the Bio::SeqFeatureI manpage with the following additions:

## The `new()` Constructor

     $feature = Bio::Graphics::Feature->new(@args);

This method creates a new feature object. You can create a simple feature that contains no subfeatures, or a hierarchically nested object.

Arguments are as follows:

      -seq_id      the reference sequence
      -start       the start position of the feature
      -end         the stop position of the feature
      -stop        an alias for end
      -name        the feature name (returned by seqname())
      -type        the feature type (returned by primary_tag())
      -primary_tag the same as -type
      -source      the source tag
      -score       the feature score (for GFF compatibility)
      -desc        a description of the feature
      -segments    a list of subfeatures (see below)
      -subtype     the type to use when creating subfeatures
      -strand      the strand of the feature (one of -1, 0 or +1)
      -phase       the phase of the feature (0..2)
      -id          an alias for -name
      -seqname     an alias for -name
      -display_id  an alias for -name
      -display_name an alias for -name  (do you get the idea the API has changed?)
      -primary_id  unique database ID
      -url         a URL to link to when rendered with Bio::Graphics
      -configurator an object (like a Bio::Graphics::FeatureFile) that knows how
                   to configure the graphical representation of the object based
                   on its type.
      -attributes  a hashref of tag value attributes, in which the key is the tag
                   and the value is an array reference of values
      -factory     a reference to a feature factory, used for compatibility with
                   more obscure parts of Bio::DB::GFF

The subfeatures passed in -segments may be an array of Bio::Graphics::Feature objects, or an array of [$start,$stop] pairs. Each pair should be a two-element array reference. In the latter case, the feature type passed in -subtype will be used when creating the subfeatures.

If no feature type is passed, then it defaults to "feature".

## Non-SeqFeatureI methods

A number of new methods are provided for compatibility with Ace::Sequence, which has a slightly different API from SeqFeatureI:

`attributes()`

  An alternative interface to get_tag_values. Pass the name of an attribute to get the `value(s)` of that attribute:

         $expression_level = $gene->attributes('expression');

  Call `attributes()` without any arguments to get a hash of all attributes:

        %attributes = $gene->attributes;

`url()`

  Get/set the URL that the graphical rendering of this feature will link to.

`add_segment(@segments)`

  Add one or more segments (a subfeature). Segments can either be Feature objects, or [start,stop] arrays, as in the -segments argument to new(). The feature endpoints are automatically adjusted.

my @features = `get_SeqFeatures('type1','type2','type3'...)`

  Get the subfeatures of this feature. If an optional list of types is provided, then only returns subfeatures with the indicated primary_tag. (This is an extension of the Bio::SeqFeatureI interface).

$feature->`add_hit($hit)`

  For nucleotide alignments, add a feature that is a "hit" on the feature.

$hit = $feature->hit

  Return the hit.

`segments()`

  An alias for get_SeqFeatures().

`get_all_SeqFeatures()`

  Alias for `get_SeqFeatures()`

`merged_segments()`

  Another alias for sub_SeqFeature().

`stop()`

  An alias for end().

`name()`

  An alias for seqname().

`exons()`

  An alias for `sub_SeqFeature()` (you don't want to know why!)

`configurator()`

  Get/set the configurator that knows how to adjust the graphical representation of this feature based on its type. Currently the only configurator that will work is Bio::Graphics::FeatureFile.

## factory

     Title   : factory
     Usage   : $factory = $obj->factory([$new_factory])
     Function: Returns the feature factory from which this feature was generated.
               Mostly for compatibility with weird dependencies in gbrowse.
     Returns : A feature factory
     Args    : None

## display_name

     Title   : display_name
     Usage   : $id = $obj->display_name or $obj->display_name($newid);
     Function: Gets or sets the display id, also known as the common name of
               the Seq object.

               The semantics of this is that it is the most likely string
               to be used as an identifier of the sequence, and likely to
               have "human" readability.  The id is equivalent to the LOCUS
               field of the GenBank/EMBL databanks and the ID field of the
               Swissprot/sptrembl database. In fasta format, the >(\S+) is
               presumed to be the id, though some people overload the id
               to embed other information. Bioperl does not use any
               embedded information in the ID field, and people are
               encouraged to use other mechanisms (accession field for
               example, or extending the sequence object) to solve this.

               Notice that $seq->id() maps to this function, mainly for
               legacy/convenience issues.
     Returns : A string
     Args    : None or a new id

## accession_number

     Title   : accession_number
     Usage   : $unique_biological_key = $obj->accession_number;
     Function: Returns the unique biological id for a sequence, commonly
               called the accession_number. For sequences from established
               databases, the implementors should try to use the correct
               accession number. Notice that primary_id() provides the
               unique id for the implemetation, allowing multiple objects
               to have the same accession number in a particular implementation.

               For sequences with no accession number, this method should return
               "unknown".
     Returns : A string
     Args    : None

## alphabet

     Title   : alphabet
     Usage   : if( $obj->alphabet eq 'dna' ) { /Do Something/ }
     Function: Returns the type of sequence being one of
               'dna', 'rna' or 'protein'. This is case sensitive.

               This is not called <type> because this would cause
               upgrade problems from the 0.5 and earlier Seq objects.

     Returns : a string either 'dna','rna','protein'. NB - the object must
               make a call of the type - if there is no type specified it
               has to guess.
     Args    : none
     Status  : Virtual

## desc

     Title   : desc
     Usage   : $seqobj->desc($string) or $seqobj->desc()
     Function: Sets or gets the description of the sequence
     Example :
     Returns : The description
     Args    : The description or none

## location

     Title   : location
     Usage   : my $location = $seqfeature->location()
     Function: returns a location object suitable for identifying location
               of feature on sequence or parent feature
     Returns : Bio::LocationI object
     Args    : none

## location_string

     Title   : location_string
     Usage   : my $string = $seqfeature->location_string()
     Function: Returns a location string in a format recognized by gbrowse
     Returns : a string
     Args    : none

This is a convenience function used by the generic genome browser. It returns the location of the feature and its subfeatures in the compact form "start1..end1,start2..end2,...". Use $seqfeature->location()->`toFTString()` to obtain a standard GenBank/EMBL location representation.

## configurator

     Title   : configurator
     Usage   : my $configurator = $seqfeature->configurator([$new_configurator])
     Function: Get/set an object that provides configuration information for this feature
     Returns : configurator object
     Args    : new configurator object (optional)

A configurator object provides hints to the Bio::Graphics::Feature as to how to display itself on a canvas. Currently this stores the Bio::Graphics::FeatureFile and descendents.

## url

     Title   : url
     Usage   : my $url = $seqfeature->url([$new_url])
     Function: Get/set the URL associated with this feature
     Returns : a URL string
     Args    : new URL (optional)

Features link to URLs when displayed as a clickable image map. This field holds that information.

## make_link

     Title   : make_link
     Usage   : my $url = $seqfeature->make_link()
     Function: Create a URL for the feature
     Returns : a URL string
     Args    : none

This method will invoke the configurator in order to turn the feature into a link. Used by Bio::Graphics::Panel to create imagemaps.

# SEE ALSO

the Bio::Graphics::Panel manpage,the Bio::Graphics::Glyph manpage, the Bio::Graphics::FeatureBase manpage GD

# AUTHOR

Lincoln Stein <lstein@cshl.edu>.

Copyright (c) 2001 Cold Spring Harbor Laboratory

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See DISCLAIMER.txt for disclaimers of warranty.

Bio::Graphics::Feature - A simple feature object for use with Bio::Graphics::Panel