FSSM::SOAPClient - Access the Fortinbras FSSM web service
# 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"; } }
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.
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.
The client object is a 'factory', from which you can set parameters, attach sequences, and run your query.
my $client = FSSM::SOAPClient->new();
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():
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:
available_parameters
@parameter_names = $client->available_parameters; @accepted_for_search = $client->available_parameters('search');
To attach your sequences, call attach_seqs(). You may specify
attach_seqs()
a FASTA-formatted file:
$client->attach_seqs('my.fas');
a hash reference with elements of the form $seq_id = $sequence>:
$seq_id =
$client->attach_seqs( { 'seq1' => 'ATC', 'seq2' => 'GGC' } )
an array reference with hashref elements of the form { seqid = $id, sequence => $sequence }>:
{ seqid =
@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 );
Simply call run() :
run()
my $result = $client->run;
The result is returned in another Perl object (of class FSSM::SOAPClient::Result). Use next_call from this object to iterate through the analyses:
FSSM::SOAPClient::Result
next_call
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:
each_call
@items = $result->each_call;
Rewind the iterator with rewind:
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:
metadata()
$date_run = $result->metadata->{'date'}; $ip = $result->metadata->{'your-ip'}; $predictor_used = $result->metadata->{'predictor'};
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;
CPAN ID: MAJENSEN Fortinbras Research http://fortinbras.us
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.
SOAP::Lite, http://fortinbras.us/fssm
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
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, ... }
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)
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
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)
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
Title : set_parameters Usage : Function: set client parameters Returns : Args :
Title : get_parameters Usage : Function: get current client parameters Returns : array Args : none
Title : reset_parameters Usage : Function: reset client parameters Returns : Args :
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)
Title : parameters_changed Usage : Function: set if client parameters have been changed since last parameter access Returns : boolean Args : new value or undef
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
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
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
Title : clear_request Usage : $client->clear_request Function: reset the request data Returns : true Args : none
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
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.
FSSM::SOAPClient::run()
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
Title : rewind Usage : $result->rewind Function: reset the next_call iterator to the beginning Returns : true Args : none
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
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
To install FSSM::SOAPClient, copy and paste the appropriate command in to your terminal.
cpanm
cpanm FSSM::SOAPClient
CPAN shell
perl -MCPAN -e shell install FSSM::SOAPClient
For more information on module installation, please visit the detailed CPAN module installation guide.