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 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.