Provided by: libbio-perl-perl_1.7.2-3_all bug

NAME

       Bio::SeqFeatureI - Abstract interface of a Sequence Feature

SYNOPSIS

           # get a seqfeature somehow, eg, from a Sequence with Features attached

           foreach $feat ( $seq->get_SeqFeatures() ) {
               print "Feature from ", $feat->start, "to ",
                     $feat->end, " Primary tag  ", $feat->primary_tag,
                     ", produced by ", $feat->source_tag(), "\n";

               if ( $feat->strand == 0 ) {
                   print "Feature applicable to either strand\n";
               }
               else {
                   print "Feature on strand ", $feat->strand,"\n"; # -1,1
               }

               print "feature location is ",$feat->start, "..",
                     $feat->end, " on strand ", $feat->strand, "\n";
               print "easy utility to print locations in GenBank/EMBL way ",
                     $feat->location->to_FTstring(), "\n";

               foreach $tag ( $feat->get_all_tags() ) {
                   print "Feature has tag ", $tag, " with values, ",
                         join(' ',$feat->get_tag_values($tag)), "\n";
               }
               print "new feature\n" if $feat->has_tag('new');
               # features can have sub features
               my @subfeat = $feat->get_SeqFeatures();
           }

DESCRIPTION

       This interface is the functions one can expect for any Sequence Feature, whatever its
       implementation or whether it is a more complex type (eg, a Gene). This object does not
       actually provide any implementation, it just provides the definitions of what methods one
       can call. See Bio::SeqFeature::Generic for a good standard implementation of this object

FEEDBACK

       User feedback is an integral part of the evolution of this and other Bioperl modules. Send
       your comments and suggestions preferably to one of the Bioperl mailing lists.  Your
       participation is much appreciated.

         bioperl-l@bioperl.org                  - General discussion
         http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

   Support
       Please direct usage questions or support issues to the mailing list:

       bioperl-l@bioperl.org

       rather than to the module maintainer directly. Many experienced and reponsive experts will
       be able look at the problem and quickly address it. Please include a thorough description
       of the problem with code and data examples if at all possible.

   Reporting Bugs
       Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their
       resolution.  Bug reports can be submitted via the web:

         https://github.com/bioperl/bioperl-live/issues

APPENDIX

       The rest of the documentation details each of the object methods. Internal methods are
       usually preceded with a _

Bio::SeqFeatureI specific methods

       New method interfaces.

   get_SeqFeatures
        Title   : get_SeqFeatures
        Usage   : @feats = $feat->get_SeqFeatures();
        Function: Returns an array of sub Sequence Features
        Returns : An array
        Args    : none

   display_name
        Title   : display_name
        Usage   : $name = $feat->display_name()
        Function: Returns the human-readable name of the feature for displays.
        Returns : a string
        Args    : none

   primary_tag
        Title   : primary_tag
        Usage   : $tag = $feat->primary_tag()
        Function: Returns the primary tag for a feature,
                  eg 'exon'
        Returns : a string
        Args    : none

   source_tag
        Title   : source_tag
        Usage   : $tag = $feat->source_tag()
        Function: Returns the source tag for a feature,
                  eg, 'genscan'
        Returns : a string
        Args    : none

   has_tag
        Title   : has_tag
        Usage   : $tag_exists = $self->has_tag('some_tag')
        Function:
        Returns : TRUE if the specified tag exists, and FALSE otherwise
        Args    :

   get_tag_values
        Title   : get_tag_values
        Usage   : @values = $self->get_tag_values('some_tag')
        Function:
        Returns : An array comprising the values of the specified tag.
        Args    : a string

       throws an exception if there is no such tag

   get_tagset_values
        Title   : get_tagset_values
        Usage   : @values = $self->get_tagset_values(qw(label transcript_id product))
        Function:
        Returns : An array comprising the values of the specified tags, in order of tags
        Args    : An array of strings

       does NOT throw an exception if none of the tags are not present

       this method is useful for getting a human-readable label for a SeqFeatureI; not all tags
       can be assumed to be present, so a list of possible tags in preferential order is provided

   get_all_tags
        Title   : get_all_tags
        Usage   : @tags = $feat->get_all_tags()
        Function: gives all tags for this feature
        Returns : an array of strings
        Args    : none

   attach_seq
        Title   : attach_seq
        Usage   : $sf->attach_seq($seq)
        Function: Attaches a Bio::Seq object to this feature. This
                  Bio::Seq object is for the *entire* sequence: ie
                  from 1 to 10000

                  Note that it is not guaranteed that if you obtain a feature from
                  an object in bioperl, it will have a sequence attached. Also,
                  implementors of this interface can choose to provide an empty
                  implementation of this method. I.e., there is also no guarantee
                  that if you do attach a sequence, seq() or entire_seq() will not
                  return undef.

                  The reason that this method is here on the interface is to enable
                  you to call it on every SeqFeatureI compliant object, and
                  that it will be implemented in a useful way and set to a useful
                  value for the great majority of use cases. Implementors who choose
                  to ignore the call are encouraged to specifically state this in
                  their documentation.

        Example :
        Returns : TRUE on success
        Args    : a Bio::PrimarySeqI compliant object

   seq
        Title   : seq
        Usage   : $tseq = $sf->seq()
        Function: returns the truncated sequence (if there is a sequence attached)
                  for this feature
        Example :
        Returns : sub seq (a Bio::PrimarySeqI compliant object) on attached sequence
                  bounded by start & end, or undef if there is no sequence attached.
                  If the strand is defined and set to -1, the returned sequence is
                  the reverse-complement of the region
        Args    : none

   entire_seq
        Title   : entire_seq
        Usage   : $whole_seq = $sf->entire_seq()
        Function: gives the entire sequence that this seqfeature is attached to
        Example :
        Returns : a Bio::PrimarySeqI compliant object, or undef if there is no
                  sequence attached
        Args    : none

   seq_id
        Title   : seq_id
        Usage   : $obj->seq_id($newval)
        Function: There are many cases when you make a feature that you
                  do know the sequence name, but do not know its actual
                  sequence. This is an attribute such that you can store
                  the ID (e.g., display_id) of the sequence.

                  This attribute should *not* be used in GFF dumping, as
                  that should come from the collection in which the seq
                  feature was found.
        Returns : value of seq_id
        Args    : newvalue (optional)

   gff_string
        Title   : gff_string
        Usage   : $str = $feat->gff_string;
                  $str = $feat->gff_string($gff_formatter);
        Function: Provides the feature information in GFF format.

                  The implementation provided here returns GFF2 by default. If you
                  want a different version, supply an object implementing a method
                  gff_string() accepting a SeqFeatureI object as argument. E.g., to
                  obtain GFF1 format, do the following:

                       my $gffio = Bio::Tools::GFF->new(-gff_version => 1);
                       $gff1str = $feat->gff_string($gff1io);

        Returns : A string
        Args    : Optionally, an object implementing gff_string().

   _static_gff_formatter
        Title   : _static_gff_formatter
        Usage   :
        Function:
        Example :
        Returns :
        Args    :

Decorating methods

       These methods have an implementation provided by Bio::SeqFeatureI, but can be validly
       overwritten by subclasses

   spliced_seq
         Title   : spliced_seq

         Usage   : $seq = $feature->spliced_seq()
                   $seq = $feature_with_remote_locations->spliced_seq($db_for_seqs)

         Function: Provides a sequence of the feature which is the most
                   semantically "relevant" feature for this sequence. A default
                   implementation is provided which for simple cases returns just
                   the sequence, but for split cases, loops over the split location
                   to return the sequence. In the case of split locations with
                   remote locations, eg

                   join(AB000123:5567-5589,80..1144)

                   in the case when a database object is passed in, it will attempt
                   to retrieve the sequence from the database object, and "Do the right thing",
                   however if no database object is provided, it will generate the correct
                   number of N's (DNA) or X's (protein, though this is unlikely).

                   This function is deliberately "magical" attempting to second guess
                   what a user wants as "the" sequence for this feature.

                   Implementing classes are free to override this method with their
                   own magic if they have a better idea what the user wants.

         Args    : [optional]
                   -db        A L<Bio::DB::RandomAccessI> compliant object if
                              one needs to retrieve remote seqs.
                   -nosort    boolean if the locations should not be sorted
                              by start location.  This may occur, for instance,
                              in a circular sequence where a gene span starts
                              before the end of the sequence and ends after the
                              sequence start. Example : join(15685..16260,1..207)
                              (default = if sequence is_circular(), 1, otherwise 0)
                   -phase     truncates the returned sequence based on the
                              intron phase (0,1,2).

         Returns : A L<Bio::PrimarySeqI> object

   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

   primary_id
        Title   : primary_id
        Usage   : $obj->primary_id($newval)
        Function:
        Example :
        Returns : value of primary_id (a scalar)
        Args    : on set, new value (a scalar or undef, optional)

       Primary ID is a synonym for the tag 'ID'

   phase
        Title   : phase
        Usage   : $obj->phase($newval)
        Function: get/set this feature's phase.
        Example :
        Returns : undef if no phase is set,
                  otherwise 0, 1, or 2 (the only valid values for phase)
        Args    : on set, the new value

       Most features do not have or need a defined phase.

       For features representing a CDS, the phase indicates where the feature begins with
       reference to the reading frame.  The phase is one of the integers 0, 1, or 2, indicating
       the number of bases that should be removed from the beginning of this feature to reach the
       first base of the next codon. In other words, a phase of "0" indicates that the next codon
       begins at the first base of the region described by the current line, a phase of "1"
       indicates that the next codon begins at the second base of this region, and a phase of "2"
       indicates that the codon begins at the third base of this region. This is NOT to be
       confused with the frame, which is simply start modulo 3.

       For forward strand features, phase is counted from the start field. For reverse strand
       features, phase is counted from the end field.

Bio::RangeI methods

       These methods are inherited from RangeI and can be used directly from a SeqFeatureI
       interface. Remember that a SeqFeature is-a RangeI, and so wherever you see RangeI you can
       use a feature ($r in the below documentation).

   start()
        See L<Bio::RangeI>

   end()
        See L<Bio::RangeI>

   strand()
        See L<Bio::RangeI>

   overlaps()
        See L<Bio::RangeI>

   contains()
        See L<Bio::RangeI>

   equals()
        See L<Bio::RangeI>

   intersection()
        See L<Bio::RangeI>

   union()
        See L<Bio::RangeI>