Bio::DB::SoapEUtilities::Result - Accessor object for SoapEUtilities results
$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;
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.
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.
[email protected] - General discussion
http://bioperl.org/wiki/Mailing_lists - About the mailing lists
Please direct usage questions or support issues to the mailing list:
[email protected]
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.
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/
Email maj -at- fortinbras -dot- us
The rest of the documentation details each of the object methods. Internal
methods are usually preceded with a _
Title : parse_methods
Usage :
Function: parse out the accessor methods
Returns : self (Result object)
Args : $alias_hash (hashref), $prune_at_nodes (scalar or arrayref)
Title : util
Usage :
Function: Name of the utility producing this result object.
Returns : scalar string
Args :
Title : som
Usage :
Function: get the original SOAP::SOM object
Returns : a SOAP::SOM object
Args : none
Title : ok
Usage :
Function:
Returns : true if no SOAP fault
Args :
Title : errstr
Usage :
Function:
Returns : fault string of SOAP object
Args : none
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
Title : webenv
Usage :
Function: contains WebEnv key referencing this
result's session
Returns : scalar
Args : none
Title : query_key()
Usage :
Function: contains the web query key assigned
to this result
Returns : scalar
Args :
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