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>.

FEEDBACK

  bioperl-l@bioperl.org                  - General discussion
http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

  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 _

 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

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 137:

You can't have =items (as at line 141) unless the first thing after the =over is an =item