Sierra is a standard web service. You can take advantage of it in any language
that provides web service libraries. To assist users, we have supplied examples
in Java and Perl. Choose the language that interests you, then download and
extract the contents. Each language bundle has included instructions on how to use
For almost all users, this will be as simple as just running the code.
Sierra should work for you right out of the box!
- Java client via JAR (Simplest install): All you need is to download the jar file and install JRE (Java Runtime Enviroment) on your computer. And you are ready to run it from the command line:
java -cp sierraClient_runnable_extract.jar edu.stanford.hiv.webservices.SierraFasta -k <key provided via email> -f <path to fasta file> -rf <path to report xml file>.
The client will contact our server at Stanford.
- Java bundle (version 1.0)
- Perl bundle (version 1.0)
For those that would rather use another language, you can find the
WSDL underlying the service here. We hope to make a C# client available soon, for those that use
the .NET environment.
In version 1.0, Sierra exposed a new report format option and two methods:
- An important feature introduced is XML 2009, a new XML-format option for the report, which has a more consistent structure and a published schema. To obtain a XML 2009-formatted report you set the type of report you need (second parameter for methods
processSequencesString) to the number "2".
processSequencesString: this method allows you to submit sequences formatted in the following formats: a single sequence string, FASTA, and GRF. Similar to the previously exposed method
processSequencesString also requires three parameters: your authorization key, the type of report you need, and your sequence.
processSequencesInFasta currently work, you can use the new method
processSequencesString to get the same results given the same input. Please be aware that the method
processSequencesInFasta is now deprecated.
processMutationLists: this method allows you to submit a mutation list - in case you don't have the sequence readily available or you have a different alignment. This mutation list must be organized as a multidimensional array where: (a) the first element is the sequence (b) the second element are the three genes (protease, RT, and integrase); if a gene is missing or no mutations are found an empty element is required (c) the third and final element are the mutation strings. For example, if K103N is the only RT mutation in the third sequence, then  = "K103N"
Since version 0.9.5, Sierra exposed two methods:
processSequence: The method expects as input arguments two strings: your authorization key and a nucleic acid sequence. The sequence should be nucleic acids only and can only contain the characters A-Z and a-z (i.e., no titles etc. should be included in this argument).
Sierra will return an XML document containing the result of processing the sequence. In the event that there is some error (e.g., invalid key, invalid sequence, etc.), an error document will be returned. An example of an error document is:
<?xml version="1.0" standalone="yes"?>
If the sequence is acceptably processed, the returned document
looks like this.
processSequences: Version 0.9.5 of Sierra exposes the
processSequences method that allows you to process multiple nucleic acid sequences in a single call to the webservice. In addition to this, you can specify the type of report you want Sierra to return. A Simple Report contains output similar to the previous versions of Sierra while a Detailed Report is a verbose report containing all the information required to recreate the result generated by the web-based HIVdb program.
processSequences expects as input arguments three parameters: your authorization key, the type of report you need (0 for simple, 1 for detailed) and a string array containing nucleic acid sequences. Each sequence should be nucleic acids only and should be specified in the FASTA format (i.e. you can provide an optional identifier with each sequence string).
The result of calling
processSequences looks like this. Note that the xml results have an associated XSL stylesheet. Opening the detailed report xml file in a browser will display the results in a format similar to the web-based HIVdb program. If you would like to design your own custom stylesheet, you can download and modify the Sierra stylesheet located here.