Provided by: libbio-perl-run-perl_1.7.3-9_all 
NAME
Bio::DB::SoapEUtilities::Result - Accessor object for SoapEUtilities results
SYNOPSIS
$fac = Bio::DB::SoapEUtilities->new();
$result = $fac->esearch( -db => 'gene', -term => 'hedgehog')->run;
$count = $result->count; # case important; $result->Count could be arrayref
@ids = $result->ids;
DESCRIPTION
This module attempts to make Entrez Utilities SOAP responses as user-friendly and
intuitive as possible. These responses can be complex structures with much useful data;
but users will generally desire the values of some key fields. The Result object provides
access to all response values via systematically named accessor methods, and commonly used
values as convenience methods. The 'raw' SOAP message (a SOAP::SOM object as returned by
SOAP::Lite) is also provided.
Convenience accessors
If a list of record ids is returned by the call, "ids()" will return these as an array
reference:
@seq_ids = $result->ids;
The total count of returned records is provided by "count()":
$num_recs = $result->count;
If "usehistory" was specified in the SOAP call, the NCBI-assigned web environment
(that can be used in future calls) is available in "webenv", and the query key
assigned to the result in "query_key":
$next_result = $fac->efetch( -WebEnv => $result->webenv,
-QueryKey => $result->query_key );
Walking the response
This module uses "AUTOLOAD" to provide accessor methods for all response data. Here
is an example of a SOAP response as returned by a "method()" call off the SOAP::SOM
object:
DB<5> x $result->som->method
0 HASH(0x2eac9a4)
'Count' => 148
'IdList' => HASH(0x4139578)
'Id' => 100136227
'QueryKey' => 1
'QueryTranslation' => 'sonic[All Fields] AND hedgehog[All Fields]'
'RetMax' => 20
'RetStart' => 0
'TranslationSet' => ''
'TranslationStack' => HASH(0x4237b4c)
'OP' => 'GROUP'
'TermSet' => HASH(0x42c43bc)
'Count' => 2157
'Explode' => 'Y'
'Field' => 'All Fields'
'Term' => 'hedgehog[All Fields]'
'WebEnv' => 'NCID_1_150423569_130.14.22.101_9001_1262703782'
Some of the data values here (at the tips of the data structure) are actually arrays
of values ( e.g., the tip "IdList =" Id> ), other tips are simple scalars. With this
in mind, "Result" accessor methods work as follows:
Data values (at the tips of the response structure) are acquired by calling a method
with the structure keys separated by underscores (if necessary):
$query_key = $result->QueryKey; # $query_key == 1
$ids = $result->IdList_Id; # @$ids is an array of record ids
Data sets below a particular node in the response structure can also be obtained with
similarly constructed method names. These 'internal node accessors' return a hashref,
containing all data leaves below the node, keyed by the accessor names:
$data_hash = $result->TranslationStack
DB<3> x $data_hash
0 HASH(0x43569d4)
'TranslationStack_OP' => ARRAY(0x42d9988)
0 'AND'
1 'GROUP'
'TranslationStack_TermSet_Count' => ARRAY(0x4369c64)
0 148
1 148
2 2157
'TranslationStack_TermSet_Explode' => ARRAY(0x4368998)
0 'Y'
1 'Y'
'TranslationStack_TermSet_Field' => ARRAY(0x4368260)
0 'All Fields'
1 'All Fields'
'TranslationStack_TermSet_Term' => ARRAY(0x436c97c)
0 'sonic[All Fields]'
1 'hedgehog[All Fields]'
Similarly, the call " $result-"TranslationStack_TermSet > would return a similar hash
containing the last 4 elements of the example hash above.
Creating accessors is somewhat costly, especially for fetch responses which can be
deep and complex (not unlike BioPerl developers). Portions of the response tree can be
ignored by setting "-prune_at_node" to a arrayref of nodes to skip. Nodes should be
specified in SOAP::SOM format, e.g.
...::Result->new( -prune_at_nodes => ['//GBSeq_references'] );
Accessor creation can be skipped altogether by passing "-no_parse =" 1> to the
"Result" constructor. This is recommended if a result is being passed to a
Bio::DB::SoapEUtilities::FetchAdaptor. The original SOAP message with all data is
always available in "$result-"som>.
Other methods
accessors()
An array of available data accessor names. This contains only the data "tips". The
internal node accessors are autoloaded.
ok()
True if no SOAP fault.
errstr()
Returns the SOAP fault error string.
som()
The original "SOAP::SOM" message.
util()
The EUtility associated with the result.
FEEDBACK
Mailing Lists
User feedback is an integral part of the evolution of this and other Bioperl modules. Send
your comments and suggestions preferably to the Bioperl mailing list. Your participation
is much appreciated.
bioperl-l@bioperl.org - General discussion
http://bioperl.org/wiki/Mailing_lists - About the mailing lists
Support
Please direct usage questions or support issues to the mailing list:
bioperl-l@bioperl.org
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.
Reporting Bugs
Report bugs to the Bioperl bug tracking system to help us keep track of the bugs and their
resolution. Bug reports can be submitted via the web:
http://redmine.open-bio.org/projects/bioperl/
AUTHOR - Mark A. Jensen
Email maj -at- fortinbras -dot- us
APPENDIX
The rest of the documentation details each of the object methods. Internal methods are
usually preceded with a _
parse_methods()
Title : parse_methods
Usage :
Function: parse out the accessor methods
Returns : self (Result object)
Args : $alias_hash (hashref), $prune_at_nodes (scalar or arrayref)
util()
Title : util
Usage :
Function: Name of the utility producing this result object.
Returns : scalar string
Args :
som()
Title : som
Usage :
Function: get the original SOAP::SOM object
Returns : a SOAP::SOM object
Args : none
ok()
Title : ok
Usage :
Function:
Returns : true if no SOAP fault
Args :
errstr()
Title : errstr
Usage :
Function:
Returns : fault string of SOAP object
Args : none
accessors()
Title : accessors
Usage :
Function: get the list of created accessors for this
result
Returns : array of scalar strings
Args : none
Note : does not include valid AUTOLOADed accessors; see
DESCRIPTION
webenv()
Title : webenv
Usage :
Function: contains WebEnv key referencing this
result's session
Returns : scalar
Args : none
query_key()()
Title : query_key()
Usage :
Function: contains the web query key assigned
to this result
Returns : scalar
Args :
fetch_type()
Title : fetch_type
Usage :
Function: Get the efetch database name according to WSDL
Returns : scalar string (db name) or undef if N/A
Args : none