qfaR: tools for Quantitative Fitness Analysis


Introduction

This page describes how to install and use an R package for carrying out quantitative fitness analysis (QFA) of the growth of microbial cultures arrayed on a solid agar surface. A more detailed description of QFA and the motivation for carrying out these experiments and subsequent analysis can be found on the QFA website.

Instructions for users specifically interested in using the data visualisation tools in the package can be found on the visualisation tool webpages.


Installing or updating the QFA package

Installing or updating under windows

You will require administrator rights on your PC to install R and the qfa package.

  1. Make sure you have the latest version of R installed on your computer. If not, download the latest .exe file to your hard drive and install.
  2. If they are not present on your system, you may need to install some extra R packages that the qfa package uses. To install these, make sure you have a working internet connection and:
    1. Start the R application (e.g. Start->All Programs->R->R x64 3.0.1)
    2. Paste the following line of code after the command line prompt, press enter, and follow the on-screen instructions:
  3. install.packages(c("knitr","DEoptim","sp","quantreg"))
  4. Install the qfa package containing the visualisation tool and the Addinall et al., 2011 QFA datasets:
    1. Start the R application (e.g. Start->All Programs->R->R x64 3.0.1)
    2. Paste the following line of code after the command line prompt (followed by Enter):
    3. install.packages("qfa", repos="http://R-Forge.R-project.org")

Installation should be complete. You do not have to go through these steps again to use the tool. To update an existing installation to the latest version, simply repeat step 3.

Installing or updating under OSX

You will require administrator rights on your machine to install R & the QFA package.

  1. Make sure you have the latest version of R installed on your computer (or at least a version >= 3.0.1). If not, download the latest R installation file (.pkg file) to your hard drive and install.
  2. If they are not present on your system, you may need to install some extra R packages that the qfa package uses. To install these:
    1. Start the R application
    2. Paste the following line of code after the command line prompt (followed by Enter):
  3. install.packages(c("knitr","DEoptim","sp","quantreg"))
  4. Install the qfa package containing the visualisation tool and the Addinall et al., 2011 QFA datasets:
    1. If you already have a version installed, you can check the installed version number by pasting the following line of code after the command line prompt in an R session (followed by Enter):
      sessionInfo("qfa")
    2. Save the latest version of the installer package to your hard-drive, noting its location
    3. Start the R application
    4. Navigate to Packages & Data -> Package Installer
    5. Choose "Local Source Package" in the menu for Package Repository
    6. Select "Install at System Level"
    7. Click the "Install" button, supplying an admininstrator username and password if required
    8. Navigate to the installer package downloaded to hard-drive in step a), click ok
    9. Check if there are any queries in the main R window. For example, if the current user is not an administrator you may be prompted with the following message:
      Warning in install.packages(file.choose(), "/Library/Frameworks/R.framework/Resources/library/",  :
        'lib = "/Library/Frameworks/R.framework/Resources/library/"' is not writable
      > 
      Would you like to use a personal library instead?  (y/n) 	
      		
      In this case, you should move the cursor to the end of the last line, type "y" and press enter.
    10. Close the "R Package Installer" window
Note that the first time that you install the QFA package, depending on the version of your operating system, you might be prompted to install the X11 software for OSX. X11 is necessary for generating interactive plots, so please install it if prompted. This may require restarting your machine.

Installation should be complete. You do not have to go through these steps again to use the tool (and in particular you should not have to install X11 again). To update an existing installation to the latest version, simply repeat step 3.

Installing or updating under Linux

You will require administrator rights to install the latest version of R and the qfa package.

  1. Make sure you have the latest version of R installed on your computer. For example, here are some instructions for installation under Ubuntu
  2. If they are not present on your system, you may need to install some extra R packages that the qfa package uses. To install these:
    1. Start the R application (e.g. type "R" at the command line)
    2. Paste the following line of code after the command line prompt (followed by Enter):
  3. install.packages(c("knitr","DEoptim","sp","quantreg"))
  4. Install the qfa package containing the visualisation tool and the Addinall et al., 2011 QFA datasets:
    1. Start the R application (e.g. type "R" at the command line)
    2. Paste the following line of code after the command line prompt (followed by Enter):
    3. install.packages("qfa", repos="http://R-Forge.R-project.org")

Installation should be complete. You do not have to go through these steps again to use the tool. To update an existing installation to the latest version, simply repeat step 3.

Other installation methods

Package source code can be checked out from the SVN repository at the R-forge website: http://r-forge.r-project.org/projects/qfa

Binary packages for MS Windows and Linux (but not OSX) can be found on the same page.


Loading & using the QFA package

Once installed, the package must be loaded, to make it ready for use, with: library(qfa) Detailed documentation can be found in the online version of the package manual or by executing: help(package="qfa") Documentation for specific functions can also be obtained using the usual R mechanisms. For example, help on the function colonyzer.read can be obtained with: ?colonyzer.read A short document outlining QFA and the package functions can be accessed online or by executing: vignette("qfa") Some example code demonstrating analysis of a small subset of the data presented in Addinall et al., 2011 can be executed by: demo("telomereCap") Finally, we can launch a demo of the interactive visualisation tool to browse fitnesses and compare between experiments: visToolDemo()


R package functions overview

This R package consists of a set of functions, split into types below:

Reading and formatting data

These functions read in image analysis output (e.g. from Colonyzer), associate these cell density estimates with culture type (e.g. genotype) & plate treatments and calculate time since inoculation for each observation. All of these data are bound together into a data.frame object, with rows representing unique observations of individual cultures.

Fitting logistic model to growth curves

These functions carry out parameter inference for a generalised logistic model of the observed growth curves. Inference is currently carried out by maximum likelihood (fast, only provides point estimates for parameter values), however we are currently developing a parallel package (qfaBayes) for Bayesian hierarchical inference which will provide distributed parameter estimates, making more efficient use of the available experimental observations. Logistic model parameter values can be used to construct quantitative fitness definitions for subsequent analysis.

Inferring genetic interaction strengths

Addinall et al., 2011 present statistical methods for inferring genetic interaction with telomere capping mutations. The analysis was based on comparing observervations of double mutant fitnesses with predicted double mutant fitnesses given observed single deletion fitnesses and assuming a multiplicative model of genetic interaction. Effectively, genome-wide observations are used to construct a linear predictor of query mutation fitness given control mutation fitness, and any deviations from this prediction are evidence for genetic interaction. Observations of multiple replicate cultures are typically made and these replicates can be summarised by mean or median fitness, and significance of deviations can correspondingly be estimated by Student's t-test or the Mann-Whitney test, corrected for multiple comparisons. Analysis based on mean/t-test is generally prefrable to that using median/Mann-Whitney test, since the former has greater statistical power, however, in the case where it has not been possible to perform adequate quality control on the source data (e.g. there are occasional contaminants, or missing cultures, resulting in statistical outliers) the former may be preferable.

Auxiliary functions

Together with the functions for carrying out the raw analysis above, we provide several functions for visualising the data, the fit of the logistic model to the data and the visualisation of evidence for epistatic interaction. These visualisation tools are important for understanding unexpected fitness patterns, tracking bugs and increasing user confidence in the validity of the sophisticated QFA workflows.

One such function, the qfaR visualisation tool, generates interactive scatterplots for browsing genome-wide fitness comparisons. To use this tool, please see the documentation which can be found on the visualisation tool website.