ColonyPy

Overview

ColonyPy automates the counting and classification of fungal colonies on petri dish images. It uses a trained StarDist deep-learning model to detect individual colonies, measures their size, and classifies each colony as either:

• Tolerance smaller than the control-derived 25th percentile (p25) colony size (grows under drug pressure)
• Heteroresistance same size or larger than the control p25 (potentially resistant sub-population)

The classification threshold is derived automatically from a matching control plate (no drug) of the same strain. A control plate is required for every strain; there is no manual or default threshold. Every image is reviewed in the Manual Editor before its result is saved.

Launching ColonyPy

ColonyPy is distributed as a standalone executable built with PyInstaller. No Python installation, no command line, and no internet connection are required on the user's machine. Everything including the trained StarDist model and all dependencies is bundled inside the executable.

Imaging Requirements

For reliable colony detection, images must match the conditions used to train the StarDist model. Deviation from these conditions will reduce detection accuracy.

ChemiDoc Export Settings

When exporting from the ChemiDoc Image Lab software, use these exact settings:

1. Select File → Export Image
2. Set image size to Medium
3. Resolution: 300 DPI
4. Format: JPEG (high quality), PNG or TIFF (use JPEG or PNG for control plates; see File Naming)
5. Do not apply any post-processing filters before export

Adjusting Exposure for Different Media

0.9 seconds is the standard exposure and should work correctly for the vast majority of plates. Only consider adjusting if you image a plate and observe clearly poor contrast. For example colonies that are nearly invisible, or a background so bright that colonies cannot be distinguished. If adjustment is needed, stay within the 0.8–1.5 second range and use the reference images below as your target.

Reference Images, What Good Contrast Looks Like

Use these images as a visual benchmark when setting your exposure. Both were acquired on a Bio-Rad ChemiDoc with Coomassie Blue lighting.

Disk Diffusion Plate

Good contrast: dense uniform colony ring clearly visible against a dark ZOI interior. Individual colonies are distinguishable as separate white dots at the outer edge. The antifungal disk appears as a bright white central circle.

Agar dilution Plate

Good contrast: colonies appear as bright, well-separated white spots on a uniformly dark background. Colonies near the rim are fully visible. No blown-out regions or bright background patches.

What Bad Contrast Looks Like. Do Not Use

Images like these will produce poor detection results:

Uneven Lighting, Agar Dilution Plate

Colonies are visible but uneven lighting for example brighter near the rim, lighter patches in the plate, causes inconsistent thresholding and missed or false-positive detections.

Confluent Growth, Disk Diffusion Plate

Uneven lighting with lighter patches in the ZOI causes false positive detection.

Good Practice Guidelines

Inoculum Preparation

Recommended practice:

• Optimise inoculum concentration so that colonies on the control plate are well-separated
• Control plates should produce distinct, non-overlapping colonies across the whole plate
• Aim for 100–500 countable colonies per plate
• During testing, if the ZOI shows a lawn, dilute the inoculum and repeat

Plate Preparation

• Use standard 90 mm round petri dishes. Disk detection is tuned for 90 mm plates; for other sizes set Plate Diameter in the Setup tab and check every disk and plate boundary in the editor
• Ensure the tray is clean before imaging. Residue on the tray creates bright spots that may be detected as colonies
• Place only one plate per image. ColonyPy analyses one plate per image file
• Remove the plate lid before imaging
• Ensure the plate is upright, resting on its bottom, with the agar surface facing up
• Do not image plates with writing on the bottom or along the sides, as markings interfere with analysis
• Ensure the plate is centred and fully in frame with no shadows cut across it

Critical: Plate Cleanliness

• The agar surface, plate rim and plate bottom must be free of artefacts, bubbles, condensation, or media residue. Any dark marks near the plate edge can disrupt the plate-boundary detection algorithm.

Re-run and Overwrite Policy

Installation

System Requirements

• Windows 10/11, macOS 12+, or Linux (Ubuntu 20.04 or newer, or an equivalent recent Linux distribution)
• 4 GB RAM minimum (8 GB recommended for large batches)
• No internet connection needed to run ColonyPy

Step-by-step Setup

1. Download the ColonyPy package for your operating system
2. Unzip or extract the file to a location of your choice (e.g. Documents/ColonyPy)
3. Double-click the executable to launch. See Launching above for platform-specific instructions

ColonyPy.exe          ← double-click to launch
USER_MANUAL.html      ← open in browser

ColonyPy.app          ← double-click to launch
USER_MANUAL.html      ← open in browser

ColonyPy/             ← folder containing the binary
  ColonyPy            ← run this
USER_MANUAL.html

Overall Workflow

File Naming Convention

Correct file naming is essential for ColonyPy to match control plates to test plates of the same strain and to group replicates for statistics.

• Control plates must end with _C (case-insensitive) immediately before the file extension. A replicate number is optional: KN99_rep1_C.jpg also works, but KN99_C.jpg is sufficient. A file without _C is always treated as a test plate.
• Test plates must contain _rep{n} followed by the condition, e.g. KN99_rep1_FLC.jpg. The replicate number and condition are what group replicates in REPLICATE_STATISTICS_*.csv. A test plate without _rep{n} is either refused (its strain cannot be matched to a control) or analysed without replicate and condition information and left out of the replicate statistics.
• How the strain is read: the strain is everything before _rep. For example, the strain in KN99_rep1_FLC.jpg and KN99_C.jpg is KN99, so the two match. A leading plate number of one or two digits is ignored (3_KN99_C.jpg → KN99).
• Avoid strain names that contain the letters ug (e.g. Bug1), because ColonyPy treats a part containing ug as a drug concentration and stops reading the strain name there.
• Supported formats: .jpg, .jpeg, .png, .bmp, .tiff, .tif. For control plates, use .jpg, .jpeg or .png: a TIFF or BMP control is not recognised as a control when it is re-detected after a boundary adjustment in the editor.

What happens when a control plate is missing?

The behaviour is the same in disk diffusion and agar dilution mode. For each test plate whose strain has no matched control:

• The log shows ❌ No control plate found for strain 'X' … Skipping X
• A dialog titled Disk Not Detected appears, asking whether to skip and continue. This dialog is shown for a missing control even in agar dilution mode, and even when the disk was fine. Check the log for the real reason.
• Yes skips that image (nothing is written for it) and continues. No stops the whole run.

If the folder contains no control plates at all, this happens for every test image.

Setup Tab Step by Step

The Setup tab is the first tab you see when ColonyPy opens. Configure everything here before running analysis.

1. Directory Selection

1. Click Browse… next to Input Directory (Images) and navigate to the folder containing your plate images
2. Click Browse… next to Output Directory (Results) and select or create a folder where results will be saved

2. Analysis Method

Select the method matching your experimental setup:

Control plates are always analysed as full plates (no disk, no ZOI), whichever method is selected.

3. Parameters

4. Colour Configuration

Set the colours used in the PDF output for tolerance colonies, heteroresistance colonies, the plate boundary, the ZOI boundary and the antifungal disk. Click any colour button to open the colour picker. Three presets are available: Default Dark Vibrant

These colours do not change the Manual Editor, which always uses the default colours. Control-plate colonies are always drawn in orange.

5. StarDist Status

At the bottom of the directory section you should see ✅ StarDist ready , bundled model loaded automatically. If StarDist cannot be loaded, ColonyPy shows an error when it starts and closes. See Troubleshooting.

Analysis Tab Step by Step

Pre-Analysis Check

The Analysis tab shows four green ticks when everything is ready:

• ✅ Input directory selected
• ✅ Output directory selected
• ✅ Analysis method chosen
• ✅ Images found in directory

If any item shows ✗, go back to Setup and correct it. Click Refresh Check to revalidate after making changes. Start Analysis stays disabled until all four checks pass.

Analysis Options

Enhanced Detection is not on this tab. It is set per plate in the Manual Editor; see Enhanced Detection.

Starting Analysis

1. Click Start Analysis
2. A confirmation dialog explains that every image will be reviewed manually. Click OK to begin or Cancel to return. Every run uses manual review; there is no fully automated mode.
3. If the output folder already has disk diffusion results for some of the images, you are asked whether to resume. See Resuming below.
4. Control plates are processed first, then test plates. For each image, the automated analysis runs and then the Manual Editor opens (window title Manual Review {image} (n/N)). Review the result and click Save & Continue to Next Image.
5. Watch progress in the log area.
6. When the last image is saved, the batch summary and replicate statistics are written and the Results tab opens automatically.

To halt a running analysis, click Stop Analysis. The run stops after the image currently open in the editor is closed. Images you have already saved stay saved, and a batch summary is written for them.

Resuming an Interrupted Analysis

When you start a run, ColonyPy looks in colony_analysis_results.csv in the output folder. If some images already have a row there, it asks Resume Session?: YES skips those images, NO processes everything again.

Results Tab

After a run, the Results tab lists every saved image with Total, Tolerance, Heteroresistance, Tol /mm², Het /mm², Tol/Het and ZOI mm (density and ZOI columns apply to disk diffusion only). Buttons:

• Open Results Folder opens the output directory
• Export to CSV saves the table shown to a CSV file of your choice
• Clear Results clears the table (files on disk are not touched)

Menus

Manual Editor, Complete Guide

Opening the Editor

• During analysis: opens automatically after each image has been analysed
• Reviewing a saved image: Tools → Load Editing Session (see Re-opening Sessions)

The editor cannot be opened on a new image outside an analysis run; every image is first analysed through Start Analysis.

Editor Interface

The editor shows the original image on the left and the analysis result on the right, with controls in the left panel: Edit Tools (modes), action buttons, Mode Instructions, Zoom Controls and live Statistics. During a run, an Analysis Results box shows the automated count, the current count and the number of corrections. Use the mouse wheel or Zoom In / Zoom Out / Reset to zoom, and View Mode to drag the image around.

Editing Modes

Workflow Buttons (during an analysis run)

Enhanced Detection

Enhanced Detection makes StarDist more sensitive to dim, small or densely packed colonies. It is off by default and is a per-plate decision, available for disk diffusion, agar dilution and control plates.

1. In the editor, tick ⚡ Enhanced detection
2. Click 🔬 Re-Detect (StarDist); the setting only takes effect when detection is re-run
3. Check the result. If colonies are being split or false positives appear, untick the box and re-detect again

Manual Boundary Adjustments

Occasionally the automatic boundary detection is imprecise. You correct it directly on the image, then re-detect colonies. The editor has no sliders; boundaries are moved and resized with the mouse (and arrow keys for the disk and ZOI).

Adjusting the ZOI Boundary and Disk (Disk Diffusion)

The ZOI (Zone of Inhibition) boundary is the yellow dashed circle around the disk; colonies are counted between the disk and this circle.

1. Select Adjust Disk/ZOI mode. The status bar tells you what is under the cursor.
2. Resize the ZOI: click on the yellow circle and drag outwards to expand or inwards to shrink it.
3. Resize the disk: click on the edge of the grey disk and drag until it matches the physical disk.
4. Move the disk: click near the disk centre and drag; the ZOI moves with it.
5. Fine-tune with the arrow keys (in this mode): ↑ / ↓ enlarge or shrink the ZOI, → / ← enlarge or shrink the disk. Each press is 1 pixel; hold Shift for 5 pixels.
6. Click 🔬 Re-Detect (StarDist) to count colonies with the new boundaries.

Adjusting the Plate Boundary

The green circle should sit precisely on the inner edge of the petri dish rim. If it is too large (picking up false colonies on the rim) or too small (missing edge colonies):

1. Select Adjust Plate mode
2. Click on the green circle and drag inwards to shrink it (excludes more rim) or outwards to expand it. Click near the plate centre and drag to move it.
3. For agar dilution plates where the rim is thick or falsely bright, shrink the boundary until the green circle sits clearly inside the rim
4. Click 🔬 Re-Detect (StarDist)

Colonies within about 10 pixels of the green circle are not counted. In disk diffusion, the plate boundary limits how far the ZOI can be enlarged but does not otherwise affect the count.

Re-detection

Clicking 🔬 Re-Detect (StarDist) asks for confirmation, then replaces all current colonies with a fresh StarDist detection. Manual edits made before re-detecting are lost (Undo restores them).

• If you changed a boundary, detection runs inside your adjusted boundaries. This uses contrast enhancement only, without the reference standardisation used in the first automated run, so counts can differ slightly from the original analysis.
• If you changed nothing, the complete automatic analysis is repeated, including detecting the plate, disk and ZOI again.

Re-opening Saved Sessions

Every image you save with Save & Continue during a run has its session saved automatically in editing_sessions/ inside your output folder. You can reload any session to review or correct it.

To Load a Saved Session

1. Go to Tools → Load Editing Session
2. Navigate to your output folder → editing_sessions/
3. Select the *_session.json file for the image you want to review
4. The editor opens showing the image with the saved colonies and boundaries
5. Make any corrections, then save using the buttons in the left panel (or the editor's File menu):
   • Save to CSV/PDF asks for an output folder and replaces that image's row in the results CSV and its PDF. Choose the original output folder to update the existing results.
   • Save Session asks where to save the session file. The session in editing_sessions/ is not updated automatically; save over it if you want your changes there.
   • Export Results saves the colony list as a separate JSON file.

Re-runs and Result Overwriting

Batch summary (BATCH_SUMMARY_*.csv) and replicate statistics (REPLICATE_STATISTICS_*.csv) files are timestamped and never overwritten. A new file is created each time a run finishes with at least one saved image; each file covers only the images saved in that run.

Output Files

CSV Column Reference for colony_analysis_results.csv (disk diffusion)

CSV Column Reference for agar_dilution_results.csv (agar dilution / population profiling)

This file uses the same identification and control columns as above, but has no disk, ZOI-area or density columns. zoi_radius_mm is kept only for column-order consistency and is always N/A.

Replicate Statistics CV Thresholds

A "HIGH VARIABILITY" flag is added when the CV across replicates exceeds the threshold for that metric:

Trained StarDist Model

The bundled StarDist model was trained specifically on fungal colony images from the Nielsen Laboratory. Understanding the model architecture and training conditions helps you get the best results and interpret detection limitations correctly.

Architecture

Training Configuration

Performance

Training Image Conditions

All training images were acquired under these exact conditions:

• Light application: Coomassie Blue
• Imager: Bio-Rad ChemiDoc, white transillumination mode
• Exposure: 0.9 seconds (standard; only adjust if contrast is poor with your specific media, see Imaging Requirements)
• Size: Medium 1830 × 1646 pixels, 300 DPI, 24-bit colour, 15.5 × 12.4 cm
• Plate: Standard 90 mm petri dish

The model is expected to perform best on images that closely match these conditions. Images from different imagers, different exposure times, or different lighting protocols may give reduced accuracy.

Image Processing Pipeline

For each image, ColonyPy runs these steps:

1. Grayscale conversion
2. CLAHE contrast-limited adaptive histogram equalisation (clip limit 3.0, 8×8 tile grid)
3. Plate detection: the plate is found as the largest bright region and fitted with a circle
4. Disk and ZOI detection (disk diffusion test plates only): the disk is found as a bright, round object near the plate centre, with a circle-detection fallback. The ZOI boundary is then fitted from the radial intensity profile with logistic regression.
5. Reference standardisation (disk diffusion test plates only): the intensity profile is matched to the training dataset's mean and standard deviation
6. StarDist detection: intensities are normalised and the model detects colonies. Only colonies inside the ZOI (disk diffusion, excluding the disk) or inside the plate boundary (control and agar dilution) are kept.
7. Classification (test plates): each colony's area is compared with the matched control's p25 threshold

Troubleshooting

Frequently Asked Questions