CGView Comparison Tool (CCT) installation

Contents

Prerequisites for CCT installation

Instructions for obtaining and installing these prerequisites and CCT are given below for Mac OS X and Linux. The instructions will likely need to be adjusted depending on the particular OS you are using, and as new versions of the perquisites are released. To use CCT on a Windows system we recommend using the CCT virtual machine (see the "CCT virtual machine" section below). The virtual machine can also be used on Mac OS X and Linux systems. The advantage of using the virtual machine is that all the dependencies are already installed.

Installation on Mac OS X

Install Xcode

Use Finder or Spotlight to determine whether the Xcode application is already installed on your system. If Xcode has not been installed and you are using Mac OS X Snow Leopard, install Xcode from the Mac OS X install DVD (insert the DVD and choose Optional Installs and run the Xcode installer). If Xcode has not been installed and you are using MacOS X Lion or newer, install Xcode through the Mac App Store (open the Mac App Store, search for Xcode, and install the application). If you are installing Xcode version 4.1 or newer, ensure that the command-line tools are installed by doing the following: after Xcode installation is complete, search for Xcode using the Finder or Spotlight and click on the Xcode icon to launch Xcode. Choose Xcode->Preferences ... from the menu bar, click on the Downloads icon to open the Downloads preferences panel. Within this panel click the Components tab and select the Command Line Tools option and install it using the Check and Install Now button. For MacOS X Mavericks and later, the Downloads pane of Xcode Preferences does not support downloading command-line tools; therefore follow the instructions provided on this technical note page on Apple's website.

For more information about Xcode including download links and frequently asked questions visit the support page on Apple's website.

The following CCT installation steps have been tested for Mac OS X 10.6.8 (Snow Leopard) with Xcode 3.2.6, for Mac OS X 10.7.3 (Lion) with Xcode 4.1 and for Mac OS X 10.11.6 (El Capitan) with Xcode 8.2.1.

Download CCT

  1. Download the CCT package and unzip the file.

  2. Place the cgview_comparison_tool folder in a convenient location such as your home directory. Keep note of the location as it will be required when setting up your environment.

Install Homebrew

Homebrew is a convenient way to install UNIX tools on Mac OS X systems. While Homebrew will be the method described here to install the required tools for CCT, it should also be possible to use other package management systems like MacPorts and Fink. Detailed instructions on how to install Homebrew can be found in this page but you should only need the following instruction to install it.

To install Homebrew, launch the Terminal application (located in the /Applications/Utilities folder) and enter the following:

  /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Install ImageMagick

Enter the following command in the terminal:

  brew install imagemagick

ImageMagick installation may take a while to complete.

Install Perl modules used by CCT

  1. In the terminal enter the following:

    sudo perl -MCPAN -e shell

    If you have not yet configured CPAN you will be prompted to do so.

  2. Enter the following configuration commands to automatically install module prerequisites:

    o conf prerequisites_policy follow
    o conf commit
  3. Install the required modules by entering these commands in the CPAN shell:

    install Error
    install LWP::UserAgent
    install LWP::Protocol::https
    install Tie::IxHash
    exit

Install BLAST

  1. Download legacy BLAST (blast-2.2.26-universal-macosx.tar.gz for example) from the NCBI website.

  2. In the terminal, change into the directory that the BLAST archive was downloaded into and enter the following to extract the files:

    tar xvzf blast-2.2.26-universal-macosx.tar.gz

    Note: change the command as required to match the version of BLAST downloaded.

  3. Depending where the BLAST files were downloaded, you may want want to place them in a more convenient location. For example, to copy them to your home directory, the following command could be used:

    mv blast-2.2.26 ~

    Note the location of the BLAST files, as it will be required when setting up your environment.

Install wget

Some CCT scripts use wget to retrieve information. Install wget with Homebrew:

brew install wget

Install EMBOSS

  1. Download EMBOSS (EMBOSS-6.6.0.tar.gz for example) from the EMBOSS website into a convenient location such as your home directory.

  2. Launch the Terminal application (located in the /Applications/Utilities folder) and enter the following from the directory where EMBOSS was downloaded to:

    tar zxvf EMBOSS-6.6.0.tar.gz
    cd EMBOSS-6.6.0
    ./configure
    make
    make check
    sudo make install

Set up your environment

  1. In order to run properly, CCT requires some environmental variables to be set. The easiest way to do this is to edit your bash config file (~/.bash_profile or ~/.bashrc). To open the config file, enter the following in the terminal:

    open ~/.bash_profile
  2. Add the following lines to the end of the config file, changing /path/to/cgview_comparison_tool and /path/to/blast-2.2.26/bin to the full path to the cgview_comparison_tool and BLAST directories.

    export CCT_HOME="/path/to/cgview_comparison_tool"
    export PATH="$PATH":"${CCT_HOME}/scripts":/path/to/blast-2.2.26/bin
    export PERL5LIB="${CCT_HOME}"/lib/bioperl-1.2.3:"${CCT_HOME}"/lib/perl_modules:"$PERL5LIB"
  3. Save the file. Now the environment will be set the next time a terminal window is opened. To load the changes in an already open terminal enter this command:

    source ~/.bash_profile

Test your setup

Launch the Terminal application and switch into the cgview_comparison_tool directory and run the following:

  cd /path/to/cgview_comparison_tool
  ./update_cogs.sh
  ./test.sh

If the script is working you should see various progress messages as test maps are created. To stop the process, press Control-C.



Installation on Linux

The following installation was performed on Ubuntu. Change them as needed for your distribution.

Download CCT

  1. Download the CCT package and unzip the file.

  2. Place the cgview_comparison_tool folder in a convenient location such as your home directory. Keep note of the location as it will be required when setting up your environment.

Install Perl modules used by CCT

  1. Launch the Terminal application (location may vary depending on your linux distribution) and enter the following:

    sudo perl -MCPAN -e shell

    If you have not yet configured CPAN you will be prompted to do so.

  2. Enter the following configuration commands to automatically install module prerequisites:

    o conf prerequisites_policy follow
    o conf commit
  3. Install the required modules by entering these commands in the CPAN shell:

    install Error
    install LWP::UserAgent
    install LWP::Protocol::https
    install Tie::IxHash
    exit

Install BLAST

  1. Download legacy BLAST (blast-2.2.26-x64-linux.tar.gz for example) from the NCBI website.

  2. In the terminal, change into the directory that the BLAST archive was downloaded into and enter the following to extract the files:

    tar xvzf blast-2.2.26-x64-linux.tar.gz

    Note: change the command as required to match the version of BLAST downloaded.

  3. Depending where the BLAST files were downloaded, you may want want to place them in a more convenient location. For example, to copy them to your home directory, the following command could be used:

    mv blast-2.2.26 ~

    Note the location of the BLAST files, as it will be required when setting up your environment.

Install Java

To install the Java Runtime Environment (JRE), use the version packaged with Ubuntu. In the terminal enter the following from your home directory:

  sudo apt-get update
  sudo apt-get install default-jre

Install EMBOSS

  1. Download EMBOSS (EMBOSS-6.6.0.tar.gz for example) from the EMBOSS website into a convenient location such as your home directory.

  2. Open a Bash terminal and enter the following from the directory where EMBOSS was downloaded to:

    tar xvzf EMBOSS-6.6.0.tar.gz
    cd EMBOSS-6.6.0
    ./configure
    [Note: If you get an error that "X11 graphics have been selected but no X11 header files have been found", then run the command: sudo apt install libx11-dev followed by ./configure again.]
    make
    sudo ldconfig
    sudo make install

Install ImageMagick

Installation for Ubuntu

In the terminal enter the following:

  sudo apt-get install imagemagick

Installation for other Linux distributions

Check the ImageMagick website. If your distribution is listed, download the ImageMagick binary release and follow their provided instructions. Otherwise, you need to install it from source.

Installation from source
  1. First install the PNG reference library:

    sudo apt-get install libpng12-0
    sudo apt-get install libpng12-dev

    The above command will verify and install these two libraries if needed.

  2. Download the ImageMagick source code. A summary of the commands to install ImageMagick from source are shown below. A detailed explanation of each step is available on the ImageMagick website: Install from Unix Source

    cd ~
    tar -xvzf ImageMagick.tar.gz
    cd ImageMagick-7.0.6-1
    ./configure
    make
    sudo make install
    sudo ldconfig /usr/local/lib

Install Geeqie

You can install Geeqie to visualize the images produced by CCT.

In the terminal enter the following:

  sudo apt-get install geeqie

Set up your environment

  1. In order to run properly, CCT requires some environmental variables to be set. The easiest way to do this is to edit your bash config file (~/.bashrc). To open the config file, enter the following in the terminal:

    gedit ~/.bashrc
  2. Add the following lines to the end of the config file, changing /path/to/cgview_comparison_tool and /path/to/blast-2.2.26/bin to the full path to the cgview_comparison_tool and BLAST directories.

    export CCT_HOME="/path/to/cgview_comparison_tool"
    export PATH="$PATH":"${CCT_HOME}/scripts":/path/to/blast-2.2.26/bin
    export PERL5LIB="${CCT_HOME}"/lib/bioperl-1.2.3:"${CCT_HOME}"/lib/perl_modules:"$PERL5LIB"
  3. Save the file. Now the environment will be set the next time a terminal window is opened. To load the changes in an already opened terminal enter this command:

    source ~/.bashrc

Test your setup

Launch the Terminal application and switch into the cgview_comparison_tool directory and run the following:

  cd /path/to/cgview_comparison_tool
  ./update_cogs.sh
  ./test.sh

If the script is working you should see various progress messages as test maps are created. To stop the process, press Control-C.



CCT virtual machine

An alternative to downloading and installing the CCT prerequisites is to use a CCT virtual machine consisting of a Linux operating system with all the dependencies preinstalled. The CCT virtual machine runs in VirtualBox, which is freely available for Windows, Linux, Macintosh, and Solaris hosts.

Depending on the virtualization product used to run the machine you may be able to drag and drop files from your host OS to the virtual machine. If this feature does not work you can easily transfer files using a USB drive.

The CCT virtual machine has the following user account:

  user: ubuntu
  password: pw2016#

Numerous programs are included with this machine, including emacs and vim for viewing and editing text files, and xpdf for viewing pdf files.

Install VirtualBox Software

Before downloading the VirtualBox virtual machine, install the VirtualBox software on your computer. VirtualBox is available from http://www.virtualbox.org. You may also need to install the "VirtualBox Extension Pack".

Download the CCT virtual machine:

Download the virtual machine from here.

Run the virtual machine:

  1. Launch VirtualBox and choose Import Appliance from the File menu.

  2. In the Appliance Import Wizard that opens use the Choose button to select the ubuntu-bioVM.ova file that was downloaded.

  3. Click Continue to view the virtual machine settings and click Done/Import to begin importing the virtual machine. This step may take a while to complete depending on your host.

  4. Select the newly imported virtual machine in the VM VirtualBox Manager and click Start.

  5. Log in to the virtual machine as user 'ubuntu' using the password 'pw2016#'.

Update CCT and test your setup:

  1. Open the Terminal application by clicking on the Terminal icon, or by choosing Applications->Accessories->Terminal.

  2. Download and extract the latest version of CCT, and prepare the COG files used for COG assignment by entering the following in the terminal from the home directory:

    ./setup_CCT.sh
  3. Navigate to the cgview_comparison_tool directory and run the test.sh script:

    cd cgview_comparison_tool
    ./test.sh

If the script is working you should see various progress messages as the maps are generated. To stop the test script, press Control-C.

Network troubleshooting

In case the scripts above in the Update CCT and test your setup section can't be executed, a network issue may be the cause. Please, try to solve these issues using the steps below.

  1. Verify that your host OS has access to the internet and can access using a web browser or ping some internet addresses like the following:

    • www.google.com
    • www.amazon.com
    • stothard.afns.ualberta.ca
  2. Do the same now inside the virtual machine.

  3. If some of the the addresses above cannot respond, check your firewall settings to see if your firewall is blocking in some way your access to sites located outside of your institution. You may need to talk to your Network Administrator.

  4. In the VirtualBox Manager, select the virtual machine and click on the Settings icon in the toolbar. In the pop-up window that appears select Network. Verify that 'Enable Network Adapter' option is checked and 'Attached to:' combobox is set to NAT.

  5. If problems persist, virtualbox.org forums provide specific answers for network problems for a variety of host operating systems, including Windows, Linux and Mac OS X. In addition, there is a Troubleshooting section in the VirtualBox manual.

  6. You can also contact us by email. Please include your host OS information and the results you have obtained using the steps above.