.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bio::DB::SeqFeature::Segment 3pm"
.TH Bio::DB::SeqFeature::Segment 3pm "2020-01-13" "perl v5.30.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::DB::SeqFeature::Segment \-\- Location\-based access to genome annotation data
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\& use Bio::DB::SeqFeature::Store;
\& # Open the sequence database
\& my $db      = Bio::DB::SeqFeature::Store\->new( \-adaptor => \*(AqDBI::mysql\*(Aq,
\&                                                \-dsn     => \*(Aqdbi:mysql:test\*(Aq);
\& my $segment  = $db\->segment(\*(AqChr1\*(Aq,5000=>6000);
\& my @features = $segment\->features(\*(AqmRNA\*(Aq,\*(Aqmatch\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "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:
.PP
.Vb 4
\& @features = $db\->features(\-seq_id=>\*(AqChr1\*(Aq,
\&                           \-start=>5000,
\&                           \-end=>6000,
\&                           \-types=>[\*(AqmRNA\*(Aq,\*(Aqmatch\*(Aq,\*(Aqrepeat_region\*(Aq]);
.Ve
.PP
with these statements:
.PP
.Vb 2
\& $segment = $db\->segment(\*(AqChr1\*(Aq,5000=>6000);
\& @features = $segment\->features(\*(AqmRNA\*(Aq,\*(Aqmatch\*(Aq,\*(Aqrepeat_region\*(Aq);
.Ve
.PP
You can also initialize a segment from an existing SeqFeature
object. The range will be picked up from the SeqFeature boundaries:
.PP
.Vb 2
\& $segment = Bio::DB::SeqFeature::Segment\->new($feature);        # for Bio::DB::SeqFeature
\& $segment = Bio::DB::SeqFeature::Segment\->new($feature,$store); # for other Bio::SeqFeatureI objects
.Ve
.PP
The segment object implements the full Bio::SeqFeature::CollectionI
interface, thereby allowing you to iterate over all features in the
range.
.SH "PUBLIC METHODS"
.IX Header "PUBLIC METHODS"
The following are public methods intended for external use.
.SS "new"
.IX Subsection "new"
.Vb 6
\& 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
.Ve
.PP
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.
.PP
First form:
.PP
.Vb 1
\& $segment = Bio::DB::SeqFeature::Segment\->new($store,$seqid,$start,$end,$strand)
.Ve
.PP
In this form a segment is defined by a Bio::DB::SeqFeature::Store, the
sequence \s-1ID,\s0 the start, end and strand. This is the form that is
invoked internally by Bio::DB::SeqFeature::Store when you call its
\&\fBsegment()\fR method.
.PP
Second form:
.PP
.Vb 1
\& $segment = Bio::DB::SeqFeature::Segment\->new($seqfeature [,$store]);
.Ve
.PP
In this form, you pass \fBnew()\fR 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.
.SS "features"
.IX Subsection "features"
.Vb 6
\& Title   : features
\& Usage   : @features = $segment\->features(@args)
\& Function: fetch seqfeatures that overlap the segment
\& Returns : list of features
\& Args    : see below
\& Status  : Public
.Ve
.PP
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.
.PP
.Vb 2
\&  Argument       Value
\&  \-\-\-\-\-\-\-\-       \-\-\-\-\-
\&
\& Location filters:
\&  \-strand        Strand
\&  \-range_type    Type of range match (\*(Aqoverlaps\*(Aq,\*(Aqcontains\*(Aq,\*(Aqcontained_in\*(Aq)
\&
\& 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=>\*(AqClone\*(Aq,\-name=>\*(AqABC123\*(Aq) is equivalent
\&                  to (\-name=>\*(AqClone:ABC123\*(Aq)
\&
\& 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
.Ve
.PP
This is identical to the Bio::DB::SeqFeature::Store\->\fBfeatures()\fR
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.
.PP
Examples:
.PP
All features that overlap the current segment:
.PP
.Vb 1
\& @features = $segment\->features;
.Ve
.PP
All features of type mRNA that overlap the current segment:
.PP
.Vb 1
\& @features = $segment\->features(\*(AqmRNA\*(Aq);
.Ve
.PP
All features that are completely contained within the current segment:
.PP
.Vb 1
\& @features = $segment\->features(\-range_type=>\*(Aqcontains\*(Aq);
.Ve
.PP
All \*(L"confirmed\*(R" mRNAs that overlap the current segment:
.PP
.Vb 1
\& @features = $segment\->features(\-attributes=>{confirmed=>1},\-type=>\*(AqmRNA\*(Aq);
.Ve
.SS "get_seq_stream"
.IX Subsection "get_seq_stream"
.Vb 6
\& 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
.Ve
.PP
This is identical to Bio::DB::SeqFeature::Store\->\fBget_seq_stream()\fR
except that the location filter is always automatically applied so
that the iterator you receive returns features that overlap the
segment's region.
.PP
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 \fBnext_seq()\fR method to
step through them (in no particular order):
.PP
.Vb 4
\&  my $iterator = $db\->get_seq_stream;
\&  while (my $feature = $iterator\->next_seq) {
\&    print $feature\->primary_tag,\*(Aq \*(Aq,$feature\->display_name,"\en";
\&  }
.Ve
.PP
You can select a subset of features by passing a series of filter
arguments. The arguments are identical to those accepted by
\&\f(CW$segment\fR\->\fBfeatures()\fR.
.PP
\&\fBget_feature_stream()\fR ican be used as a synonym for this method.
.SS "store"
.IX Subsection "store"
.Vb 6
\& 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
.Ve
.SS "primary_tag, type,"
.IX Subsection "primary_tag, type,"
.Vb 6
\& Title   : primary_tag,type
\& Usage   : $primary_tag = $segment\->primary_tag
\& Function: returns the string "region"
\& Returns : "region"
\& Args    : none
\& Status  : public
.Ve
.PP
The primary_tag method returns the constant tag \*(L"region\*(R". \fBtype()\fR is a
synonym for this method.
.SS "as_string"
.IX Subsection "as_string"
.Vb 6
\& 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
.Ve
.PP
The \fBas_string()\fR method is overloaded into the "\*(L" operator so that the
object is represented as a human readable string in the form
\&\*(R"seq_id:start..end" when used in a string context.
.SS "rel2abs"
.IX Subsection "rel2abs"
.Vb 6
\& 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
.Ve
.PP
This function takes a list of positions in relative coordinates to the
segment, and converts them into absolute coordinates.
.SS "abs2rel"
.IX Subsection "abs2rel"
.Vb 6
\& 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
.Ve
.PP
This function takes a list of positions in absolute coordinates
and returns a list expressed in relative coordinates.
.SS "Bio::SeqFeatureI compatibility methods"
.IX Subsection "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 \*(L"region\*(R"
(\s-1SO:0000001\s0 \*(L"Continous sequence >=1 base pair\*(R").
.PP
All these methods are read-only except for the primary_id, which can
be get or set.
.PP
The following Bio::SeqFeatureI methods are supported:
.IP "start" 4
.IX Item "start"
.PD 0
.IP "end" 4
.IX Item "end"
.IP "seq_id" 4
.IX Item "seq_id"
.IP "strand" 4
.IX Item "strand"
.IP "length" 4
.IX Item "length"
.IP "display_name" 4
.IX Item "display_name"
.IP "primary_id" 4
.IX Item "primary_id"
.ie n .IP "primary_tag (always returns ""region"")" 4
.el .IP "primary_tag (always returns ``region'')" 4
.IX Item "primary_tag (always returns region)"
.ie n .IP "source_tag (always returns ""Bio::DB::SeqFeature::Segment"")" 4
.el .IP "source_tag (always returns ``Bio::DB::SeqFeature::Segment'')" 4
.IX Item "source_tag (always returns Bio::DB::SeqFeature::Segment)"
.IP "get_SeqFeatures (always returns an empty list)" 4
.IX Item "get_SeqFeatures (always returns an empty list)"
.IP "seq" 4
.IX Item "seq"
.IP "entire_seq" 4
.IX Item "entire_seq"
.IP "location" 4
.IX Item "location"
.IP "All Bio::RangeI methods" 4
.IX Item "All Bio::RangeI methods"
.PD
.SH "BUGS"
.IX Header "BUGS"
This is an early version, so there are certainly some bugs. Please
use the BioPerl bug tracking system to report bugs.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
bioperl,
Bio::DB::SeqFeature::Store,
Bio::DB::SeqFeature::GFF3Loader,
Bio::DB::SeqFeature::Store::DBI::mysql,
Bio::DB::SeqFeature::Store::bdb
.SH "AUTHOR"
.IX Header "AUTHOR"
Lincoln Stein <lstein@cshl.org>.
.PP
Copyright (c) 2006 Cold Spring Harbor Laboratory.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.