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

NAME

       Bio::DB::SeqFeature::Segment -- Location-based access to genome annotation data

SYNOPSIS

        use Bio::DB::SeqFeature::Store;
        # Open the sequence database
        my $db      = Bio::DB::SeqFeature::Store->new( -adaptor => 'DBI::mysql',
                                                       -dsn     => 'dbi:mysql:test');
        my $segment  = $db->segment('Chr1',5000=>6000);
        my @features = $segment->features('mRNA','match');

DESCRIPTION

       The segment object simplifies access to Bio::DB::SeqFeature store by acting as a
       placeholder for a region of the genome. You can replace this statement:

        @features = $db->features(-seq_id=>'Chr1',
                                  -start=>5000,
                                  -end=>6000,
                                  -types=>['mRNA','match','repeat_region']);

       with these statements:

        $segment = $db->segment('Chr1',5000=>6000);
        @features = $segment->features('mRNA','match','repeat_region');

       You can also initialize a segment from an existing SeqFeature object. The range will be
       picked up from the SeqFeature boundaries:

        $segment = Bio::DB::SeqFeature::Segment->new($feature);        # for Bio::DB::SeqFeature
        $segment = Bio::DB::SeqFeature::Segment->new($feature,$store); # for other Bio::SeqFeatureI objects

       The segment object implements the full Bio::SeqFeature::CollectionI interface, thereby
       allowing you to iterate over all features in the range.

PUBLIC METHODS

       The following are public methods intended for external use.

   new
        Title   : new
        Usage   : $segment = Bio::DB::SeqFeature::Segment->new(@options)
        Function: create a new Segment object
        Returns : A Bio::DB::SeqFeature::Segment object
        Args    : several - see below
        Status  : public

       This class method creates a Bio::DB::SeqFeature::Segment object. You must provide a
       Bio::DB::SeqFeature::Store as well as the coordinates of the segment. These arguments can
       be provided explicitly or indirectly.

       First form:

        $segment = Bio::DB::SeqFeature::Segment->new($store,$seqid,$start,$end,$strand)

       In this form a segment is defined by a Bio::DB::SeqFeature::Store, the sequence ID, the
       start, end and strand. This is the form that is invoked internally by
       Bio::DB::SeqFeature::Store when you call its segment() method.

       Second form:

        $segment = Bio::DB::SeqFeature::Segment->new($seqfeature [,$store]);

       In this form, you pass new() a Bio::SeqFeatureI object. The segment is constructed from
       the seq_id and coordinates are taken from the object. If you pass a store-aware seqfeature
       object (e.g. Bio::DB::SeqFeature) then the store database is also derived from the
       feature. Otherwise you will have to pass the store as a second argument.

   features
        Title   : features
        Usage   : @features = $segment->features(@args)
        Function: fetch seqfeatures that overlap the segment
        Returns : list of features
        Args    : see below
        Status  : Public

       This is the workhorse for feature query and retrieval. It takes a series of -name=>$value
       arguments filter arguments. Features that match all the filters are returned.

         Argument       Value
         --------       -----

        Location filters:
         -strand        Strand
         -range_type    Type of range match ('overlaps','contains','contained_in')

        Name filters:
         -name          Name of feature (may be a glob expression)
         -aliases       If true, match aliases as well as display names
         -class         Archaic argument for backward compatibility.
                         (-class=>'Clone',-name=>'ABC123') is equivalent
                         to (-name=>'Clone:ABC123')

        Type filters:
         -types         List of feature types (array reference) or one type (scalar)
         -type          Synonym for the above
         -primary_tag   Synonym for the above

         -attributes    Hashref of attribute=>value pairs as per
                           get_features_by_attribute(). Multiple alternative values
                           can be matched by providing an array reference.
         -attribute     synonym for -attributes

       This is identical to the Bio::DB::SeqFeature::Store->features() method, except that the
       -seq_id, -start, and -end arguments are provided by the segment object. If a simple list
       of arguments is provided, then the list is taken to be the set of feature types (primary
       tags) to filter on.

       Examples:

       All features that overlap the current segment:

        @features = $segment->features;

       All features of type mRNA that overlap the current segment:

        @features = $segment->features('mRNA');

       All features that are completely contained within the current segment:

        @features = $segment->features(-range_type=>'contains');

       All "confirmed" mRNAs that overlap the current segment:

        @features = $segment->features(-attributes=>{confirmed=>1},-type=>'mRNA');

   get_seq_stream
        Title   : get_seq_stream
        Usage   : $iterator = $segment->get_seq_stream(@args)
        Function: return an iterator across all features in the database
        Returns : a Bio::DB::SeqFeature::Store::Iterator object
        Args    : (optional) the feature() method
        Status  : public

       This is identical to Bio::DB::SeqFeature::Store->get_seq_stream() except that the location
       filter is always automatically applied so that the iterator you receive returns features
       that overlap the segment's region.

       When called without any arguments this method will return an iterator object that will
       traverse all indexed features in the database that overlap the segment's region. Call the
       iterator's next_seq() method to step through them (in no particular order):

         my $iterator = $db->get_seq_stream;
         while (my $feature = $iterator->next_seq) {
           print $feature->primary_tag,' ',$feature->display_name,"\n";
         }

       You can select a subset of features by passing a series of filter arguments. The arguments
       are identical to those accepted by $segment->features().

       get_feature_stream() ican be used as a synonym for this method.

   store
        Title   : store
        Usage   : $store = $segment->store
        Function: return the Bio::DB::SeqFeature::Store object associated with the segment
        Returns : a Bio::DB::SeqFeature::Store: object
        Args    : none
        Status  : public

   primary_tag, type,
        Title   : primary_tag,type
        Usage   : $primary_tag = $segment->primary_tag
        Function: returns the string "region"
        Returns : "region"
        Args    : none
        Status  : public

       The primary_tag method returns the constant tag "region". type() is a synonym for this
       method.

   as_string
        Title   : as_string
        Usage   : $name = $segment->as_string
        Function: expands the object into a human-readable string
        Returns : "seq_id:start..end"
        Args    : none
        Status  : public

       The as_string() method is overloaded into the "" operator so that the object is
       represented as a human readable string in the form "seq_id:start..end" when used in a
       string context.

   rel2abs
        Title   : rel2abs
        Usage   : @coords = $s->rel2abs(@coords)
        Function: convert relative coordinates into absolute coordinates
        Returns : a list of absolute coordinates
        Args    : a list of relative coordinates
        Status  : Public

       This function takes a list of positions in relative coordinates to the segment, and
       converts them into absolute coordinates.

   abs2rel
        Title   : abs2rel
        Usage   : @rel_coords = $s->abs2rel(@abs_coords)
        Function: convert absolute coordinates into relative coordinates
        Returns : a list of relative coordinates
        Args    : a list of absolute coordinates
        Status  : Public

       This function takes a list of positions in absolute coordinates and returns a list
       expressed in relative coordinates.

   Bio::SeqFeatureI compatibility methods
       For convenience, segments are interchangeable with Bio::SeqFeature objects in many cases.
       This means that segments can be passed to BioPerl modules that expect Bio::SeqFeature
       objects and they should work as expected. The primary tag of segment objects is "region"
       (SO:0000001 "Continous sequence >=1 base pair").

       All these methods are read-only except for the primary_id, which can be get or set.

       The following Bio::SeqFeatureI methods are supported:

       start
       end
       seq_id
       strand
       length
       display_name
       primary_id
       primary_tag (always returns "region")
       source_tag (always returns "Bio::DB::SeqFeature::Segment")
       get_SeqFeatures (always returns an empty list)
       seq
       entire_seq
       location
       All Bio::RangeI methods

BUGS

       This is an early version, so there are certainly some bugs. Please use the BioPerl bug
       tracking system to report bugs.

SEE ALSO

       bioperl, Bio::DB::SeqFeature::Store, Bio::DB::SeqFeature::GFF3Loader,
       Bio::DB::SeqFeature::Store::DBI::mysql, Bio::DB::SeqFeature::Store::bdb

AUTHOR

       Lincoln Stein <lstein@cshl.org>.

       Copyright (c) 2006 Cold Spring Harbor Laboratory.

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.