chlamy_clusters

Introduction

This utility analyzes microscopy images to quantify the number and size of cell clusters. This is determined by using threshold values and gaussian blurring, followed by identification of contiguous regions. The utility was written for use on a project in the King Lab at UConn Health to study Chlamydomonas; the code and concept are suitably general to be applied in other applications.

Parameters

• imageDir: source directory that contains micrscopy image files
• imageFormat: list of file extensions to process (default=['.tif'])
• grayThresh: threshold pixel value for identifying features in image (default=150, on 0-255 scale)
• blurKernel: radius of Gaussian blur (default=9)
• histogramPlots: boolean flag, when provided, generates histogram plots
• outputDir: directory for stats and figures (default='/output-blurX-threshY')

Input

Input:

    <imageDir>
    ├── KO/                 -> input images for KO (arbitrary file names)
    └── WT/                 -> input images for WT (arbitrary file names)

Output

    <imageDir>
    └── images/         -> raw images, relocated and renamed into single collection
        ├── KO-#.pdf    -> indexed KO images
        └── WT-#.pdf    -> indexed WT images
    
    <outputDir>
    ├── histograms/     -> figures showing comparitive distrubutions
        ├── KO-#.pdf    -> figure showing raw image, processed image, and histogram for each KO image
        └── WT-#.pdf    -> figure showing raw image, processed image, and histogram for each WT image
    ├── cumultive.pdf   -> lineplots and violin plots comparing cluster size distributions in WT and KO images
    ├── data.csv        -> data export for use outside chlamy_clusters 
    └── data.pkl        -> pickle file containing processed data (auto-loads)

Analysis

The cumulative.pdf gives various summary metrics on the collection of WT amd KO images. The stats show raw counting of numbers of clusters. However, since the number of cells captured in each image is not uniform, additional plots are provided, which include normalization.

Getting Started

Create a python virtual environment, activate the environment, and install chlamy-cluster:

python3.14 -m venv cc-venv
source cc-venv/bin/activate
pip3 install chlamy-clusters

Check that the software is installed by getting version number or the help dialog

chlamy-clusters -v
chlamy-clusters -h

Run the package and provide your image files:

chlamy-clusters --imageDir /path/to/your/image/files --grayThresh 150 --blurKernel 9 --histogramPlots