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.
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
$num_recs = $result->count;
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
$next_result = $fac->efetch( -WebEnv => $result->webenv, -QueryKey => $result->query_key );
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_22.214.171.124_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
An array of available data accessor names. This contains only the data "tips". The internal node accessors are autoloaded.
True if no SOAP fault.
Returns the SOAP fault error string.
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.
firstname.lastname@example.org - General discussion http://bioperl.org/wiki/Mailing_lists - About the mailing lists
Please direct usage questions or support issues to the mailing list:
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:
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