2 Installing and Running Genesis

2.1 Installing Genesis

The latest code can be found at http://www.bioinf.wits.ac.za/software/genesis

Genesis does not special installation and the file can simply be executed using Java. It does, however, require the Java SE Runtime Environment 1.7 or higher to be installed on the user's system. The latest version of the Java SE Runtime Environment 1.7 can be found at: http://www.oracle.com/technetwork/java/javase/downloads/jre7-downloads-1880261.html

To check if you already have Java installed, you can open your Operating System's command line interface and enter

java -version

If Java is installed, one line of the response should read

Java(TM) SE Runtime Environment (build 1.x.0_*)

where x is the version number (and should be 7 or higher) and the * is not important.

Alternatively, Windows users can open Control Panel and then open Add/Remove Programs and check the list for Java SE Runtime Environment (in windows XP and earlier) or open Programs then Programs and Features and if Java x is in the list, then Java is installed where x is the version number (in Windows Vista, 7 or 8).

Mac OSX requires X11 to be installed. This can be downloaded from http://xquartz.macosforge.org/landing/.

Genesis is compatible with the 32 and 64 bit varieties of Windows, Mac OSX and Linux.

If you are using a version of Java other than Oracle's, you may need to install the SWT libraries separately. On Ubuntu, installing openjdk, the following should work

apt-get install jre-default

OR (but NOT both)

apt-get install  libswt-gtk-3-java  openjdk-7-jre-headless

2.2 Running Genesis

Windows and Linux If the Java SE Runtime Environment 1.7 is installed, the user should be able to open Genesis by double-clicking the file. If this does not work, the user will have to launch the jar manually through a command line editor (cmd in windows or terminal in linux) using the following command.

java -jar Genesis.jar

For Linux and MacOSX the recommended configuration is to unzip, cd into the genesis-distrib directory and then say

sudo mv Genesis.jar misc/genesis /usr/local/bin
sudo chmod a+x /usr/local/bin/genesis

and then, the program can be run by executing the command genesis

OS X: Ensure that the Java SE Runtime Environment 1.7 is installed. In OSX, the user must launch the file through the command line with an extra argument as follows

java -XstartOnFirstThread -jar Genesis.jar

Wrapper script A simple wrapper script genesis is provided to aid the use of the program which works for Linux or MacOS X. Installation of the JAR and wrapper can be done by running install.sh. By default, the script installs into /usr/local/bin. If you want it elsewhere, specify the directory name, e.g ./install.sh /Users/scott/bin. You may need sudo privileges.

Memory usage: If you are building up very complex charts (e.g, in a large study doing admixture charts for 6 or 7 values of K on the same Genesis chart), you may require extra memory when running Genesis.

java -Xmx2048m -Xms521m -jar Genesis.jar

2.3 Known bugs

• On MacOS X, when the program is first run the SWT menu does not appear on the menu bar. If you make another application active and then come back to Genesis, the menu appears. This appears to be a bug of SWT on MacOS X.
• Using some versions of SWT, occasionally when opening a previous project the program crashes with an obscure error message. Update your SWT to a later version. We try to package the latest available version with Genesis. (This appears to have gone away with the latest version of SWT).

2.4 Supported input data formats

For structure charts, Genesis supports the output of the admixture and CLUMPP programs. In addition, we provide a python script that will convert the output of the structure program into the appropriate input format. See See Creating Structure Plots.

For PCA charts, Genesis supports the output of the eigenstrat and plink programs and the SNPRelate R package. In addition, we provide Python scripts that will convert the output of the fastpca program into the appropriate format. See See Creating PCA Plots.

We shall try to add to the suite of conversion scripts, but we intend that future versions of Genesis will automatically detect the correct input format and deal appropriately.

2.5 Menu structure

When Genesis runs, a menu appears at the top. The menu items are File, Graph and Help. File allows creation and saving of graphs, and exporting image files. Graph allows changing data and appearance options. The manual is available under help.

For added usability the icons with the key menu features apper at the top of the Genesis window. If the cursor is placed over the icon, a brief description of the menu item is given. The menu items are briefly described below and the functions are described in detail in next sections.

From left to right, the menu items are:

• Admix: create a new Admixture chart
• PCA: create a new PCA chart
• Save Project: this saves the current charts being created in a Genesis format file, which incorporates all changes the user has made. This does not save images, but the internal state of the program for later reloading.
• Load Project: this loads a previously savied Genesis project. Note that the New Admix and PCA options are used to create charts from raw output of the admixture and PCA tools. The Load Project option loads previosly saved charts.
• Data Options: allows the user to provide constraints on the data files used. For example, the user can specify which column in the file contains the phenotype data, or which principal components should be displayed.
• Appearance Options: gives the user flexibility in determinig how what the charts look like. Examples are: size of margin, choice of font and size, headings and so on.
• Refresh.
• Show/Hide 3D Rotate Panel: if the user is showing a 3D PC chart, simple rotation is supported.
• Search for individual: the user can specify the ID of an individual in the study and that inviduals data is highlighed in the chart.
• Unhide: individuals or groups can be hidden from the display. This option allows unhiding.
• Line: Simple lines can be drawn
• Arrow: Simple arrows can be draw
• Export: The picture can be exported to a PNG, SVG, or PDF file.
• Close Project: The current chart is closed. If not previously saved, it is deleted.