Guidelines for contributors

This page is intended only for people who are currently contributing code to TractoR, or who may in the future. It covers topics such as the coding conventions used by TractoR and the procedures applied for quality assurance. Those who wish to use TractoR within R, but not necessarily to contribute to the project itself, should see the page on TractoR for R users.

Coding conventions

TractoR is primarily written in a mixture of R and C++. The first of these may not be familiar to many developers. R is a high-level, interpreted, multiparadigm language with particular strengths in statistics. It is vectorised, like Matlab, and therefore encourages an array-based programming style which can perform complex transformations on substantial amounts of data very concisely. It has a simple mechanism for interfacing to compiled C or C++ code. Further details on R itself can be found in the manuals on its web site (more readable mirror here).

General philosophy and style

Data types and naming

Functions versus methods

TractoR has historically used top-level functions for creating and manipulating objects. Names of these functions tend to reflect the class being created, and a hint of their effect, as in newMriImageByMasking(), which creates an MriImage object from two other images, a base image and a mask. However, such functions will result in a new object being created, which may be wasteful for large objects such as images. There has therefore been a gradual shift towards using reference class methods to manipulate existing objects where appropriate, and in TractoR 3.0 that function has been deprecated in favour of image$mask(), which modifies the original image object. (The image can duplicated first when necessary, using image$copy()$mask().) This style should be favoured for new classes.

Tests and quality assurance

TractoR provides a small test data set and associated set of self-tests to ensure that the package is installed and working properly. These are simple shell scripts with a short self-description, which run one or more TractoR scripts. The output is compared to a stored reference output, and the test fails if they do not match. See tests/Makefile for the exact mechanism, and the contents of tests/00_Basics for example test files. Significant additions to TractoR should be accompanied with one or more new tests, which can be added to the relevant subdirectory of tests, followed by running

cd tests
make create-tests

Before the release of a new version of the package, it should be possible to run all of the tests cleanly, without any failures. Since the tractor.base R package is released on CRAN, it should also be possible to run

R CMD check --as-cran tractor.base

without generating any warnings or errors. Any issues raised by any of these quality assurance processes need to be addressed before release. Typical issues are changes in the output of a particular script, which may result in failure of one of the tests; or changes to the arguments of a function exported from the tractor.base package, which will require a corresponding change to the package documentation.

If a test is failing for reasons which are definitely benign, such as an intended change to the output of a script, the reference output may be regenerated using, for example,

cd tests
make -B 00_Basics/

The updated file(s) will then need to be checked in with git.