This is a short introduction to the ROSE WebServices offered by BiBiServ. If you're not familiar with using webservices in general you should have a closer look at our webservice related linklist.

If you've a closer look at the WSDL file describing the ROSE webservice, you can see two pairs of methods belonging together.

request and response
request_orig and response_orig

Bioinformatic programs often perform computation on large data sets and therefore require much CPU time. This can cause problems like http connection timeouts (usually after 5 minutes) during online usage. To avoid such problems when using ROSE WebService we use a technique called Request and Reply with polling based on BiBiWS. First the client side (e.g. your program) requests a ROSE job submitting the necessary data (parameter and data) and gets an id after the job is started. Afterwards the client can request the result by calling the corresponding response method with the id returned earlier. If the ROSE job is not finished, the user gets a status code with an enhanced description of current status back (see HOBIT status codes for more information).

request_orig
The request method gets two parameters as input - an email address (optional) and a parameter array with key/value pairs as described in the following table - return values are either a unique id or a fault message.

Note:

Default values are in bold face, colors are refferent to the sequence type. DNA RNA Protein Optional parameters are marked (optional).

general parameters

key	type	value	description
sequenceType	String	dna|rna|protein	self explainatory
SequenceNum	Integer	1 - 1000	Number of sequences to be generated
SequenceLen	Integer	1 - 1000, 29	Avarage length of generated sequences (optional)
Relatedness	Integer	0 - 1000, 250	Avarage pairwise distance (optional)
ChooseFromLeaves	String	True|False	Choose sequence names from PHYLIP tree (optional)

DNA model specific

key	type	value	description
TheDNAmodel	String	"JC"|"HKY"|"F81"|"F84"|"K2P"	predefined DNA models: "JC": Jukes/Cantor "HKY": Hasegawa/Kishino/Yano "F81": Felsenstein 1981 "F84": Felsenstein 1984 "K2P": Kimura (optional)
MeanSubstitution	Double	0.01342302	see manual (optional)
TransitionBias	Double	1.0	see manual (optional)
TTratio	Double	0.0	see manual (optional)

optional parameters

key	type	value	description
TheSequence	String	a genomic sequence	Root sequence (optional)
TheTree	String	a PHYLIP tree in Newick notation	Tree containing sequence names and distances (optional)
TheMutationProbability	String	see manual 1.0	Mutation probablities (optional)

output options

key	type	value	description
AlignmentFormat	String	"FASTA"|"PHYLIP"	Format of alignment output (optional)
TreeWithSequences	String	True|False	Show sequences in PHYLIP tree (optional)
TreeSequencesWithGaps	String	True|False	Show aligned sequences in PHYLIP tree (optional)
TreeWithAncestors	String	True|False	Display ancestors in PHYLIP tree (optional)

expert parameters

key	type	value	description
TheInsFunc	String	see manual	The insertation function (optional)
TheDelFunc	String	see manual	The deletation function (optional)
TheInsertThreshold	String	0.00001 0.00001 0.00005	The insertation threshold (optional)
TheDeleteThreshold	String	0.00001 0.00001 0.00005	The deletation threshold (optional)
SeedVal	Integer		Random seed (optional)

guru parameters

key	type	value	description
InputType	Integer	4 4 1	Type of sequences (optional)
TheAlphabet	String	"ACGT" "ACGU" "ARNDCQEGHILKMFPSTWYV"	Alphabet for sequences (optional)
TheFreq	String	see manual	Base frequencies (optional)
ThePAMMatrix	String	see manual	The Dayhoff PAM matrix (optional)

response_orig
The response_orig gets the id returned by the request and request_orig methods as input parameter and returns the original ROSE result as ASCII text.

request
The request method has the same parameters and return value as the request_orig method except an additional parameter which has to be in PhyloML xml format.

response_alignment
The response_alignment method gets the id returned by the request and request_orig methods as input parameter and returns the calculated alignment as an AlignmentML xml document (http://hobit.sourceforge.net/xsds/2005/alignmentML.xsd). Note: This method will only return a reasonable result if AlignmentFormat is set to "FASTA".

response_sequences
The response_sequences method gets the id returned by the request and request_orig methods as input parameter and returns the generated sequences as a SequenceML xml document (http://hobit.sourceforge.net/xsds/2005/sequenceML.xsd).

response_tree
The response_tree method gets the id returned by the request and request_orig methods as input parameter and returns the generated phylogenetic tree as a PhyloML xml document.

The example perl client implementation for both methods request_orig and response_orig is based on SOAP::Lite.

request_orig (download)
The implementation of the request_orig method is quite simple. Simply call request_orig.pl without any parameter. If no error occured, a bibiid will be printed to STDOUT.

#!/usr/bin/env perl
use SOAP::Lite;

my $wsdlurl = "http://bibiserv.techfak.uni-bielefeld.de/wsdl/rose.wsdl";

print "Submitting your request ...\n";

my @params = ("sequenceType","DNA",
              "SequenceNum",SOAP::Data->type(int => "4"),
              "Relatedness",SOAP::Data->type(int => "250"),
              "TheSequence","\"AATTAAGAACAAATAACCGGT\"",
              "AlignmentFormat","\"FASTA\"");

my $result = SOAP::Lite->service($wsdlurl)
                       ->on_fault(sub {soapFaultHandler(@_)})
                       ->request_orig("",\@params);

print "got id: '$result'\n";

sub soapFaultHandler {
  my($soap, $res) = @_;

  if (ref $res) {
    my $detail = $res->faultdetail;
    if(defined($detail->{"hobitStatuscode"})) {
      print $detail->{"hobitStatuscode"}->{"description"};
      print "(".$detail->{"hobitStatuscode"}->{"statuscode"}.")\n";
    } else {
      print "Sevlet Error - no Hobit Statuscode\n";
    }
  } else {
    print "HTTP layer Error: ";
    print $soap->transport->status."\n";
  }
  exit 1;
}

response_orig (download)
If you want to recieve the result of your ROSE run, call response_orig.pl with a valid bibiid (retrieved by request_orig). If no error occured, the ROSE result will be printed to STDOUT.

#!/usr/bin/env perl 
use SOAP::Lite;

my $wsdlurl = "http://bibiserv.techfak.uni-bielefeld.de/wsdl/rose.wsdl";

if(!defined $ARGV[0]) {
  print "usage: response_orig.pl <bibiid>\n";
  exit 1;
}

print "Submitting your id...\n";

my $result = SOAP::Lite->service($wsdlurl)
                       ->on_fault(sub {soapFaultHandler(@_)})
                       ->response_orig($ARGV[0]);

print $result;

sub soapFaultHandler {
  my($soap, $res) = @_;

  if (ref $res) {
    my $detail = $res->faultdetail;
    if(defined($detail->{"hobitStatuscode"})) {
      print $detail->{"hobitStatuscode"}->{"description"};
      print "(".$detail->{"hobitStatuscode"}->{"statuscode"}.")\n";
    } else {
      print "Sevlet Error - no Hobit Statuscode\n";
    }
  } else {
    print "HTTP layer Error: ";
    print $soap->transport->status."\n";
  }
  exit 1;
}