CellProfiler 3 to 4 migration guide

(This guide is currently under construction)

CellProfiler 4.0 is our first Python3 release and has a number of under-the-hood changes, which means upgrading CellProfiler 3 pipelines to CellProfiler 4 will require some updates to your plugins to work nicely in the new systems.

The CellProfiler team may upgrade plugins from CellProfiler3.X to 4.X from time to time as we need them, but we do not guarantee maintenance of modules here in the plugins repository - that is the ultimate responsibility of the author. If you work to update a plugin from 3.X to 4.X, we encourage you to contribute your updated version back here to the repository, and/or to add to this guide to help others migrate modules more easily!

Python2 to Python3

Any aspects of your code that use Python2 syntax will not work, as CellProfiler 4 is written in Python3. Many tools and guides online have been written to guide developers in making these changes- we cannot reproduce them all here, but we find this guide helpful, and welcome others' experience in making these upgrades.

cellprofiler_core

Many of CellProfiler's backbone functionality - things like the workspace, the settings, the pipelines, etc have moved to a new package called cellprofiler_core. If you find yourself running into the error NameError: name 'cellprofiler' is not defined, the line in question throwing it may have a functionality that moved to core.

At minimum, you will commonly need to upgrade the following imports

cellprofiler.image -> cellprofiler_core.image cellprofiler.measurement -> cellprofiler_core.measurement cellprofiler.module -> cellprofiler_core.module cellprofiler.object -> cellprofiler_core.object cellprofiler.pipeline -> cellprofiler_core.pipeline cellprofiler.setting -> cellprofiler_core.setting cellprofiler.workspace -> cellprofiler_core.workspace

cellprofiler_core.setting

The setting library underwent perhaps the biggest outward-facing change in the 3->4 migration. Settings are now arranged in sections. We provide here a non-comprehensive list of setting updates.

Settings that no longer exist

cellprofiler.setting.NONE -> "None" cellprofiler.setting.NO -> "No" cellprofiler.setting.YES -> "Yes"

Settings that have just moved to core, but are not part of a larger section

In general, these are in the top folder of core/setting cellprofiler.setting.Binary -> cellprofiler_core.setting.Binary cellprofiler.setting.Divider -> cellprofiler_core.setting.Divider cellprofiler.setting.Measurement -> cellprofiler_core.setting.Measurement

Settings that are now part of the choice sections

cellprofiler.setting.Choice -> cellprofiler_core.setting.choice.Choice cellprofiler.setting.MultiChoice -> cellprofiler_core.setting.multichoice.MultiChoice

Settings that are now part of the text section

cellprofiler.setting.ImageNameProvider -> cellprofiler_core.setting.text.ImageName cellprofiler.setting.ObjectNameProvider -> cellprofiler_core.setting.text.LabelName

cellprofiler.setting.Float -> cellprofiler_core.setting.text.Float cellprofiler.setting.Integer -> cellprofiler_core.setting.text.Integer cellprofiler.setting.Number -> cellprofiler_core.setting.text.Number

cellprofiler.setting.DirectoryPath -> cellprofiler_core.setting.text.Directory cellprofiler.setting.FilenameText -> cellprofiler_core.setting.text.Filename

Settings that are now part of the subscriber section

cellprofiler.setting.ImageNameSubscriber -> cellprofiler_core.setting.subscriber.ImageSubscriber cellprofiler.setting.ObjectNameSubscriber -> cellprofiler_core.setting.subscriber.LabelSubscriber

If you find your setting is not represented here, you have a couple of options-

1. Search the core repository for your setting name
2. Check the module(s) in CellProfiler that you know use a similar type of setting, and see how it is implemented there.

Other libraries

You may encounter syntax changes in other libraries you use, such as numpy, skimage, etc. Please refer to those packages' own guides to migrate that functionality.