Guidelines for contributing can be found in the Contributing document in the CellProfiler repository. Here, we provide guidance for understanding CellProfiler's code.

• Writing a CellProfiler module
• Module Templates
• Module Structure and Data Storage
• General Python Style Guide
• Module Help
• Buttons
• Distributing your module
• General stylistic notes
• Settings

---

You can customize CellProfiler by creating your own module, which you can then use in any pipeline. New modules can be easily run in CellProfiler as a plugin; see Distributing your Module for more details.

• If possible, include your code as an extension to a current module, such as by adding a new setting.
• If your code is not suited for any of the current modules, create a new module with the new functionality.

---

We have examples of modules that create new images (imagetemplate.py) and new measurements (measurementtemplate.py). These can be used as jumping-off points for your own module, feel free to rename them and use them as a skeleton for your own code.

---

This section will familiarize you with the class details of key data structures in CellProfiler: Module-structure-and-data-storage-retrieval.

---

The release version of CellProfiler scans its "plugins" directory for modules when it starts. You can set the directory that CellProfiler uses in the preferences dialog (File/Preferences in the menu, "CellProfiler plugins directory" in the dialog). You can also set the plugins directory from the command line with the --plugins-directory switch:

python CellProfiler.py --plugins-directory c:/my_plugins

Place your Python file in this directory and restart CellProfiler and your module will be available.

PEP8 is a "Style Guide for Python Code", which provides coding conventions that we attempt to follow.

The Module Help window (which also constitutes a section of the CellProfiler manual) is populated by the documentation string of the module's code, and contains the following:

• The module's name: This is printed as a title automatically and is not specified within the code for the module.

• Module name phrase description

  Example: Identify Prim Automatic identifies objects via thresholding and contouring

  The section begins with three single quotes. While the module's official name has no spaces, use spaces and sentence case in this case to make it comprehensible. The phrase description is something like: "identifies primary objects..." or "places outlines of objects..."

• <hr> Creates a horizontal line

• Full description/explanation of the module's function. Use headings, usually level < h2 >, when needed

  When providing an overview of major capabilities of the module, options for a given setting should be placed in an unordered list, although this should be rare because usually it would be redundant with the help for the individual setting. Each list item should start with the option name in italics, followed by a colon, then the option description. For example:

To use this module, the following options are available:

• Option 1: Blah, blah...
• Option 2: Blah, blah...

• Features that can be measured by this module: Provide as an unordered list, like this

• First measurement: Description of first measurement
• Second measurement: Descrption of second measurement

*:This creates a bulleted list of measurements that the module can make. We say "can" because depending on the user's settings, not all measurements will be made by a module during a run. We will eventually make modules self-aware so that the list of possible measurements that can be made will be generated by the code of the module itself.

• See also: OtherModuleName: Other relevant/related modules are listed here
• ''' (end quotes): ''' The general module help section ends with three single quotes
• License information follows and is commented out using #
• Help for each available setting for the module: this text is automatically extracted from the documentation strings for each setting and hence does not need to be written out here.

Buttons which add or remove items should follow the form "Add another [item]" if adding and Remove this [item] if removing, where [item] is Object, Image, Measurement, etc.

Buttons should have a minimum width of 30 pixels to look good on the Mac.

• Other module names that are mentioned in the help should be bold . We will add hyperlinking function to go the other module's help eventually.
• References/citations that are mentioned should be '''' italicized ''''

In general, settings descriptions (which are displayed to the user in the GUI) should be:

• Concise. For example, Enter the threshold scaling factor should be Threshold scaling factor
• Punctuation-free, except for question marks. E.g., no colon at the end of the setting descriptions
• No personal pronouns (e.g., "you") in the settings description, although they are permissible in the Help
• Rules of thumb:
  • If the setting is a checkbox, the setting description is most likely a question.
  • If the setting is an edit box, the setting description is most likely a phrase with no helper text (e.g., "Radius, in pixels"); using the phrase "Enter the..." only if needed for clarity.
  • If the setting is a plain menu, the setting description most likely begins with Select (e.g., "Select the thresholding method") especially if it's unclear whether the question is asking about a property of your existing images/situation (in which case, you're less likely to use "Select") or whether it's giving you an option to choose among options that are equally valid (in which case, you're more likely to use "Select").
  • If the setting is a menu + an edit box, the setting description most likely begins with Select.

Some common standardized settings descriptions:

• Select the input image, or for measure modules, Select an image to measure or Select objects to measure
• Name the output image (the Help for this setting would be more wordy, beginning like: "What do you want to call the image with text markings that is displayed by this module?")
• Name the identified objects
• ''Add another image ''
• ''File output location ''
• ''Retain the [DESCRIPTION] image for use later in the pipeline (for example, in SaveImages)? ''
  • This is followed by a contingent setting: Name the [DESCRIPTION] image

For cases where objects are identified and outlines can be retained, the following text goes in the main help:

• Special note on saving images: Using the settings in this module, object outlines can be passed along to the module OverlayOutlines and then saved with the SaveImages module. The identified objects themselves can be passed along to the object processing module ConvertToImage and then saved with the SaveImages module.

In the main help, the last annotation prior to the setting help is if there are related modules that the user should be referred to. If so, list them as "See also [module_name1],[module_name2], ..." with the module names in bold.

If the appearance of a setting is contingent on another setting, include text in the help stating what the setting depends upon. For example:

• In LoadImages, if the "Extract metadata from the file name?" setting is checked, then an additional setting appears so the user can specify the metadata.
• The Help for this additional setting should start with: "(Used only if metadata is extracted from the file name)" followed by a line break, followed by the rest of the docstring

The text for each setting's help is grabbed from the module's code, where it looks like this: def create_settings(...):

  self.foo = cps.Bar("Quox", True, doc = '''          Setting help is here bla bla,          bla bla bla           bla bla''')

Note that the text for the setting is indented to line up at least after the period within self.foo.

The Help uses the settings definition (which returns the settings in the order that they are saved/loaded) to order the help items, and the visible_settings definition to control the display order in the main GUI. If the Help items needs to be ordered in a different way than the settings, use the help_settings definition to describe the order.