Tag Archives: tool

Resource: You want REST with that GreenMamba?

When you set up a GreenMamba resource, you get not only a web interface for human users, but also a REST web service API meant for scripts to interact with your tool. The REST interface is such an integral part of GreenMamba, that it is not even optional – you get it whether you want it or not. However, since the purpose of setting up GreenMamba resources is to make your tools and databases accessible to others, we cannot think of a good reason why you would not want to expose them as web services when it takes no extra work.

To illustrate how command-line tools can be accessed as web services, we return to the Motifs tool described in an earlier blot post. In addition to having an HTML web interface, it is accessible as a REST web service through the following URL (here shown as a GET request for simplicity; POST requests are also supported):

http://localhost:8080/REST/Motifs?fasta=sequences&
motif=regular expression

The name and parameters for the web service map one-to-one to the resource name and command-line arguments specified in the inifile:

[Motifs]
command : greenmamba/examples/motifs.pl $motif @fasta

GreenMamba also provides a REST web service API around any database that you configure through the inifile, although it is admittedly not as elegant as it could be. However, there is not much need for an API in this case, as the database functionality of GreenMamba is only intended for databases that are so small that they can easily be downloaded in their entirety instead.

In case of a GreenMamba metatool there is not a corresponding web service per se. However, because a metatool is made up of a list of subtools that all have their individual sections in the inifile, each of the underlying tools has a REST web service. All the functionalities of a metatool are thus nonetheless exposed as web services.

It should be noted that the REST web services provided by GreenMamba return the output from the underlying tools as is. It may thus be worthwhile to change (or write a post-processing scripts for) tools so that they produce simple tabular output. This will both make GreenMamba format the output nicer in the HTML web interface and make the REST web services more usable.

Advertisements

Resource: Adding bells & whistles to GreenMamba

My latest blog post ended at the stage where we had combined the Instances database and the Motifs tool into a single metatool. In this post I will show how little it takes to add the bells and whistles that turn it into the complete, professional web resource that I showed as a teaser in the first blog post of this series.

You may not want green to be the design color used throughout your web interface. This is easily changed by adding a line like color : #083D65 to your inifile. You can use named colors instead of hex values if you prefer. Whichever color you pick will be used throughout the web interface to ensure a consistent design.

In the simple default design the frame changes size when changing between the Motifs and Instances input forms because the forms are not equally wide. This can easily be changed by setting a fixed width for all lines by adding line such as width : 650px. You do not have to necessarily specify the width in pixels, any units permitted in cascading style sheets can be used.

Most bioinformatics web resources require one or more pages to explain what the resource is all about. Such pages can easily be provided within the GreenMamb framework a by adding lines with the same syntax as page_home. If you add a page_about line, you will get an ABOUT menu item at the top right, which when clicked will show provided HTML text wrapped with within the GreenMamba layout to provide a consistent look. There is nothing magic to the word “about”; for example, if you write page_download you will get a page named DOWNLOAD.

You may want to also add a footer that is shown at the bottom of every page that, for example, mentions who made the resource, whom to contact in case of scientific questions or technical problems, and possibly points to one or more papers that describe the tools and which the user is requested to cite. To insert a footer you simple add a line to the inifile with the keyword footer followed by the text you want shown; this text can contain HTML code.

If you set up a Mamba server to host a single resource, you will want the Mamba server to automatically direct users to the main input form in case they access the server without requesting a specific page. For example, we would want to redirect requests for localhost:8080 to localhost:8008/HTML/ELM. This can be done the [REWRITE] section in the inifile, which allows you to specify simple URL rewrite rules similar to what can be done in Apache.

Below is the inifile required to set up the complete ELM example resource as it was shown in the first blog post of this series:

[SERVER]
host : localhost
port : 8080
plugins : ./greenmamba

[REWRITE]
/ : /HTML/ELM

[Instances]
database : greenmamba/examples/instances.tsv

[Motifs]
command : greenmamba/examples/motifs.pl $motif @fasta
page_home : greenmamba/examples/motifs_home.html

[ELM]
tools : Motifs; Instances;
color : #083D65
width : 650px
footer : Disclaimer: This is ELM mirror only serves as an example for the GreenMamba framework. For scientific purposes, please use the real ELM server instead.
page_about : greenmamba/examples/elm_about.html

Starting up the Mamba server with this inifile and accessing localhost:8080 yields this interface:

Clicking the ABOUT link will brings up the contents of the file elm_about.html wrapped with the GreenMamba design elements:

In case you want to include pictures or other content on your pages, you do not need a separate web server to host this. Mamba implements a simple web server that you can use for this purpose; all you have to do is to add a www_dir : <directory> in the [SERVER] section of the inifile and place the files you want to serve within the specified directory.

Finally, the output pages of the metatool are also formatted to follow the design specified in the inifile. The header shows the name if the metatool, color matches that of the other pages, the menu with links to the pages is shown, and the footer is included:

Resource: Combining tools and databases into a single GreenMamba web resource

In the four previous blog posts I introduced the GreenMamba framework (download) and showed how it can be used to turn a simple tab-delimited files or command-line tools into web resources with a bare minimum of effort. In this post I will show how easy it is to configure multiple databases or tools to run under the same Mamba server and how to make them accessible as a single web resource.

To illustrate this, I will take the Instances database and the Motifs tool and turn them into a web resource called ELM (the name of the database from which the instance data and motifs were obtained in the first place). The following inifile is all it takes to do so:

[SERVER]
host : localhost
port : 8080
plugins : ./greenmamba

[Instances]
database : greenmamba/examples/instances.tsv

[Motifs]
command : greenmamba/examples/motifs.pl $motif @fasta
page_home : greenmamba/examples/motifs_home.html

[ELM]
tools : Motifs; Instances;

The [SERVER] section is exactly as in all the previous examples, instructing the Mamba server to run on localhost port 8080 and to import the GreenMamba plugin. The [Instances] section configures a simple database called Instances based on the tab-delimited file instances.tsv, and the [Motifs] section configures a web tool called Motifs that runs the Perl script motifs.pl. These two sections are unchanged compared to the previous blog posts and have here simply been put into inifile, which is how one hosts multiple databases or tools under the same Mamba server. The last section, [ELM], is the only new part. It instructs GreenMamba to configure a metatool called ELM that combines the two tools Motifs and Instances.

Starting the Mamba server with this inifile and accessing http://localhost:8080/HTML/ELM yields the following web interface:

As you can see, what used to be a tool called Motifs has now become a tab within the resource ELM that shows the same (customized) input form. Similarly, the database Instances has become a tab within the same resource:

If you press the submit button for Motifs or Instances, you will get output that is formatted as it was when using Motifs and Instances as separate resources, the only change being that the header says ELM. In the next blog post, I will show how the design of GreenMamba web resources can be further customized and how design changes are consistently applied throughout all the individual tools that make up the metatool.

Resource: Turning a command-line tool into a web tool with GreenMamba

In two previous blog posts we introduced the GreenMamba framework (download) and showed how it can be used to easily set up a web database from an Excel sheet or tab-delimited file. However, the primary motivation for developing GreenMamba was to make it as simple as possible to turn command-line tools, e.g. sequence-based prediction methods, into full-fledged web tools.

The work that would normally be required to do so is to install a web server, create an HTML page with an input form, and code a CGI script that receives the input from the form, converts the input data into command-line arguments, executes the command-line tool, and returns the result. This is not terribly difficult provided that you know how to configure a web server (e.g. Apache) and write CGI scripts. However, it takes considerable time to design a consistent, professional looking HTML web interface that handles both input and output and works correctly on all major web browsers.

With GreenMamba setting up a command-line tool as a web tool requires only a few lines in the inifile describing the name and command syntax of the tool. To exemplify this, we have made a simple example Perl script that simply searches a regular expression against a set of protein or DNA sequences in a FASTA file, both of which are provided by the user. The following inifile is all it takes to turn that Perl script into a web tool:

[SERVER]
host : localhost
port : 8080
plugins : ./greenmamba

[Motifs]
command : greenmamba/examples/motifs.pl $motif @fasta

The first two lines should be familiar from the previous blog post, and the last two lines specify that we have a tool called Motifs, which should run the Perl script motifs.pl with two arguments $motif and @fasta. The difference between handles starting with $ and @ is that the former will be replaced with the input data, whereas the latter will be replaced with the name of temporary file containing the input data. In the example, the script is to be run with a regular expression ($motif) as first argument and the name of a fasta file (@fasta) as second argument.

Based on the command-line syntax given in the inifile alone, GreenMamba creates the following rudimentary web interface, which can be accessed through http://localhost:8080/HTML/Motifs (here shown with a query):

The names of the various handles (@fasta and $motif) are used as labels for the input fields. It is thus possible to improve the interface a bit simply by giving the handles more descriptive names (underscores will be shown as spaces). GreenMamba also allows the use of a customized input form, which will be explained in an upcoming blog post.

In this example above, pressing the submit button causes GreenMamba to take the command from the inifile, replace $motif with the content of the motif text field, replace @fasta with the name of a temporary file into which the content of the fasta textarea has been written, and execute the resulting command using a system call. Subsequently the output of the command is read and temporary files deleted. In this particular case, the script produces tab-delimited output, which GreenMamba automatically detects and formats as an HTML table in the output page:

If the output is not tab-delimited, it is by default shown as plain pre-formatted text. However, through the .ini file you can change it to handle several other types of output including comma-separated values, HTML, and several image formats. We will likely add support for more formats in the future.

Resource: Turning databases and tools into web resources with GreenMamba

Today, the users of bioinformatics databases and tools increasingly rely on being able to access them through web interfaces. Almost all major databases and most of the commonly used tools can be accessed in this manner, which is mostly good news from the users perspective. However, in my experience from teaching on numerous courses, these users have never worked with a command line and thus typically run their head against a wall the moment they have to do anything slightly more specialized than, for example, running a BLAST search or making a multiple alignment.

The reason for this is simple: specialist tools and databases are typically not made available through user-friendly web interfaces, because they have too few users to make it worthwhile to create such an interface. Worse yet, the tools are in many cases not even distributed, because the many dependencies and lack of documentation would result in too many questions if one were to distribute it. Consequently, almost every bioinformatician that I have spoken about this has one or more resources that they are currently not sharing – not because they are not willing to share, but because sharing would imply too much extra work. To address this problem, we have developed a web server that allows you to easily wrap existing databases and tools with a web interface like the one shown below.

In my group we are involved in the development and maintenance of many bioinformatics web resources, and I have thus been pushing the development of a reusable infrastructure. The result of this is the Python framework Mamba, which has primarily been developed by Sune Frankild and myself. Briefly, Mamba is a network-centric, multi-threaded queuing system that deals with the many technical aspects related to network communication with the clients and server-side resource management. All the specific work pertaining to a resource is done by modules that run under the Mamba server. GreenMamba is one such Mamba module, which based on a simple configuration file can provide a complete web interface around a tab-delimited data file or a command-line tool.

It is thus with great pleasure that we can now release the first version of the Mamba queuing system and GreenMamba wrapper under the BSD license. We hope that by eliminating most of the work in setting up bioinformatics web resources, it will encourage people to make available data sets and tools that hitherto were not worthwhile the time and effort to set up.

Over the next days and weeks, I plan to publish a series of blog posts that illustrate how one can use this framework to wrap a web interface around existing databases and command-line tools with practically no work. Impatient people are welcome to download the software and look in the greenmamba/examples directory.