Researcher's Documentation Contents About Re-searcher Getting Re-searcher Installing Re-searcher Starting and stopping Re-searcher Configuring Re-searcher Using Re-searcher Getting help

1. About Re-searcher

Re-searcher is a highly configurable system for recurrent PSI-BLAST searches. It enables timely detection of new homologs in the protein sequence databases. Searches can be done on a local server or at NCBI. It has a user-friendly web interface.

Re-searcher has been developed by Valdemaras Repšys, Mindaugas Margelevičius and Česlovas Venclovas at the Institute of Biotechnology, Laboratory of Bioinformatics, Vilnius, Lithuania.

To use Re-searcher, enter a new protein sequence (query) and choose PSI-BLAST parameters for the search. Each user has his own sequence (query) list for which PSI-BLAST searches are executed periodically.

Sequences which have new hits are marked with red color. User can always see all the hits found. New hits are also marked with red color. The user gets an email notification whenever new hits are found if he selects this option when entering a new sequence. Note that the SMTP address must be configured for this feature to work.

There is a possibility to perform double searches. In such case, the search is being performed within two distinct databases. For instance, if you choose to perform the primary search on the NR database and the secondary search on the PDB database then the last PSI-BLAST iteration will be performed against the PDB database using PSSM resulting from the search against the NR database.

2. Getting Re-searcher

Re-searcher is an open source project licensed under GPL license. You can download it for free from sourceforge.net.

3. Installing Re-searcher

Make sure that you have java runtime environment version 6 or higher and java binary is in your path. You can check java version and whether it is in path by writing 'java -version' in your command line. If you don't have java, you can download it from www.java.com.

Download researcher-windows.tar.gz or researcher-linux.tar.gz for windows or linux operating systems respectively. Uncompress the archive to the desired location. That's it!

Additional Notes
Sometimes you might want to change the hostname or the port of the Re-searcher's web server, this can be done by editing config/config.properties file.

Running Re-searcher on your own web server

Re-searcher comes bundled with the Jetty web server. If you want to run Re-searcher on your own web server (like Tomcat), you have to download researcher.jar. It contains the standard directory hierarchy for a java web application. IMPORTANT: When running Re-searcher using your own java web server (servlet container) you must set a few java options: derby.system.home - directory for the Re-searcher's database (usually just a location of an empty direcory, the database gets created there automatically on the first run), log4j.conf - path to the log4j.properties file. You can get an example of log4j.properties from one of the Re-searcher's archives conf/log4j.properties

4. Starting and stopping Re-searcher

Windows

To start the Re-searcher you can execute bin/researcher.bat.

If you want Re-searcher to start every time you boot your computer you can install it as a windows service by clicking on bin/install-service.bat. After installing the service you start it with bin/start-service.bat. To stop the service, execute the bin/stop-service.bat file. To uninstall the service execute bin/uninstall-service.bat file.

The application can take a few minutes to start. To begin using Re-searcher go to the following link in your web browser: http://localhost:8080/Researcher/app (localhost must be replaced by a different hostname, if it is configured like this in config/config.properties file)

Linux

In linux Re-searcher is controlled with bin/researcher file. 'bin/researcher start' command starts the program in a background process, 'bin/researcher stop' stops it. 'bin/researcher status' shows whether the program is currently running or not.

Also it is possible to start Re-searcher in the current console to see all the output. For this you need to execute 'bin/researcher console' command. You can then stop it by pressing ctrl+c.

The application can take a few minutes to start. To begin using Re-searcher go to the following link in your web browser: http://localhost:8080/Researcher/app (localhost must be replaced by a different hostname, if it is configured like this in config/config.properties file)

5. Configuring Re-searcher

When you run the application for the first time, you might want to configure some options like the local PSI-BLAST server address, the SMTP address and so on.

To access the application enter the address http://localhost:8080/Researcher/app in your web browser. The login window should appear. When application runs for the first time, user admin is created with the password admin. Admin can add and delete users and also configure other advanced options. To configure advanced options enter the configuration page by pressing on Configuration menu item.

Configuring local psiblast server

You acquire the ability to perform periodical searches on your own server if you configure a local PSI-BLAST server. If you do not need this ability you can skip this paragraph.

For the system to execute PSI-BLAST searches on your server, the ssh server software must be installed there. Also, the following options must be configured on Re-searcher:

• Blast Server Hostname or IP address: Your server's address.
• Blast Server SSH Username: Username that will be used to connect to the server and perform PSI-BLAST searches.
• Blast Server SSH Password: You need to specify password that will be used to connect to the blast server. IMPORTANT NOTE: sometimes password authentication is disabled on ssh servers for security reasons. In that case, leave this field empty and use public key authentication.
• Path to the Private Key File on the Web Server: Fill this field and leave 'Blast Server SSH Password' field empty if you use public key authentication. This field must contain the path to the private key, for instance, 'c:\documents\private.ppk'
• Passphrase for the Private Key: if there is no passphrase or you do not use public key authentication leave this field blank.
• Command Used to Invoke PSI-BLAST: path to the PSI-BLAST executable, for instance '/usr/local/blast/bin/blastpgp'
• Command Used to Invoke Fastacmd: path to the fastacmd executable, for instance '/usr/local/blast/bin/fastacmd'
• Path for Temporary File Storage: folder for temporary files on blast server, for instance: /tmp/
• Number of Processors to Use for Blast: enter the number of processors you have or want to use on a blast server.

You also need to define the databases for the local blast server. To add a new database, enter the name of the database and a path to it in the corresponding fields at the bottom of the configuration page and press add. For instance, the name can be: 'NR', path: '/usr/local/blast/data/nr'. You can see all the databases in the table on the bottom right.

Configuring email notification options

• SMTP Hostname: this address is used to send emails after new hits were found.
• Email From: When user gets notification he sees this email address as a sender of the message.
• Application Link (Needed to Generate a Link to a Hit List): If you fill this field, users will get the link to the hits list on their emails. It is a very convenient option since user can view new hits at once, without logging in. Usually what you fill-in will be 'http://localhost:8080/Researcher/app'. You can also leave this field blank, then emails will not contain the link to the hits list.

Configuring other options

• Allow User Registration: if this field is set on, 'Create new user' link appears on the login page so new users can register themselves.

6. Using Re-searcher

You need to have a user account to work with Researcher. Administrator can create one for you. Also, you can create it yourself if you see the 'Crete new user' link on the login page. To create an account, follow the link, enter your data and press create new user button. Now use your username and password to log in.

New Sequence page

After you log in, you are redirected to the sequence list (which is empty if you logged in for the first time). To enter a new sequence for the PSI-BLAST search follow the "New Sequence" link on menu and click "Add" button after specifying search parameters. Exhaustive description for search parameters is provided in a separate document.

To perform a double search you need to specify the secondary database. Double search means that after performing the search against the primary database PSI-BLAST will use generated PSSM to run one additional iteration against the secondary database. This strategy is often very useful in detecting distant homologs in a small database (such as PDB sequences).

The search should start in a few minutes after entering a new sequence. Searches are executed sequentially and there may be a longer delay if other searches are running at the time.

A single search can take anywhere from minutes to hours depending on search parameters and a number of hits.

Sequence List page

The sequence list page shows the main information about every sequence entered. The row in the table of sequences is colored red if new hits were found for the corresponding sequence. There are four links in every row of the table.

By pressing the query details link you enter the page with all the information about the search and the sequence. If you press the 'Search Now' the search for the sequence will be started as soon as possible, usually in a few minutes. Number of hits and new hits (in brackets) are shown on Hits column. By pressing on it you enter the hits page. You delete the sequence and all it's hits by pressing the delete link.

Hits page

All hits for the specific query are listed here. There is a possibility to order the hits table by any column. New hits are marked red. To mark all hits as old, press 'mark all hits as old' link. To see the alignment, press the 'Alignment' link. To see the sequence of the hit, press the id of the hit. To get fasta-formated sequences of the hits follow the 'View New Sequences' or the 'View All Sequences' link.

7. Getting Help

You can ask for help by email: posu(at)users.sourceforge.net