Commits

Fabrice Jossinet committed 8491e71

First commit

Comments (0)

Files changed (5)

+PyRNA REST clients -- Documentation and source code samples to use the PyRNA Web Services
+==========================================================================================
+
+This project provides a documentation and several source code samples for basic clients using the Web Services exposed by the REST server of [PyRNA](https://bitbucket.org/fjossinet/pyrna) (see the script restserver.py). More advanced clients can also be used, like [Assemble2](http://www.bioinformatics.org/assemble/).
+
+For all the clients described here, the default URL is : http://arn-ibmc.in2p3.fr/. This can be changed using the options -h for the host name and -p for the port. Examples: 
+
+* with the default base URL: annotate3d.js -f PDB_file.pdb
+
+* with a user defined base URL: annotate3d.js -f PDB_file.pdb -h http://localhost -p 8080
+
+#Computation of RNA Secondary Structure(s)
+
+The base URL is: http://arn-ibmc.in2p3.fr/api/compute/2d
+
+The webservice is accessible through GET and POST requests:
+
+* GET request => predict a 2D from a single sequence or annotate a 3D using its PDBID
+* POST request => if the first line of the data sent starts with a '>' (FASTA format), a structural alignment will be computed. If not, the webservice tries to annotate a 3D.
+
+### GET request
+
+It returns the JSON description of a secondary structure.
+
+Examples (click on the link to see the result. We suggest you to use a browser like Google Chrome which is able to format raw JSON data into tree view): 
+
+<http://arn-ibmc.in2p3.fr/api/compute/2d?tool=rnaview&pdbid=1GID>
+
+<http://arn-ibmc.in2p3.fr/api/compute/2d?tool=rnaview&pdbid=1EHZ&output=rnaml>
+
+<http://arn-ibmc.in2p3.fr/api/compute/2d?tool=contrafold&seq=AGAGGGGAGGACCAAAAACCCCC&output=bpseq>
+
+<http://arn-ibmc.in2p3.fr/api/compute/2d?tool=rnafold&seq=AGAGGGGAGGACCAAAAACCCCC&output=vienna&name=my_seq>
+
+<http://arn-ibmc.in2p3.fr/api/compute/2d?tool=rnafold&seq=AGAGGGGAGGACCAAAAACCCCC&name=my_seq>
+
+#### The parameters
+
+* tool (mandatory): the name of the tool to be used.
+	* Accepted values for a 2D prediction: contrafold, rnafold.  
+	* Accepted values for a 3D annotation: rnaview  
+* pdbid (mandatory for the 3D annotation): id of the PDB file to annotate. The web service will download it from the PDB website.
+* output (optional): the output format. If no output is precised, the 2D is described using the JSON format.
+	* Accepted values for a 2D prediction: vienna, bpseq.  
+	* Accepted values for a 3D annotation: rnaml.
+* seq (mandatory for the 2D prediction): an RNA primary sequence
+* name (optional, only used for the 2D prediction): the name for the RNA sequence 
+
+### POST request
+
+It returns the JSON description of a secondary structure (for a PDB file or a FASTA file containing a single sequence) or of a structural alignment (for a FASTA file containing more than one sequence). Take a look at the Java and Javascript code samples for details.
+
+#### The parameters:
+
+* tool (mandatory): the name of the tool to be used. 
+	* accepted values for a structural alignment: mlocarna, foldalign.  
+	* accepted values for a 3D annotation: rnaview
+* data (mandatory): the content of a FASTA file (for the computation of an RNA2D structure or structural alignment) or the content of a PDB file (for an RNA 3D annotation).
+* output (optional, only used for the 3D annotation): if its value is "rnaml", the rnaml ouput of the rnaview algorithm is returned (and not a JSON version, which is the default behavior)
+
+#Computation of a 2D plot for an RNA Secondary Structure
+
+The base URL is: http://arn-ibmc.in2p3.fr/api/compute/2dplot
+
+The webservice is accessible through POST requests.
+
+### POST request
+
+It returns the JSON description of a 2D plot.
+
+* data (mandatory): the content of a VIENNA file.
+* output (optional): the output format. If no output is precised, the 2D plot is described using the JSON format. Accepted values: svg.
+
+#Source code examples
+
+* client.nb:
+	Mathematica 9 notebook with GET requests.
+
+* annotate3d.js:
+	Javascript file using node.js (http://nodejs.org/). It annotates a local PDB file using a POST request.  
+	__Usage__: ./annotate3d.js -f PDB_file [-h host_name (default: http://arn-ibmc.in2p3.fr)] [-p port (default: 80)]   
+
+* annotate3d.R: 
+	R script to annotate a 3D structure using its PDB ID using a GET request.  
+	__Usage__: ./annotate3d.R <pdb_id>  
+
+* Annotate3d.java: 
+	Java program to annotate a local PDB file using a POST request.  
+	__Compilation__: javac ./Annotate3d.java  
+	__Usage__: java -cp . Annotate3d -f PDB_file [-h host_name (default: http://arn-ibmc.in2p3.fr)] [-p port (default: 80)]
+
+#Other Web Services clients:
+
+* [Assemble2](http://www.bioinformatics.org/assemble/) a Java GUI using PyRNA Web Services to construct RNA 3D models, 

src/Annotate3d.java

+import java.io.*;
+import java.lang.Integer;
+import java.net.MalformedURLException;
+import java.net.URL;
+import java.net.HttpURLConnection;
+import java.net.URLEncoder;
+
+public class Annotate3d {
+
+    public static void main(String[] args) throws IOException {
+        int port = 80;
+        String hostname = "http://arn-ibmc.in2p3.fr";
+        String pdbFile = null;
+        if (args.length == 0) {
+            System.err.println("Usage: java -cp . Annotate3d -f PDB_file [-h host_name (default: http://arn-ibmc.in2p3.fr)] [-p port (default: 80)] ");
+            System.exit(-1);
+        } else {
+            for (int i=0 ; i < args.length-1 ; i++) {
+                if ("-f".equals(args[i]))
+                    pdbFile = args[i+1].trim();
+                else if ("-h".equals(args[i]))
+                    hostname = args[i+1].trim();
+                else if ("-p".equals(args[i]))
+                    port = Integer.parseInt(args[i+1].trim());
+            }
+        }
+        new Annotate3d(pdbFile, hostname+":"+port+"/api/compute/2d");
+    }
+
+    private Annotate3d(String pdbFile, String url_representation) throws IOException {
+                
+        StringBuilder stringBuilder = new StringBuilder();
+        BufferedReader reader = new BufferedReader( new FileReader (pdbFile));
+        String line = null;
+        while( ( line = reader.readLine() ) != null )
+            stringBuilder.append(line+"\n");
+
+        StringBuffer parameters = new StringBuffer();                        
+        parameters.append(URLEncoder.encode("data", "UTF-8") + "=" + URLEncoder.encode(stringBuilder.toString(), "UTF-8"));
+        parameters.append("&");
+        parameters.append(URLEncoder.encode("tool", "UTF-8") + "=" + URLEncoder.encode("rnaview", "UTF-8"));
+
+        URL url = null;
+        try {
+            url = new URL(url_representation);
+        }
+        catch (MalformedURLException e) {
+            e.printStackTrace();
+            System.exit(-1);
+        }
+        HttpURLConnection connection = (HttpURLConnection) url.openConnection();
+        connection.setDoOutput(true);
+        connection.setDoInput(true);
+        connection.setInstanceFollowRedirects(false);
+        connection.setRequestMethod("POST");
+        connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded"); 
+        connection.setRequestProperty("charset", "utf-8");
+        connection.setRequestProperty("Content-Length", "" + Integer.toString(parameters.toString().getBytes().length));
+
+        OutputStreamWriter wr = new OutputStreamWriter(connection.getOutputStream());
+        wr.write(parameters.toString());
+        wr.flush();
+
+        // Get the response
+        BufferedReader rd = null;
+        try {
+            rd= new BufferedReader(new InputStreamReader(connection.getInputStream()));
+        }
+        catch (java.io.FileNotFoundException e) {
+            e.printStackTrace();
+            System.exit(-1);
+        }
+        while ((line = rd.readLine()) != null)
+            System.out.println(line);
+        wr.close();
+        rd.close();
+    }
+
+}
+#!/usr/bin/env Rscript --slave
+
+#You need to install the libraries RCurl and rjson to use this script
+library("RCurl")
+library("rjson")
+
+argv <- commandArgs(TRUE)
+
+if (length(argv) == 0) {
+  cat("I need a pdb_Id...", "\n")
+  q()
+}
+
+pdbId <- argv[1]
+url <- paste("http://arn-ibmc.in2p3.fr/api/compute/2d?pdbid=", pdbId, "&tool=rnaview", sep="")
+
+annotations <- fromJSON(httpGET(url))
+
+for (i in 1:length(annotations)) {
+  count <- length(annotations[[i]]$`2D`$tertiaryInteractions)
+  cat("Number of tertiary interactions in chain", annotations[[i]]$`2D`$rna$name , ":", count, "\n") 
+}

src/annotate3d.js

+#!/usr/bin/env node
+
+var args = process.argv.splice(2),
+    fs = require('fs'),
+    path = require('path'),
+    http = require('http'),
+    querystring = require('querystring'),
+    pdbFile = undefined,
+    pdbContent = "",
+    host_name = "arn-ibmc.in2p3.fr",
+    port = 80;
+
+if (args.indexOf("-f") == -1) {
+  console.log("Usage: annotate3d.js -f PDB_file [-h host_name (default: http://arn-ibmc.in2p3.fr)] [-p port (default: 80)]");
+  process.exit(-1);
+} else {
+  pdbFile = args[args.indexOf("-f")+1]
+  if (args.indexOf("-h") != -1)
+      host_name =  args[args.indexOf("-h")+1].split('http://')[1]
+  if (args.indexOf("-p") != -1)
+      port =  parseInt(args[args.indexOf("-p")+1])
+}
+
+var readStream = fs.createReadStream(path.normalize(pdbFile));
+
+readStream.on('data', function(data) {
+    pdbContent += data;
+});
+
+readStream.on('end', function() {
+  var post_data = querystring.stringify({  
+    'tool' : 'rnaview',  
+    'data': pdbContent 
+  });
+
+  var options = {
+    host: host_name,
+    port: port,
+    path: '/api/compute/2d',
+    method: 'POST',
+     headers: {  
+    'Content-Type': 'application/x-www-form-urlencoded',  
+    'Content-Length': post_data.length  
+    }
+  };
+
+  var req = http.request(options, function(res) {
+    res.setEncoding('utf8');
+    res.on('data', function (chunk) {
+      console.log(chunk);
+    });
+  });
+
+  req.on('error', function(e) {
+    console.log('problem with request: ' + e.message);
+  });
+
+  req.write(post_data);
+  req.end();    
+});
+
+
+
+(* Content-type: application/vnd.wolfram.mathematica *)
+
+(*** Wolfram Notebook File ***)
+(* http://www.wolfram.com/nb *)
+
+(* CreatedBy='Mathematica 8.0' *)
+
+(*CacheID: 234*)
+(* Internal cache information:
+NotebookFileLineBreakTest
+NotebookFileLineBreakTest
+NotebookDataPosition[       157,          7]
+NotebookDataLength[      6592,        169]
+NotebookOptionsPosition[      5986,        147]
+NotebookOutlinePosition[      6426,        164]
+CellTagsIndexPosition[      6383,        161]
+WindowFrame->Normal*)
+
+(* Beginning of Notebook Content *)
+Notebook[{
+Cell[BoxData[
+ RowBox[{"URLFetch", "[", 
+  RowBox[{"\"\<http://arn-ibmc.in2p3.fr/api/compute/2d\>\"", ",", " ", 
+   RowBox[{"\"\<Parameters\>\"", " ", "\[Rule]", " ", 
+    RowBox[{"{", 
+     RowBox[{
+      RowBox[{"\"\<tool\>\"", "\[Rule]", " ", "\"\<rnaview\>\""}], ",", 
+      RowBox[{"\"\<pdbid\>\"", " ", "\[Rule]", " ", "\"\<1EHZ\>\""}]}], 
+     "}"}]}]}], "]"}]], "Input",
+ CellChangeTimes->{{3.563334487692856*^9, 3.563334493057666*^9}, {
+   3.563334528480916*^9, 3.563334567154187*^9}, {3.5633347849877872`*^9, 
+   3.563334787034759*^9}, {3.563335032031789*^9, 3.563335033558959*^9}, {
+   3.564116111179791*^9, 3.564116127318824*^9}, {3.564116160573656*^9, 
+   3.5641161975635023`*^9}, {3.564116326238626*^9, 3.564116355954146*^9}, {
+   3.564116393839931*^9, 3.564116418026305*^9}, {3.564116456409255*^9, 
+   3.56411646119971*^9}, {3.564119172597487*^9, 3.564119298358059*^9}, 
+   3.564120626544922*^9, 3.5641213661369963`*^9}],
+
+Cell[BoxData[
+ RowBox[{"URLFetch", "[", 
+  RowBox[{"\"\<http://arn-ibmc.in2p3.fr/api/compute/2d\>\"", ",", " ", 
+   RowBox[{"\"\<Parameters\>\"", " ", "\[Rule]", " ", 
+    RowBox[{"{", 
+     RowBox[{
+      RowBox[{"\"\<tool\>\"", "\[Rule]", " ", "\"\<rnaview\>\""}], ",", 
+      RowBox[{"\"\<pdbid\>\"", " ", "\[Rule]", " ", "\"\<1EHZ\>\""}], ",", 
+      " ", 
+      RowBox[{"\"\<output\>\"", " ", "\[Rule]", " ", "\"\<rnaml\>\""}]}], 
+     "}"}]}]}], "]"}]], "Input",
+ CellChangeTimes->{{3.564127652758677*^9, 3.564127672519047*^9}}],
+
+Cell[BoxData[
+ RowBox[{"URLFetch", "[", 
+  RowBox[{"\"\<http://arn-ibmc.in2p3.fr/api/compute/2d\>\"", ",", " ", 
+   RowBox[{"\"\<Parameters\>\"", " ", "\[Rule]", " ", 
+    RowBox[{"{", 
+     RowBox[{
+      RowBox[{"\"\<tool\>\"", "\[Rule]", " ", "\"\<rnafold\>\""}], ",", " ", 
+      RowBox[{
+      "\"\<seq\>\"", " ", "\[Rule]", " ", 
+       "\"\<GCGGAUUUAGCUCAGUUGGGAGAGCGCCAGACUGAAGAUCUGGAGGUCCUGUGUUCGAUCCACAGA\
+AUUCGCACCA\>\""}], ",", " ", 
+      RowBox[{"\"\<output\>\"", " ", "\[Rule]", " ", "\"\<vienna\>\""}]}], 
+     "}"}]}]}], "]"}]], "Input",
+ CellChangeTimes->{{3.564119304757852*^9, 3.5641193089572573`*^9}, 
+   3.564120541696074*^9, 3.56412136854501*^9, {3.56412562689957*^9, 
+   3.5641256714109983`*^9}, {3.5641259264348707`*^9, 3.564125927103545*^9}, 
+   3.564127661900036*^9}],
+
+Cell[BoxData[
+ RowBox[{"URLFetch", "[", 
+  RowBox[{"\"\<http://arn-ibmc.in2p3.fr/api/compute/2d\>\"", ",", " ", 
+   RowBox[{"\"\<Parameters\>\"", " ", "\[Rule]", " ", 
+    RowBox[{"{", 
+     RowBox[{
+      RowBox[{"\"\<tool\>\"", "\[Rule]", " ", "\"\<rnafold\>\""}], ",", " ", 
+      RowBox[{
+      "\"\<seq\>\"", " ", "\[Rule]", " ", 
+       "\"\<GCGGAUUUAGCUCAGUUGGGAGAGCGCCAGACUGAAGAUCUGGAGGUCCUGUGUUCGAUCCACAGA\
+AUUCGCACCA\>\""}], ",", " ", 
+      RowBox[{"\"\<output\>\"", " ", "\[Rule]", " ", "\"\<bpseq\>\""}]}], 
+     "}"}]}]}], "]"}]], "Input",
+ CellChangeTimes->{{3.564125945858778*^9, 3.564125949695263*^9}, 
+   3.5641276640606728`*^9}],
+
+Cell[BoxData[
+ RowBox[{"URLFetch", "[", 
+  RowBox[{"\"\<http://arn-ibmc.in2p3.fr/api/compute/2d\>\"", ",", " ", 
+   RowBox[{"\"\<Parameters\>\"", " ", "\[Rule]", " ", 
+    RowBox[{"{", 
+     RowBox[{
+      RowBox[{"\"\<tool\>\"", "\[Rule]", " ", "\"\<contrafold\>\""}], ",", 
+      " ", 
+      RowBox[{
+      "\"\<seq\>\"", " ", "\[Rule]", " ", 
+       "\"\<GCGGAUUUAGCUCAGUUGGGAGAGCGCCAGACUGAAGAUCUGGAGGUCCUGUGUUCGAUCCACAGA\
+AUUCGCACCA\>\""}]}], "}"}]}]}], "]"}]], "Input",
+ CellChangeTimes->{{3.5641195306698*^9, 3.564119532069872*^9}, {
+   3.564120342195415*^9, 3.564120342454384*^9}, {3.5641205292454987`*^9, 
+   3.564120543557147*^9}, 3.564121370809905*^9}],
+
+Cell[BoxData[
+ RowBox[{"URLFetch", "[", 
+  RowBox[{"\"\<http://arn-ibmc.in2p3.fr/api/compute/2d\>\"", ",", " ", 
+   RowBox[{"\"\<Parameters\>\"", " ", "\[Rule]", " ", 
+    RowBox[{"{", 
+     RowBox[{
+      RowBox[{"\"\<tool\>\"", "\[Rule]", " ", "\"\<contrafold\>\""}], ",", 
+      " ", 
+      RowBox[{
+      "\"\<seq\>\"", " ", "\[Rule]", " ", 
+       "\"\<GCGGAUUUAGCUCAGUUGGGAGAGCGCCAGACUGAAGAUCUGGAGGUCCUGUGUUCGAUCCACAGA\
+AUUCGCACCA\>\""}], ",", 
+      RowBox[{"\"\<output\>\"", " ", "\[Rule]", " ", "\"\<vienna\>\""}]}], 
+     "}"}]}]}], "]"}]], "Input",
+ CellChangeTimes->{{3.564126002908988*^9, 3.564126007108761*^9}, 
+   3.564127048137803*^9, 3.564127101447673*^9}],
+
+Cell[BoxData[
+ RowBox[{"URLFetch", "[", 
+  RowBox[{"\"\<http://arn-ibmc.in2p3.fr/api/compute/2d\>\"", ",", " ", 
+   RowBox[{"\"\<Parameters\>\"", " ", "\[Rule]", " ", 
+    RowBox[{"{", 
+     RowBox[{
+      RowBox[{"\"\<tool\>\"", "\[Rule]", " ", "\"\<contrafold\>\""}], ",", 
+      " ", 
+      RowBox[{
+      "\"\<seq\>\"", " ", "\[Rule]", " ", 
+       "\"\<GCGGAUUUAGCUCAGUUGGGAGAGCGCCAGACUGAAGAUCUGGAGGUCCUGUGUUCGAUCCACAGA\
+AUUCGCACCA\>\""}], ",", "\[IndentingNewLine]", 
+      RowBox[{"\"\<output\>\"", " ", "\[Rule]", " ", "\"\<bpseq\>\""}]}], 
+     "}"}]}]}], "]"}]], "Input",
+ CellChangeTimes->{{3.564126018969789*^9, 3.564126026859522*^9}, {
+  3.564127080089512*^9, 3.56412710292773*^9}}],
+
+Cell[BoxData[
+ RowBox[{"URLFetch", "[", 
+  RowBox[{"\"\<http://arn-ibmc.in2p3.fr/api/compute/2d\>\"", ",", " ", 
+   RowBox[{"\"\<Parameters\>\"", " ", "\[Rule]", " ", 
+    RowBox[{"{", 
+     RowBox[{
+      RowBox[{"\"\<tool\>\"", "\[Rule]", " ", "\"\<rnafold\>\""}], ",", " ", 
+      RowBox[{
+      "\"\<seq\>\"", " ", "\[Rule]", " ", 
+       "\"\<GCGGAUUUAGCUCAGUUGGGAGAGCGCCAGACUGAAGAUCUGGAGGUCCUGUGUUCGAUCCACAGA\
+AUUCGCACCA\>\""}]}], "}"}]}]}], "]"}]], "Input"]
+},
+WindowSize->{1159, 718},
+WindowMargins->{{Automatic, -1637}, {Automatic, 176}},
+PrivateNotebookOptions->{"VersionedStylesheet"->{"Default.nb"[8.] -> False}},
+FrontEndVersion->"9.0 for Mac OS X x86 (32-bit, 64-bit Kernel) (November 20, \
+2012)",
+StyleDefinitions->"Default.nb"
+]
+(* End of Notebook Content *)
+
+(* Internal cache information *)
+(*CellTagsOutline
+CellTagsIndex->{}
+*)
+(*CellTagsIndex
+CellTagsIndex->{}
+*)
+(*NotebookFileOutline
+Notebook[{
+Cell[557, 20, 935, 16, 28, "Input"],
+Cell[1495, 38, 534, 11, 28, "Input"],
+Cell[2032, 51, 794, 16, 63, "Input"],
+Cell[2829, 69, 647, 14, 63, "Input"],
+Cell[3479, 85, 662, 14, 46, "Input"],
+Cell[4144, 101, 673, 15, 63, "Input"],
+Cell[4820, 118, 695, 15, 63, "Input"],
+Cell[5518, 135, 464, 10, 46, "Input"]
+}
+]
+*)
+
+(* End of internal cache information *)