#GUIDE TO INSTALLATION & USE OF BORICE: BAYESIAN OUTCROSSING RATE AND INBREEDING COEFFICIENT ESTIMATION SOFTWARE
BORICE is free software developed by Vanessa Koelling, Patrick Monnahan, and John Kelly to estimate the mean outcrossing rate and inbreeding coefficient of populations using Bayesian methods. To learn more about how this software works, its uses, and for the purposes of citing this software, please refer to the following publication:
Koelling, V. A., P. J. Monnahan, and J. K. Kelly. 2012. A Bayesian method for the joint
estimation of outcrossing rate and inbreeding depression. Heredity 109: 393-400.
doi:10.1038/hdy.2012.58
##How To Format Your Data Files for Use with BORICE:
BORICE takes genotype data in the form of comma-separated value (csv) files. In your csv file, missing data should be coded as '-9'. The first row of the csv file should contain the following in the first three cells: 1) the number of marker loci, 2) a 0 or 1 to indicate the absence or presence of a population name in your data, and 3) a 0 or 1 to indicate the absence or presence of a subgroup name in your data. Currently, subgroups are not supported, so if subgroups are present they will be ignored. The second row should contain the names of your marker loci. All other rows should be in the following format: cell 1 = family name; cell 2 = population name (unless there isn't one); cell 3 = allele 1 of marker locus 1; cell 4 = allele 2 of marker locus 1; and so forth for all loci. If maternal individuals are present, they should be indicated with a '!' after the family name (e.g., 'fam1!').
##How To Install BORICE for Windows users:
###STEP 1
BORICE was developed using Python 2.7. It has not been tested with Python 3. Download the Python 2.7 Installer that works with your system architecture. Note for Mac users: you must download the Installer with 64-bit/32-bit architecture in order for BORICE to function. Go to the following website to download Python:
http://www.python.org/download/
BORICE functions through a graphical user interface (GUI). In order for the GUI to function, you will need to install some additional third party software.
###STEP 2 You will need to install PyQt. Download the Installer (listed under “Binary Packages”) for Python 2.7.x and your operating system (Windows 32 or 64 bit). PyQt can be found at the following website:
http://www.riverbankcomputing.co.uk/software/pyqt/download/
###STEP 3 Double-click on main.py in the BORICE folder to execute the GUI. The “.py” denotes that this is a Python file. A Python window will then open labeled “BORICE”. The Command Prompt window will also be launched. Any errors that occur during the run will appear in the Command Prompt window.
##How To Install BORICE for Mac users: ###STEP 1
BORICE was developed using Python 2.7. It has not been tested with Python 3. Download the Python 2.7 Installer that works with your system architecture. Note for Mac users: you must download the Installer with 64-bit/32-bit architecture in order for BORICE to function. Go to the following website to download Python:
http://www.python.org/download/
BORICE functions through a graphical user interface (GUI). In order for the GUI to function, you will need to install some additional third party software.
###STEP 2 The BORICE GUI functions on the latest version of Mac OS X Yosemite. The following instructions assume that Yosemite is used. I will try to keep up with operating system updates as they arise. But be aware that if you are using a different version of the Mac OS X, you will very likely need to install different versions of the following software.
First, you must download the Xcode Developer Tools software. As of this writing, this is Xcode 6.3.1. This can be found at the Developer Center on the Apple website:
https://developer.apple.com/xcode/
Xcode is a free download, but you will likely need to register in the Member Center to obtain it. If you are a regular Mac user and already have an Apple ID and password, this will just mean signing in. Otherwise you will need to create an Apple ID (any email address can be used as your Apple ID). If you are using an older version of OS X, follow the link for additional developer tools downloads to find the version of Xcode that works with your operating system.
Once you have downloaded and installed Xcode, you will need to install some additional tools to make sure that you have the C++ compiler installed on your system. To do this, open Xcode “Preferences” and click on the “Downloads” pane. Then select “Check and Install Now”. This will install the command-line tools needed for the GUI to function properly.
If you have difficulty installing an older version of Xcode for an older OS X version, a quick search on the internet should be able to help you with troubleshooting the installation. But to avoid problems, I highly recommend using the latest OS X and Xcode versions if at all possible.
###STEP 3 Next, you will need to download and install Qt libraries from the Qt Project website:
http://qt-project.org/downloads
Download and install the free Qt 5.x libraries Mac. Use default settings. The Qt libraries are necessary for your computer to understand how to construct the GUI. Note: If Qt Creator launches after installation of the libraries, just close it—you will not be using it.
###STEP 4 Finally, you need to download and install PyQtX from the following website:
http://sourceforge.net/projects/pyqtx/
Click on the download button that says PyQtX 4.9.4 Complete (that is the latest version). You will likely need to control-click on the installer to open it, otherwise you will get a message that it is from an unknown developer and it won’t open. The PyQtX libraries are also necessary for your computer to understand how to construct the GUI.
###STEP 5 Find the file labeled “main.py” in the BORICE folder. The “.py” denotes that this is a Python file. To ensure that Python recognizes this file, right-click on the file and select “Get Info”. Under “Open With”, select Python Launcher.
Now you are ready to launch BORICE. Double-click on main.py in the BORICE folder to execute the GUI. A Python window will then open labeled “BORICE”. The Terminal window will also be launched. Any errors that occur during the run will appear in the Terminal window. Note: You may need to have the BORICE files on your desktop in order for BORICE to launch.
##How To Run BORICE once installed:
From the file menu, select “Open Data File”. Then select your input data file. You will then have the option to run BORICE with default settings or to change the settings. The following defaults are listed under the “General Settings” tab:
Default Settings Number of Steps = 100000 — The number of steps is the number of steps taken in the MCMC chain. If replicate runs of BORICE yield varying estimates of t or F, this may indicate that the chain length is too short.
Number of Burn In Steps = 9999 —The number of burn in steps is the number of initial steps that will be discarded before the posterior distributions are calculated. If replicate runs of BORICE yield varying estimates of t or F, this may indicate that the burn-in length is too short.
Outcrossing Rate Tuning Parameter = 0.05 —The outcrossing rate tuning parameter is the value that determines how large a change in outcrossing rate is made at each step.
Allele Frequency Tuning Parameter = 0.1 —The allele frequency tuning parameter is the value that determines how large a change in allele frequency is made at each step.
Initial Population Outcrossing Rate = 0.5 —The initial population outcrossing rate is the starting outcrossing rate value for the chain.
File Output Options—You also have the option of choosing the output files from your BORICE run under the “File Output Options” tab. The default settings are to produce all files. Output 1 is always produced; it contains the posterior distributions of t and F, population inbreeding history, and allele frequencies at each locus. Output 2 contains the posterior distributions of maternal inbreeding histories. Output 3 contains the list of t and F values from every 10 steps in the MCMC chain. Output 4 contains the posterior distributions for each maternal genotype at each locus in each family. These output files are tab-delimited text files that can be imported into spreadsheets.
Input Data Check—The “Input Data Summary” tab shows you the number of marker loci, number of families, and number of individuals read from your input data file. If these numbers are not correct, then you should check your input data file.
Locus Settings—The “Locus Settings” tab allows you to choose whether to run each locus as having null alleles or not. The default setting is all boxes unchecked, which means null alleles will not be considered at a locus. Checking a locus box means null alleles will be considered at that locus. If you are uncertain whether or not to run BORICE with null alleles considered at a locus, you may want to try running BORICE with and without null alleles to compare the average ln likelihood. If you see a substantial improvement in the ln likelihood when running the model with null alleles at that locus, then null alleles may be present. In addition, BORICE makes an initial check of the data for impossible genotypes. If impossible genotypes are present at a locus even after you have checked your data for input errors, then null alleles may be present at that locus and you may wish to try the model with null alleles considered.
Click “Run” to run BORICE. If you do not see the prompt in the Command or Terminal window, BORICE is running. You will get an alert message when the run is complete.