-
Notifications
You must be signed in to change notification settings - Fork 68
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!
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.
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-
- Search the core repository for your setting name
- Check the module(s) in CellProfiler that you know use a similar type of setting, and see how it is implemented there.
cellprofiler.setting.NONE -> "None"
cellprofiler.setting.NO -> "No"
cellprofiler.setting.YES -> "Yes"
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
cellprofiler.setting.Choice -> cellprofiler_core.setting.choice.Choice
cellprofiler.setting.MultiChoice -> cellprofiler_core.setting.multichoice.MultiChoice
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
cellprofiler.setting.ImageNameSubscriber -> cellprofiler_core.setting.subscriber.ImageSubscriber
cellprofiler.setting.ObjectNameSubscriber -> cellprofiler_core.setting.subscriber.LabelSubscriber
cellprofiler.setting.DoSomething -> cellprofiler_core.setting.do_something.DoSomething
cellprofiler.setting.RemoveSettingButton -> cellprofiler_core.setting.do_something.RemoveSettingButton
cellprofiler.setting.AlphanumericText -> cellprofiler_core.setting.alphanumeric.Alphanumeric
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
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__
)
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.