*CirGO (Circular Gene Ontology) Version 1.0 01/03/2018
© Copyright (C) 2018
Irina Kuznetsova, [email protected]
https://github.com/IrinaVKuznetsova/CirGO.git

This manual was designed to help people with limited or no programming experience to install the CirGO software.

Description: CirGO (Circular Gene Ontology) is an alternative way of visualising GO terms in 2D space that is suitable for publishing and presenting gene expression Ontology data.

Dependencies: The software package was developed under Python 2.7 with specific versions of NumPy 1.13.1, and Matplotlib 2.1.0. CirGO software can be run on Windows, Unix\Linux, or Mac OS. There are two folders that contains scripts requires for running the CirGO software on:

• Windows and Unix
• Mac OS contains own scripts.

Software architecture:
CirGO can be run on Windows, Unix/Linux and Mac OS as:
      (1) Graphical User Interface (GUI)
      (2) Command Line (CMD)
      (3) Interactive Command Line (INT)

Briefly, CirGO visualisation algorithm consists of three steps that are described at the Supplementary Material of the X publication:
      (1) Formatting of the csv input file obtained from the TreeMap tab on REVIGIO page.
      (2) Values calculation
      (3) GO visualisation as two-layer full hierarchies.

Note: four header lines are omitted.

Note: there is no header.

1. Download Anaconda distribution also called Anaconda Prompt for Python 2.7 on your Windows machine.

2. Open Anaconda Prompt terminal.

3. Create a virtual environment. Virtual environment acts as an isolated platform where you can install all required packages for the specific project without modifying existing projects. For example, if your computer has Python 2.7, you can easily install Python 3+ without affecting Python 2+.
         Example (Create a new environment ): > conda create --name SelectEnvirName

4. Activate created virtual environment.
         Example (Activate created environment): > activate SelectEnvirName
         Example (Check installed packages. Note: Empty environment has no installed packages): (SelectEnvirName)> conda list
         Example (Install pip, which is package manager, and enables installation of required software): (SelectEnvirName)> conda install pip

--------------------------NOTE-----------------------------

If conda install pip command offers Python3.7+, reply n to the proceed question, deactivate and delete just created environment and run conda create -n SelectEnvirName python=2.7 command. More details at conda documentation page.

      Example (Deactivate created environment): conda deactivate
      Example (Delete created environment): conda env remove --name SelectEnvirName
      Example (Install a new environment with Python2.7+): conda create -n SelectEnvirName python=2.7
      Example (Activate created environment): activate SelectEnvirName
      Example (Check installed Python version): conda list

--------------------------NOTE-----------------------------

      Example (Check installed packages): (SelectEnvirName)> conda list

1. Download the CirGO software from GitHub repository as zip folder (Clone or Download; Download ZIP). Unzip folder into a directory of your choice. For example, to the desktop.

2. Navigate Anaconda Prompt terminal to the setup.py script of the CirGO software, which is located at the docs folder.       Example (Navigate to docs folder): (SelectEnvirName)> cd YOURPATH\CirGO-master\docs

3. Create a source distribution for CirGO package. This step generates two folders CirGO.egg-info and dist.
         Example (Create a source distribution) : (SelectEnvirName)> python setup.py sdist

4. Navigate to the dist folder and install CirGO package.
         Example (Navigate to a folder):(SelectEnvirName)> cd dist
         Example (Install CirGO package);(SelectEnvirName)> pip install CirGO-0.1.0.tar.gz

5. Navigate to the CirGO_Wind_Unix folder.
         Example (Navigate to the CirGO_Wind_Unix folder):(SelectEnvirName)> cd YOURPATH\CirGO-master\CirGO_Wind

      Example (Help page):(SelectEnvirName)> python CirGO.py –h

There are three options on CirGO usage:
      (1) Graphical User Interface (GUI);
      (2) Command Line (CMD);
      (3) Interactive Command Line (INT).

Graphical User Interface (GUI) is the simplest option for visualising GO terms. When the command python CirGO.py -gui is executed an interactive window will pop-up. The required parameters can be changed or left as default, an input file can be opened with the Open File button, and visualised by pressing Visualize button. The output file will be automatically saved in svg format to the same folder with the input file, or the output file name can be changed by pressing Save output as SVG button. Please note, that the legend name should be changed depending on what process (biological process, cellular component, or molecular function) is visualised. To leave GUI press Exit.
      Example (Graphical user interface):(SelectEnvirName)> python CirGO.py –gui

Command Line (CMD) requires a user to provide parameters in the command line space as described at the help page:
      Example (Help page): (SelectEnvirName)> python CirGO.py -h
 
CirGO - inputFile INPUTFILE [-outputFile OUTPUTFILE] [-fontSize FONTSIZE] [-numCat NRCATEGORIES] [-leg FIGURE_LEGEND]
 
      Example: (SelectEnvirName)> python CirGO.py -inputFile Example_REVIGO_Input_BP.csv -outputFile Visual_BP.svg -fontSize 6.5 -numCat 40 -legend "Name & Proportion of Biological process (inner ring)"

Interactive (INT) command line option enables to run the CirGO software in the interactive mode.
      Example (Interactive command line (INT)):(SelectEnvirName)> python CirGO.py -int
CirGO [-int]
      Parameters:
            inputFile: [file name]
                        Input path and filename of an REVIGO file. NOTE, provide a file directory as a string, where PATH backslashes '\' have to be changed to forward slashes '/'.
            outputFile: [file name]
                        Output path and filename in svg format. NOTE, provide a file directory as a string, where PATH backslashes '\' have to be changed to forward slashes '/'.
            fontSize: [float]
                        A positive float value (Example: 7.0). It is advised to select one from 6.0 -7.0.
            numCat: [int]
                        A positive integer value of categories to be visualised (Example: 40).
            legend: [str]
                        Legend title to be displayed in the figure. A string (Example: Name & Proportion of Biological process (inner ring)). Select relevant example of the legend name:
                        (1) Name & Proportion of Biological process (inner ring)
                        (2) Name & Proportion of Cellular component (inner ring)
                        (3 )Name & Proportion of Molecular function (inner ring)

Version control:
       Tested on Windows 7 Professional / Windows 10
       Conda 4.3.25
       Python 2.7
       NumPy 1.13.1
       Matplotlib 2.1.0
       Seaborn 0.8.1

1. Open Unix terminal

2. Install virtualenv tool on your Unix terminal if you have not installed already. This tool allows to create isolated Python environment.
         Example (Install virtual environment): $ pip install virtualenv

3. Also install pip tool if you have not installed yet. Pip designed for managing software written in Python. A good introduction on how to setup virtual environment, and install required modules can be found at the blog.
         Example (Install pip): $ sudo apt-get install python-pip

4. Create a virtual environment. Virtual environment acts as an isolated platform where you can install all required packages for the specific project without modifying existing projects. For example, if your computer has Python 2.7, you can easily install Python 3+ without affecting Python 2+.
         Example (Create a new environment ): $ virtualenv SelectEnvirName

5. Activate created virtual environment.
         Example (Create a new environment ): $ source SelectEnvirName/bin/activate

6. Download the CirGO software from GitHub repository as zip folder (Clone or Download; Download ZIP). Unzip folder into a directory of your choice. For example, to the desktop.

7. Navigate Unix/Linux terminal to the setup.py script of the CirGO software, which is located at the docs folder.
         Example (Navigate to docs folder): (SelectEnvirName)$ cd YOURPATH\CirGO-master\docs

8. Create a source distribution for the CirGO package. This step generates two folders CirGO.egg-info and dist.
         Example (Create a source distribution) : (SelectEnvirName)$ python setup.py sdist

9. Navigate to the dist folder and install CirGO package.
         Example (Navigate to the dist folder):(SelectEnvirName)$ cd dist
         Example (Install CirGO package);(SelectEnvirName)$ pip install CirGO-0.1.0.tar.gz

10. Navigate to the CirGO_Wind_Unix folder.
          Example (Navigate to the CirGO_Wind_Unix folder):(SelectEnvirName)$ cd YOURPATH\CirGO-master\CirGO_Unix

      Example (Help page):(SelectEnvirName)> python CirGO.py –h

There are three options on CirGO usage:

      (1) Graphical User Interface (GUI);
      (2) Command Line (CMD);
      (3) Interactive Command Line (INT).

Graphical User Interface (GUI) is the simplest option for visualising GO terms. When the command python CirGO.py -gui is executed an interactive window will pop-up. The required parameters can be changed or left as default, an input file can be opened with the Open File button, and visualised by pressing Visualize button. The output file will be automatically saved in svg format to the same folder with the input file, or the output file name can be changed by pressing Save output as SVG button. Please note, that the legend name should be changed depending on what process (biological process, cellular component, or molecular function) is visualised. To leave GUI press Exit.  
      Example (Graphical user interface):(SelectEnvirName)$ python CirGO.py –gui

Command Line (CMD) requires a user to provide parameters in the command line space as described at the help page:
      Example (Help page): (SelectEnvirName)$ python CirGO.py -h
 
CirGO - inputFile INPUTFILE [-outputFile OUTPUTFILE] [-fontSize FONTSIZE] [-numCat NRCATEGORIES] [-leg FIGURE_LEGEND]

        Example: (SelectEnvirName)$ python CirGO.py -inputFile Example_REVIGO_Input_BP.csv -outputFile Visual_BP.svg -fontSize 6.5 -numCat 40 -legend "Name & Proportion of Biological process (inner ring)"

Interactive (INT) command line option enables to run the CirGO software in the interactive mode.
      Example (Interactive command line (INT)):(SelectEnvirName)$ python CirGO.py -int  
CirGO [-int]
      Parameters:
            inputFile: [file name]
                        Input path and filename of an REVIGO file.
            outputFile: [file name]
                        Output path and filename in svg format.
            fontSize: [float]
                        A positive float value (Example: 7.0). It is advised to select one from 6.0 -7.0.
            numCat: [int]
                        A positive integer value of categories to be visualised (Example: 40).
            legend: [str]
                        Legend title to be displayed in the figure. A string (Example: Name & Proportion of Biological process (inner ring)). Select relevant example of the legend name:
                        (1) Name & Proportion of Biological process (inner ring)
                        (2) Name & Proportion of Cellular component (inner ring)
                        (3 )Name & Proportion of Molecular function (inner ring)

Version control:
       Tested on Windows 7 Professional / Windows 10
       Conda 4.3.25
       Python 2.7
       NumPy 1.13.1
       Matplotlib 2.1.0
       Seaborn 0.8.1

1. Open Mac terminal.

2. Install xcode-select utility on your Mac OS if you have not installed already. This utilities enables usage of common Unix-based tools.
         Example (Install xcode-select utility): $ xcode-select --install

3. Install Homebrew, which is free open source software package, if you have not installed already. It facilitates software installation on Mac OS. Note: please always check the command from the Homebrew website, as it frequently modified.
         Example (Install Homebrew): $ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

4. Check Python version. Python 2+ is required version for the CirGO software. Note: Python 2.7 generally comes with Mac OS.
         Example (Check Python version): $ python --version

5. Create a virtual environment. Virtual environment acts as an isolated platform where you can install all required packages for the specific project without modifying existing projects. For example, if your computer has Python 2.7, you can easily install Python 3+ without affecting Python 2+.
         Example (Create virtual environment) $ virtualenv -p /usr/bin/python2.7 SelectEnvirName

6. Activate created virtual environment.
         Example (Activate virtual environment): $ source SelectEnvirName/bin/activate

7. Install the latest pip version.
         Example (Install the latest pip): (SelectEnvirName)$ curl https://bootstrap.pypa.io/get-pip.py | python

8. Download the CirGO software from GitHub repository as zip folder (Clone or Download; Download ZIP). Unzip folder into a directory of your choice. For example, to the desktop.

9. Navigate Mac terminal to the setup.py script of the CirGO software, which is located at the docs folder.
         Example (Navigate to docs folder): (SelectEnvirName)$ cd YOURPATH\CirGO-master\docs

10. Create a source distribution for the CirGO package. This step generates two folders CirGO.egg-info and dist.
          Example (Create a source distribution) : (SelectEnvirName)$ python setup.py sdist

11. Navigate to the dist folder and install CirGO package.
          Example (Navigate to the dist folder):(SelectEnvirName)$ cd dist
          Example (Install CirGO package):(SelectEnvirName)$ pip install CirGO-0.1.0.tar.gz

12. Navigate to the CirGO_Mac folder.
          Example (Navigate to the CirGO_Mac folder):(SelectEnvirName)$ cd YOURPATH\CirGO-master\CirGO_Mac

      Example (Help page):(SelectEnvirName)> python CirGO.py –h

There are three options on the CirGO usage:
      (1) Graphical User Interface (GUI);
      (2) Command Line (CMD);
      (3) Interactive Command Line (INT).

Graphical User Interface (GUI) is the simplest option for visualising GO terms. When the command python CirGO.py -gui is executed an interactive window will pop-up. The required parameters can be changed or left as default, an input file can be opened with the Open File button, and visualised by pressing Visualize button. The output file will be automatically saved in svg format to the same folder with the input file, or the output file name can be changed by pressing Save output as SVG button. Please note, that the legend name should be changed depending on what process (biological process, cellular component, or molecular function) is visualised. To leave GUI press Exit.  
      Example (Graphical user interface):(SelectEnvirName)$ python CirGO.py –gui

Command Line (CMD) requires a user to provide parameters in the command line space as described at the help page:
      Example (Help page): (SelectEnvirName)$ python CirGO.py -h
 
CirGO - inputFile INPUTFILE [-outputFile OUTPUTFILE] [-fontSize FONTSIZE] [-numCat NRCATEGORIES] [-leg FIGURE_LEGEND]
 
      Example: (SelectEnvirName)$ python CirGO.py -inputFile Example_REVIGO_Input_BP.csv -outputFile Visual_BP.svg -fontSize 6.5 -numCat 40 -legend "Name & Proportion of Biological process (inner ring)"

Interactive (INT) command line option enables to run the CirGO software in the interactive mode.
      Example (Interactive command line (INT)):(SelectEnvirName)$ python CirGO.py -int  
CirGO [-int]
      Parameters:
            inputFile: [file name]
                        Input path and filename of an REVIGO file.
            outputFile: [file name]
                        Output path and filename in svg format.
            fontSize: [float]
                        A positive float value (Example: 7.0). It is advised to select one from 6.0 -7.0.
            numCat: [int]
                        A positive integer value of categories to be visualised (Example: 40).
            legend: [str]
                        Legend title to be displayed in the figure. A string (Example: Name & Proportion of Biological process (inner ring)). Select relevant example of the legend name:
                        (1) Name & Proportion of Biological process (inner ring)
                        (2) Name & Proportion of Cellular component (inner ring)
                        (3 )Name & Proportion of Molecular function (inner ring)

Version control:
       Tested on Windows 7 Professional / Windows 10
       Conda 4.3.25
       Python 2.7
       NumPy 1.13.1
       Matplotlib 2.1.0        Seaborn 0.8.1

The example dataset was obtained from GSE83471.

This project is licensed under the terms of the GNU version 3 general public license.