Iobion GeneTraffic API Reference Manual

Iobion^TM GeneTraffic^TM API Reference Manual

Version 1.0.3.2.5
December 2004

Iobion, Iobion Informatics, GeneTraffic, and the Iobion logo are trademarks of Iobion Informatics, LLC.

The use of Iobion System software and GeneTraffic software is covered by software license agreements.

Table of Contents

I. Overview
II. Login and Logout
III. Getting a Project List
IV. Getting a File List
V. Spot Table Query
VI. Gene Table Query
VII. Getting a Dataset List
VIII. Getting a Project Summary
IX. Getting a Hyb List
X. Import and Export
XI. Deleting a Project
XII. Getting more information about a Project
XIII. Acknowledgments
XIV. Contact Information

I. Overview

This document explains in detail the semantics of the function calls you can make using the GeneTraffic Web Service API. In this document, you will learn:

How to connect to a GeneTraffic server using the GeneTraffic Web services API
How to interpret the search results information sent back by the GeneTraffic Web APIs service.
You may also find the following files from the GeneTraffic Web APIs developer kit to be helpful:

c#/ - Example .NET C# programs that uses GeneTraffic Web Service API.
perl/ - Example perl programs that uses GeneTraffic Web Service API.
php/ - Example php programs that uses GeneTraffic Web Service API.
GeneTrafficAPI.wsdl - WSDL description for GeneTraffic Web APIs SOAP interface.

II. Login and Logout

string GetChallenge()
string Login(string user, string pass)
bool Logout(string sessid)
bool ReLogin(string user, string pass)

In order to connect to a GeneTraffic server you need to login using a username and password just as using the regular GeneTraffic interface. You also need a challenge key, because the password must be transmitted over the network in this format:

pass = lowercase_hex_md5(lowercase_hex_md5(challenge) . lowercase_hex_md5(real_password))

After logging in into the GeneTraffic server using the Login function, you will get in return a session id, which is needed further on when using any other function. If you are already logged in, you can use the ReLogin function which permits you to relogin by closing the old session and creating a new one.

III. Getting a Project List

ProjectStruct[] GetProjectList(string session_id)

This function retrieves the list of projects you currently have rights to access, based on the username/password combo that you used to login. The ProjectStruct structure is defined in the Web Services wsdl file as follows:

<xsd:complexType name="ProjectStruct">
   <xsd:sequence>
      <xsd:element name="id" type="xsd:int" />
      <xsd:element name="project_id" type="xsd:string" />
      <xsd:element name="project_description" type="xsd:string" />
      <xsd:element name="project_name" type="xsd:string" />
      <xsd:element name="creation_date" type="xsd:string" />
      <xsd:element name="type" type="xsd:string" />
   </xsd:sequence>
</xsd:complexType>

IV. Getting a File List

FileStruct[] GetFileList(string session_id)

GetFileList returns a list of files that can be exported form all the GeneTraffic projects that you have access to. It basically does the same thing as the 'Export Files' button in the standard GeneTraffic interface. Every individual file can be retrieved based on the "location" attribute. The FileStruct structure is defined as well in the wsdl file as:

<xsd:complexType name="FileStruct">
   <xsd:sequence>
      <xsd:element name="id" type="xsd:int" />
      <xsd:element name="file_id" type="xsd:int" />
      <xsd:element name="file_name" type="xsd:string" />
      <xsd:element name="location" type="xsd:string" />
      <xsd:element name="file_type" type="xsd:string" />
      <xsd:element name="file_format" type="xsd:string" />
      <xsd:element name="project_id" type="xsd:string" />
      <xsd:element name="project_name" type="xsd:string" />
      <xsd:element name="hyb_id" type="xsd:string" />
      <xsd:element name="hyb_name" type="xsd:string" />
   </xsd:sequence>
</xsd:complexType>

V. Spot Table Query

string SpotTableQuery(string session_id, string project_id, QueryCondition query_condition)

SpotTableQuery returns a list of spots htat corresponds to a query in a similar manner as "Spot Query" button form the standard GeneTraffic interface. The response is presented in an XML string as a datagrid (supported natively by Microsoft Visual Studio .NET).

The query condition has the following structure:

<xsd:complexType name="QueryCondition">
   <xsd:sequence>
      <xsd:element name="SearchOn" type="wsdlns:SearchOn" />
      <xsd:element name="View" type="wsdlns:View" />
      <xsd:element name="OrderBy" type="wsdlns:OrderBy" />
      <xsd:element name="OrderByDesc" type="xsd:boolean" />
   </xsd:sequence>
</xsd:complexType>

where "SearchOn", "View", "OrderBy" and "OrderByDesc" are as follows:

<xsd:complexType name="SearchOn">
   <xsd:complexContent>
      <xsd:restriction base="SOAP-ENC:Array">
      <xsd:attribute ref="SOAP-ENC:arrayType" wsdl:arrayType="wsdlns:SearchOnItem[]"/>
      </xsd:restriction>
   </xsd:complexContent>
</xsd:complexType>

<xsd:complexType name="View">
   <xsd:complexContent>
      <xsd:restriction base="SOAP-ENC:Array">
      <xsd:attribute ref="SOAP-ENC:arrayType" wsdl:arrayType="xsd:string[]" />
      </xsd:restriction>
   </xsd:complexContent>
</xsd:complexType>

<xsd:complexType name="OrderBy">
   <xsd:complexContent>
      <xsd:restriction base="SOAP-ENC:Array">
      <xsd:attribute ref="SOAP-ENC:arrayType" wsdl:arrayType="xsd:string[]" />
      </xsd:restriction>
   </xsd:complexContent>
</xsd:complexType>

<xsd:complexType name="SearchOnItem">
   <xsd:sequence>
      <xsd:element name="LogicalOperator" type="xsd:string" />
      <xsd:element name="ComparisonOperator" type="xsd:string" />
      <xsd:element name="TableField" type="xsd:string" />
      <xsd:element name="ArrayOfComparisonValue" type="wsdlns:ComparisonValue" />
   </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="ComparisonValue">
   <xsd:complexContent>
      <xsd:restriction base="SOAP-ENC:Array">
      <xsd:attribute ref="SOAP-ENC:arrayType" wsdl:arrayType="xsd:string[]" />
      </xsd:restriction>
   </xsd:complexContent>
</xsd:complexType>

The fields can be one of:

"Hyb. Group"
"Hybridization"
"Gene ID"
"Grid"
"Row"
"Column"
"Chip Signal"
"Baseline Signal"
"Fold Change"
"Flag"
"Gene Description"
"Probe Set ID"
"LEX.E - BG"
"LEX.R - BG"
"LEX.R Norm."
"Absolute Call"
"Pairs Used"
"Detection P-Value"
"Baseline Abs Call"
"Baseline Abs Pct"
"UniGene Clus. ID"
"UniGene Name"
"UniGene Symbol"
"Gene Aliases"
"LocusLink ID"
"Rep. mRNA Acc."
"Chromosome Loc."
"Cytoband"
"Summary Function"
"GO Annotation"

Comparison operators can be:

"equal"
"lessThan"
"lessThanOrEqual"
"greaterThan"
"greaterThanOrEqual"
"containText"
"containTextMulti"
"regularExpression"
"regularExpressionNot"
"textEqualNotCaseSensitive"

VI. Gene Table Query

string GeneTableQuery(string session_id, string project_id, QueryCondition query_condion)

GeneTableQuery is similar to SpotTableQuery in all its definitions and acts pretty much like te "Gene Query" button from the standard GeneTraffic interface.

The fields can be one of:

"Hyb. Group"
"Gene ID"
"Num. Valid Probe Sets"
"Mean Log2 Ratio"
"STDEV"
"COV"
"Norm. STDEV"
"UniGene Clus. ID"
"UniGene Name"
"UniGene Symbol"
"Gene Aliases"
"LocusLink ID"
"Rep. mRNA Acc."
"Chromosome Loc."
"Cytoband"
"Summary Function"
"GO Annotation"

VII. Getting a Dataset List

GTDataSet[] GetDataSetList(string session_id, string project_id)

GetDataSetList returns a list of datasets available for a certain project. The GTDataSet structure is defined in the wsdl file as follows:

<xsd:complexType name="GTDataSet">
   <xsd:sequence>
      <xsd:element name="iID" type="xsd:int" />
      <xsd:element name="iParentID" type="xsd:int" />
      <xsd:element name="iChildNum" type="xsd:int" />
      <xsd:element name="iDirectChildNum" type="xsd:int" />
      <xsd:element name="sName" type="xsd:string" />
      <xsd:element name="sDesc" type="xsd:string" />
      <xsd:element name="sDataURL" type="xsd:string" />
      <xsd:element name="iGeneNum" type="xsd:int" />
      <xsd:element name="iExpNum" type="xsd:int" />
      <xsd:element name="dCreateDate" type="xsd:string" />
      <xsd:element name="iFileType" type="xsd:int" />
      <xsd:element name="sInfo" type="xsd:string" />
      <xsd:element name="DataSetType" type="xsd:string" />
      <xsd:element name="GeneOrSpot" type="xsd:string" />
      <xsd:element name="InternalOrUpload" type="xsd:string" />
      <xsd:element name="DataSetOrList" type="xsd:string" />
      <xsd:element name="bRoot" type="xsd:boolean" />
      <xsd:element name="ProcessStatus" type="xsd:string" />
      <xsd:element name="bDeleted" type="xsd:boolean" />
   </xsd:sequence>
</xsd:complexType>

VIII. Getting a Project Summary

string GetProjectSummary(string session_id, string project_id)

GetProjectSummary returns the location of the project summary zip file for the specified project which can be retrieved later.

IX. Getting a Hyb List

HybStruct[] GetHybList(string session_id, string project_id)

GetHybList returns a list of hybs in this project. The HybStruct structure is defined as well in the wsdl file:

<xsd:complexType name="HybStruct">
   <xsd:sequence>
      <xsd:element name="hyb_id" type="xsd:int" />
      <xsd:element name="hyb_type_id" type="xsd:int" />
      <xsd:element name="hyb_protocol_id" type="xsd:int" />
      <xsd:element name="numerator" type="xsd:string" />
      <xsd:element name="denominator" type="xsd:string" />
      <xsd:element name="hyb_name" type="xsd:string" />
      <xsd:element name="hyb_description" type="xsd:string" />
      <xsd:element name="retired_state" type="xsd:string" />
      <xsd:element name="data_file_type" type="xsd:string" />
      <xsd:element name="other1" type="xsd:string" />
      <xsd:element name="other2" type="xsd:string" />
      <xsd:element name="washing_protocol_id" type="xsd:int" />
      <xsd:element name="scanning_protocol_id" type="xsd:int" />
   </xsd:sequence>
</xsd:complexType>

X. Import and Export

string ImportStatus(string session_id, string project_id)
string ExportStatus(string session_id, string project_id)
string Import(string session_id, string file)
string Export(string session_id, string project_id, sting dats, string probes)

The Import and Export are used in the case one might need to import/export projects from one GeneTraffic server to another. Export is used to start a project export while Import is used to start a project import. ExportStatus is used to check that status of an export and ImportStatus is used to check the status of an import.

probes - if 'yes', probes will be excluded from the Project Summary zip file
dats - if 'yes', dat files will be excluded from the Project Summary zip file
file - the location of the file to be imported

ExportStatus return values:
-1 - project does not exist
0 - export not yet started
1 - export started and in progress
2 - export finished and file available for download
3 - export finished but out of date

ImportStatus return values:
-1 - import does not exist
1 - import started and in progress
2 - import finished

Export returns the string 'started' if the project export has started.
Import returns the id of the projects that is being imported - it looks something like 'zz_2532' (which is an actual id of one of the demo projects that are preinstalled on a GeneTraffic machine).

XI. Deleting a Project

string DeleteProject(string session_id, string project_id)

The DeleteProject function is used to delete a project.

DeleteProject returns the string 'Project deleted' if the delete was successful.

XII. Getting more information about a Project

ProjectInfo GetProjectInfo(string session_id, string project_id)

The GetProjectInfo function retrieves more information about a project than the function GetProjectList.

GetProjectInfo returns the structure ProjectInfo defined as follows:
<xsd:complexType name="ProjectInfo">
   <xsd:sequence>
      <xsd:element name="id" type="xsd:int" />
      <xsd:element name="project_id" type="xsd:string" />
      <xsd:element name="project_name" type="xsd:string" />
      <xsd:element name="project_description" type="xsd:string" />
      <xsd:element name="creation_date" type="xsd:string" />
      <xsd:element name="type" type="xsd:string" />
      <xsd:element name="status" type="xsd:string" />
      <xsd:element name="size" type="xsd:string" />
      <xsd:element name="owner" type="xsd:string" />
      <xsd:element name="owner_id" type="xsd:string" />
   </xsd:sequence>
</xsd:complexType>

The status field returns an empty string if the project is accessible, otherwise it returns one of the following strings, just as the GeneTraffic interface:
      Restore in progress...
      Normalization in progress...
      Data upload in progress...
      Data compression in progress...
      Optimization in progress...
In these cases, the project is not accessible.
The size field returns the size of the project that this project occupies on the GeneTraffic server in Megabytes.
The owner and owner_id fields return information about the project owner.

XIII. Acknowledgments

GenePix is a trademark of Axon Instruments, Inc. QuantArray is a registered trademark of Packard BioChip Technologies, LLC. ImaGene is a trademark of BioDiscovery, Inc. Cy is a trademark of Amersham International. Java is a trademark of Sun Microsystems, Scanalytics is a trademark of Scanalytics, Inc. ArrayVision is a trademark of Imaging Research, Inc. Microsoft, Windows, Windows NT, Visual Studio .NET and Excel are registered trademarks of Microsoft Corporation. Macromedia is a registered trademark, and Flash is a trademark, of Macromedia, Inc. Intel and Pentium are registered trademarks, and Xeon is a trademark, of Intel Corporation.

XIV. Contact Information

For further information regarding all aspects of the program’s functionality please contact Iobion Informatics, LLC at:

IOBION INFORMATICS, LLC
11011 North Torrey Pines Road
La Jolla CA 92037
1 (877) 852-1441 (Toll-Free)
1 (858) 535-0219 (Fax)

info@www.iobion.com
http://www.iobion.com