Good enough practices in scientific computing

Three years ago, Greg Wilson of Software Carpentry fame, along with fellow members of the Software Carpentry Community, published an article entitled Best Practices for Scientific Computing. This article is a great reference and covers all aspects of scientific computing. However, the paper could be intimidating to novices. To remedy this, Greg Wilson et al. recently published a follow-up paper entitled Good Enough Practices in Scientific Computing, which aims to present a set of “good enough” practices that represent a minimum set of tools and techniques that they believe every researcher can and should adopt.

The authors emphasize that these recommendation are primarily to help your most important collaborator, your future self. Importantly, they also acknowledge that change is hard and that if researchers do not quickly see the benefits of adopting these recommendations, they will likely revert back to their old practices. Thus, the early benefits need to outweigh the pain that comes with learning a new way doing things.

Wilson and colleagues make the following recommendations to researchers:

Data Management

  1. Save the raw data.
  2. Create the data you wish to see in the world (file formats, variable names, filenames, etc).
  3. Create analysis-friendly data.
    1. Make each column a variable.
    2. Make each row an observation.
  4. Record all the steps used to process data.
  5. Anticipate the need to use multiple tables.
  6. Submit data to a reputable DOI-issuing repository so that others can access and cite it.

Software

  1. Place a brief explanatory comment at the start of every program.
  2. Decompose programs into functions.
  3. Be ruthless about eliminating duplication.
  4. Give functions and variables meaningful names.
  5. Make dependencies and requirements explicit.
  6. Do not comment and uncomment section of code to control a program’s behaviour.
  7. Provide a simple example or test data set.
  8. Submit code to a reputable DOI-issuing repository.

Collaboration

  1. Create an overview of your project.
  2. Create a shared public “to do” list.
  3. Make the software license explicit.
  4. Make the project citable.

Project Organization

  1. Put each project in its own directory, which is named after the project.
  2. Put text documents associated with the project in the doc directory.
  3. Put raw data and metadata in a data directory, and files generated during cleanup and analysis in a results directory.
  4. Put project source code in the src directory.
  5. Put external scripts, or compiled programs in the bin directory.
  6. Name all files to reflect their content or function.

Keeping Track of Changes

  1. Back up (almost) everything created by a human being as soon as it is created.
  2. Keep changes small.
  3. Share changes frequently.
  4. Create, maintain, and use a checklist for saving and sharing changes.
  5. Store each project in a folder that is mirrored off the researcher’s working machine.

Manual Versioning.

  1. Add a file called CHANGELOG.txt to the project’s doc subfolder.
  2. Copy the entire project whenever a significant change has been made.

Version Control System.

  1. Use a version control system.

Manuscripts

Instead of an email-based workflow, try to make writing scalable, collaborative, and reproducible. Wilson et al. point out that the workflow you choose is less important than having all authors agree on the workflow before writing starts.

  1. Write manuscripts using online tools with rich formatting, change tracking, and reference management (e.g., Google Docs).

or

  1. Write the manuscript in a plain text format that permits version control.

Manuscript writing.The recommendation for writing manuscripts in plain text formats will likely be met with resistance by some collaborators. People are attached to the graphical user interface word processors and various tools such as reference managers. Wilson et al. make some good points on the issue of manuscript writing, and also include feedback provided to them by reviewers.

Summary

The recommendations put forth in this paper are simple and to the point. However, their implementation does require some effort and planning. Rather than get overwhelmed by how many recommendations there are, consider reading through a section and implementing those in your next project. Or select a few of the lowest hanging fruit—the easiest recommendations to implement—to start with.

At a broader level, institutions, universities and granting agencies will value the importance of good computing practices and support their researchers with training opportunities.

 

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s