Reactomes

From ReactomeWiki
Jump to: navigation, search

Our reason for being is the official Reactome Project, that site can be found here.

We have a standard operating procedure for our releases, which is specific to human data and our particular computer set up, but which might be useful to you.

Documentation

  • Documentation Software documentation - APIs, installations howtos, FAQs, etc.

Other Reactomes

The following Reactomes are known to us. Clicking on any one of these will take you to an editable page giving you a detailed description.

  • Arabidopsis Reactome - a curated knowledgebase of plant biological pathways (John Innes Centre). Contains many plant pathways curated by the John Innes team, plus plant pathways imported from AraCyc and KEGG.
  • Gallus Reactome - pathways for the chicken.
  • Drosophila.
  • C. Elegans.
  • Archaea.
  • Plant Reactome (managed by Gramene)
    • Under development, scheduled for beta release Jan 2013
    • Designed to host pathways for rice, Arabidopsis, and maize
      • Currently contains rice pathways imported from RiceCyc
      • Will add Arabidopsis pathways imported from AraCyc and the Arabidopsis Reactome in Spring 2013
      • Maize pathways TBA

Setting up Your Own Reactome

This (rather lengthy) section tells you how to get a Reactome server up and going on our machines. It is also possible to set up your own local Reactome, but our preferred strategy is to centralize Reactome repositories, to reduce redundancy, prevent ID clashes and improve inter-Reactome compatibility.

It is assumed that you have at least one curator feeding data specific to your project into Reactome's central database, "gk_central". A little experience with using Linux at the command-line level would be a useful prerequisite, if you wish to go ahead with this. You should also be familiar with at least one of the editors avaiable on Linux systems, such as vi or emacs.

A Reactome "server" comprises of two parts, the Reactome directory hierarchy and a running Apache server that has been configured to execute Reactome CGI scripts. Typically, you will want to have a development server on reactomedev.oicr.on.ca for doing the compute-intensive jobs necessary at release time. Additionally, you will want to have a development and a live server on reactome.oicr.on.ca, the latter being the one normally visible to the outside world.

If you are doing this yourself, you will need:

  • to have user accounts on our computers reactomedev.oicr.on.ca and reactome.oicr.on.ca;
  • to have permission to use the "sudo" command;
  • to have permission to check out Reactome source code from CVS;
  • two port numbers to run your servers on, which are preferably the same both on reactomedev.oicr.on.ca and on reactome.oicr.on.ca (refered to as <primary port> and <secondary port> in the rest of this text);
  • to know the Reactome <database password>.

For all of these things, please contact David Croft.

Set up a Server on reactomedev.oicr.on.ca

Reactome Directory Hierarchy

Log on to reactomedev.oicr.on.ca, e.g. from a Linux terminal:

ssh reactomedev.oicr.on.ca

Go to the directory where your server will live:

cd /usr/local/reactomes

Create a new directory that reflects the name of your project, e.g.

mkdir <your organism>

Check out the Reactome directory hierarchy:

cd <your organism>

cvs co GKB

You will need to give your password here.

This directory, /usr/local/reactomes/<your organism>/GKB, is important, because it is the heart of your installation of Reactome. In subsequent sections, the full path to this directory will be abbreviated as <path_to_GKB_directory>.

Now you need to do some initial customization of the configuration, to get things going.

First, the Config.pm file:

cd <path_to_GKB_directory>/modules/GKB

Edit the file with your favorite editor (e.g. vi):

vi Config.pm

Scroll down to the line beginning with:

$GK_DB_USER =

Change the value from 'reactome_user' to 'curator'. For the line beginning with:

$GK_DB_PASS =

Change the value to be the Reactome database password.

For the line:

$GK_DB_NAME = 'reactome';

Change 'reactome' to 'test_reactome_24'. You will need to change this again at a later stage, but use this value for the time being to test your server.

Delete the '#' symbol at the beginning of the line:

#$WWW_USER = 'nobody';

And insert a '#' symbol at the beginning of the line:

$WWW_USER = 'www';

For the line:

$GK_ROOT_DIR = '/usr/local/gkb';

Replace '/usr/local/gkb' with <path_to_GKB_directory>.

Save the file and exit the editor.

Apache Server

Now it's time to set the Apache configuration:

cd <path_to_GKB_directory>/website/conf

Edit the file httpd.conf using your favorite editor (e.g. vi):

vi httpd.conf

Globally replace '/usr/local/gkb' with <path_to_GKB_directory>.

Scroll down to the last line of the file, and then add (on its own line):

Port <your port>

Finally, start the server:

httpd -f httpd.conf

Testing

Make sure the server is working by opening up a web browser and then entering the URL:

http://reactomedev.oicr.on.ca:<primary port>

You will see the Reactome frontpage (admittedly, this is human Reactome, but we are about to customize things).

Congratulations, you now have a running version of Reactome, dedicated to your project!

But admittedly, it is only running on reactomedev.oicr.on.ca, which is not the official public machine.

Customize the Look and Feel of Your Server

You will probably want to specify your own colors, project name, etc. This section will tell you how to go about this.

At the end of most of the following subsections, you will be advised to "refresh the web page in your browser". This means forcing the broser to redraw the web page from scratch. In Internet Explorer, you can do this by going to the "View" menu and then clicking "Refresh". For Firefox, go to the "View" menu and then click "Reload".

If you skim through the customization subsections, you will see that there is a lot that you could do. Some things are more essential than others, and you may wish to start off with some fairly basic customizations, and later on (perhaps even months later on), customize some more. This is a perfectly feasible way of doing things, but you should read the special note at the end of The Release Cycle section. If you decide to go for minimum customization, you don't need to read through all of the text below.

For a minimal customization, you need to implement:

If you want a slightly more ambitious customization, implement the minimal customization and then try:

Customizing the Title that Appears on the Front Page

By default, the title you see at the top of the front page is 'Reactome - a curated knowledgebase of biological pathways'. You will probably want to change this to reflect the species and content of your own database. Here's how:

cd <path_to_GKB_directory>/modules/GKB

Edit Config.pm, e.g. with vi:

vi Config.pm

Search for the line beginning with:

$PROJECT_TITLE =

Change as required, then save the file and quit the editor.

Refresh the web page in your browser to see how it looks.

Customizing the Color Scheme

Part of what makes a website recognisable and unique is its color scheme. This defines what colors the various elements in a web page should have. It's done via a cascading stylesheet (a.k.a. css). The css is defined in a file, which you must edit if you want to make changes.

cd <path_to_GKB_directory>/website/html

Assuming your favorite editor is vi:

vi stylesheet.css

Right near the beginning of this file, you will find a section titled 'colors' which lists all of the colors used by Reactome and the hexadecimal numbers used to refer to them in the rest of the file. To change the color used for a given purpose, e.g. the cells in an HTML table, you need to globally search and replace this hexadecimal number. You can create your own colors and get back the hexadecimal values by using this color blender.

Once you have saved stylesheet.css, the changes you have made will take effect. To see them, you will need to refresh the web page in your browser.

The Reactome logo is that funny "R" symbol that appears at the top-left hand corner of most Reactome pages. It also appears as part of the URL in your browser, at least in more modern browsers. You might want to display your own custom logo, perhaps an "R" but with a different color scheme, or perhaps something completely unique to your project.

This is the logo that appears at the top-left hand corner of most Reactome pages.

Your logo should be in a .jpg, .gif or .png file, and should measure 87x80 pixels. The regular Reactome logo can be found in:

<path_to_GKB_directory>/website/html/icons/R-purple.png

One option for creating a new logo would be to take this file and use a photo editor, such as the Gimp, to change the colors. Alternatively, you may wish to create something completely new. In any case, once you have produced your logo, you should place it in the directory:

<path_to_GKB_directory>/website/html/icons

If you have decided to use a name other than "R-purple.png" for your logo, you will need to change the Reactome configuration file:

cd <path_to_GKB_directory>/modules/GKB

Edit Config.pm, e.g. with vi:

vi Config.pm

Search for the line:

$PROJECT_LOGO_URL = '/icons/R-purple.png';

Substitute "R-purple.png" with the name of the file containing your logo. Save the file and quit the editor.

The changes you have made will take immediate effect. To see them, you will need to refresh the web page in your browser.

This is the logo that appears as part of the URL, and often is also incorporated into tab titles.

It is stored in a file:

<path_to_GKB_directory>/website/html/favicon.ico

You will find that this file already exists, it contains the regular Reactome icon. You can overwrite this with your own icon file. This should be in ICO format and either 16x16 or 32x32 pixels big. You can convert the icon that you generated in the previous section into a favicon.ico file using the tool at Alt-Web.

Note: you must clear your browser cache before changes to this file become visible.

  • In InternetExplorer, you must first quit the browser and restart it, then click on the "Tools" menu and select "Delete Browsing History". A small window will pop up; click the buttons "Delete files" and "Delete history". Click "Close".
  • For Firefox, click on the "Tools" menu and select "Clear Private Data". A small window will pop up; deselect everything except "Cache", and click the button "Clear Private Data Now". You don't need to restart the browser.

Once you have cleared the cache, re-enter your website's URL in the URL field of the browser, and your new icon will become visible.

Customizing the Sky Panel on the Front Page

The "Starry Sky" or simply "Sky" is the graphical overview of Reactome pathways that appears on the front page. The coordinates for the little arrows that represent reactions are supplied manually to Reactome via a special tool. This is a time-consuming job, and in any case, it is likely that the Sky will be retired at some point. For the reactions in your project, the coordinates needed to construct a Sky will not be present. By default, Reactome will attempt to show a sky, even if you don't have any coordinates, which will look silly.

So, most likely, you will opt not to show a Sky for your project. In this case, you have two possibilities:

  • Show nothing at all;
  • Display an image of your choice.

Both of these involve editing the Config.pm file:

cd <path_to_GKB_directory>/modules/GKB

Edit Config.pm, e.g. with vi:

vi Config.pm

Search for the line beginning with:

$SKY_REPLACEMENT_IMAGE = undef;

If you don't want to display anything at all (the easy option), simply replace "undef" with two single quote characters, ' '.

If you want to display an image, replace "undef" with the name of the image file, preceded by a slash and surrounded in single quotes. E.g.:

$SKY_REPLACEMENT_IMAGE = '/stats.png';

If you have decided to display an image, there are two further tasks to be performed.

  1. The image may be too big or (perhaps) too small to fit into a regular web page. In this case, you will need to scale it. You can use a photo editing tool such as the Gimp to do this.
  2. You must put a copy of the file in a location where it can be found by Reactome; that place is <path_to_GKB_directory>/website/html, ensuring that it has the same filename as the one you put in Config.pm.

Before these changes can take effect, you will need to clear the old cached version of the Sky. This is stored in a file, which you should delete:

rm <path_to_GKB_directory>/website/html/img-fp/test_reactome_24/[0-9]*/[0-9]*.html

Now you can refresh the web page in your browser to see your changes.

Customizing the "Reactome is seeking..." Panel on the Front Page

This panel can be used for advertising things specific to your site. Most likely, you won't want the human Reactome-specific advert that comes packaged with the system. The simplest thing to do is just to make it go away, as follows:

cd <path_to_GKB_directory>/website/html

mv advert.html advert.html.bak

Customizing the "About Reactome" Panel on the Front Page

The contents of this panel are stored as a regular HTML file in:

cd <path_to_GKB_directory>/website/html/about.html

You will need to edit this, e.g. with vi, in order to change the panel. Scroll down to the line:

< !-- please keep this here -->< !-- begin about -->

The text following this line, down to the line:

< !-- end about -->< !-- please keep this here -->

...gets included into the front page, and you should change it to suit your project.

Once you have written the file and quit the editor, your changes will take effect. Refresh the web page in order to see them.

Here are some hints on some of the things you might want to change and how to go about it.

  • Title. This is actually defined in two places, and you will need to change both. Search for the string "About Reactome" and substitute your own title.
  • Title. This is actually defined in two places, and you will need to change both. Search for the string "About Reactome" and substitute your own title.

Customizing the "News and Notes" Panel on the Front Page

The contents of this panel are stored as a regular HTML file in:

cd <path_to_GKB_directory>/website/html/news.html

You will need to edit this, e.g. with vi, in order to change the panel.

As you will see, the news is split up into sections by date. In the copy of the news.html file that you have, these sections correspond to old Reactome releases. You should change these to show important events in the evolution of your own project.

Each section starts with:

< li class="normalsize">< b>...

and ends with:

< /li>

The text between these < li> ... < /li> pairs defines a news section. You should remove the existing sections, and substitute your own. Do not remove the lines:

< /ul>

or

< /TD>< /TR>

or

< /TABLE>

that you find near the end of the file. These are important for formatting.

Once you have written the file and quit the editor, your changes will take effect. Refresh the web page in order to see them.

Customizing the Funding Information that Appears Near the Foot of the Front Page

If you want to make the sources of your funding (grants, etc.) public, proceed as follows:

cd <path_to_GKB_directory>/modules/GKB

Edit Config.pm, e.g. with vi:

vi Config.pm

Search for the line beginning with:

$PROJECT_FUNDING = ' '

Add in the grants between the pair of single-quotes, separating each grant with a comma, then save the file and quit the editor.

Refresh the web page in your browser to see how it looks; the grant information should appear near the bottom of the page.

Customizing the Copyright Information that Appears at the Foot of Most Pages

If you want to provide copyright information on your content (strongly recommended), proceed as follows:

cd <path_to_GKB_directory>/modules/GKB

Edit Config.pm, e.g. with vi:

vi Config.pm

Search for the line beginning with:

$PROJECT_COPYRIGHT = ' '

Add in the copyright information between the pair of single-quotes. The general format is something like: "Copyright <year> <institute/company>". E.g. we use "Copyright 2003 Cold Spring Harbor Laboratory and European Bioinformatics Institute" for human Reactome. Save the file and quit the editor.

Refresh the web page in your browser to see how it looks.

Customizing User Help

At various places in a Reactome page, there may be links or buttons that a user can click on to get help. The default setting in your configuration is to open up a mail window, that allows the user to send an email to help@reactome.org. You will probably want to change this, e.g. so that an email gets sent to you instead. Or you might even want to send them to a web page. To do this proceed as follows:

cd <path_to_GKB_directory>/modules/GKB

Edit Config.pm, e.g. with vi:

vi Config.pm

Search for the line beginning with:

$PROJECT_HELP_URL = 'mailto:help@reactome.org';

If you would like to have help mail sent to you, replace "help@reactome.org" with your own email address, but leave the "mailto" part unchanged.

If you want to direct the user to a web page, rather than sending an email, replace the entire string "mailto:help@reactome.org" with the URL of the web page.

Save the file and quit the editor.

Refresh the web page in your browser to see how it looks.

Customizing Detailed Project Information

The front page presents summary information about various aspects of your project, e.g. in the "About Reactome" panel. You can also give the user access to more detailed information, by a number of routes. This information is stored in the following files in <path_to_GKB_directory>/website/html:

  • about.html. Contains 3 sections: 1) a general description of the project, 2) a list of the team members, 3) a list of the scientific advisory board members.
  • advert.html. You can use this to advertise things, e.g. if you are seeking new staff.
  • content_funding.html. Detailed list of which parts of the project are being funded by which bodies.
  • copyright.html. Detailed terms of copyright.
  • disclaimer.html. Detailed liability waiver.
  • editorial_calendar_public.html. A timetable, showing which pathways you plan to curate, and when.
  • news.html. News ticker.
  • other_reactomes.html. A list of sibling Reactomes that you would like to make your users aware of.
  • referring2GK.html. Tells people how to link to your website.
  • stats.html. A statistics page, giving the number of pathways, reactions, etc. in your database.

The default content of these files is specific to human Reactome, so if you are familiar with HTML, you are encouraged to adapt them to your own project. Otherwise, you should make the contents of these files invisible to the user.

In terms of what the user sees, there is a general rule that applies to all of these files: if the file is present, then the user is able to view its contents. If the file cannot be found, the user is not made aware that such content might exist. E.g. if you don't want to have news on your project presented to users, then rename the news.html file to something else, such as news.html.bak.

If you want to hide all detailed information, proceed as follows:

cd <path_to_GKB_directory>/website/html

mv content_funding.html content_funding.html.bak

mv copyright.html copyright.html.bak

mv disclaimer.html disclaimer.html.bak

mv editorial_calendar_public.html editorial_calendar_public.html.bak

mv other_reactomes.html other_reactomes.html.bak

mv referring2GK.html referring2GK.html.bak

mv stats.html stats.html.bak

Some special cases:

If you have not carried out the instructions given in the section: Customizing the "Reactome is seeking..." Panel on the Front Page, then you will need to rename the advert.html file:

mv advert.html advert.html.bak

If you have carried out the instructions given in the section: Customizing the "About Reactome" Panel on the Front Page, you should also consider what you want to do with the other parts of this file, since they will be visible to users. In the simplest case, you could simply remove them, leaving the description of your project. Make a backup copy of the file before you do this. If you skipped the aforementioned section, you will need to rename the about.html file:

mv about.html about.html.bak

If you have not carried out the instructions given in the section: Customizing the "News and Notes" Panel on the Front Page, then you will need to rename the news.html file:

mv news.html news.html.bak

Create an Initial Database

Now that you have the website working, it is time to switch over to using your own data.

Creating a Reactome database usually has two stages:

  • Taking a slice. This means extracting the instances from the core Reactome database that are specific to your project, and putting them into their own database. The core database, by the way, is called "gk_central" and contains all curated instances.
  • Creating a releasable database. This means taking the slice database and adding additional information to it that might be interesting for your users.

For the time being, we will simply create a slice database.

cd <path_to_GKB_directory>/slicingTool

Your first task is to decide which pathways you would like to see on the front page. These are known in Reactome parlance as "top-level pathways" or "topics". They are stored as a list in the file "test_topics.txt". This file contains two columns, separated by a tab. The first column contains DB_IDs for each top-level pathway. The second column contains the title that you want to show for the corresponding pathway. These titles should be kept short.

DB_ID is short for "database identifier", and is the unique number used to identify things in Reactome. You will need to dind out the DB_IDs for your chosen top-level pathways. If you are already familiar with the CuratorTool, then you will already know how to do this. Otherwise, you can also use the web interface. If you find your pathways (e.g. using the search facility), then take a look at the URL, you will see that it contains "ID=....". The number that directly follows is the DB_ID. Make a note of the DB_ID for each of your top-level pathways, and jot down the title next to it.

Now edit the file "test_topics.txt", e.g. with vi:

vi test_topics.txt

You will see that it is already populated with DB_ID/title pairs. This is just to give you an idea of the required format. You should delete the existing lines, and add your own from the list you have just compiled.

Once you are done, write the file and quit the editor.

The configuration file for the slicing tool is called slicingTool.prop e.g. with vi:

vi slicingTool.prop

Search for the line beginning with:

dbPwd=

Change the password to the Reactome <database password>.

Scroll a bit further to the line beginning with:

slicingDbName=

Change the slice database name to <your organism>_release_0.

Write the file and quit the editor.

Now you are ready to run the slicing tool:

./runSlicingTool.sh

Once this has finished, you will have a new database under MySQL, called <your organism>_release_0.

Edit the Config.pm file so that it knows about the new database (e.g. vi):

cd <path_to_GKB_directory>/modules/GKB

vi Config.pm

Scroll down to the line beginning with:

$GK_DB_NAME =

Change the database name to '<your organism>_release_0'.

Save the file and quit the editor.

Verify that this is OK by going to the web page:

http://reactomedev.oicr.on.ca:<primary port>/

Note that the search facility will not work with this database; you would need to covert it to a myisam database for search to function. This is something that you will do once yo create your first full release.

Set up Servers on reactome.oicr.on.ca

The setup that you have done on reactomedev.oicr.on.ca has produced a fully-functional Reactome, but this is not a public server, it is primarily intended for you to do the compute-intensive part of your releases on.

Your public server will run on the machine reactome.oicr.on.ca. You will need to copy the setup you have on reactomedev.oicr.on.ca over to reactome.oicr.on.ca. This divides into 2 parts: copy over the Reactome source code setup and copy over the database.

Once you have done this, you will need to start the appropriate Apache servers.

Copy over Reactome Directory Hierarchy

Whilst still logged in to reactomedev.oicr.on.ca, create a tarball of the Reactome directory hierarchy:

tar cvf ~/GKB.tar <path_to_GKB_directory>

cd

gzip GKB.tar

Now log in to reactome.oicr.on.ca, e.g. with ssh:

ssh reactome.oicr.on.ca

Create your directory:

cd /usr/local/reactomes

mkdir <your organism>

cd <your organism>

Copy over the tarball:

scp reactomedev.oicr.on.ca:GKB.tar.gz .

You will be asked for your password.

Unpack the tarball:

tar zxvf GKB.tar.gz

This will create the live server, that will be visible by the public. You also need to create a backup server, which will be used during the release process:

cp -a <your organism>_gkb <your organism>_gkb_prod

Edit the Config.pm for the backup server (e.g. vi):

cd <your organism>_gkb_prod/modules/GKB

vi Config.pm

Scroll down to the line beginning with:

$GK_ROOT_DIR =

Add "_prod" to the root directory name.

Save the file and quit the editor.

Copy over Database

If you are still logged in to reactome.oicr.on.ca, return to reactomedev.oicr.on.ca, e.g. with:

logout

Dump your database into a file:

cd

mysqldump --opt -u curator -p<database password> <your organism>_release_0 > <your organism>_release_0.dump

gzip <your organism>_release_0.dump

Log back into reactome.oicr.on.ca, e.g.:

ssh reactome.oicr.on.ca

Copy over the database dump:

scp reactomedev.oicr.on.ca:<your organism>_release_0.dump.gz .

You will be asked for your password.

Unpack the database dump:

gunzip <your organism>_release_0.dump.gz

Initialize database:

mysql -u curator -p<database password>

create database <your organism>_release_0;

exit;

Upload database:

cat <your organism>_release_0.dump | mysql -u curator -p<database password> <your organism>_release_0

Start Apache Servers

Now it's time to set the Apache configuration. First, the backup server:

cd /usr/local/<your organism>_gkb_prod/website/conf

Edit the file httpd.conf using your favorite editor (e.g. vi):

vi httpd.conf

Globally replace <your organism>_gkb with <your organism>_gkb_prod.

Scroll down to the last line of the file, which should look like this:

Port <primary port>

Change it to:

Port <secondary port>

Start the server:

httpd -f httpd.conf

Now for the live server:

cd /usr/local/<your organism>_gkb/website/conf

httpd -f httpd.conf

Your database is now publicly visible!

You can leave this running until you do your first proper release.

The Release Cycle

Your data is fed by curators into the database "gk_central" on reactomedev.oicr.on.ca. This database is growing constantly, but its contents are a work-in-progress, subject to change at any time. This is the reason why "gk_central" is not made publically visible. Instead, "snapshots" are taken every few months, where only those pathways are extracted that are deemed finished.

Human Reactome has a 3 monthly release cycle, that is, the release procedure is repeated every 3 months. This procedure is quite complex and you may not wish to go through it as frequently; this is something you will need to decide for yourself. In any case, there is no need for you to synchronize with the human Reactome - you can release whenever you want to. Details of the release procedure can be found in the Release SOP.

Special Note: if, after a release or two, you decide to make further customizations, you should first curtomize the reactomedev.oicr.on.ca server and then copy over the Reactome directory hierarchy to reactome.oicr.on.ca, as documented in the section Copy over Reactome Directory Hierarchy. It is recommended that you do this immediately before you are planning to do a release.

Notes from FlyReactome

A couple of odd problems arose with FlyReactome that didn't affect human Reactome, but might manifest themselves as problemmatic with other Reactomes. Both occurred only with IE7:

  • in /usr/local/reactomes/drosophila/GKB/website/html/stylesheet.css, it was necessary to comment out the line beginning with "A.DOI".
  • in /usr/local/reactomes/drosophila/GKB/modules/GKB/WebUtils.pm, it was necessary to comment out the line $self->omit_view_switch_link(1);