Easyfig Manual

Version 2.1 (16 April 2012)

Mitchell J. Sullivan, Nicola K. Petty and Scott A. Beatson. (2011) Easyfig: a genome comparison visualiser. Bioinformatics; 27 (7):

1009-1010

http://easyfig.sourceforge.net/

2

Easyfig Easyfig is a Python application for creating linear comparison figures of multiple genomic loci with an easy-to-use graphical user interface (GUI). BLAST comparisons between multiple genomic regions, ranging from single genes to whole prokaryote chromosomes, can be generated, visualised and interactively coloured, enabling a rapid transition between analysis and the preparation of publication quality figures.

Installation Microsoft Windows: Download the latest version of Easyfig (currently Easyfig_win_2.1.zip). Extract contents to the desired location. From within the downloaded folder run Easyfig by double-clicking on the Easyfig_win_2.x.exe executable file; ensure that the folder has been fully extracted and that Easyfig_win_2.x.exe is being run from within the folder. On Windows Vista/7, the Easyfig folder may appear as an application rather than a folder: simply double-click the application to launch Easyfig (known to work on Windows Vista/7 and on PCs younger than 4 years old running Windows XP). Mac OS X: Download the latest version of Easyfig (currently Easyfig_mac_2.1.tar.gz) and double click on the download to extract contents. Double-click on the Easyfig_2.x application to run Easyfig (known to work on Mac OS X versions 10.5 and 10.6). Fedora/Ubuntu/Linux 64 bit: Download the latest version of Easyfig (currently Easyfig_linux_2.1.tar.gz). Extract contents to the desired location. From within the downloaded folder run Easyfig by double-clicking on the Easyfig_linux_2.x binary file; ensure that the folder has been fully extracted and that Easyfig_linux_2.x is being run from within the folder. There are some known issues running compiled versions of Python applications on Windows/Mac OS X. If Easyfig does not run using the above methods we recommend using the Linux/Unix/Windows cmd version. Linux/Unix/Windows cmd: Easyfig_2.x.py is executable from a terminal window in any Unix machine (including Mac OS X). Download the latest version of Easyfig (currently Easyfig_2.1.py) and save to desired location. Open a terminal window, navigate to the directory where you saved Easyfig and type 'python Easyfig_2.1.py' on the command line; this will launch the GUI. Alternatively, Easyfig_2.x.py can be run on Windows or Mac OS X by right-clicking and choosing open with Python or Python Launcher. Using this version of

3

Easyfig requires Python 2.5 or later to be installed. This is available at http://python.org. The graphical user interface library used by Easyfig (Tkinter) is not included with some distributions of Linux and Mac OS X. We recommend reinstalling Python 2.7 from the Python website as Tkinter is included in the standard library. Command-line version: Easyfig_CL_2.x.py is identical to Easyfig_2.x.py except that it does not launch the Easyfig GUI. BLAST and Figure-drawing parameters are set using command-line arguments. Running Easyfig_CL_2.x.py with no arguments will print to screen the available options for Easyfig.

Setting up Easyfig to automatically generate BLAST files: Easyfig can run using pre-computed BLAST comparison files, but it is also capable of generating BLAST comparisons if BLAST executables have been installed. Easyfig can automatically install BLAST executables. From the menu bar click 'Blast' and choose 'Download Blast Automatically'. This may take a while on slower connections as the download is large (> 50 MB). If BLAST installs correctly you will be presented with a message saying 'BLAST+ installed', you will now be able to automatically generate BLAST comparisons using the generate buttons. If an FTP connection cannot be created or the correct binaries for your system cannot be found you will be presented with a message asking you to download BLAST manually. To do so click 'Blast' in the menu bar and choose 'Download Blast Manually'. This will bring up a message box recommending a version of BLAST to download, clicking 'ok' will open the download page in your browser.

4

Organisation of this manual: Part 1: Tutorials We strongly recommend that all new users follow the examples below to familiarise themselves with Easyfig. Part 2: Features of Easyfig All options and screens available in Easyfig are described in detail. Part 3: Command-line options Options available using the command-line (non-graphical user interface) version of Easyfig

5

Part 1: Tutorials Please ensure that files are loaded in the order specified below. Words/characters in parentheses e.g. (open) refer to button labels Example files (Easyfig_example1_files.zip and Easyfig_example2_files.zip) can be downloaded from the SourceForge Easyfig download page at http://sourceforge.net/projects/easyfig/files/ Example 1. Simple genome region comparison In this example we will compare two ~50 Kb prophage regions from different Salmonella genomes. The files needed for this example are in Easyfig_example1_files. (available to download from http://sourceforge.net/projects/easyfig/files/) A: Comparison of two genomic regions. 1. Launch Easyfig. LOAD ANNOTATION FILES: 2. Click the Add feature file button immediately underneath the “Annotation files” box to navigate to the Easyfig_example1_files folder 3. Select the Newport_Gifsy.gbk file and click ( open ) 4. Click the Add feature file button again 5. Select the LT2_Gifsy.gbk file in the Easyfig_example1_files folder and click ( open ) LOAD BLAST COMPARISON FILE: 6. Click the Add blast file ( … ) immediately underneath “Blast files” box;; navigate to the Easyfig_example1_files folder and select: Newport_Gifsy1_v_LT2_Gifsy1.blastn.out SPECIFY OUTPUT FILE 7. Click ( Save as ), enter example1.bmp in the box and click ( Save )

6

CREATE FIGURE 8. Click ( Create Figure ). Easyfig progress will be displayed in the yellow dialog box. 9. Open the folder where you saved the Easyfig image and open it with your favourite image-viewer.

B: Invert the LT2 region to obtain a clearer comparison 1. Click Image on the menu bar and select Subregion 2. In the popup window, double-Click on the second file, select the “Reverse” radio button and click ( Save & Close ) 3. Close the Subregion window using (close) 4. CREATE FIGURE as described in part 1A.

C: Colour the coding-sequence (CDS) features 1. Click Image on the menu bar and select Annotation 2. Unclick the “gene” radio button under the “Include following features” section of the Annotation Window 3. Click the “CDS” radio button

7

4. (Optional) Add a scale by entering 5000 in the “Length of scale legend (in base pairs)” box found in the figure window accessible from Image dropdown menu. 5. CREATE FIGURE as described in part 1A.

Colours can be added to any feature from within Easyfig using a pop-up colour palette, or by adding a /colour feature qualifier to the annotation file (as has been done for these examples). The /colour qualifiers can be added using an annotation tool such as Artemis www.sanger.ac.uk/resources/software/artemis/, or by editing the annotation file in a text editor. Both Artemis colour codes (0-18) and standard RGB colour codes (/colour=255 0 0) are interpreted by Easyfig. In the example files loaded in parts A and B, the Artemis colour codes have been added to the CDS features e.g. CDS 4038..4265 /locus_tag="STM2585A" /note="similar to pagK" /codon_start=1 /transl_table=11 /product="PagK-like protein" /protein_id="NP_461521.1" /db_xref="GI:16765906" /db_xref="GeneID:1254108" /colour=10 By default, gene features are shown, which is why all the features are the same colour in exercise A and B.

8

D: Zoom in on a ~15kb subregion at one end of the sequences 1. Access the subregion window from the Image dropdown menu; click on file 01 and then enter 32599 and 50099 in the Min and Max “Range” boxes located directly under the list of annotation files 2. Click (change cutoffs) 3. Click on file 02 and then enter 1 and 15000 in the Min and Max “Range” boxes and click (change cutoffs) IMPORTANT: remember that the second Annotation file (LT2_Gifsy.gbk) has been inverted, this has been taken into account when entering the subregion range 4. Close the subregion window with (close) 5. Click on ( Generate blastn Files ) to generate the BLAST comparison files for these subregions (a pop-up box will ask you where you want to save the BLAST files – default is usually in the Easyfig_example1_files folder) 4. CREATE FIGURE as described in part 1A. In the new image, the scale is still 5000 bp, but the image is zoomed in on the variable region. The minimum BLAST identity value is shown in the yellow dialog box after each figure is drawn – this can be used to calibrate the BLAST identity scale shown on the right (i.e. in this case the matches range from 100% (darkest) to 85% (lightest)).

As described in the manual there are many ways to customise the image further e.g. the following list shows a few of the options available: - Feature rendering type from arrows to boxes or pointers - Colours of any of the features - Thickness of any lines - Height of BLAST matches - Height of features

9

- Width of figure - Type of image file (bmp is default, but svg [scalable vector graphics] files can be produced by changing the file type) - Add a feature legend or label the features

10

Example 2. Whole genome comparison Example files are contained in the Easyfig_example2_files folder (available to download from http://sourceforge.net/projects/easyfig/files/) In this example we are creating a comparison figure of three Escherichia coli genomes, O157:H7 EDL933, O157H7 Sakai and K12 MG1655. We want to illustrate the phage regions, but as these are not labeled uniquely in the original GenBank files we have added them manually using “phage” as a feature label. For example in the K12 file we add 12 lines, one for each phage: FEATURES Location/Qualifiers source 1..4639675 /organism="Escherichia coli K12" /mol_type="genomic DNA" /strain="K-12" /sub_strain="MG1655" /db_xref="taxon:83333" phage 262182..296489 phage 1195443..1210646 etc… The phage features have already been added to the files provided: EcSakai.withPhage.gbk, EcEDL933.withPhage.gbk, EcK12.withPhage.gbk. A. Comparison of three E. coli genomes 1. Launch Easyfig. (If continuing from Example 1, quit Easyfig before starting) 2. LOAD ANNOTATION FILES as described in part 1A, in this order: EcSakai.withPhage.gbk EcEDL933.withPhage.gbk EcK12.withPhage.gbk 3. LOAD BLAST COMPARISON FILES as described in part 1A, in this order: Sakai_EDL933.blastn.out EDL933_K12.blastn.out 4. SPECIFY OUTPUT FILE as described in part 1A

11

5. CREATE FIGURE as described in part 1A.

IMPORTANT: By default, Easyfig does not display features or BLAST matches smaller than 4 pixels. This feature can be turned off and on using the “Filter small blast hits/annotations” button found in the Blast option from the Image dropdown menu. If this filter is turned off with a whole genome sequence comparison the thousands of small, insignificant BLAST matches and features will swamp the image and greatly prolong rendering times. It is recommended that you turn this filter off and use the BLAST options and custom features (as described in Part B) to filter the small BLAST matches and features in whole genome comparisons. B. Display custom features on a whole genome comparison 1. Access the annotation window by choosing annotation from the Image dropdown menu and uncheck the “gene” radio button under “Include following features” 2. Enter the word phage into the open custom feature box under “Include following features” and click the radio button on the right of the box 3. Click on Colour button ( … ) to the right of the custom feature box and change to your favourite colour 4. Use the pull-down menu to the far right of the custom feature box and choose “rect” for rectangle 5. Close the annotation window using the (close) button 6. Access the blast window by choosing Blast from the Image dropdown menu 7. Enter 10000 under “Min. length”

12

8. Unclick the “Filter small blast hits/annotations” button 9. CREATE FIGURE as described in part 1A.

C. Change the BLAST identity gradient and show a graph 1. In the Blast window from the Image dropdown menu, click the colour buttons ( … ) and choose colours for minimum and maximum colours for normal and inverted BLAST matches: normal-minimum: aqua normal-maximum: blue inverted-minimum: orange inverted-maximum: red (the exact colours you choose is not important, as long as there is a contrast between the normal and inverted BLAST matches) 2. Unclick the “Outline blast hits in black” 3. Access the Graph window by choosing graph from the Image dropdown menu 4. Choose “GC content” from the pull-down “Graph:” menu

13

5. CREATE FIGURE as described in part 1A.

14

Part 2: Features of Easyfig

Main Screen

Above is the window available upon immediately opening Easyfig. Versions may vary slightly as the graphical user interface uses a style native to the operating system in use. Annotation Files: A list of GenBank, EMBL, FASTA or multiFASTA files you wish to create a figure from. Blast Files: A list of BLAST files for drawing the comparison between two annotation files. The annotation file above must be the query, and the annotation file below must be the reference. Valid input files are legacy blast and blast+ tab delimited output without headers and crunch files. Files must be made using BLASTn or tBLASTx. These are made using the -outfmt 6 tag in blast+ or –m 8 tag in legacy blast. Generate blastn/tblastx Files: Will generate BLASTn or tBLASTx comparisons between loaded annotation files. Requires BLAST to be installed, see above for installation instructions.

15

IMPORTANT: tBLASTx is very memory expensive and it may not be possible to perform on large genomes. We recommend using it to compare smaller regions only (< 500 Kb). Save As: This changes the location of where your figure will be created. Changing this after your figure has been created will not save it again under the new name. File type: Easyfig figures may be saved as Bitmap (bmp) or Scalable vector graphics (svg). SVG files require an image viewer such as photoshop or GIMP, but are much better quality than bmp files and easier to manipulate. We recommend Inkscape, a free open source image editor for viewing and manipulating SVG files. Create Figure: Creates the figure at the location specified in Save As. Will overwrite previous figures without warning File: For saving and loading settings or preferences Image: Access windows for modifying the figure being created Blast: Access options to manually or automatically download BLAST Help: Information about using and referencing Easyfig

16

Image →Figure

Width of figure: The width of the image generated in pixels. Thickness of genome line: Thickness in pixels of the line representing the full sequence. Height of genes in figure: The height of the annotation parts of the figure. Height of blast hits in figure: The height of the regions showing blast matches. The total height of the figure generated will be (no of annotation files x height of genes in figure) + (no of blast files x height of blast hits in figure). Alignment of genomes: Left, right, centre, best blast. Genomes can be aligned on the left, the right or centered in the middle of the figure. Alternatively they can be aligned so that each genome is perpendicular to the adjacent genomes at the site of their best blast hit. Draw blast identity legend: Draws a colour gradient legend for visualising the identity of your blast hits. Scale legend: Draws a H bracket of the size specified in base pairs for help visualising the length of your genomes. The default “0” will mean there is no scale legend drawn. Feature Legend: Creates legend of all the features used in the image. Get feature names from: Gets feature names from this descriptor in the genbank/embl file

17

Image →Annotation

Feature labels: Label features (information on feature labels can be found at the end of this section) Get feature name from: Gets feature names from this descriptor in genbank/embl file Thickness of exon line: Thickness of the line in pixels joining exons, or segments of a pseudo gene. Thickness of gene outline: Thickness of the black outline around the genes. Include following features: Tick checkbox for Easyfig to draw any feature of the type represented. The last box allows the user to input a feature type. This is case sensitive. Colour: will be the default colour used if no colour annotation can be found in the feature file. Colour tags are of type /colour= And can either be 3 spaced integers in RGB form or colour coded using the Artemis colour codes (integers ranging from 1 to 18). Type: How to illustrate each feature.

Arrow: Direction arrows of features.

Rect: Rectangle of the length of the feature.

Frame: Directional arrows in frame.

Pointer: Pointers at the start of each feature.

18

Image →Blast

Min. length: Minimum length of blast hits to be drawn. Max. e Value: Maximum expect value of blast hits to be drawn. Min identity Value: Minimum identity value of blast hits to be drawn. Choose minimum/maximum blast colour: BLAST hits are coloured on a gradient with minimum BLAST colour being the colour of BLAST hits with the minimum identity reported and maximum BLAST colour being the colour of BLAST hits with 100% identity. Normal is the colour for forward-forward and reverse-reverse matches. Inverted is the colour for forward-reverse blast matches. Outline blast hits in black: By default, either side of the blast hit is outlined by a solid black line. This helps distinguish between blast hits but may obfuscate identity for smaller blast hits. Uncheck to turn off. Filter small blast hits/annotations: Filter BLAST hits or features under 4 pixels wide. Reduces noise for initial view of comparison. For example, without this option, whole genome comparisons are unreadable due to all the low significance matches, and thousands of features. Once familiar with the image, it is recommended that users turn this off and use BLAST options and custom annotations to reduce the complexity of the image (as described above in example 2).

19

Image →Graph

Graph: Select type of graph.

x GC content: Percentage of guanines and cytosines in each window, given by (G + C) / (G + C + A + T) where G, C, A and T are the count of each nucleotide.

x GC skew: Ratio of guanines to cytosines in each window, given by (G – C) / (G + C). x Coverage: If provided with an ACE file in the input file field, Easyfig will calculate

the coverage across each contig, and plot it against the first identical sequence found in the feature file. Can only be used with the top genome.

x Custom: Plots a custom graph. Input is a plain text file with a single column of numbers, one line per data point.

If more datapoints are provided than the width of the image, datapoints correlating to each pixel will be averaged. Multiple graphs: If unchecked only the top sequence file will be graphed. If checked all sequence files will be graphed. To plot multiple custom graphs, the input file should have numbers in columns separated by tabs for each sequence file to be plotted. Input file: Give the filename of the user created custom file, or an ACE file.

20

Step: Generate a data point every x base pairs. Window size: Amount of bases adjacent to each step to calculate GC content/skew. This is the amount of bases in total to be counted i.e. 1000 counts 500 bases to each side of the step position. Maximum Y: maximum value of the Y axis. If set to “Auto” this will be set to the maximum of the Y axis will be set as the maximum Y value. Log Scale (log 10): Make the Y axis log10 scaled. Useful for high coverage data. Graph type: Choose histogram or line graph. Axis line thickness: Thickness of the x axis line in pixels. Positive value colour: Colour of the line or histogram bars with positive y values or GC content greater than 50%. Negative value colour: Colour of the line or histogram bars with negative y values or GC content lower than 50%. Gap between graph and figure: Gap in pixels between the graph and the annotation and comparison drawings.

21

Image →Subregions

List of subregions of annotation files to use. Cutoffs may be changed for highlighted value by entering new values into the input boxes below the lists and clicking (change cutoffs). Double-clicking a file will also bring up a box to change the cutoffs.

22

Legend options Feature legend (available from Image→Figure) Lists all genes (genes appearing in multiple genomes are only listed once) under the figure in a single or two columns. Maximum genes listed is 100, maximum length of gene name is 50 characters. Feature legends cannot be used in conjunction with feature labels.

Feature labels (available from Image→Annotation) Labels genes (labels largest gene if label doesn’t fit) on the top and/or bottom genome. Maximum length of gene name is 10 characters. Does not work in conjunction with feature legend. Cannot label top genome and include graph.

23

File →New Figure Removes all files and resets preferences to default

File → Save Settings Saves all settings including preferences and filenames

File →Load Settings Loads a previously saved configuration

File →Preferences

Save preference as: If no file exists at ./.easyfig.pref creates one. Saves all image preferences (but not file names) Load preferences: Loads previously saved image preferences, does not change files loaded. Remove: Removes a preference Set as default: Preferences loaded at start up (easyfig_standard originally)

24

Part 3: Command-line options Easyfig_CL_2.1.py Written by: Mitchell Sullivan mjsull@gmail.com Supervisor: Dr. Scott Beatson & Dr. Nicola Petty, University of Queensland Version 2.1 20.04.2012 License: GPLv3 Usage: Easyfig_CL_2.1.py [options] GenBank/EMBL/fasta GenBank/EMBL/fasta GenBank/EMBL/fasta ... This script should work on 1 to an infinite amount of GenBank/EMBL files (given enough memory) Adding 2 integers after the annotation file will crop the annotation file. Adding a R after the annotation file will reverse compliment it. WARNING: Will overwrite output file without warning. *************************************************************** GenBank or EMBL file must have source line, or Sequence. ' source 1..<sequence length>' or 'FT source 1..<sequence length>' for GenBank / EMBL *************************************************************** The GenBank file preceding the blast file should always be the query the GenBank file after the blast file should always be the reference In it's present state only 'CDS' features will be recorded Options: -o <string> Specify output file. <REQUIRED!> -blastn Generate blastn files automatically. Requires blastall or blast+ in the path, Annotation file must have nucleotide sequence. [Default] -tblastx Generate tblastx files automatically. Requires blastall or blast+ in the path, Annotation file must have nucleotide sequence. -blast_files List of previously generated blast files, ordered. Query must be annotation file on top, reference annotation file on bottom. -svg Create Scalable Vector Graphics (svg) file instead of bmp. -filter Filter small blast hits or annotations (< 4 pixels wide). [F] GENERAL OPTIONS: -width <int> width of figure in pixels. [5000] -ann_height <int> height of annotations in figure (pixels). [50] -blast_height <int> height of blast hits in figure (pixels). [100] -f1 <T/F> draw colour gradient figure for blast hits. [F] -f2 <int> draw scale figure <int> base pairs long. [0] -uncomp <T/F> Do not compress figure. [F] -f <string> [r g b] [arrow/rect/pointer/frame] Draw features of type <string> (case sensitive) in the color r g b with illustration type arrow, rectangle, pointer or frame. Default light blue arrows. EXAMPLE: -f CDS 255 0 0 rect will draw all CDS features as a red rectangle. if none specified easyFig automatically draws CDS features. If you want a figure with no features drawn use -f F

25

-glt <int> Genome line is <int> pixels thick [5] -exont <int> exon lines joining introns are <int> pixels thick. [1] -genet <int> outline of features is <int> pixels thick. [1] -aln <best/left/right/centre> [centre] Alignment of genomes best aligns feature file perpendicular to best blast hit. -legend <single/double/top/bottom/both/None> Single: Gene names in single column Double: Gene names in two columns Top: Top feature file genes labelled above figure Bottom: Bottom feature file genes labelled below figure Both: Top and bottom feature files genes labelled above and below genome. None: No legend or gene labelling <default> -leg_name Where to get feature name from [gene] BLAST OPTIONS: -e <float> maxmimum e value of blast hits to be drawn. [0.001] -i <float> minimum identity value of blast hits to be drawn. [0] -min_length <int> minimum length of blast hits to be drawn. [0] -blast_col <red/blue> changes blast hits to gradient of red or blue alternitively <int1 int2 int3 int4 int5 int6> defines color gradient for blast hits worst blast hit reported will be color int1 int2 int3 where int 1 2 3 is the RGB of color range[0-255] 100% identity blast hits will be color int4 int5 int6 [default 20 20 20 175 175 175] <gray> -blast_col_inv Colour for inverted blast hits. -bo <T/F> Black outline of blast hits. [T] GRAPH OPTIONS: -G <GCContent/GCSkew/Coverage/Custom [filename]> Plot GC Content, GC Skew, Coverage or Custom graph. if Coverage or Custom filename for ace or custom file needs to be provided. Details on how to make custom graph files in manual. -wind_size <int> Window size for calculating GC content/GC skew. [1000] -step <int> Step size for calculating GC content/GC skew. [1000] -line <T/F> Draw graph as a line graph. [T] -axis_t Thickness of X axis. [1] -pos_col <int int int> RGB colour of positive values in graph. [Red] -neg_col <int int int> RGB colour of negative values in graph. [Blue] -g_height <int> height of graph in pixels. [50] -gap gap between graph and annotations. [10] -y_max Maximum y value [Default: max Y calculated.] EXAMPLES: Easyfig_CL_1.2.py -filter -o outfile.bmp genbank1.gbk genbank2.gbk genbank3.gbk Easiest way to generate a simple comparison file between three (or more) annotation files. Shows CDS features as red arrows. Easyfig_CL_1.2.py -o outfile.bmp -e 0.00001 -f gene frame 0 0 255 -G GCContent ann1.embl ann2.gbk ann3.gbk ann4.embl Generate a blastn comparison between 4 annotation files, Display genes as blue arrows in frame. Only report blast hits under 0.00001 expect value. Display the GC content of each file as a graph.

26

Easyfig_CL_1.2.py -tblastx -o outfile.svg -svg ann1.embl 1 10000 ann2.embl 1 10000 R Show a tblastx comparison of the first 10000 base pairs of ann1.embl and ann2.embl Reverse compliment ann2.embl. Writes as a SVG file.

Final comments Please email the author at mjsull@gmail.com if program crashes or bugs are found. Console printout and short description of what was being attempted is appreciated. Feel free to email if you have any ideas for future implementations (other commonly used graphs, formats to make compatible, other illustration options) Thank you for using Easyfig, The Easyfig team