CellProfiler 4.0 Release: Improvements in speed, utility, and usability

David R. Stirling

We have now released CellProfiler version 4.0! Download it here.

The primary goal of this release has been to migrate CellProfiler from Python 2 to Python 3. This has involved extensive restructuring of the code base, leading to a lot of “under-the-hood” improvements.

Important Compatibility Notes

As a major release, this version contains changes to CellProfiler that will alter the behaviour of pipelines from previous versions of the software. Key points to take note of are as follows:

• The 3-Class Otsu thresholding method was calculated incorrectly in some situations and has now been fixed. In general, many of the libraries we use have updated their thresholding implementations, so thresholding settings on all upgraded pipelines should be checked and adjusted before use. This will impact the Threshold, IdentifyPrimaryObjects and IdentifySecondaryObjects modules.
• The MeasureObjectSizeShape module now uses the scikit-image implementation for most measurements. This can produce slightly different results.
• The MeasureColocalization module previously assumed that input images were in 8-bit format when performing Costes measurements. This could produce invalid results when working with 16-bit images. This has now been corrected, but these statistics can be computationally expensive on high bit depth images. Users concerned about processing speed may wish to disable running Costes measurements in the module settings.
• The MeasureTexture module now allows users to explicitly select how many gray levels they wish to measure their images at- CellProfiler 2 used 8, CellProfiler 3 used 256. Upgraded pipelines will default to 256.
• The MeasureGranularity module now analyses all selected images with the same detection settings. Multiple copies of the module can be used to specify different parameters for specific images. Upgraded pipelines will attempt to analyse all images with the first set of parameters from the old pipeline
• The MeasureImageIntensity module now measures all selected images and objects together, rather than needing the user to specify individual pairs. In upgraded pipelines this may result in extra measurements being recorded. Multiple copies of the module can be used to restrict measurements to specific images or objects.
• The “MySQL/CSV” output mode from ExportToDatabase has been removed. Similar functionality can be achieved using the ExportToSpreadsheet module instead.
• As the pipeline encoding format has changed, text fields such as custom file list filters may not import correctly if they contain non-ASCII characters. It may be best to check these before running an upgraded pipeline.
• CellProfiler 4 has been far better-tested on successfully importing CellProfiler 3.X pipelines than on 2.1-2.3 pipelines; if you encounter issues updating a CellProfiler 2.X pipeline into 4.0, consider importing first into CellProfiler 3, saving, then importing from 3 to 4.

Interface

At its core, CellProfiler is built for scientists. We’ve listened to your feedback and made adjustments to the user interface with the goal of making the software easier to use. Some major changes are as follows:

• We’ve redesigned the interface for selecting multiple image and object sets in measurement modules. The “Add another image/object” buttons and dropdown lists have been replaced with a series of checkboxes to make selection easier. This new widget will also automatically highlight invalid selections.

• The ‘Add modules’ dialog has been reworked to make finding modules faster. Typing in the ‘Search modules’ box will now display a live list of modules with names matching the entered text. As a bonus, you can also use the arrow keys and ‘enter’ key to select and add modules from this dialog.

• We’ve revised the contrast display options when viewing figures. The new contrast popup allows for brightness adjustment and changes to normalization with a live preview. We’ve also added an option to apply display settings to all figures in the window, rather than needing to adjust each plot individually.

• The 3D viewer added in CellProfiler 3.0 was somewhat limited. We’ve replaced this with a single-frame viewer accompanied by a slider to allow the user to view any plane in a volume. Normalization settings are applied across the entire volume. This also grants access to all the 2D viewer tools when working with volumes.

• The Workspace Viewer from CellProfiler 2 has returned! This feature provides a customisable preview of your results during test mode, with the ability to overlay images, objects and measurements. This preview will be maintained and updated when running a module or switching image sets. This allows you to easily monitor a region of interest while making pipeline adjustments.

• The pipeline list has also been improved. In Test Mode you’ll now find ‘step’ buttons marking modules which have been run and the next module which is set to execute. This replicates the ‘slider’ functionality from CellProfiler 2, allowing you to step back to specific modules. We’ve also refined the right-click menu to better identify the selected module and ease working with multiple modules at once. On top of this, the right-click menu now also includes a ‘step from’ option, allowing you to execute a specific module individually rather than running the entire pipeline.

• We’ve added an option to display accepted local maxima in IdentifyPrimaryObjects. This should assist with tuning parameters for segmentation of touching objects.
• We’ve revised the ‘Welcome’ screen to be a bit more welcoming.
   

Performance

While most individual modules should see comparable performance in the new release, CellProfiler’s overhead has been improved to reduce the time taken to set up and begin executing modules. Highlights include:

• File reading has been optimised to substantially speed up the process of adding images to the file list. Adding large folders of images is now much faster.
• Issues impacting MeasureTexture’s performance on objects have been resolved, this is particularly noticeable when working with large input images.
• MeasureColocalization also exhibited poor performance when working with large images. We’ve made some optimisations and also added an optional “Fast” mode which dramatically reduces processing time. Results should be identical, but the original implementation is still available for backwards-compatibility.
• The Costes measurements from MeasureColocalization now properly consider the bit-depth of input images.
• Test mode now executes more smoothly, we’ve cut back on unnecessary interface display updates.
• CellProfiler has an extensive set of help buttons and popups. We’ve made the “Search All Help” function much faster to help users find the information they’re looking for.
• CellProfiler startup time should now be improved, particularly on Windows.
• Surface area calculations on volumes now use a much faster implementation of the marching cubes algorithm.
• The MedianFilter module is now much faster, particularly when working with 3D images.

API

• Split CellProfiler package to create CellProfiler-Core. “Core” now contains the primary functionality of CellProfiler, while CellProfiler contains the user interface and non-essential modules.
• Much of CellProfiler’s core functionality is now more readily accessible within other packages such as Jupyter. See this page for more details. 

Additions

• The Threshold module has been reworked to improve speed and allow the use of all automatic thresholding methods in ‘adaptive’ mode. We’ve also added the ‘Sauvola’ adaptive thresholding method.
• MeasureObjectSizeShape has been upgraded to provide additional measurements in both 2D and 3D.
• RescaleIntensity is now compatible with color images.
• Added the CombineObjects module, which allows separately identified object sets to be combined into a single set.
• Added the ErodeObjects module and renamed Erode to ErodeImage. Alongside DilateImage/DilateObjects this allows the functionality of ExpandOrShrinkObjects to be replicated when working with 3D pipelines.
• Add option to clip the output corrected image results in CorrectIlluminationApply.
• Added option to replace NaN with 0 in ImageMath.
• Added option to ResizeObjects to resize the objects to match another image’s dimensions.
• Added optional rounding to CalculateMath.
• Added option to SaveImages to choose whether to save image series in the Z or T dimension.
• Added ability to download pipelines or CSVs from a URL.
• Added an option to include image folder and file name in objects tables made by ExportToSpreadsheet.
• Higher quality pony.

Removals

• The LoadImages and LoadSingleImages modules have been removed. These have been deprecated for a long time and didn’t play well with CellProfiler’s internal design. The LoadData module provides similar functionality in a more robust way.
• HDF5/MAT file dumping has been removed, along with the “resume pipeline” option. This did not work reliably.
• The ‘Data tools’ menu has been removed. Data tools can still be executed as individual modules, but loading files into them is no longer supported.
• MySQL/CSV mode has been removed from the ExportToDatabase module. ExportToSpreadsheet generally does a better job of this.
• Loading of .mat-format-images created by CellProfiler 1.X or 2.X is no longer supported.

Bug Fixes

Here are some of the more noteworthy bugs that are addressed in this release. Please see our GitHub issue tracker for more.

• MeasureObjectNeighbors now properly supports measuring distances between different sets of objects.
• The 3-Class Otsu thresholding has been corrected. The original implementation had a tendency to produce lower thresholds than expected.
• We’ve added a more robust approach for finding the correct Java installation on Windows.
• CellProfiler will now attempt to display a more informative message and instructions when Java installation problems are detected.
• EditObjectsManually now more reliably selects objects which the user clicks on.
• Fixed a crash when using the LAP tracker in TrackObjects.
• The ‘Random image set’ option in test mode now properly initialises the new object set.
• ‘Random image group’ has been added as an option in the test mode menu.
• Metadata extraction from image file headers should now be more reliable. CellProfiler will try to keep track of whether extraction has been performed correctly and will alert users if extraction is needed.
• Modules which display the same object set multiple times will now use the same colormap.
• Object sets with very large numbers of objects will now display with a properly randomised colormap.
• Figure axes labels and titles will no longer overlap with other figures.
• Displayed figures from the Crop and Resize modules no longer have their zoom levels linked. This should make the results of the transformation more obvious.
• Fixed a bug on Mac where dragging modules in the pipeline list would duplicate them. Holding ‘Control’ when dragging can be used to duplicate modules.
• ImageMath will now ‘subtract’ boolean images more sensibly.

Contributors

The following users contributed to the CellProfiler 4.0 release — we’re very grateful for all their help!

Mark Bray, Madison Bowden, Anne Carpenter, Tommy Carozzani, Beth Cimini, Jan Eglinger, Allen Goodman, Nasim Jamali, Maxim Lippeveld, Alice Lucas, David Stirling, Vito Zanotelli.