Read Me

Colonyzer: automated quantification of characteristics of microorganism colonies growing on solid agar
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To use Colonyzer you need at least one image of spots growing on an agar plate, and to create a Colonyzer.txt file containing estimates of the location of the top left and bottom right spots.  Several example images of various dimensions and with different features are available in the ExampleImages folder here: https://sourceforge.net/projects/colonyzer/files/ , together with a Colonyzer.txt file appropriate for analyzing them, and a Colonyzer output file for each image.  Please read the included Colonyzer.txt file for instructions on how to create your own.

The ColonyzerParametryzer script can help you produce your own version of Colonyzer.txt for large numbers of files with different spot locations.

Colonyzer is a Python script, so you will need a local Python installation to get it to run.  It also relies on several libraries, which you will need:

Python Imaging Library
Numerical Python (NumPy)
RPy

RPy also requires a local R installation, and uses the R library rgenoud.

To use ColonyzerParametryzer (optional) for your own images, you will additionally need PyGame.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Requirements (all freely available open source software, which can be installed on most operating systems):

Python				http://www.python.org/
Python Imaging Library		http://www.pythonware.com/products/pil/
Numpy				http://numpy.scipy.org/
R				http://www.r-project.org/
RPy				http://rpy.sourceforge.net/
rgenoud				http://cran.r-project.org/web/packages/rgenoud/index.html
PyGame (optional)		http://www.pygame.org/
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Installation Instructions (assuming you have none of the required packages installed):

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

First install Python.  You should be able to find an installation file appropriate for your CPU (64 bit: x64 or 32 bit: i386) and operating system here:

http://www.python.org/download/

If you are using Windows, you should install the version of Python for Windows extensions appropriate for your CPU & version of Python from here:

https://sourceforge.net/projects/pywin32/

Now install the version of the Python Imaging Library appropriate for your operating system and version of Python from here:

http://www.pythonware.com/products/pil/

Now install the version of Numerical Python appropriate for your CPU, operating system and version of Python from here:

http://sourceforge.net/projects/numpy/files/

Now install the latest version of R appropriate for your operating system here.  Be careful choosing an r version compatible with rpy (below):

http://www.r-project.org/

Install the rgenoud R library either from .zip file (windows) or from within R (depends on internet proxy settings being correct).

Assuming your installation of R can connect to the internet, simply execute the following command from within R to install:

install.packages("rgenoud",lib=.libPaths()[2])

The argument lib=.libPaths()[2] is to ensure that this package is installed to your native R directory.  This is necessary so that RPy can find it.

Now install the correct version of RPy for your operating system, version of Python and version of R from here:

http://sourceforge.net/projects/rpy/files/

NOTE for mac users: you may have to install RPy via Fink instead.

If you have multiple version of R installed, you may have to adjust the Colonyzer.py script, to point RPy at the correct one.  Simply uncomment these
two lines at the top of the script:

from rpy_options import set_options
set_options(RHOME="C:\\Program Files (x86)\\R\\R-2.9.1\\")

replacing C:\\Program Files (x86)\\R\\R-2.9.1\\ with the path to your R installation directory.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A note on package versions for Microsoft Windows installations:
The most difficult part of the above installation is getting the R->Python connection working correctly via RPy.  As of 31st August 2011, the most
up-to-date version of RPy is only compatible with R-2.12.1.  Generally it is worth checking how recent the latest R version compatible with RPy is
and installing that version of R.  Currently the best version numbers for 

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Using Colonyzer

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Hopefully, at this stage you should be ready to go!  Simply place Colonyzer.py in a directory containing .jpg images of plates, with an appropriate Colonyzer.txt file, and execute Colonyzer.py.  Under Windows for example, this can be achieved by just double-clicking on Colonyzer.py, or by switching to the command-line, navigating to the directory containing the images and the script, and typing:

python Colonyzer.py

This method has the advantage of displaying any error messages which can help with troubleshooting.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Disable automatic thresholding or lighting correction

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can disable automatic thresholding by editing the Colonyzer.py file (with any text editor for example) and changing the line:

fixThreshold=-99

so that fixThreshold is a threshold value between 0 and 255.  

You can also disable lighting correction by changing the line:

lightCorrect=True

to:

lightCorrect=False

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Colonyzer Output

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Colonyzer outputs tab-delimited text files (*OUT.dat) to the directory containing the Colonyzer.py script.  Each of the columns contains:

FILENAME ROW COLUMN TOPLEFTX TOPLEFTY WHITEAREA(px) TRIMMED THRESHOLD INTENSITY EDGEPIXELS COLR COLG COLB BKR BKG BKB EDGELEN XDIM YDIM

Where TOPLEFTX/Y are the coordinates of the top left hand corner of the current tile, WHITEAREA is the thresholded culture area, TRIMMED is the culture IOD, THRESHOLD is the thresholding intensity for the lighting corrected image, INTENSITY is the summed pixel intensity over the entire tile (less the median background value), EDGEPIXELS is the number of culture pixels touching the edge of the tile, COLR, COLG, COLB are the RGB components of the mean culture colour, BKR, BKG, BKB are the RGB components of the mean background colour, EDGELEN is the number of pixels in the gradient mask for this tile, XDIM and YDIM are the x and y dimensions of this tile.

Colonyzer also outputs lighting-corrected versions of the original images, and thresholded versions of those images.  Tile locations are marked in these by coloured rectangles.  Colonyzer also generates a directory containing each tile image individually cut out.  These image outputs allow for rapid visual confirmation that Colonyzer is performing well.

Colonyzer also produces diagnostic thresholding histogram images as a visual verification that the Gaussian segmentation algorithm is working.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Auxiliary Scripts

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ColonyzerParametryzer script is not necessary to use Colonyzer, but is provided as a convenient tool for generating initial guesses for spot locations visually.  

DEPRECATED - Use qfa.R instead: https://r-forge.r-project.org/projects/qfa/
ColonyzerLogisticyzer is a script for analyzing the results of timecourse experiments and summarising the observed cell density timecourse with a logistic growth model.  It currently depends on Colonyzer output which has been modified by a third-party tool called ROD (Robot Object Database) which is still under development.