Guidelines for contributors

Thank you for willing to contribute with your work and time to the community!

In this page, you will find guidelines for coding, data types, and Jupyter notebook narrative, so that we can make our code consistent across workflows

Take the time to document your code! Code without documentation is rarely reused and hard to understand. Documentation is as important as code itself!

Coding guidelines

Naming Style

  • Variables, functions, methods, modules, packages:

  • Constants:

  • Classes and exceptions:



  • 4 spaces or 1 tab


  • Leave space between operators in case of assignment and arithmetic operations:

    var = 4
    result = var * 5
  • Leave space after a comma:

    var1, var2 = get_values(num1, num2)


  • Comments are introduced by #, are above the code they refer to, and are indented as the code they refer to:

    # assign variable
    a = 5

Why are comments important? As part of a community we want to write code that can be readable and reusable by others. Be generous and precise with your comments!


Explanations below the example:

def my_function (input1, input2):
    """This functions does ... .
    x : type
        Description of the parameter `x`.
    y : type
        Description of the parameter `y`.
    output: int
        Description of the variable `output`
    # function body
    return output

The function documentation is right below the function header, and it is in between three opening and three closing single quotes ''' or double quotes: """. It is composed of 3 parts:

  1. Description of what the function does. It is written right next to the opening quotes

  2. Parameters, i.e. inputs of the function. It contains:

    • Parameters as a title, underlined by minuses

    • A list of parameters. For each parameter, we write:

      • Parameter name, colon (:), and parameter type (string, list, ITKimage, etc.)

      • On the following line, indented description of the parameter

  3. Returns, i.e. outputs of the function. It contains:

    • Returns as a title, underlined by minuses

    • The list of returns, using the same structure as for parameters

    • Special cases:

      • It the function does not return any variable, we omit the whole Returns section

      • If the function does not return a variable but the output of another function, we omit the variable name, as in this example:

        Integer component of the variable float_variable
  • Why is documentation important?
    These comments decleared in between triple double quotes (""") are called docstrings. And they are used:

    • By users to know what the function does by typing help (my_function)

    • To create whole code documentation using, for example, pydoc or Sphinx, where you get a list of all the functions in a package, and their documentation

Classes, Modules, Packages

Coming soon!

Data types

  • Images:

    • Our pipelines usually start with .dcm images for CT/MR acquisitions or .isq images for µCT/HR-pQCT acquisitions

    • Images are then transformed into other file formats for simplicity

  • Meshes and point clouds:

    • From images, we often extract point clouds and/or meshes

  • Here are the recommended types for images, meshes, and point clouds:

Data type

Data representation

file format


ITK / SimpleITK / VTK / Numpy array / Zarr

.dcm / .mha /. (more to be added)





VTKPoints / Numpy array


Notebook narrative

One of the main strengths of Jupyter notebook is the integration of code with narrative. Sharing notebooks without narrative highly reduces the understanding of a workflow

We recommend using the ORMIR notebook template, which is based on the following structure:

  1. Title section: It can contain:

    • Notebook title

    • Author name(s) and year

    • Text and code license (If you are not familiar with licenses, watch this video)

  2. Aims: Description of the notebook purpose. It can include aims, table of content, description of data, etc.

  3. Imports: List of package and module imports

  4. Constants and variables: List of constants and variables used in the code

  5. Reading, processing, and saving data: Computational core of the workflow. Use:

    • Markdown narrative to indicate what each step does and to comment results

    • Python comments to describe what the code does

  6. Dependencies: Print out of computer characteristics and software versions to favor reproducibility

    • If using watermark (installation: pip install watermark), convenient commands are:

      • %load_ext watermark: to load the extension

      • %watermark: to print out your computer characteristics

      • %watermark --iversions: to print out the versions of the used packages