User Manual Group

User Manual: Pdf

Open the PDF directly: View PDF .
Page Count: 8

Download
Open PDF In Browser	View PDF

User manual: Group 3
Dhevan Lau (1433596)
Kenan Karavoussanos (1348582)
Aimee Handley (1354032)
13/05/2018

1

Introduction

This User Manual serves as a basic guide in the installing, running and understanding of ReGenesis
functionality. The Technical Manual gives an overview of the general design and design of key classes.

Git repository
The Git repository for our project is located at https://github.com/KenanKarav/ReGenesis

2

User manual

2.1

Installing

The following packages need to be downloaded and installed:
1. matplotlib
2. wxPython
3. enum
These packages can easily be downloaded and installed using pip. It is assumed that python 3 has
already been installed onto your machine.
2.1.1

Windows Installation

Open terminal and change your directory to where pip3.exe has been installed. Once in that directory
type in the following commands to install each of the packages:
• pip3 install matplotlib
• pip3 install wxPython
• pip3 install enum

1

2.1.2

Mac Installation

Open terminal and type in the following command cd /usr/local/bin/ and hit Enter:
Then enter following commands:
• python3.6 -m pip install matplotlib
• python3.6 -m install wxPython
• python3.6 -m install enum
2.1.3

Linux Installation

Open terminal in any directory and enter the following commands:
• pip3 install matplotlib
• pip3 install enum
The installation process for wxPython is more complex.
1. Go to http://wxpython.org/Phoenix/snapshot-builds/ and download the latest .tar.gz
2. Untar the tarball : tar -xvzf downloaded-tar-file-name
3. Cd into the new directory
4. Read the readme and take note of the Linux section which tells you what dependencies you
need to install for the version.
5. Install : sudo python setup.py install

2.2

Running

Open terminal and change your directory to the downloaded ReGenesis folder. Within that directory
enter the following command to run the ReGenesis program:
py graphManager.py

2.3

Known Bugs

2.4

User Interface Structure

When ReGenesis runs, a window appears. This window is not re-sizeable. A menu bar is shown at
the top of the window and a toolbar is shown at the bottom.
The menu items are:
• New Graph: shows the sub-menu items PCA Graph and Admixture Graph which will allow
the plotting of a PCA Graph and an Admixture Graph respectively.
• Manage Graphs: shows the sub-menu items Save, Load and Export which allow the saving,
loading and exporting of graph files.
2

The toolbar buttons are:
• Reset: resets the graph display to it’s original position before any panning or zooming occured.
• Undo: the last panning or zooming change made to the graph display is undone.
• Redo: the last undone panning or zooming change made to the graph display is redone.
• Pan: enables panning functionality by clicking the left mouse button in the graph display area
and dragging the mouse.
• Zoom: enables zooming functionality by clicking the left or right mouse button in the graph
display area and dragging the mouse. The left mouse button allows zooming in and the right
mouse button allows zooming out.
• Edit Appearance: shows a window for editing the appearance of the graph (see Appearance
Options subsection).
• Save: allows the saving of the state of the graph being shown in the display area.
• Load: allows the loading of a previously saved graph state.
• Export: allows the exporting of a graph as a .png, .pdf, etc.

2.5
2.5.1

Structure Plots
Input Data Format

ReGenesis requires two mandatory input files: Admixture(.Q.) and Fam(.fam). A third phenotype file
(.pheno) is optional but recommended.
2.5.2

Inputting Data

To input the files for creating a structure plot, click New Graph then Admixture Graph. This will bring
up the Admix Creator GUI. Clicking on a Browse button will bring up GUI for navigating to find the
respective file. The first file that needs to be imported is the admixture file. After clicking Browse
and choosing the correct file, the Browse button to import the fam file will become available. The
option to import a phenotype file will only become available after both the admixture file and fam file
have been selected. If a phenotype file is selected, the column representing the phenotype data can be
selected by choosing one of the drop-down options.
To draw the graph, the Confirm button must be clicked. The Reset button will reset the Admix
Creator form and the Cancel button will close the window.
2.5.3

Appearance Options

Appearance editing functionality will be added in a future release.

3

2.6

PCA Plots

2.6.1

Input Data Format

ReGenesis requires one mandatory input file and one optional file to draw a PCA plot. The compulsory
input file is a PCA file in the eigenstrat format(.evec) and the optional but recommended file is a
phenotype file (.phe).
2.6.2

Inputting Data

To input the files for creating a PCA plot, click New Graph then PCA Graph. This will bring up the
PCA Creator GUI. Clicking on a Browse button will bring up GUI for navigating to find the respective
file. The first file that needs to be imported is the PCA file. After clicking Browse and choosing the
correct file, the Browse button to import the optional phenotype file will become available as well
as the drop down boxes for selecting the PCA columns. If a phenotype file is selected, the column
representing the phenotype data (grouping) can be selected by choosing one of the drop-down options.
To draw the graph, the Confirm button must be clicked. The Reset button will reset the PCA
Creator form and the Cancel button will close the window.
2.6.3

Appearance Options

Click the Edit Appearance button in the toolbar to access the general and group appearance settings
of the current PCA graph open.
General Appearance:
• Heading: To set or change the heading type the heading into the text box that says ”Title”.
• Grid: To show/hide the grid (un)check the relevant checkbox.
• Axes Labels: To show/hide the axes Labels (un)check the relevant checkbox.
Group Appearance:
• Group Name: To choose the group currently being edited, click the drop down box labelled
”group name” and make a selection.
• Group Colour: To change the colour of the current group, click on the colour box labelled ”Set
group colour” and select a colour. Click the OK button once you are satisfied with your colour
selection.
• Group Shape: To change the shape of the current group, click the drop down box labelled ”Set
group shape” and make a selection.
• Group Size: To change the size of the current group, type a value into the text box or use the
arrows to count to your desired value. Note that the maximum value is 36 and the minimum
value is 2.
Once you are satisfied with all changes made, clicking the Accept Changes button will make all
changes visible on the graph. Clicking the Cancel button will close the window.

4

2.7
2.7.1

File Management
Saving a Project

To save a project currently in use, click the Manage Graphs menu item and then the Save sub-menu
item. The Save option in the toolbar can also be clicked. Enter a filename and navigate to the location
you wish to save the file and click Save.
2.7.2

Loading a Project

To load a project previously saved, click the Manage Graphs menu item and then the Load sub-menu
item. The Load option in the toolbar can also be clicked. Navigate to and select the file you wish to
load and click Load.
2.7.3

Exporting Graphs

To export the graph as an image file(.png), PDF, etc. click the Manage Graphs menu item and then
the Export sub-menu item. The Export option in the toolbar can also be clicked. From the dialog that
opens, select the filetype you wish to export the graph as (PNG, PDF, SVG, etc.), then navigate to the
location you wish to save the file and click OK.

5

3

Technical Manual

3.1

Design Overview

3.1.1

Directory Structure

At the root level ReGenesis is split into the main script, graphManager.py, and three top level directories:
1. fileManagement
2. graphDrawing
3. Testing Suite
fileManagement is responsible for the importing and formatting of input files.
graphDrawing is responsible for graph creation and appearance editing.
Testing Suite is responsible for running the ReGenesis unit tests.
3.1.2

Class Structure

Architecture ReGenesis in general follows the MVC architecture. Certain classes are not totally
strict with the separation into a Model, View or Controller due to simplifying the design of the system.
A Model class in ReGenesis communicates with no other classes other than its corresponding
controller and its functionality is limited to formatting and structuring of the data stored within it.
A View class in ReGenesis communicates exclusively with its corresponding controller and its
functionality is limited to presenting data passed to it in a specific manner.
A Controller class in ReGenesis communicates and coordinates Model, View and other Controller
classes. It receives user input and converts it into commands for it controlled classes. It passes data
from Model to View classes.
Composition over Inheritance ReGenesis makes use of composition of classes as opposed to inheritance, this is due to enhanced modularity of the design and increases design flexibility.
Model Classes
• File
• pcaGraph
• admixGraph
View Classes
• graphManager

6

Controller Classes
• fileImporter
• pcaCreator
• admixCreator
• graphManager
• pcaAppearance
3.1.3

3.2

Functionality Overview

Design of Key Classes

This section describes the purpose and functionality of all the key classes implemented in the current
version of ReGenesis.
3.2.1

Class Diagram

Figure 1: ReGenesis Class Diagram

3.2.2

File

This class is responsible for storing data and metadata of a file including the file type and file name.

7

3.2.3

pcaGraph

This class is responsible for storing individuals, their coordinates and their groups for the PCA plot.
It also stores appearance settings for the graph.
3.2.4

admixGraph

This class is responsible for storing individuals, their ancestral proportions and their population groups
for the structure plot.
3.2.5

graphManager

This class is the central controller for ReGenesis. It controls all other classes directly or indirectly via
the other controller classes. This class also acts as the view for ReGenesis. This violates the MVC
architecture, however this choice was made as all of the view functionality is implemented using
external libraries. As such, it was deemed that separating this class into two would unnecessarily
complicate the design and increase the time cost of the project.
3.2.6

pcaCreator

This class provides an interface for the importing of the files required for a PCA plot. This class also
controls the fileImporter.
3.2.7

admixCreator

This class provides an interface for the importing of the files required for a structure plot. This class
also controls the fileImporter.
3.2.8

fileImporter

This class is responsible for interfacing with the file system as well as generating a File object for the
parent Creator object.
3.2.9

pcaAppearance

This class provides an interface for the user to edit the appearance of a pcaGraph object. Currently
the user can change the colour, shape and size of each group of individuals. The user can also set a
title and choose whether to show grid-lines and axis-labels.

8



---

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.5
Linearized                      : No
Page Count                      : 8
Producer                        : pdfTeX-1.40.17
Creator                         : TeX
Create Date                     : 2018:05:14 01:30:51Z
Modify Date                     : 2018:05:14 01:30:51Z
Trapped                         : False
PTEX Fullbanner                 : This is pdfTeX, Version 3.14159265-2.6-1.40.17 (TeX Live 2016/Debian) kpathsea version 6.2.2

EXIF Metadata provided by EXIF.tools