Guidelines for contributors

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¶

In this page, you will find a summary of our coding guidelines. They are derived from established coding guidelines:
- For variable naming and style, we follow the coding guidelines of the Python community
- For function and class documentation, we follow the NumPy guidelines

Naming Style¶

Variables, functions, methods, modules, packages:
```
lower_case_with_underscores
```
Constants:
```
ALL_CAPS_WITH_UNDERSCORES
```
Classes and exceptions:
```
CapWords
```

Indentation¶

4 spaces or 1 tab

Space¶

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¶

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!

Functions¶

Explanations below the example:

                                                def my_function (input1, input2):
    
    """This functions does ... .
    
    Parameters
    ----------
    x : type
        Description of the parameter `x`.
    y : type
        Description of the parameter `y`.
    
    Returns
    -------
    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:

Description of what the function does. It is written right next to the opening quotes
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
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:

                                                    Returns
    -------
    int
        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
Image	ITK / SimpleITK / VTK / Numpy array / Zarr	.dcm / .mha /. (more to be added)
Mesh	VTK	.vtk
Points	VTKPoints / Numpy array	.vtk

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:

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)
Aims: Description of the notebook purpose. It can include aims, table of content, description of data, etc.
Imports: List of package and module imports
Constants and variables: List of constants and variables used in the code
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
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