.\" Automatically generated by Pod::Man 4.09 (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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Bio::Graphics::Browser2::RegionSearch 3pm"
.TH Bio::Graphics::Browser2::RegionSearch 3pm "2018-10-03" "perl v5.26.2" "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::Graphics::Browser2::RegionSearch \-\- Search through multiple databases for feature matches.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\&  my $dbs = Bio::Graphics::Browser2::RegionSearch\->new(
\&              { source => $data_source, 
\&                state  => $session_state
\&              });
\&  $dbs\->init_databases();
\&  my $features = $dbs\->search_features({\-search_term=>\*(Aqsma\-3\*(Aq});
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This implements a feature search based on the heuristics in
Bio::Graphics::Browser2::Region. The search is distributed across all
local and remote databases as specified in the data source.
.SH "METHODS"
.IX Header "METHODS"
The remainder of this document describes the methods available to the
programmer.
.ie n .SS "$db = Bio::Graphics::Browser2::RegionSearch\->new({opts})"
.el .SS "\f(CW$db\fP = Bio::Graphics::Browser2::RegionSearch\->new({opts})"
.IX Subsection "$db = Bio::Graphics::Browser2::RegionSearch->new({opts})"
Create a new RegionSearch object. Required parameters are:
.PP
.Vb 1
\&        Parameter     Description
\&
\&        source        The Bio::Graphics::Browser2::DataSource
\&                      object describing the local and remote
\&                      databases for this source.
\&
\&        state         The page_settings document describing the
\&                      current state of the user session (for
\&                      looking up search_options and the like in the
\&                      future).
.Ve
.ie n .SS "$db\->init_databases(\e@labels)"
.el .SS "\f(CW$db\fP\->init_databases(\e@labels)"
.IX Subsection "$db->init_databases(@labels)"
This method will initialize all the databases in preparation for a
search. Pass it a list of track labels to search only in the databases
defined by those tracks. Otherwise it will sort all tracks into local
and remote ones.
.ie n .SS "$source = \fIsource()\fP"
.el .SS "\f(CW$source\fP = \fIsource()\fP"
.IX Subsection "$source = source()"
Return the data source.
.SS "\fIstate()\fP"
.IX Subsection "state()"
.SS "\fIremote_dbs()\fP"
.IX Subsection "remote_dbs()"
.SS "\fIlocal_dbs()\fP"
.IX Subsection "local_dbs()"
.ie n .SS "@features = $db\->features(@args)"
.el .SS "\f(CW@features\fP = \f(CW$db\fP\->features(@args)"
.IX Subsection "@features = $db->features(@args)"
Pass \f(CW@args\fR to the underlying db adaptors' \fIfeatures()\fR methods and return all
matching features. Example:
.PP
.Vb 1
\&   @features = $db\->features(\-type=>\*(AqCDS\*(Aq)
.Ve
.ie n .SS "$meta_segment = $db\->segment($segment)"
.el .SS "\f(CW$meta_segment\fP = \f(CW$db\fP\->segment($segment)"
.IX Subsection "$meta_segment = $db->segment($segment)"
Given an existing segment, return a
Bio::Graphics::Browser2::MetaSegment object, which behaves more or
less like a regular Bio::Das::SegmentI object, but searches multiple
databases. Both iterative and non-iterative feature fetching is
supported.
.PP
(The class definitions for Bio::Graphics::Browser2::MetaSegment are
located in the Bio/Graphics/Browser/RegionSearch.pm file.)
.ie n .SS "$segment = $db\->feature2segment($feature)"
.el .SS "\f(CW$segment\fP = \f(CW$db\fP\->feature2segment($feature)"
.IX Subsection "$segment = $db->feature2segment($feature)"
Converts a feature into a segment in the database that the feature
corresponds to.
.ie n .SS "@segments = $db\->features2segments($feature)"
.el .SS "\f(CW@segments\fP = \f(CW$db\fP\->features2segments($feature)"
.IX Subsection "@segments = $db->features2segments($feature)"
As above, but takes an arrayref of features and returns an array of
segments.
.ie n .SS "$found = $db\->search_features($args)"
.el .SS "\f(CW$found\fP = \f(CW$db\fP\->search_features($args)"
.IX Subsection "$found = $db->search_features($args)"
This method will search all the databases for features matching the
search term and will return the results as an array ref of
Bio::SeqFeatureI objects. The arguments are a hash ref containing the
various options passed to the db adaptors' \fIfeatures()\fR method
(e.g. \*(L"\-type\*(R"), or a hashref with the key \*(L"\-search_term\*(R", in which
case the search term is parsed as any of gbrowse's heuristic keyword
searches.
.PP
If no args are provided, then the search term is taken from the \*(L"name\*(R"
field of the settings object.
.ie n .SS "$found = $db\->search_features_locally($args)"
.el .SS "\f(CW$found\fP = \f(CW$db\fP\->search_features_locally($args)"
.IX Subsection "$found = $db->search_features_locally($args)"
Search only the local databases for the term.
.PP
\&\f(CW$Args\fR is a hashref:
.PP
.Vb 4
\&   Key             Value
\&   \-\-\-             \-\-\-\-\-
\&   \-search_term    term to search for
\&   \-shortcircuit   stop searching if term is found in default db
.Ve
.PP
If \-shortcircuit is not provided, it defaults to true.
.ie n .SS "$found = $db\->search_features_remotely($args)"
.el .SS "\f(CW$found\fP = \f(CW$db\fP\->search_features_remotely($args)"
.IX Subsection "$found = $db->search_features_remotely($args)"
Search only the remote databases for the term.
.ie n .SS "$db\->add_dbid_to_features($db,$features)"
.el .SS "\f(CW$db\fP\->add_dbid_to_features($db,$features)"
.IX Subsection "$db->add_dbid_to_features($db,$features)"
Add a \fIgbrowse_dbid()\fR method to each of the features in the list.
.ie n .SS "$mapper = $search\->coordinate_mapper($segment,$optimize)"
.el .SS "\f(CW$mapper\fP = \f(CW$search\fP\->coordinate_mapper($segment,$optimize)"
.IX Subsection "$mapper = $search->coordinate_mapper($segment,$optimize)"
Create a Bio::Graphics coordinator mapper on the current segment. If
optimize set to true, then features that map outside the current
segment's seqid and region are nulled.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Bio::Graphics::Browser2::Region,
Bio::Graphics::Browser,
Bio::Graphics::Feature,
.SH "AUTHOR"
.IX Header "AUTHOR"
Lincoln Stein <lincoln.stein@gmail.com>.
.PP
Copyright (c) 2008 Cold Spring Harbor Laboratory & Ontario Institute for Cancer Research
.PP
This package and its accompanying libraries is free software; you can
redistribute it and/or modify it under the terms of the \s-1GPL\s0 (either
version 1, or at your option, any later version) or the Artistic
License 2.0.  Refer to \s-1LICENSE\s0 for the full license text. In addition,
please see \s-1DISCLAIMER\s0.txt for disclaimers of warranty.