NAME

FSSM::SOAPClient - Access the Fortinbras FSSM web service

SYNOPSIS

 # create client
 my $client = FSSM::SOAPClient->new();

 # set parameters
 $client->search('none');
 $client->predictor('subtype B SI/NSI');
 $client->expansion('avg');
 $client->seqtype('nt');
 # or...
 $client->new( search => 'align', expansion => 'avg',
               seqtype => 'nt', predictor => 'subtype C SI/NSI' );

 # attach sequences
 $client->attach_seqs('my.fas');

 # run query
 my $result = $client->run;

 # parse query
 while ( my $item = $result->next_call ) {
    print $item->{seqid}, "\t";
    if ($item->{predicted}) {
       print "predicted SI\n";
    }
    else {
       print "predicted NSI\n";
    }
 }

DESCRIPTION

This module allows the user to conveniently call the HIV-1 coreceptor predictor web service at http://fortinbras.us and parse the resulting analysis. For details about this service and its purpose, please visit http://fortinbras.us/fssm.

The external module SOAP::Lite is required, and is available from CPAN.

USAGE

The basic steps are (1) create a client object, (2) set client parameters, (3) attach a set of nucleotide or amino acid sequences, (4) run the query to obtain a result object, (5) iterate the result object to obtain the analysis for each sequence.

Create a client

The client object is a 'factory', from which you can set parameters, attach sequences, and run your query.

 my $client = FSSM::SOAPClient->new();

Set parameters

Parameters for a query include:

 Parameter  Function            Acceptable values
 =========  ===========         =================
 search     how to find V3      none | fast | align
 expansion  handle ambiguities  none | avg | full
 seqtype    residue type        aa | nt | auto
 predictor  desired matrix      names as given at 
                                http://fortinbras.us/fssm

To set parameters, call the corresponding method from the client:

 $client->search('none');
 $client->predictor('subtype B SI/NSI');

or use set_parameters():

 $client->set_parameters( search => 'none', expansion => 'avg' );

Parameters can also be set when the client is created:

 $client->new( search => 'align', expansion => 'avg',
               seqtype => 'nt', predictor => 'subtype C SI/NSI' );

For details on the meaning of these parameters, see http://fortinbras.us/fssm.

If you forget the available parameters or their acceptable values, use available_parameters:

 @parameter_names = $client->available_parameters;
 @accepted_for_search = $client->available_parameters('search');

Attach sequences

To attach your sequences, call attach_seqs(). You may specify

• a FASTA-formatted file:

   $client->attach_seqs('my.fas');

• a hash reference with elements of the form $seq_id = $sequence>:

   $client->attach_seqs( { 'seq1' => 'ATC', 'seq2' => 'GGC' } )

• an array reference with hashref elements of the form { seqid = $id, sequence => $sequence }>:

   @seqs = ( { seqid => $id, sequence => $sequence } );
   $client->attach_seqs(\@seqs);

• or, if you use BioPerl (http://bioperl.org), an arrayref of BioPerl sequence objects of any type:

   @seqs = $align->each_seq;
   $client->attach_seqs( \@seqs );

Running a query

Simply call run() :

 my $result = $client->run;

Parsing the result

The result is returned in another Perl object (of class FSSM::SOAPClient::Result). Use next_call from this object to iterate through the analyses:

 while ( my $item = $result->next_call ) {
    print $item->{seqid}, "\t";
    if ($item->{predicted}) {
       print "predicted SI\n";
    }
    else {
       print "predicted NSI\n";
    }
 }

To obtain an array of all items at once, use each_call:

 @items = $result->each_call;

Rewind the iterator with rewind:

 $result->rewind;
 # starting over...
 while ( my $item = $result->next_call ) {
   # ...
 }

Use metadata() to obtain the date, ip-address, and predictor used for the run:

 $date_run = $result->metadata->{'date'};
 $ip = $result->metadata->{'your-ip'};
 $predictor_used = $result->metadata->{'predictor'};

UNDER THE HOOD

The SOAP::Lite client object can be retrieved with

 $soap = $client->soap_client()

The SOAP::SOM message can be retrieved with

 $som = $client->som;

Request data in SOAP::Data format can be retrieved with

 $data = $client->request_data;

and cleared with

 $client->clear_request;

AUTHOR - Mark A. Jensen

    CPAN ID: MAJENSEN
    Fortinbras Research
    http://fortinbras.us

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

SOAP::Lite, http://fortinbras.us/fssm

METHODS

run()

 Title   : run
 Usage   : $client->run;
 Function: run FSSM query using currently set client
           parameters
 Returns : result object on succesful query,
           undef on SOAP fault (see
           errcode() and errstr() for 
           detail)
 Args    : none

attach_seqs()

 Title   : attach_seqs
 Usage   : 
 Function: attach a set of sequences to the client in 
           preparation for query
 Returns : true on sucess
 Args    : fasta file name | array of BioPerl seq objects |
           arrayref of hashes { seqid => $id, sequence => $seq }|
           hashref of { $id => $sequence, ... }

Parameters

seqtype()

 Title   : seqtype
 Usage   : 
 Function: get/set sequence type [aa|nt|auto] for the client
 Returns : scalar string
 Args    : [aa|nt|auto]
           aa   : amino acid data
           nt   : nucleotide data
           auto : let BioPerl guess each sequence (unreliable when
                  many ambiguity symbols present)

predictor()

 Title   : predictor
 Usage   : $client->predictor('subtype B SI/NSI');
 Function: get/set underlying predictor for client
 Returns : scalar string
 Args    : run $client->available_parameters('predictor') 
           for a list of accepted predictors

expansion()

 Title   : expansion
 Usage   : $client->expansion('avg');
 Function: get/set ambiguity expansion selector for client
 Returns : scalar string
 Args    : none | avg | full
           none : no amibiguity expansion (ambig treated like 'X')
           avg  : return average score over all possible non-ambig seqs
           full : return individual scores for all non-ambig seqs 
                  (can fail if too many)

search()

 Title   : search
 Usage   : $client->search('align');
 Function: get/set search selector for client
 Returns : scalar string
 Args    : none | fast | align
           none : treat each sequence as already aligned
           fast : find V3 loop using a regular expression heuristic
           align: align seqs to PSSM matrix to find V3 loop

Parameter manipulation

set_parameters()

 Title   : set_parameters
 Usage   : 
 Function: set client parameters
 Returns : 
 Args    : 

get_parameters()

 Title   : get_parameters
 Usage   : 
 Function: get current client parameters
 Returns : array
 Args    : none

reset_parameters()

 Title   : reset_parameters
 Usage   : 
 Function: reset client parameters
 Returns : 
 Args    : 

available_parameters()

 Title   : available_parameters
 Usage   : @parms = $client->available_parameters;
           @accept = $client->available_parameters('seqtype');
 Function: list available parameters or acceptable values
 Returns : array of scalar strings or undef
 Args    : scalar string (a valid parameter name)

parameters_changed()

 Title   : parameters_changed
 Usage   : 
 Function: set if client parameters have been changed
           since last parameter access
 Returns : boolean
 Args    : new value or undef

Accessors/Attributes

soap_client()

 Title   : soap_client
 Usage   : $soap = $client->soap_client
 Function: Get the SOAP::Lite client attached to this object
 Returns : a SOAP::Lite object or undef
 Args    : none

som()

 Title   : som
 Alias   : message
 Usage   : $som = $client->som
 Function: get the current SOAP::SOM (message) object 
           attached to the client
 Returns : a SOAP::SOM object or undef
 Args    : none

request_data()

 Title   : request_data
 Usage   : $data =$self->request_data
 Function: creates/gets the SOAP::Data structure forming the 
           request
 Returns : a SOAP::Data object
 Args    : none

clear_request()

 Title   : clear_request
 Usage   : $client->clear_request
 Function: reset the request data
 Returns : true
 Args    : none

ok(), errcode(), errstr()()

 Title   : ok(), errcode(), errstr()
 Usage   : if (!$client->ok()) { warn $client->errstr }
 Function: test the SOAP response message for faults
 Returns : ok() : true if success, false if fault present
           errcode() : the SOAP fault code (scalar int)
           errstr() : the SOAP faultstring (scalar string)
 Args    : none

NAME

FSSM::SOAPClient::Result - access the returned FSSM analysis

FSSM::SOAPClient::Result objects are returned by FSSM::SOAPClient::run(). Use the following methods to retrieve the analysis.

METHODS

next_call()

 Title   : next_call
 Usage   : $item = $result->next_call
 Function: get the FSSM call for the next submitted sequence
 Returns : hashref of data, with the following key => value pairs:
           seqid => the submitted sequence name/id
           ourid => the id as modified by FSSM (for differentiating
                    among strand/frame/non-amibig translations of
                    a single submitted sequence, with symbol
                    indicating comment)
           score => PSSM score
           left-end => 5' or N-terminal coordinate of V3
           right-end => 3' or C-terminal coordinate of V3
           comment => describes a possible caveat for this sequence
           predicted => 1 if X4/SI or dual, 0 if R5/NSI
           plabel => predicted phenotype in this predictor's context
 Args    : none

rewind()

 Title   : rewind
 Usage   : $result->rewind
 Function: reset the next_call iterator to the beginning
 Returns : true
 Args    : none

each_call()

 Title   : each_call
 Usage   : @calls = $result->each_call;
 Function: returns an array of call hashes as described 
           in next_call()
 Returns : array of hashrefs
 Args    : none

metadata()

 Title   : metadata
 Alias   : meta
 Usage   : $run_info = $result->metadata
 Function: Obtains some data about the run
 Returns : hashref with following key => value pairs
           date : date/time of run
           your-ip : ip address from which the run originated
           predictor : predictor used
 Args    : none

cpanm FSSM::SOAPClient

perl -MCPAN -e shell
install FSSM::SOAPClient