Bio::D...:Result(3pm)

💖 Bio::DB::SoapEUtilities::Result — the accessor object for SoapEUtilities results 💖

okay bestie, so this is a Perl module from the Bioperl fam, and it's literally the little helper that holds onto your Entrez Utilities SOAP responses and makes them not-a-nightmare to read. Let's get into it 🦋

---

✨ 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 🌸

So here's the vibe: this module is doing its absolute best to make Entrez Utilities SOAP responses as user-friendly and intuitive as possible. Those responses? They're complex structures, highkey packed with useful data, but realistically you usually just want the values of a few key fields. That's where the Result object comes in — it gives you access to all the response values through systematically named accessor methods, plus the commonly used values as convenience methods. And the 'raw' SOAP message (a SOAP::SOM object, exactly as returned by SOAP::Lite) is also provided, no gatekeeping 💅

Convenience accessors

If the call returns a list of record ids, ids() hands them back to you as an array reference:

@seq_ids = $result->ids;

The total count of returned records? That's count()'s whole job:

$num_recs = $result->count;

And if usehistory was specified in the SOAP call, then the NCBI-assigned web environment (which you can use in future calls, iconic) lives in webenv, and the query key assigned to the result lives 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's 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>), while 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

---

okay that's the whole page bestie, you ate it up 💅✨ this was perl v5.36.0, dated 2023-01-22, and it's the Bio::D...:Result(3pm) page. go slay your SOAP responses 🎀🦋💖