Stanford University HIV Drug Resistance Database - A curated public database designed to represent, store, and analyze the divergent forms of data underlying HIV drug resistance.

Sierra—The Stanford HIV Web Service (Version 1.1)

A Web Service to allow individuals and institutions to interact programatically with the HIVdb program. Sierra enables other computers to obtain the latest Stanford HIV Drug Resistance Algorithm scores, comments, and inferred levels of resistance to 17 FDA-approved protease and RT inhibitors.

Table of Contents

  1. Introduction
  2. Benefits
  3. Registration
  4. Usage
  5. Logging and Privacy Policy
  6. News
 

Sierra, the Stanford Algorithm web service, is a way for machines to interface with the HIVdb program. Sierra enables other computers to obtain the latest Stanford HIV Drug Resistance Algorithm scores, comments, and inferred levels of resistance to 17 FDA-approved protease and RT inhibitors.

The HIVdb program on the web accepts user-submitted protease and RT sequences and returns inferred levels of resistance in a human readable HTML-formatted report. Sierra is an essentially identical service, but one tailored to computers instead of humans.

 
2. Benefits

Why might you want to use Sierra? You might already be handling your sequences via code. If so, getting Stanford interpretation results from a human-centric web page is possible but needlessly difficult. Sierra can give your code results in a straightforward and simple way without markup language used for purely aesthetic purposes.

There are several advantages to using Sierra (compared to, say, running the Stanford Algorithm locally):

  • Setup is easy. Only client code is needed, and client code examples have already been created.
  • Your code will always access the latest Stanford Algorithm results.
  • Web services are an accepted standard for remote computing.
  • Sierra returns an XML report that is easy to interpret and it follows a strict schema.

 
3. Registration

We require users (or organizations) to register before using Sierra. Upon registration, you will be supplied with a key. Performing an interpretation is computationaly expensive; by registering use, we can ensure only legitimate requests are made to Sierra.

If you would like to register for a Sierra key, please complete the registration form. We will reply with an authorizing key. A single key can be used by multiple members as long as they share the same affiliation (e.g., all members of a research group can share a key).

 
4. Usage

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 the contents. For almost all users, this will be as simple as just running the code. Sierra should work for you right out of the box!

  1. Java client via JAR (version 1.1) (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.
  2. Java bundle (version 1.0)
  3. 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:

  1. 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 processSequences and processSequencesString) to the number "2".

  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 processSequences, processSequencesString also requires three parameters: your authorization key, the type of report you need, and your sequence.

    Although methods processSequence and 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.

  3. 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 [2][1][0] = "K103N"

Since version 0.9.5, Sierra exposed two methods:

  1. 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"?>
    
    <Stanford_Algorithm_Interpretation>
        <algorithmVersion>java-beta-0.9.1</algorithmVersion>
        <webServiceVersion>beta-0.9.2</webServiceVersion>
        <failure>
            <errorMessage>Invalid key.</errorMessage>
        </failure>
    </Stanford_Algorithm_Interpretation>
    
    If the sequence is acceptably processed, the returned document looks like this.

  2. 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.

 
5. Logging and Privacy Policy

Our policy is based on the NLM's policy.

Stanford HIV Resistance Database provides web services and related pages as a public service to educational institutions. We do not collect personal information about you when you visit our sites unless you choose to provide that information to us.

Information Collected and Stored Automatically (Web Pages)

Of the information we learn about you from your visit to our sites, we store only the following: the IP address from which you access the Internet, the date and time, the Internet address of the Web site from which you linked directly to our site, and the browser used to access our site. This information is used to measure the number of visitors to the various sections of our site and identify system performance or problem areas. We also use this information to help us expand the coverage of the sites and to make the site more useful. Stanford HIV Resistance Database periodically deletes its Web logs.

Information Collected and Stored Automatically (Web Services)

Each invocation of the Sierra web service is logged. The only information that is stored is:

  • the time the request was made to Sierra;
  • the name of the method that processed the request;
  • the user's key;
  • the average length of the received sequences;
  • the time taken for the algorithm to run.
Received sequences are not stored on our system. They are held in memory for purposes of making a drug resistance interpretation, then deleted from memory. An example of a Sierra log entry appears below:
<entry>
    <time>Fri Nov 03 19:52:17 PST 2006</time>
    <method>processSequence</method>
    <key>0000-0000-0000-00000</key>
    <numberOfSequences>10</numberOfSequences>
    <averageSequenceLength>1138</averageSequenceLength>
    <millisecondsElapsed>13084</millisecondsElapsed>
</entry>

Personally Provided Information

If you choose to provide us with personal information by sending an email, or by filling out a form with your personal information and submitting it through our Web site, we use that information to respond to your message and to help us provide you with information or material that you request. The personal information provided will be kept confidential and will not be made available to third parties.

 
6. News

News items of interest to Sierra users are collected in chronological order.