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.

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

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

USAGE

UNDER THE HOOD

AUTHOR - Mark A. Jensen

COPYRIGHT

SEE ALSO

METHODS

run()

attach_seqs()

Parameters

seqtype()

predictor()

expansion()

search()

Parameter manipulation

set_parameters()

get_parameters()

reset_parameters()

available_parameters()

parameters_changed()

Accessors/Attributes

soap_client()

som()

request_data()

clear_request()

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

NAME

METHODS

next_call()

rewind()

each_call()

metadata()

Module Install Instructions