Quick Start
User Guide
BioMercator¶
Introduction¶
BioMercator V4 is a genetic map compilation and QTL meta-analysis software providing tools to integrate these data with genome structural and functional annotation. It offers wizards to run analyses and display input and output maps through a user friendly graphical user interface (GUI). In addition to map compilation and meta-analysis methods available in previous BioMercator version, this new release includes algorithms from the MetaQTL package (http://www.bioinformatics.org/mqtl/wiki/).
The GUI has evolved, and now offers new ways of zooming. A cascading zoom allows to progressively enlarge a region of a map while conserving alongside the whole chromosome representation. It is now possible to use the zoom from the whole map representation to focus on zones of interest of several chromosomes. Image can be exported in various format including SVG for subsequent image editing in third-party software.
BioMercator V4 also implements a new file loading wizard capable of reading an unlimited number of files and automatically recognize their format.
The possibility of using MetaQTL’s package algorithms directly inside BioMercator V4 came with a file format evolution ; to use fully those algorithms, more data will be required than in the previous BioMercator version.
The user will be able to export maps and analyses in a format compliant for submission to the URGI databases (GnpIS).
How to install BioMercator¶
BioMercator is a Java program; all you need is Java (v1.6 or above) installed on your machine. To install java see http://www.java.com/.
On Windows: Double-click on the BioMercatorV4.jar to launch the program
On other OS: Open a terminal and execute the command line :
java -jar BioMercatorV4.jar
Memory management : On any OS, If the software doesn’t launch or exits with a memory error (when working with large genome annotation dataset), you should open a console (terminal) and type the following line :
java -jar -Xmx512m BioMercatorV4.jar
Tutorial¶
This tutorial will guide you through new functionalities and analyses in BioMercatorV4; data files used are situated in the “Tutorial_files” folder.
When launching the software for the first time, the workspace is totally empty.
Data Loading¶
First, we’ll load the genetic maps. The wizard is accessible through the “File” menu and “Genetic data loading” sub menu. Choose “New project” and name it “data”.
Create new project¶
The next step is the files choosing; browse your files and select all files inside the “tutorial/Genetic Files” folder. (hold the “shift” or “control” button to select all files, or press the combined keys “Control” and “a” (replace “control” by the “apple” key on mac OS))
Genetic maps loaded¶
The next step shows a summary on all loaded files.
Once the wizard is finished, the new maps will be displayed in the explorer on the left side, inside the chosen project. You can delete a single map, click right on the map Laurence and then click on supress button.
Maps explorer on the left¶
Chromosomes display¶
For displaying a whole map, click on the map in the explorer, move the mouse in the drawing panel and release the mouse button. The whole map should appear with all chromosomes and linkage groups. You can drag an drop a chromosome or linkage group the same way. Drag the chromosomes ‘1’ from ‘Cardinal_2001’, ‘Groh_1998’ and ‘Mechin_2001_inv1’ maps to see the dynamic comparison. You see now the common markers linked with blue and red lines; red lines show the inverted markers. Now drag the ‘Mechin_2001_inv1’ from the right side to the left side of ‘Groh’_1998’ by moving it (holding the mouse left button). We see lots of inversion; right click on the ‘Mechin_2001_inv1’ and select “Reverse linkage group”; the whole linkage group is now in the right order. To remove an element from the display panel, you have 2 ways : * use the middle click of the mouse on the element to remove * right click on the element, then select “remove from view” in the contextual menu
Chromosome display¶
Individual zoom¶
Drag several chromosomes into the display panel; now, put the mouse inside a chromosome, and use the mouse wheel; you will zoom inside the chromosome, keeping other chromosome un-zoomed. (You can also right click on the chromosome, and choose “Zoom in/out”. To keep an idea of your position in the chromosome, a mini-chromosome is displayed below, with a scroller indication your viewing window. (Try this functionality a bit later on chromosomes with more markers on them.)
Individual zoom¶
Cascading zoom¶
Clear the drawing panel and drag the chromosome 8 from ‘Chardon_2005a’. Clicking on it will launch the cascading view; a scroller appears and can be move/resized with your mouse for exploring the chromosome with more details.
Fig6 here
You can click on the zoomed chromosome for more details.
Cascading zoom¶
The zoom allows to display more information on the markers; (some markers are hidden by default when there are too many; this option can be changed in the “Expert” tab, below the maps explorer).
Genetic maps analyses¶
Previous BioMercator version allows you to directly use command line analyses from the metaQTL toolbox. The standard workflow is the following: * Verify connectivity between input maps * Create a consensus map * Launch a meta-analysis on all QTLs from the consensus map
Connectivity (InfoMap)¶
This method creates text files about connectivity (where dynamic comparison is only used in a visual way), in order to determine if the can be used for creating a consensus map.
Click on “Analysis”, “Statistics”, “InfoMap”
Create a project “Statistics” and validate
Select all maps from the “Data” project
Set the result name as “connectivity”
Click ‘Next’ for launching the analysis
Select dataset¶
Once the analysis done, you’ll see 2 created files in the Statistics folder; they contain informations about markers and their connectivity.
Connectivity files (1/2)¶
Connectivity files (2/2)¶
Consensus map creation (ConsMap)¶
This analysis is done in single one step, avoiding the iteration part. * Click on “Analysis”, “Map compilations”, “MetaQTL Cons” * Create a project “Consensus” and validate * Select all maps from the “data” project * Set the resulting map name to “pre_consensus” * Launch the analysis
Select dataset¶
When the analysis finishes, a information dialog is shown; the analysis should be a success, and the resulting consensus map should be visible in the explorer. Drag it to display it; you notice that no QTL is present; the next analysis is needed.
Display consensus map¶
QTLs projection (QTLProj)¶
Once the consensus map is created, use this analysis in order to project QTLs from all the maps used. * Click on “Analysis”, “Map compilations”, “MetaQTL QTLProj” * Choose the “Consensus” project and validate * In the next window, in the left explorer, select all maps from the “data” project * In the right explorer, select the “pre_consensus” map from the “Consensus” project * Set the resulting map name to “consensus” * Launch the analysis
Select dataset¶
QTLs projection¶
QTLs Meta-analysis (QTLClust)¶
This meta-analysis is a two steps analysis; the first one calculates and estimates the best models (ie number of meta QTLs), so you can choose the one to show in the second.
First step¶
Click on ‘Analyses’, ‘QTL Meta analyses’, ‘MetaQTL Meta analysis 1/2’
Choose ‘meta_v1’ for the meta analysis’ name
Select the ‘Consensus’ project
Select the ‘consensus’ map
Select the ‘1’ chromosome
Select the ‘1’ linkage group
Choose to regroup the traits into a single meta trait named ‘FT’ (for Flowering Time)
Click ‘Next’ to launch the analysis
QTLs meta-analysis parameters¶
Once the analysis is done, browse the explorer down to the created meta analysis situated inside the previously selected linkage group (project ‘Consensus’, map ‘consensus’, chromosome ‘1’, linkage group ‘1’). You’ll see 3 created files; drag the one named ‘meta_v1_model.txt’; it corresponds to the most probable model given different criterions.(for more explications, please refer to the ‘MetaQTL’ software documentation)
First step analysis¶
Second step¶
Click on ‘Analyses’, ‘QTL Meta analyses’, ‘MetaQTL Meta analysis 2/2’
Select the ‘Consensus’ project
Select the ‘consensus’ map
Select the ‘1’ chromosome
Select the ‘1’ linkage group
Choose ‘meta_v1’ for the meta analysis’ name
Choose the meta trait named ‘FT’
Click ‘Next’ to launch the analysis
Set ‘5’ for the ‘best’ parameter
Second step parameters¶
Once the analysis is done, browse the explorer down to the created meta analysis situated inside the previously selected linkage group (project ‘Consensus’, map ‘consensus’, chromosome ‘1’, linkage group ‘1’). Inside the folder, you’ll see a linkage group named ‘1’, drag it to see the meta-QTLs along with the QTLs and their percentage of belonging.
Display meta-analysis results¶
Genome viewer¶
BioMercator integrates structural and functional annotation; a genome version corresponds to a structural annotation, a functional annotation and anchors between the genetic map and the sequence.
Loading a new genome version¶
You’ll need to download 2 files corresponding to the annotation (too heavy to be included in the BioMercator package). You’ll find them in the “tutorial/Physic Files” folder. * The structural annotation in maize sequence ZmB73_5b_FGS.gff.gz * The functional annotation ZmB73_5a_xref.txt.gz Extract each file into the ‘tutorial/Physic Files’ folder.
Click in the menu: ‘File/New genome version’; Choose a name for the genome version (‘maize_1’) Click on browse for the structural annotation, and choose the ‘ZmB73_5b_FGS.gff’ file
Browse GFF file¶
The wizard show you the first lines in the file; it is set by default to use a GFF3 file, so you don’t need to change anything; just click on Finish.
Now, click on browse for the functional annotation, and choose the ‘xref.txt’ file. As before, just click finish as the columns are in the right order. Click on browse for the anchors and choose the ‘anchors.csv’ file.
Browse anchor file¶
As you can see, the wizard fails to display correctly the file; here, the file separator should be “space-comma-space”; select the ‘Custom’ separator and type “ , “ (in words : “space” “comma” “space”). The display should now be better.
Define custom separator¶
As you can see, the columns titles don’t corresponds to the files columns. Click on the column and use the combo box to change their title until they are similar to the following screenshot.
Change columns order¶
Carefully verify that the columns are the same, and then click on ‘Finish’ At last, click on browse for the database links and choose the ‘dblinks.txt’ file. Choose tabulation as separator, and then click on ‘Finish’.
You should wait for the files to be loaded until you get the following dialog; then, just click ‘Finish’ to save the genome version.
Progress state of file loading¶
Display a new genome version¶
We’re now going to display the new genome version; in the tab ‘Genome Version’ select ‘maize_1’; a progress bar should appear; wait until it’s completely loaded. Drag the linkage group from the explorer: Consensus/consensus/1/1/meta_v1 and unselect the QTLs display under the QTL tab (for a clearer view). Drag the scroller on the genetic map, and you’ll see it move along the sequence (vertical line in the middle), as well as the genes under the selected area (on the right side). As the ratio between cM and bp isn’t always the same, look at the scroller’s size on the sequence as you move the other one on the genetic map. (you can also resize the scoller or move the other one). You can also move the mouse over a gene. A menu appears with links to URGI, gramene or maizeGDB databases. You can click on one of them, it will open a browser with the page corresponding to the selected gene.
Display genome view¶
Click then on the first meta-QTL. The Cursor is positioned automatically around it. Now, in the ‘View’ menu, choose ‘Show the GO view’. A panel appears at the bottom. The colors shown in the chart represent the Gene Ontology terms, and are used for the genes color; clicking on a chart section will enlighten the corresponding genes, and clicking a second time (not a double-click) will make you go deeper in the GO hierarchy.
Display Gene Ontology piechart¶
Analyzing GO terms over-representation¶
Another tool in BioMercator is the GO representation analysis; select the Analysis tab in the new panel, check the scroller is situated around the first metaQTL (click on the metaQTL if not) and just launch the analysis. The analysis gives you a list of GO terms over and under represented in the selected area (here, the meta-QTL) compared to the whole linkage group. The columns gives you more information about the term. Clicking on it will enlighten the genes with the corresponding annotation. Other analysis parameters are available, you could decide to analyze the representation along all intervals of a trait compared to the whole genome for instance.
Emphasis annotated genes¶
Finally you can export genes into GFF3 file; Right click on the genes window, and select ‘Export to GFF’.
GFF export form¶
You can export all features or only genes. You can choose the window of export (just the scroller’s area, the whole chromosome or the whole genome). And you can choose to export only genes with the corresponding GO functional annotation. Browse to select the path of your new file, and click next. You’ll see in the created GFF the genes with all the structural annotation, but with also the GO annotation. The QTLs and meta-QTLs will be present in the GFF file.