DIPY Coding Style Guideline

Coding style

DIPY uses the standard Python PEP8 style to ensure the readability and consistency across the toolkit. Conformance to the PEP8 syntax is checked automatically when requesting to push to DIPY. There are software systems that will check your code for PEP8 compliance, and most text editors can be configured to check the compliance of your code with PEP8. Beyond the aspects checked, as a contributor to DIPY, you should try to ensure that your code, including comments, conforms to the above principles.

import nibabel as nib
import numpy as np
import numpy.testing as npt
import scipy as sp

import h5py

Cython coding style

DIPY recommends the use of the standard Python PEP8 style when writing Cython code.

Cython-specific syntax should follow these additional rules:

cimport numpy as cnp

# Good
cdef int n
cdef char * s
cdef double Xf[3]
cdef double d[3]
cpdef int i, j, k
cdef ClusterMapCentroid clusters = ClusterMapCentroid()
cdef:
    double *ps = <double *> cnp.PyArray_DATA(seed)
    cnp.npy_intp *pstr = <cnp.npy_intp *> qa.strides
    cnp.npy_intp d, i, j, cnt
    double direction[3]
    double tmp, ftmp
cdef int get_direction_c(self, double* point, double* direction):
    return 1

# Bad
cdef  char *s
cdef char * s, * t, * u, * v
cdef double Xf[3], d[3]
cdef double x=42, y=x+1, z=x*y
cdef ClusterMapCentroid     clusters   = ClusterMapCentroid()
cdef   int   get_direction_c(self, double* point, double* direction):
    return 0

# Good
cdef void estimate_kernel_size(self, verbose=True):
cdef:
    double [:] x
    double [:] y

# Bad
cdef void estimate_kernel_size(self, verbose=True):
    cdef double [:] x
    self.kernelmax = self.k2(x, y, r, v)
    cdef double [:] y
    x = np.array([0., 0., 0.])

from libc.stdlib cimport calloc, realloc, free

# Good
cdef void bar() except *
cdef void c_extract(Feature self, Data2D datum, Data2D out) nogil except *:
cdef int front(x) except +:
    ...

# Bad
cdef char * hat(x) except *:
cdef int front(x)    except   +  :
    ...

# Good
cdef int& i
cdef char * s
i = &j

# Bad
cdef int &i
cdef char *s
i = & j

# Good
<float> i
<void *> s

# Bad
< float >i
<void*>  s

for i in range(nrows):
  ...

Documentation

DIPY uses Sphinx to generate documentation. We welcome contributions of examples, and suggestions for changes in the documentation, but please make sure that changes that are introduced render properly into the HTML format that is used for the DIPY website.

DIPY follows the numpy docstring standard for documenting modules, classes, functions, and examples.

The documentation includes an extensive library of examples. These are Python files that are stored in the doc/examples folder and contain code to execute the example, interleaved with multi-line comments that contain explanations of the blocks of code. Examples demonstrate how to perform processing (segmentation, tracking, etc.) on diffusion files using the DIPY classes. The code is intermixed with generous comments that describe the former, and the rationale and aim of it. If you are contributing a new feature to DIPY, please provide an extended example, with explanations of this feature, and references to the relevant papers.

If the feature that you are working on integrates well into one of the existing examples, please edit the .py file of that example. Otherwise, create a new .py file in that directory. Please also add the name of this file into the doc/examples/valid_examples.txt file (which controls the rendering of these examples into the documentation).

Additionally, DIPY relies on a set of reStructuredText files (.rst) located in the doc folder. They contain information about theoretical backgrounds of DIPY, installation instructions, description of the contribution process, etc.

Again, both sets of files use the reStructuredText markup language for comments. Sphinx parses the files to produce the contents that are later rendered in the DIPY website.

The Python examples are compiled, output images produced and corresponding .rst files produced so that the comments can be appropriately displayed in a web page enriched with images.

Particularly, in order to ease the contribution of examples and .rst files, and with the consistency criterion in mind, beyond the numpy docstring standard aspects, contributors are encouraged to observe the following guidelines:

• The acronym for the Diffusion Imaging in Python toolkit should be written as DIPY.

• The classes, objects, and any other construct referenced from the code should be written with inverted commas, such as in In DIPY, we use an object called ``GradientTable`` which holds all the acquisition specific parameters, e.g. b-values, b-vectors, timings, and others.

• Cite the relevant papers. Use the [NameYear] convention for cross-referencing them, such as in [Garyfallidis2014], and put them under the References section.

• Cross-reference related examples and files. Use the .. _specific_filename: convention to label a file at the top of it. Thus, other pages will be able to reference the file using the standard Sphinx syntax :ref:`specific_filename`.

• Use an all-caps scheme for acronyms, and capitalize the first letters of the long names, such as in Constrained Spherical Deconvolution (CSD), except in those cases where the most common convention has been to use lowercase, such as in superior longitudinal fasciculus (SLF).

• As customary in Python, use lowercase and separate words with underscores for filenames, labels for references, etc.

• When including figures, use the regular font for captions (i.e. do not use bold faces) unless otherwise required for a specific text part (e.g. a DIPY object, etc.).

• When referring to relative paths, use the backquote inline markup the convention, such as in doc/devel. Do not add the greater-than/less-than signs to enclose the path.