.\" 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::Das::SegmentI 3pm"
.TH Bio::Das::SegmentI 3pm "2020-10-28" "perl v5.30.3" "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::Das::SegmentI \- DAS\-style access to a feature database
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  # Get a Bio::Das::SegmentI object from a Bio::DasI database...
\&
\&  $segment = $das\->segment(\-name=>\*(AqLandmark\*(Aq,
\&                           \-start=>$start,
\&                           \-end => $end);
\&
\&  @features = $segment\->overlapping_features(\-type=>[\*(Aqtype1\*(Aq,\*(Aqtype2\*(Aq]);
\&  # each feature is a Bio::SeqFeatureI\-compliant object
\&
\&  @features = $segment\->contained_features(\-type=>[\*(Aqtype1\*(Aq,\*(Aqtype2\*(Aq]);
\&
\&  @features = $segment\->contained_in(\-type=>[\*(Aqtype1\*(Aq,\*(Aqtype2\*(Aq]);
\&
\&  $stream = $segment\->get_feature_stream(\-type=>[\*(Aqtype1\*(Aq,\*(Aqtype2\*(Aq,\*(Aqtype3\*(Aq];
\&  while (my $feature = $stream\->next_seq) {
\&     # do something with feature
\&  }
\&
\&  $count = $segment\->features_callback(\-type=>[\*(Aqtype1\*(Aq,\*(Aqtype2\*(Aq,\*(Aqtype3\*(Aq],
\&                                       \-callback => sub { ... { }
\&                                       );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Bio::Das::SegmentI is a simplified alternative interface to sequence
annotation databases used by the distributed annotation system. In
this scheme, the genome is represented as a series of landmarks.  Each
Bio::Das::SegmentI object (\*(L"segment\*(R") corresponds to a genomic region
defined by a landmark and a start and end position relative to that
landmark.  A segment is created using the Bio::DasI \fBsegment()\fR method.
.PP
Features can be filtered by the following attributes:
.PP
.Vb 2
\&  1) their location relative to the segment (whether overlapping,
\&          contained within, or completely containing)
\&
\&  2) their type
\&
\&  3) other attributes using tag/value semantics
.Ve
.PP
Access to the feature list uses three distinct APIs:
.PP
.Vb 1
\&  1) fetching entire list of features at a time
\&
\&  2) fetching an iterator across features
\&
\&  3) a callback
.Ve
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "Mailing Lists"
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.
.PP
.Vb 1
\&  bioperl\-l@bio.perl.org
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
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.
.SS "Reporting Bugs"
.IX Subsection "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:
.PP
.Vb 1
\&  https://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "AUTHOR \- Lincoln Stein"
.IX Header "AUTHOR - Lincoln Stein"
Email lstein@cshl.org
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object
methods. Internal methods are usually preceded with a _
.SS "seq_id"
.IX Subsection "seq_id"
.Vb 6
\& Title   : seq_id
\& Usage   : $ref = $s\->seq_id
\& Function: return the ID of the landmark
\& Returns : a string
\& Args    : none
\& Status  : Public
.Ve
.SS "display_name"
.IX Subsection "display_name"
.Vb 6
\& Title   : seq_name
\& Usage   : $ref = $s\->seq_name
\& Function: return the human\-readable name for the landmark
\& Returns : a string
\& Args    : none
\& Status  : Public
.Ve
.PP
This defaults to the same as seq_id.
.SS "start"
.IX Subsection "start"
.Vb 6
\& Title   : start
\& Usage   : $s\->start
\& Function: start of segment
\& Returns : integer
\& Args    : none
\& Status  : Public
.Ve
.PP
This is a read-only accessor for the start of the segment.  Alias
to \fBlow()\fR for Gadfly compatibility.
.SS "end"
.IX Subsection "end"
.Vb 6
\& Title   : end
\& Usage   : $s\->end
\& Function: end of segment
\& Returns : integer
\& Args    : none
\& Status  : Public
.Ve
.PP
This is a read-only accessor for the end of the segment. Alias to
\&\fBhigh()\fR for Gadfly compatibility.
.SS "length"
.IX Subsection "length"
.Vb 6
\& Title   : length
\& Usage   : $s\->length
\& Function: length of segment
\& Returns : integer
\& Args    : none
\& Status  : Public
.Ve
.PP
Returns the length of the segment.  Always a positive number.
.SS "seq"
.IX Subsection "seq"
.Vb 6
\& Title   : seq
\& Usage   : $s\->seq
\& Function: get the sequence string for this segment
\& Returns : a string
\& Args    : none
\& Status  : Public
.Ve
.PP
Returns the sequence for this segment as a simple string.
.SS "ref"
.IX Subsection "ref"
.Vb 6
\& Title   : ref
\& Usage   : $ref = $s\->ref([$newlandmark])
\& Function: get/set the reference landmark for addressing
\& Returns : a string
\& Args    : none
\& Status  : Public
.Ve
.PP
This method is used to examine/change the reference landmark used to
establish the coordinate system.  By default, the landmark cannot be
changed and therefore this has the same effect as \fBseq_id()\fR.  The new
landmark might be an \s-1ID,\s0 or another Das::SegmentI object.
.SS "absolute"
.IX Subsection "absolute"
.Vb 6
\& Title   : absolute
\& Usage   : $s\->absolute([$new_value])
\& Function: get/set absolute addressing mode
\& Returns : flag
\& Args    : new flag (optional)
\& Status  : Public
.Ve
.PP
Turn on and off absolute-addressing mode.  In absolute addressing
mode, coordinates are relative to some underlying \*(L"top level\*(R"
coordinate system (such as a chromosome). \fBref()\fR returns the identity
of the top level landmark, and \fBstart()\fR and \fBend()\fR return locations
relative to that landmark.  In relative addressing mode, coordinates
are relative to the landmark sequence specified at the time of segment
creation or later modified by the \fBref()\fR method.
.PP
The default is to return false and to do nothing in response to
attempts to set absolute addressing mode.
.SS "features"
.IX Subsection "features"
.Vb 6
\& Title   : features
\& Usage   : @features = $s\->features(@args)
\& Function: get features that overlap this segment
\& Returns : a list of Bio::SeqFeatureI objects
\& Args    : see below
\& Status  : Public
.Ve
.PP
This method will find all features that intersect the segment in a
variety of ways and return a list of Bio::SeqFeatureI objects.  The
feature locations will use coordinates relative to the reference
sequence in effect at the time that \fBfeatures()\fR was called.
.PP
The returned list can be limited to certain types, attributes or
range intersection modes.  Types of range intersection are one of:
.PP
.Vb 3
\&   "overlaps"      the default
\&   "contains"      return features completely contained within the segment
\&   "contained_in"  return features that completely contain the segment
.Ve
.PP
Two types of argument lists are accepted.  In the positional argument
form, the arguments are treated as a list of feature types.  In the
named parameter form, the arguments are a series of \-name=>value
pairs.
.PP
.Vb 2
\&  Argument    Description
\&  \-\-\-\-\-\-\-\-   \-\-\-\-\-\-\-\-\-\-\-\-
\&
\&  \-types      An array reference to type names in the format
\&              "method:source"
\&
\&  \-attributes A hashref containing a set of attributes to match
\&
\&  \-rangetype  One of "overlaps", "contains", or "contained_in".
\&
\&  \-iterator   Return an iterator across the features.
\&
\&  \-callback   A callback to invoke on each feature
.Ve
.PP
The \-attributes argument is a hashref containing one or more
attributes to match against:
.PP
.Vb 2
\&  \-attributes => { Gene => \*(Aqabc\-1\*(Aq,
\&                   Note => \*(Aqconfirmed\*(Aq }
.Ve
.PP
Attribute matching is simple string matching, and multiple attributes
are ANDed together.  More complex filtering can be performed using the
\&\-callback option (see below).
.PP
If \-iterator is true, then the method returns an object reference that
implements the \fBnext_seq()\fR method.  Each call to \fBnext_seq()\fR returns a
new Bio::SeqFeatureI object.
.PP
If \-callback is passed a code reference, the code reference will be
invoked on each feature returned.  The code will be passed two
arguments consisting of the current feature and the segment object
itself, and must return a true value. If the code returns a false
value, feature retrieval will be aborted.
.PP
\&\-callback and \-iterator are mutually exclusive options.  If \-iterator
is defined, then \-callback is ignored.
.PP
\&\s-1NOTE:\s0 the following methods all build on top of \fBfeatures()\fR, and do not
need to be explicitly implemented.
.PP
.Vb 4
\&    overlapping_features()
\&    contained_features()
\&    contained_in()
\&    get_feature_stream()
.Ve
.SS "overlapping_features"
.IX Subsection "overlapping_features"
.Vb 6
\& Title   : overlapping_features
\& Usage   : @features = $s\->overlapping_features(@args)
\& Function: get features that overlap this segment
\& Returns : a list of Bio::SeqFeatureI objects
\& Args    : see below
\& Status  : Public
.Ve
.PP
This method is identical to \fBfeatures()\fR except that it defaults to
finding overlapping features.
.SS "contained_features"
.IX Subsection "contained_features"
.Vb 6
\& Title   : contained_features
\& Usage   : @features = $s\->contained_features(@args)
\& Function: get features that are contained in this segment
\& Returns : a list of Bio::SeqFeatureI objects
\& Args    : see below
\& Status  : Public
.Ve
.PP
This method is identical to \fBfeatures()\fR except that it defaults to
a range type of 'contained'.
.SS "contained_in"
.IX Subsection "contained_in"
.Vb 6
\& Title   : contained_in
\& Usage   : @features = $s\->contained_in(@args)
\& Function: get features that contain this segment
\& Returns : a list of Bio::SeqFeatureI objects
\& Args    : see below
\& Status  : Public
.Ve
.PP
This method is identical to \fBfeatures()\fR except that it defaults to
a range type of 'contained_in'.
.SS "get_feature_stream"
.IX Subsection "get_feature_stream"
.Vb 6
\& Title   : get_feature_stream
\& Usage   : $iterator = $s\->get_feature_stream(@args)
\& Function: get an iterator across the segment
\& Returns : an object that implements next_seq()
\& Args    : see below
\& Status  : Public
.Ve
.PP
This method is identical to \fBfeatures()\fR except that it always generates
an iterator.
.PP
\&\s-1NOTE:\s0 This is defined in the interface in terms of \fBfeatures()\fR.  You do not
have to implement it.
.SS "factory"
.IX Subsection "factory"
.Vb 6
\& Title   : factory
\& Usage   : $factory = $s\->factory
\& Function: return the segment factory
\& Returns : a Bio::DasI object
\& Args    : see below
\& Status  : Public
.Ve
.PP
This method returns a Bio::DasI object that can be used to fetch
more segments.  This is typically the Bio::DasI object from which
the segment was originally generated.
.SS "primary_tag"
.IX Subsection "primary_tag"
.Vb 6
\& Title   : primary_tag
\& Usage   : $tag = $s\->primary_tag
\& Function: identifies the segment as type "DasSegment"
\& Returns : a string named "DasSegment"
\& Args    : none
\& Status  : Public, but see below
.Ve
.PP
This method provides Bio::Das::Segment objects with a \fBprimary_tag()\fR
field that identifies them as being of type \*(L"DasSegment\*(R".  This allows
the Bio::Graphics engine to render segments just like a feature in order
nis way useful.
.PP
This does not need to be implemented.  It is defined by the interface.
.SS "strand"
.IX Subsection "strand"
.Vb 6
\& Title   : strand
\& Usage   : $strand = $s\->strand
\& Function: identifies the segment strand as 0
\& Returns : the number 0
\& Args    : none
\& Status  : Public, but see below
.Ve
.PP
This method provides Bio::Das::Segment objects with a \fBstrand()\fR field
that identifies it as being strandless.  This allows the Bio::Graphics
engine to render segments just like a feature in order nis way useful.
.PP
This does not need to be implemented.  It is defined by the interface.