view release on metacpan or  search on metacpan

lib/Bio/DB/SoapEUtilities.pm  view on Meta::CPAN

# $Id$
#
# BioPerl module for Bio::DB::SoapEUtilities
#
# Please direct questions and support issues to <bioperl-l@bioperl.org>
#
# Cared for by Mark A. Jensen <maj -at- fortinbras -dot- us>
#
# Copyright Mark A. Jensen
#
# You may distribute this module under the same terms as perl itself

# POD documentation - main docs before the code

=head1 NAME

Bio::DB::SoapEUtilities - Interface to the NCBI Entrez web service *BETA*

=head1 SYNOPSIS

 use Bio::DB::SoapEUtilities;

 # factory construction

 my $fac = Bio::DB::SoapEUtilities->new()

 # executing a utility call

 #get an iteratable adaptor
 my $links = $fac->elink( 
               -dbfrom => 'protein',
               -db => 'taxonomy',
               -id => \@protein_ids )->run(-auto_adapt => 1);

 # get a Bio::DB::SoapEUtilities::Result object
 my $result = $fac->esearch(
               -db => 'gene',
               -term => 'sonic and human')->run;

 # get the raw XML message
 my $xml = $fac->efetch(
             -db => 'gene',
             -id => \@gids )->run( -raw_xml => 1 );

 # change parameters 
 my $new_result = $fac->efetch(
                   -db => 'gene',
                   -id => \@more_gids)->run;
 # reset parameters
 $fac->efetch->reset_parameters( -db => 'nucleotide',
                                 -id => $nucid );
 $result = $fac->efetch->run;
                
 # parsing and iterating the results

 $count = $result->count;
 @ids = $result->ids;
 
 while ( my $linkset = $links->next_link ) {
    $submitted = $linkset->submitted_id;
 }
 
 ($taxid) = $links->id_map($submitted_prot_id);
 $species_io = $fac->efetch( -db => 'taxonomy',
                             -id => $taxid )->run( -auto_adapt => 1);
 $species = $species_io->next_species;
 $linnaeus = $species->binomial;

=head1 DESCRIPTION

This module allows the user to query the NCBI Entrez database via its
SOAP (Simple Object Access Protocol) web service (described at
L<http://eutils.ncbi.nlm.nih.gov/entrez/eutils/soap/v2.0/DOC/esoap_help.html>).
The basic tools (C<einfo, esearch, elink, efetch, espell, epost>) are
available as methods off a C<SoapEUtilities> factory
object. Parameters for each tool can be queried, set and reset for
each method through the L<Bio::ParameterBaseI> standard calls
(C<available_parameters(), set_parameters(), get_parameters(),
reset_parameters()>). Returned data can be retrieved, accessed and
parsed in several ways, according to user preference. Adaptors and
object iterators are available for C<efetch>, C<egquery>, C<elink>,
and C<esummary> results.

=head1 USAGE

The C<SoapEU> system has been designed to be as easy (few includes,
available parameter facilities, reasonable defaults, intuitive
aliases, built-in pipelines) or as complex (accessors for underlying
low-level objects, all parameters accessible, custom hooks for builder
objects, facilities for providing local copies of WSDLs) as the user
requires or desires. (To the extent that it does not succeed in either
direction, it is up to the user to report to the mailing list
(L</FEEDBACK>)!)

=head2 Factory

To begin, make a factory:

 my $fac = Bio::DB::SoapEUtilities->new();

From the factory, utilities are called, parameters are set, and
results or adaptors are retrieved.

If you have your own copy of the wsdl, use

 my $fac = Bio::Db::SoapEUtilities->new( -wsdl_file => $my_wsdl );

otherwise, the correct one will be obtained over the network (by