Difference between revisions of "iRefScape 0.8 Installation"

From irefindex
 
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
==Installation==
 
==Installation==
  
=== Before you begin ===
+
=== Before You Begin ===
  
* These instructions assume that you have downloaded and installed the Cytoscape application. See http://cytoscape.org for a manual and a set of tutorials which describe the installation and use of Cytoscape.
+
* These instructions assume that you have downloaded and installed the Cytoscape application. See http://cytoscape.org/ for a manual and a set of tutorials which describe the installation and use of Cytoscape.
 
* Make sure you have an active Internet connection. During installation the plugin will download files from the iRefIndex FTP site.
 
* Make sure you have an active Internet connection. During installation the plugin will download files from the iRefIndex FTP site.
* Make sure you have latest JAVA environment installed (minimum requirement Java 1.5)
+
* Make sure you have latest Java environment installed: Java 1.5 or later is required.
 +
* '''If you have a plugin called iRefIndex installed, it is recommended that you first delete it''', selecting the "Manage Plugins" option in the "Plugins" menu. This will only be the case for people who may have tried earlier development versions of the plugin.
  
* '''If you have a plugin called iRefIndex installed, it is recommended that you first delete it''' using the Manage Plugins utility under the Plugins menu.  This will only be the case for people who may have tried earlier developmental versions of the plugin.
+
=== Using the Cytoscape Plugin menu ===
 
 
===Using the Cytoscape Plugin menu===
 
  
 
[[Image:IRefIndex-Cytoscape-Manage-Plugins.png|thumb|300px|Manage Plugins]]
 
[[Image:IRefIndex-Cytoscape-Manage-Plugins.png|thumb|300px|Manage Plugins]]
 
 
  
 
# Start Cytoscape. You must start Cytoscape as a user that has write privileges to the target directory.  
 
# Start Cytoscape. You must start Cytoscape as a user that has write privileges to the target directory.  
 
# From the menu select "Plugins" -> "Manage Plugins".   
 
# From the menu select "Plugins" -> "Manage Plugins".   
 
# Select "Manage plugins" from the plugin menu.
 
# Select "Manage plugins" from the plugin menu.
# Locate "Available for Install" then "Network and Attribute I/O", verifying that iRefIndex is listed in this category.
+
# Locate "Available for Install" then "Network and Attribute I/O", verifying that iRefScape is listed in this category.
# Select the iRefIndex plugin and then click "Install" (in the bottom-right-hand corner of the window).
+
# Select the iRefScape plugin and then click "Install" (in the bottom-right-hand corner of the window).
# Click "Close" to leave the "Manage Plugins" dialogue.
+
# When you see the message "iRefScape v.0.8.x install complete" click "Close" to leave the "Manage Plugins" dialogue.
# Close and then Restart Cytoscape
+
# Close and then restart Cytoscape.
# Select iRefIndex_0.7x from Cytoscape's plugin menu.
+
# Select iRefIndex_0.8x from Cytoscape's "Plugins" menu.
 
# When the plugin is started for the first time, it will download the publicly available dataset.
 
# When the plugin is started for the first time, it will download the publicly available dataset.
# See Completing the installation
 
  
=== Completing the installation ===
+
<br clear="all" />
 +
=== Completing the Installation ===
  
 
[[Image:IRefIndex-Cytoscape-Location.png|thumb|300px|Indicating the location of iRefIndex data]]
 
[[Image:IRefIndex-Cytoscape-Location.png|thumb|300px|Indicating the location of iRefIndex data]]
Line 32: Line 29:
 
[[Image:IRefIndex-Cytoscape-Download.png|thumb|300px|The download status dialogue]]
 
[[Image:IRefIndex-Cytoscape-Download.png|thumb|300px|The download status dialogue]]
  
# You will be prompted to select an installation directory for the data and indices. The recommended place would be the plugin home directory which would appear as the recommended (default). The data and indices require a minimum disk space of 1 Gb  at this location. We encourage the users to use this default directory.
+
# You will be prompted to select an installation directory for the data and indices. The recommended place would be the plugin home directory which would appear as the recommended (default). The data and indices require a minimum disk space of 1 GB at this location. Using this default directory is strongly encouraged.
# If the default directory is selected and it is not accessible the user would be prompted to restart Cytoscape. If this message appears on second or subsequent attempts, this would mean there might be a problem accessing this directory and please make sure that you have write access and a minimum available free space of 1Gb.
+
# If the default directory is selected and is not accessible, you will be prompted to restart Cytoscape. If this message appears on second or subsequent attempts, this may mean that there is a problem accessing this directory. To avoid such problems, ensure that you have write access to the directory and at least 1GB of free space on the disk.
# The downloading and installation of indices usually takes less than 5 minutes if you have a internet connection of 10Mb/sec or more. However we have experienced delays up to 15 to 30 minutes when the installation was done using wireless network with below average signal strength.  
+
# The downloading and installation of indices usually takes less than 5 minutes if you have a internet connection of 10Mb/sec or more. However testing has demonstrated installation times of between 15 and 30 minutes when the installation was done using a wireless network with below average signal strength.
 
# The installation process should now complete itself.
 
# The installation process should now complete itself.
# If the installation was successful, you will see a new iRefIndex panel near the "Network" tab of Cytoscape as well as an iRefIndex menu (blue) at the top of the Cytoscape interface.
+
# If the installation was successful, you will see a new iRefScape panel near the "Network" tab of Cytoscape as well as an iRefScape menu (blue) at the top of the Cytoscape interface.  Also, you will see an Information frame with several tabs in it ("Messages", "Search history", "Query helper", and so on). This window can be closed.
  
===To uninstall the plugin===
+
<br clear="all" />
 +
=== Uninstalling the Plugin===
  
# Select "Currently Installed" -> "Network and Attribute I/O Plugins" and choose the iRefIndex plugin.
+
# Select "Currently Installed" -> "Network and Attribute I/O Plugins" and choose the iRefScape plugin.
 
# Then, click the "Delete" button and confirm.
 
# Then, click the "Delete" button and confirm.
 
# Click "Close" to leave the "Manage Plugins" dialogue and restart Cytoscape.
 
# Click "Close" to leave the "Manage Plugins" dialogue and restart Cytoscape.
Line 46: Line 44:
 
=== Using the iRefIndex Installation site ===
 
=== Using the iRefIndex Installation site ===
  
In rare cases, the Cytoscape plugin site may be down.  In this case, you have the option of using the iRefindex plugin site.
+
In rare cases, the Cytoscape plugin site may be down.  In this case, you have the option of using the iRefScape plugin site.
 
 
  
 
# Start Cytoscape. You must start Cytoscape as a user that has write privileges to the target directory.  
 
# Start Cytoscape. You must start Cytoscape as a user that has write privileges to the target directory.  
 
# From the menu select "Plugins" -> "Manage Plugins".
 
# From the menu select "Plugins" -> "Manage Plugins".
  
 
+
To use the iRefScape plugin site:
To use the iRefIndex plugin site:
 
  
 
# Click on "Change Download Site" button (in the top-right-hand corner of the window).
 
# Click on "Change Download Site" button (in the top-right-hand corner of the window).
 
# Click "Edit Sites".
 
# Click "Edit Sites".
 
# Click "Add" and for each of the following fields, enter the suggested values:
 
# Click "Add" and for each of the following fields, enter the suggested values:
#* Name: <tt>iRefIndex</tt>
+
#* Name: <tt>iRefScape</tt>
 
#* URL: <tt>ftp://ftp.no.embnet.org/irefindex/Cytoscape/plugin/current/plugins_irefindex.xml</tt>
 
#* URL: <tt>ftp://ftp.no.embnet.org/irefindex/Cytoscape/plugin/current/plugins_irefindex.xml</tt>
 
# Click "OK" to close each of the dialogues until the "Manage Plugins" dialogue is visible.
 
# Click "OK" to close each of the dialogues until the "Manage Plugins" dialogue is visible.
Line 64: Line 60:
 
To install the plugin:
 
To install the plugin:
  
# Locate "Available for Install" then "Network and Attribute I/O", verifying that iRefIndex is listed in this category.
+
# Locate "Available for Install" then "Network and Attribute I/O", verifying that iRefScape is listed in this category.
# Select the iRefIndex plugin and then click "Install" (in the bottom-right-hand corner of the window).
+
# Select the iRefScape plugin and then click "Install" (in the bottom-right-hand corner of the window).
 
# Click "Close" to leave the "Manage Plugins" dialogue.
 
# Click "Close" to leave the "Manage Plugins" dialogue.
 
# Restart Cytoscape.
 
# Restart Cytoscape.
 
# Go to the "Completing the installation" step above.
 
# Go to the "Completing the installation" step above.
  
 +
=== Manual Installation ===
  
 
=== Manual installation ===
 
 
# Before starting:
 
# Before starting:
 
#* Make sure that Cytoscape is not running.
 
#* Make sure that Cytoscape is not running.
#* Remove any other installations of iRefIndex beta or directories created by iRefIndex.(e.g. \.....\Cytoscape_v2.6.0\plugins\iRefIndex\ )
+
#* Remove any other installations of iRefScape (or iRefIndex) or directories created by those installations (such as <tt>.../Cytoscape_v2.6.0/plugins/iRefScape</tt>).
# Copy the <tt>iRefIndex_0.7x.jar</tt> file to the <tt>plugins</tt> directory of Cytoscape. For example:
+
# Copy the <tt>iRefScape_0.8x.jar</tt> file to the <tt>plugins</tt> directory of your Cytoscape installation. For example:
#* On Unix: <tt>/.../Cytoscape_v2.6.2/plugins/</tt>
+
#* On Unix: <tt>.../Cytoscape_v2.6.2/plugins/</tt>
#* On Windows: <tt>\...\Cytoscape_v2.6.2\plugins\</tt>
+
#* On Windows: <tt>...\Cytoscape_v2.6.2\plugins\</tt>
#* (You should have write privileges for this directory, during installation and also during operation.)  
+
#* '''Note''' that you should have write privileges for this directory during installation and also during operation, and that this directory is ''not'' the recommended default location for the plugin (which is in a <tt>.cytoscape</tt> directory inside the user's home directory).
 
# You may now start Cytoscape.
 
# You may now start Cytoscape.
  
 +
<br clear="all" />
 +
 +
== Troubleshooting and Security Issues==
  
 +
The plugin has two components:
  
<br clear="all" />
+
* The Java executable file (<tt>iRefScape_0.8x.jar</tt>) which is the software component providing the plugin functionality.
 +
* The data component containing protein-protein interaction data.
  
== Trouble shooting and security issues==
+
Both these components are required for the functioning of the plugin. The installation section above explains how to install the executable components, and once this component is installed and the plugin is loaded, the data component will then be downloaded by the plugin itself. The downloaded file is compressed and has the extension <tt>.irfz</tt> and a size of around 200 MB. After the download is complete this file will be partially uncompressed (the indices and few other files required for immediate operation will be extracted from the complex file). However, the bulk of the data will remain compressed and will only be uncompressed when needed. Thus, the speed of query execution will increase with usage and the size of the <tt>iRefIndex</tt> directory will increase. Therefore, although 250MB of available free space is enough during installation, the plugin requires up to 1GB of space for its operation.
#The plugin has two componants.
 
*The java executable file (JAR) which is the software component dealing with all the functionalities.
 
*Data component containing protein-protein interaction data.
 
  
both these components are required for the functioning of the plugin. The installation section above explains how to install the JAR and once the JAR is installed and the plugin is loaded the data component will be downloaded by it. The downloaded file is a compressed one and has the extension .irfz and a size around 200 MB.  After the download is complete this file will be partially uncompressed (The indices and few other files required for the immediate operation will be extracted from the complex file). However, the bulk of the data will remain compressed and will be uncompressed when needed. Thus, the speed of query execution will increase with usage and the size of the iRefIndex folder will increase. Therefore, although available free space of 250Mb is enough during installation, the plugin requires available free space of 1Gb for its operation.
+
If the plugin manager is used for the installation (as of Cytoscape 2.6.3), the plugin will be placed in a directory under the home area and a record file is kept in a file named <tt>track_plugins.xml</tt>. The location of these would as follows:
  
If the plugin manager is used for the instalation,(as of Cytoscape 2.6.3) the plugin will be placed in a directory under the home area and a record file is kept in a file named 'track_plugins.xml'. The location of these would as follows.
+
* Linux: <tt>~/.cytoscape/2.6</tt>
*Linux : ~/.cytoscape/2.6  
+
* Windows: <tt>''<user's home directory>''\.cytoscape\2.6</tt>
*Windows: user's home directory/.cytoscape/2.6  
 
  
The entry corresponding to iRefIndex plugin would looks like follows:
+
The entry corresponding to iRefScape plugin would looks like follows:
  
 
  <plugin>
 
  <plugin>
      <uniqueID />
+
  <uniqueID>999</uniqueID>
      <name>iRefIndex</name>
+
  <name>iRefScape</name>
      <description>.&lt;br&gt;http://irefindex.uio.no/wiki/README_Cytoscape_plugin_0.7x&lt;p&gt;</description>
+
  <description>.&lt;br&gt;http://irefindex.uio.no/wiki/README_Cytoscape_plugin_0.8x&lt;p&gt;</description>
      <cytoscapeVersion>2.6</cytoscapeVersion>
+
  <cytoscapeVersion>2.6</cytoscapeVersion>
      <url />
+
  <url>ftp://ftp.no.embnet.org/irefindex/Cytoscape/plugin/archive/beta8/iRefScape_0_83.jar</url>
      <downloadUrl />
+
  <downloadUrl>ftp://ftp.no.embnet.org/irefindex/Cytoscape/plugin/current/plugins_irefindex.xml</downloadUrl>
      <category>Network and Attribute I/O</category>
+
  <category>Network and Attribute I/O</category>
      <releaseDate>JANUARY 15, 2009</releaseDate>
+
  <releaseDate>MAY 20, 2010</releaseDate>
      <pluginVersion>0.63</pluginVersion>
+
  <pluginVersion>0.83</pluginVersion>
      <classname>cytoscape.no.uio.biotek.Main</classname>
+
  <classname>cytoscape.no.uio.biotek.Main</classname>
      <projectUrl>http://irefindex.uio.no</projectUrl>
+
  <projectUrl>http://irefindex.uio.no</projectUrl>
      <filetype>jar</filetype>
+
  <filetype>jar</filetype>
      <installLocation>/............/Cytoscape_2_6_3/plugins/iRefIndex_beta6.jar</installLocation>
+
  <installLocation>.../.cytoscape/2.6/plugins/iRefScape-0.83</installLocation>
      <license>
+
  <license>
        <text />
+
    <text />
      </license>
+
  </license>
      <authorlist>
+
  <filelist>
        <author>
+
    <file>.../.cytoscape/2.6/plugins/iRefScape-0.83/iRefScape.jar</file>
          <name>Ian Donaldson and Sabry Razick</name>
+
  </filelist>
          <institution>Biotechnology Centre of Oslo, University of Oslo</institution>
+
  <authorlist>
        </author>
+
    <author>
      </authorlist>
+
      <name>Ian Donaldson and Sabry Razick</name>
      <filelist>
+
      <institution>Biotechnology Centre of Oslo, University of Oslo</institution>
        <file>/........../Cytoscape_2_6_3/plugins/iRefIndex_beta6.jar</file>
+
    </author>
      </filelist>
+
  </authorlist>
    </plugin>
+
</plugin>
  
*TIP!. If you do encounter an exception during start up of Cytoscape due to a plugin and there is no way of uninstalling it, you could remove the entry for the corresponding plugin from this file when Cytoscape is not running (Take a backup of the file, then delete everything from <plugin> to </plugin> for the troubling plugin, save the file and then start Cytoscape).
+
'''Note:''' If you encounter an exception during Cytoscape's start-up process due to a plugin failure and there is no way of uninstalling it, you could remove the entry for the corresponding plugin from this file when Cytoscape is not running. First, take a backup of the file, then delete the plugin entry resembling that shown above for the plugin concerned. Finally, save the file and restart Cytoscape.
  
The downloading and installation of the plugin JAR is manged by Cytoscape core and if the plugin complies with the requirements the instalation should be smooth. However, some of our users do encounter  problems when instating the data component. This is mainly due to privileged and security issues.  
+
The download and installation of the plugin executable is managed by the core functionality provided by Cytoscape, and if the plugin complies with the requirements defined for the plugin framework, the installation should proceed smoothly. However, some users have encountered problems when installing the data component; this is mainly due to privilege and security issues.
*Privileged issue is whether the user has access to the place where he intends to download the data component (The directory should have write access)
 
*Security issues are mainly encountered in Microsoft Windows based systems. When software tries to perform a suspicious operation the operation is blocked and the user is prompted to confirm that this is something they know about. If the user selects "block", the iRefIndex plugin installation fails and may not be able to install again until the block is removed manually. We have tested this with several popular virus guards but have not encountered any issues relating to them yet. If you encounter any issues please report to these to the [http://groups.google.com/group/irefindex?hl=en iRefIndex Google Group]. 
 
  
The behavior of the plugin when installed using plugin manager is different before and ofter Cytoscape is restarted. After the installation, the plugin will appear in the plugin manager and could be activated, however it is not aware of its surroundings;i.e, it doesn't know its installation location. Therefore it is highly recommended that the user restart Cytoscape immediately after installing the plugin and avoid activating the plugin before the first restart (do not click on the menu entry iRefIndex). When a manual installation was performed the plugin could be activated for the first start up of Cytoscape as Cytoscape is not running during installation.  
+
* Privilege issues arise when a user does not have access to the place where the data component is to be installed. This directory should permit write access for that user.
After the first restart of Cytoscape after installing the plugin when the plugin is activated it tries to download the data component. For this the plugin requests a location to place the data and it suggests a default location under the home area (or plugin folder for manual installation), we recommend using this default location unless there is a absolute requirement to do otherwise.  
+
* Security issues are mainly encountered with Microsoft Windows-based operating systems. When software tries to perform a suspicious operation, the operation is blocked and the user is prompted to confirm that this is something they have chosen to do themselves. If the user selects "block", the iRefScape plugin installation fails and it may not be possible to attempt to install the plugin again until the blocking action is revoked manually. Although antivirus products are also known to interfere with software installers, the plugin installation process has been tested on systems running several popular antivirus products, but has not revealed any issues relating to them at the time of writing. If you encounter any such issues, please report to these to the [http://groups.google.com/group/irefindex?hl=en iRefIndex Google Group].
  
some of the reasons behind distributing the data with the plugin rather than more popular approach like web services is as follows;
+
The behaviour of the plugin when installed using the plugin manager is different before and after Cytoscape is restarted. After the installation, the plugin will appear in the plugin manager and could be activated, however it is not aware of its environment: for example, it does not know its installation location. Therefore it is highly recommended that Cytoscape be restarted immediately after installing the plugin, and that the plugin is not activated before the first restart (do not click on the "iRefScape" menu entry). When a manual installation is performed, the plugin can be activated after starting Cytoscape for the first time, since Cytoscape is not running during the installation process.
*Execution speed
+
 
*No need for a fast internet connection after installation
+
Some of the reasons behind distributing the data with the plugin rather than more popular approaches such as the use of Web services include the following:
*Our server-side limits
+
 
*Privacy for the user (There is no monitoring of the types of searches the end user performs, this remains private unless the user decides to share it)
+
* Execution speed
 
+
* No need for a fast internet connection after installation
 +
* Hosting restrictions applying to the iRefScape/iRefIndex download site
 +
* Privacy for the user: there is no monitoring of the types of searches the user performs; thus, the user's activities remain private unless they decide to share such details with others
  
 
<br clear="all" />
 
<br clear="all" />
 
+
== Troubleshooting Platform-Specific Issues ==
== Trouble shooting platform-specific issues ==
 
  
 
=== Windows Vista and Windows XP ===
 
=== Windows Vista and Windows XP ===
  
You will require write privileges to the installation directory not only during installation but also during operation. If the plugin disappears from the plugin menu or it does not appear at all, then Cytoscape has to be started as an administrator. This could be done by right-clicking on the Cytoscape shortcut and selecting "Run as" option. When requesting help for such situations please include a copy-paste of the Cytoscape error console ("Help" -> "Error console"). (To copy-paste, open the error console, click inside, press <tt>Ctrl-A</tt> (to select all) then <tt>Ctrl-C</tt> (to copy). The selection can then be pasted into a message using <tt>Ctrl-V</tt>.)
+
You will require write privileges to the installation directory not only during installation but also during operation of the plugin. If the plugin disappears from the "Plugins" menu or it does not appear at all, then Cytoscape has to be started as an administrator. This could be done by right-clicking on the Cytoscape shortcut and selecting "Run as" option. When requesting help for such situations, please include a copy-paste of the Cytoscape error console ("Help" -> "Error console"). (To copy-paste, open the error console, click inside, press <tt>Ctrl-A</tt> (to select all) then <tt>Ctrl-C</tt> (to copy). The selection can then be pasted into a message using <tt>Ctrl-V</tt>.)
  
 
=== Mac OS X ===
 
=== Mac OS X ===
Line 168: Line 163:
 
  export _JAVA_OPTIONS='-Dawt.useSystemAAFontSettings=lcd'
 
  export _JAVA_OPTIONS='-Dawt.useSystemAAFontSettings=lcd'
  
 +
== About the Installation Files ==
  
 +
During installation the plugin downloads protein-protein interaction data from iRefIndex (ftp://ftp.no.embnet.org/irefindex/Cytoscape/plugin/current/) in a compressed form. The downloaded files will reside in the <tt>iRefIndex</tt> directory under the Cytoscape plugin folder. It is recommended that the files in this directory '''not''' be modified as this may lead to unpredictable results. In particular, please do not open them in word-processing software (such as Microsoft Office). After successful installation you will also find some index files and serialized Java object files which will be used in the search and load operations.
  
==About the installation files==
+
=== Brief Description of the Files ===
  
During installation the plugin downloads protein-protein interaction data from iRefIndex (ftp://ftp.no.embnet.org/irefindex/Cytoscape/plugin/current/) in a compressed form. The downloaded files will be in the directory iRefIndex under the Cytoscape plugin folder. We recommend not to change any files in this folder as this may lead to unpredictable results. Especially, please do not open them in word processor software (e.g. Microsoft office).
+
* irft files: this file contains a ROG (Redundant Object Group) to PARAMETER mapping. This is a sort of index that maps identifiers like accessions and names to ROGs. The ROG is an integer representation of the ROGID. However, ROG is not stable like ROGID and it may be different from one version to another. However, from beta4 onwards the ROGID to ROG mapping will be propagated for backwards compatibility for live proteins (proteins which are not removed from original source). 
After successful installation you will also find some index files and serialized Java objects files which will be used in  search and load operations.
+
* Irfm files: These are index files containing information about partners of each interaction.
 +
* ROGS Directory: Contains protein attributes (Warning! Please do not try to open this directory in a file browser; the computer may crash)
 +
* RIGS Directory: Contains interaction attributes (Warning! Please do not try to open this directory in a file browser; the computer may crash)  
 +
* Irfj files : these files contain the interaction and object data in a compressed form. When requested for the first time the information will be uncompressed to the RIGS or ROGS directory.
  
# Brief description of the files
+
[[Category:iRefIndex]]
#* irft files: this file contains a ROG(Redundant Object Group) to PARAMETER mapping. This is a sort of index that maps identifiers like accessions and names to ROGs. The ROG is an integer representation of the ROGID. However, ROG is not stable like ROGID and it may be different from one version to another. However, from beta4 onwards the ROGID to ROG mapping will be propagated for backwards compatibility for live proteins (proteins which are not removed from original source). 
 
#* Irfm files: These are index files containing information about partners of each interaction.
 
#* ROGS Directory: Contains protein attributes (Warning! Please do not try to open this directory in  a file browser; the computer may crash)
 
#* RIGS Directory: Contains interaction attributes (Warning! Please do not try to open this directory in a file browser; the computer may crash)
 
#* Irfj files : these files contain the interaction and object data in a compressed form. When requested for the first time the information will be uncompressed to the RIGS or ROGS directory.
 

Latest revision as of 16:09, 6 July 2011

Installation

Before You Begin

  • These instructions assume that you have downloaded and installed the Cytoscape application. See http://cytoscape.org/ for a manual and a set of tutorials which describe the installation and use of Cytoscape.
  • Make sure you have an active Internet connection. During installation the plugin will download files from the iRefIndex FTP site.
  • Make sure you have latest Java environment installed: Java 1.5 or later is required.
  • If you have a plugin called iRefIndex installed, it is recommended that you first delete it, selecting the "Manage Plugins" option in the "Plugins" menu. This will only be the case for people who may have tried earlier development versions of the plugin.

Using the Cytoscape Plugin menu

Manage Plugins
  1. Start Cytoscape. You must start Cytoscape as a user that has write privileges to the target directory.
  2. From the menu select "Plugins" -> "Manage Plugins".
  3. Select "Manage plugins" from the plugin menu.
  4. Locate "Available for Install" then "Network and Attribute I/O", verifying that iRefScape is listed in this category.
  5. Select the iRefScape plugin and then click "Install" (in the bottom-right-hand corner of the window).
  6. When you see the message "iRefScape v.0.8.x install complete" click "Close" to leave the "Manage Plugins" dialogue.
  7. Close and then restart Cytoscape.
  8. Select iRefIndex_0.8x from Cytoscape's "Plugins" menu.
  9. When the plugin is started for the first time, it will download the publicly available dataset.


Completing the Installation

Indicating the location of iRefIndex data
The download status dialogue
  1. You will be prompted to select an installation directory for the data and indices. The recommended place would be the plugin home directory which would appear as the recommended (default). The data and indices require a minimum disk space of 1 GB at this location. Using this default directory is strongly encouraged.
  2. If the default directory is selected and is not accessible, you will be prompted to restart Cytoscape. If this message appears on second or subsequent attempts, this may mean that there is a problem accessing this directory. To avoid such problems, ensure that you have write access to the directory and at least 1GB of free space on the disk.
  3. The downloading and installation of indices usually takes less than 5 minutes if you have a internet connection of 10Mb/sec or more. However testing has demonstrated installation times of between 15 and 30 minutes when the installation was done using a wireless network with below average signal strength.
  4. The installation process should now complete itself.
  5. If the installation was successful, you will see a new iRefScape panel near the "Network" tab of Cytoscape as well as an iRefScape menu (blue) at the top of the Cytoscape interface. Also, you will see an Information frame with several tabs in it ("Messages", "Search history", "Query helper", and so on). This window can be closed.


Uninstalling the Plugin

  1. Select "Currently Installed" -> "Network and Attribute I/O Plugins" and choose the iRefScape plugin.
  2. Then, click the "Delete" button and confirm.
  3. Click "Close" to leave the "Manage Plugins" dialogue and restart Cytoscape.

Using the iRefIndex Installation site

In rare cases, the Cytoscape plugin site may be down. In this case, you have the option of using the iRefScape plugin site.

  1. Start Cytoscape. You must start Cytoscape as a user that has write privileges to the target directory.
  2. From the menu select "Plugins" -> "Manage Plugins".

To use the iRefScape plugin site:

  1. Click on "Change Download Site" button (in the top-right-hand corner of the window).
  2. Click "Edit Sites".
  3. Click "Add" and for each of the following fields, enter the suggested values:
  4. Click "OK" to close each of the dialogues until the "Manage Plugins" dialogue is visible.

To install the plugin:

  1. Locate "Available for Install" then "Network and Attribute I/O", verifying that iRefScape is listed in this category.
  2. Select the iRefScape plugin and then click "Install" (in the bottom-right-hand corner of the window).
  3. Click "Close" to leave the "Manage Plugins" dialogue.
  4. Restart Cytoscape.
  5. Go to the "Completing the installation" step above.

Manual Installation

  1. Before starting:
    • Make sure that Cytoscape is not running.
    • Remove any other installations of iRefScape (or iRefIndex) or directories created by those installations (such as .../Cytoscape_v2.6.0/plugins/iRefScape).
  2. Copy the iRefScape_0.8x.jar file to the plugins directory of your Cytoscape installation. For example:
    • On Unix: .../Cytoscape_v2.6.2/plugins/
    • On Windows: ...\Cytoscape_v2.6.2\plugins\
    • Note that you should have write privileges for this directory during installation and also during operation, and that this directory is not the recommended default location for the plugin (which is in a .cytoscape directory inside the user's home directory).
  3. You may now start Cytoscape.


Troubleshooting and Security Issues

The plugin has two components:

  • The Java executable file (iRefScape_0.8x.jar) which is the software component providing the plugin functionality.
  • The data component containing protein-protein interaction data.

Both these components are required for the functioning of the plugin. The installation section above explains how to install the executable components, and once this component is installed and the plugin is loaded, the data component will then be downloaded by the plugin itself. The downloaded file is compressed and has the extension .irfz and a size of around 200 MB. After the download is complete this file will be partially uncompressed (the indices and few other files required for immediate operation will be extracted from the complex file). However, the bulk of the data will remain compressed and will only be uncompressed when needed. Thus, the speed of query execution will increase with usage and the size of the iRefIndex directory will increase. Therefore, although 250MB of available free space is enough during installation, the plugin requires up to 1GB of space for its operation.

If the plugin manager is used for the installation (as of Cytoscape 2.6.3), the plugin will be placed in a directory under the home area and a record file is kept in a file named track_plugins.xml. The location of these would as follows:

  • Linux: ~/.cytoscape/2.6
  • Windows: <user's home directory>\.cytoscape\2.6

The entry corresponding to iRefScape plugin would looks like follows:

<plugin>
  <uniqueID>999</uniqueID>
  <name>iRefScape</name>
  <description>.<br>http://irefindex.uio.no/wiki/README_Cytoscape_plugin_0.8x<p></description>
  <cytoscapeVersion>2.6</cytoscapeVersion>
  <url>ftp://ftp.no.embnet.org/irefindex/Cytoscape/plugin/archive/beta8/iRefScape_0_83.jar</url>
  <downloadUrl>ftp://ftp.no.embnet.org/irefindex/Cytoscape/plugin/current/plugins_irefindex.xml</downloadUrl>
  <category>Network and Attribute I/O</category>
  <releaseDate>MAY 20, 2010</releaseDate>
  <pluginVersion>0.83</pluginVersion>
  <classname>cytoscape.no.uio.biotek.Main</classname>
  <projectUrl>http://irefindex.uio.no</projectUrl>
  <filetype>jar</filetype>
  <installLocation>.../.cytoscape/2.6/plugins/iRefScape-0.83</installLocation>
  <license>
    <text />
  </license>
  <filelist>
    <file>.../.cytoscape/2.6/plugins/iRefScape-0.83/iRefScape.jar</file>
  </filelist>
  <authorlist>
    <author>
      <name>Ian Donaldson and Sabry Razick</name>
      <institution>Biotechnology Centre of Oslo, University of Oslo</institution>
    </author>
  </authorlist>
</plugin>

Note: If you encounter an exception during Cytoscape's start-up process due to a plugin failure and there is no way of uninstalling it, you could remove the entry for the corresponding plugin from this file when Cytoscape is not running. First, take a backup of the file, then delete the plugin entry resembling that shown above for the plugin concerned. Finally, save the file and restart Cytoscape.

The download and installation of the plugin executable is managed by the core functionality provided by Cytoscape, and if the plugin complies with the requirements defined for the plugin framework, the installation should proceed smoothly. However, some users have encountered problems when installing the data component; this is mainly due to privilege and security issues.

  • Privilege issues arise when a user does not have access to the place where the data component is to be installed. This directory should permit write access for that user.
  • Security issues are mainly encountered with Microsoft Windows-based operating systems. When software tries to perform a suspicious operation, the operation is blocked and the user is prompted to confirm that this is something they have chosen to do themselves. If the user selects "block", the iRefScape plugin installation fails and it may not be possible to attempt to install the plugin again until the blocking action is revoked manually. Although antivirus products are also known to interfere with software installers, the plugin installation process has been tested on systems running several popular antivirus products, but has not revealed any issues relating to them at the time of writing. If you encounter any such issues, please report to these to the iRefIndex Google Group.

The behaviour of the plugin when installed using the plugin manager is different before and after Cytoscape is restarted. After the installation, the plugin will appear in the plugin manager and could be activated, however it is not aware of its environment: for example, it does not know its installation location. Therefore it is highly recommended that Cytoscape be restarted immediately after installing the plugin, and that the plugin is not activated before the first restart (do not click on the "iRefScape" menu entry). When a manual installation is performed, the plugin can be activated after starting Cytoscape for the first time, since Cytoscape is not running during the installation process.

Some of the reasons behind distributing the data with the plugin rather than more popular approaches such as the use of Web services include the following:

  • Execution speed
  • No need for a fast internet connection after installation
  • Hosting restrictions applying to the iRefScape/iRefIndex download site
  • Privacy for the user: there is no monitoring of the types of searches the user performs; thus, the user's activities remain private unless they decide to share such details with others


Troubleshooting Platform-Specific Issues

Windows Vista and Windows XP

You will require write privileges to the installation directory not only during installation but also during operation of the plugin. If the plugin disappears from the "Plugins" menu or it does not appear at all, then Cytoscape has to be started as an administrator. This could be done by right-clicking on the Cytoscape shortcut and selecting "Run as" option. When requesting help for such situations, please include a copy-paste of the Cytoscape error console ("Help" -> "Error console"). (To copy-paste, open the error console, click inside, press Ctrl-A (to select all) then Ctrl-C (to copy). The selection can then be pasted into a message using Ctrl-V.)

Mac OS X

  • Please verify that Java 1.5 or later is available. The plugin will not work unless Java 1.5 or later is installed.
  • Increase the Xmx setting to 512m and the Xms setting to 512m in cytoscape.sh.
  • This version of the plugin is not extensively tested on Mac OS and we are sorry that the support we could provide for Mac users is limited at this point.

Unix/Linux

  • Please verify that Java 1.5 or later is available.
  • You will require write privileges to the installation directory not only during installation but also during operation.
  • The plugin behavior is proven to be very stable in Unix/Linux environments.
  • To improve font appearance, try adding the following environment variable definition to your configuration (in .bashrc or .bash_profile), as described in this guide to Java fonts for Arch Linux:
export _JAVA_OPTIONS='-Dawt.useSystemAAFontSettings=lcd'

About the Installation Files

During installation the plugin downloads protein-protein interaction data from iRefIndex (ftp://ftp.no.embnet.org/irefindex/Cytoscape/plugin/current/) in a compressed form. The downloaded files will reside in the iRefIndex directory under the Cytoscape plugin folder. It is recommended that the files in this directory not be modified as this may lead to unpredictable results. In particular, please do not open them in word-processing software (such as Microsoft Office). After successful installation you will also find some index files and serialized Java object files which will be used in the search and load operations.

Brief Description of the Files

  • irft files: this file contains a ROG (Redundant Object Group) to PARAMETER mapping. This is a sort of index that maps identifiers like accessions and names to ROGs. The ROG is an integer representation of the ROGID. However, ROG is not stable like ROGID and it may be different from one version to another. However, from beta4 onwards the ROGID to ROG mapping will be propagated for backwards compatibility for live proteins (proteins which are not removed from original source).
  • Irfm files: These are index files containing information about partners of each interaction.
  • ROGS Directory: Contains protein attributes (Warning! Please do not try to open this directory in a file browser; the computer may crash)
  • RIGS Directory: Contains interaction attributes (Warning! Please do not try to open this directory in a file browser; the computer may crash)
  • Irfj files : these files contain the interaction and object data in a compressed form. When requested for the first time the information will be uncompressed to the RIGS or ROGS directory.