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 has performed a preliminary migration of CellProfiler3 plugins to CellProfiler4- these may be found in the CellProfiler4_AutoConvert folder. Note that these have not been verified to be completely migrated, nor to run- only plugins in the top folder of the repository should be considered fully CellProfiler4-compatible. Our team may complete the upgrade of plugins from CellProfiler3.X to 4.X from time to time as we have time and/or 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 finish updating 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

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.

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.

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

cellprofiler.setting.SettingsGroup -> cellprofiler_core.setting.SettingsGroup

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

Other

cellprofiler.setting.DoSomething -> cellprofiler_core.setting.do_something.DoSomething

cellprofiler.setting.RemoveSettingButton -> cellprofiler_core.setting.do_something.RemoveSettingButton

cellprofiler_core.module.Module

upgrade_setting method dropped 'from_matlab' from it's signature:
Old:

    def upgrade_settings(self,setting_values,variable_revision_number,
                         module_name,from_matlab):
    -> return setting_values, variable_revision_number, from_matlab

New:

    def upgrade_settings(self,setting_values,variable_revision_number,
                         module_name):
    -> return setting_values, variable_revision_number

Other details

Module classes need to have the same name as their .py file

In CP4 the module class does not only need to subclass form Module but also needs to have the same name as the .py file it is defined in. Upper/lowercase is ignored.

Otherwise there will be an error:

    raise ValueError(
        "Could not find cellprofiler_core.module.Module class in %s" % m.__file__
    )

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.