NAME

       Bio::Graphics::Browser2::RegionSearch -- Search through multiple databases for feature
       matches.

SYNOPSIS

         my $dbs = Bio::Graphics::Browser2::RegionSearch->new(
                     { source => $data_source,
                       state  => $session_state
                     });
         $dbs->init_databases();
         my $features = $dbs->search_features({-search_term=>'sma-3'});

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.

METHODS

       The remainder of this document describes the methods available to the programmer.

   $db = Bio::Graphics::Browser2::RegionSearch->new({opts})
       Create a new RegionSearch object. Required parameters are:

               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).

   $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.

   $source = source()
       Return the data source.

   state()
   remote_dbs()
   local_dbs()
   @features = $db->features(@args)
       Pass @args to the underlying db adaptors' features() methods and return all matching
       features. Example:

          @features = $db->features(-type=>'CDS')

   $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.

       (The class definitions for Bio::Graphics::Browser2::MetaSegment are located in the
       Bio/Graphics/Browser/RegionSearch.pm file.)

   $segment = $db->feature2segment($feature)
       Converts a feature into a segment in the database that the feature corresponds to.

   @segments = $db->features2segments($feature)
       As above, but takes an arrayref of features and returns an array of segments.

   $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' features() method (e.g.
       "-type"), or a hashref with the key "-search_term", in which case the search term is
       parsed as any of gbrowse's heuristic keyword searches.

       If no args are provided, then the search term is taken from the "name" field of the
       settings object.

   $found = $db->search_features_locally($args)
       Search only the local databases for the term.

       $Args is a hashref:

          Key             Value
          ---             -----
          -search_term    term to search for
          -shortcircuit   stop searching if term is found in default db

       If -shortcircuit is not provided, it defaults to true.

   $found = $db->search_features_remotely($args)
       Search only the remote databases for the term.

   $db->add_dbid_to_features($db,$features)
       Add a gbrowse_dbid() method to each of the features in the list.

   $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.

SEE ALSO

       Bio::Graphics::Browser2::Region, Bio::Graphics::Browser, Bio::Graphics::Feature,

AUTHOR

       Lincoln Stein <lincoln.stein@gmail.com>.

       Copyright (c) 2008 Cold Spring Harbor Laboratory & Ontario Institute for Cancer Research

       This package and its accompanying libraries is free software; you can redistribute it
       and/or modify it under the terms of the GPL (either version 1, or at your option, any
       later version) or the Artistic License 2.0.  Refer to LICENSE for the full license text.
       In addition, please see DISCLAIMER.txt for disclaimers of warranty.