If you know nothing about R, or about R/qtl, then the place to start is Karl Broman's web page on R/qtl.

R/qtlbim contains vignettes, help pages, help examples and demos. You can start the "Html help" from the help pulldown menu. Then, in your browser, you will see the main R help page. Click on "Packages", then click on "qtlbim". At the top, click on "overview" to get the list of vignettes for this package. These are full documents that describe the package as a whole. In addition, R has a "demo" facility. In R, type > demo(package = "qtlbim") to get a list of demos for this package. Now try > demo(qb.tour, package = "qtlbim") and follow instructions. This "qb.tour" demo gets to all the other demos. You can learn more about specific commands from the individual help pages available on the "Html help" for package "qtlbim". Alternatively, from inside R, you can use the "help" and "example" functions. For instance, > help(qb.scanone) gives you the help page for "qb.scanone". Typing > example(qb.scanone) will run the example at the bottom of that help page. [Note that most examples are designed to run, with the exception of "qb.sweave" and some internal functions. Also, not that a call to "qb.load" to load an example dataset is run at the beginning of most examples, but is not shown on the help page.]

Please feel free to contact Brian Yandell or Nengjun Yi directly with questions. We will try to be prompt in reply.

If you are planning to cite R/qtlbim in your work, please quote the following publication:

Yandell BS, Mehta T, Banerjee S, Shriner D, Venkataraman R, Moon JY, Neely WW, Wu H, Smith R, Yi N (2007) R/qtlbim: QTL with Bayesian Interval Mapping in experimental crosses. Bioinformatics 23(5):641-643; doi:10.1093/bioinformatics/btm011

This error message arises if you are using a version of R/qtl that is older than 1.03. The best way to fix this is to open a fresh R session, without opening any packages, and click on the "Packages" menu, then click "Update Packages...". After selecting a mirror near you, and a short wait, a list of packages needing update on your R system will appear. If "qtl" is on that list, click "OK" and the newer version will be loaded. If that does not work, then you can use "Install Packages..." and re-install package "qtl". It will replace your older version with the newer one. Close this session of R, and the next time you open it, it should have the latest version. Note that the "Html help" page for any package will tell you the version installed.

If you download R/qtlbim and try to attach our library, you may get the following:

> library(qtlbim)
Loading required package: qtl
Loading required package: lattice
Loading required package: coda
Error: package 'coda' could not be loaded
In addition: Warning message:
there is no package called 'coda' in library
		

When you loaded r/qtlbim, there was probably a message that it depends on 'coda'. Perhaps you did not notice this. The remedy is to load the package 'coda' from CRAN and then try attaching library(qtlbim) again.

The URL for R/qtlbim is www.ssg.uab.edu/qtlbim but unfortunately the non-existent URL www.soph.uab.edu/qtlbim was entered on some help pages in the earliest release. This was corrected in release 1.05-6. You can resolve this by updating your packages or re-installing a fresh copy of R/qtlbim (see how to do this under the calc.genoprob question).

R/qtlbim now works on Mac OSX. You need R/qtlbim 1.6.0 or later.

Currently, R/qtlbim routines require access to the cross object used by qb.mcmc. If you create the qb object within a function call, then it might not get the right name. Here is a work-around for those writing their own routines to call qb.mcmc.

my.function <- function(cross, ...)
{
  ## Create qb object.
  my.qb <- qb.mcmc(cross, ...)

  ## Kludge: reset "qb" attribute to my.qb.
  attr(my.qb, "qb") <- deparse(substitute(cross))

  ## continue with analyis of QB object.
}
		

The R/qtlbim command qb.sweave creates a LaTeX document. You need to process this into PDF using a system command. The system command pdflatex, which turns LaTex into a PDF document, is a standard part of Linux systems. However, most non-stat Windows users are unfamiliar with LaTeX, a text processing language for statisticians and mathematicians as an alternative to Word and PowerPoint. You can download free software to turn LaTeX into PDF with a few steps. Download the required tool, MikTeX, which compiles LaTeX documents. MikTeX will take awhile to install. [It typically puts things in C:/texmf.] You will need some more LaTeX packages (e.g. beamer) that are not automatically installed. When you run pdflatex, either from within R (see below) or using WinTeX, a Command window will open up and stream the LaTeX compilation of your document. You may get a popup window called "Package Installation" saying "The installation of the following pakage is required". Click on the "Change..." button to pick a LaTeX mirror near you on the "Internet". Then click "Install". Once you have MikTeX installed (and WinTex if you want it), from inside R, you can type the following:

> qb.sweave(hyper)
## Run hyperslide document.
## This will take some time and a number of steps.
## ...
> system("pdflatex hyperslide")
> system("pdflatex hyperslide")
		

The call to pdflatex is done twice to get cross-referencing for the document outline. Here hyperslide was the name of the Sweave (*.Rnw) document and the created LaTex (*.tex) document. If your document has a different name, use that. I did have a small problem with MikTex. It choked on something called "miktek-yandy-support". I apparently solved this by going to the Windows Start menu, to All Programs, to MikTex folder, then to "MikTex Options". Click on the "Packages" tab, then click on "Start Package Manager". I scrolled down to highlight "miktek-yandy-support" and then under repository clicked "Synchronize". Then I went back to R and did the system call to pdflatex.

You can use the Stangle command in R:

> Stangle(system.file("doc", "hyperslide.Rnw", package = "qtlbim"))
Writing to file hyperslide.R
		

Then you can click on File, then Open Script, to open this file and examine or edit it. Be warned that much of the code you see is not displayed in the final document, but you can streamline this for your own automation purposes.

There are a few words of advice on qb.sweave that are not in the package yet.

1. It can take a long time to run the command.
2. It creates external files, including PDF files in a folder and a LaTeX document described above.
3. It also creates some internal objects that are not properly removed, with names like cross.arch and pos. It can easily clobber your own objects, so watch out.
4. The option hpd.level is rather important. It sets the HPD level that screens the chromosomes to be included for subsequent analysis. Too small a value will restrict your set, while too big will include everything. We are working on how to calibrate this for data exploration. The same can be said about the threshold in terms of epistatic effects.
5. It will remove the objects it creates unless you set the option remove.qb = FALSE.
6. If you set remove.qb = FALSE, you can refine the analysis as you wish. For instance change the HPD level and reexamine the genetic architecture. In particular, the objects cross and cross.qb correspond to a copy of your cross object and the qb object created during qb.sweave by qb.mcmc.
7. If you want to get really fancy, you can edit the LaTeX output (*.tex) using Open Script (inside R), WordPad (in Windows) or Xemacs (on most systems) or any other simple text editor.
8. If you want to edit LaTeX in a nice system specific to LaTex, you can download the free version of WinTeX. Note that with the free WinTeX you can only configure three programs. Choose LaTeX, PDFLaTeX and BibTeX.
9. If you wan to get even fancier, you can edit the Sweave source file (*.Rnw) and make your own version.
10. You might be interested in addition in the Cygwin system, which has an X-Windows application if you are interested. You can learn more about that from our UW-Madison Statistics Laptop Info page.