Goal - literate programming

When we communicate scientific research, we want to be unambiguous, clear, concise, and transparent. When we write a paragraph or a paper, we want the ideas to stand on their own, supported by clearly sourced evidence. When we communicate through statistical or dynamical modeling, we want the ideas and the code to stand on their own, and be supported by relevant data or other information.

Write code that stands on its own is called “literate programming.” Just as we would like to give a friend an article we wrote and have them be able to read and understand it, so too with computer code. We would like to say, “Here. Run this, and see what you think.” That is the power of a scripted language like R – it can contain everything you need to run and to understand what was done.

A few tricks for a 672 script

Make sure that your script includes

  • comments that explain briefly each part,
  • loads necessary packages, (but does not install them); if an unusual package is necessary, provide comment at the beginning that instructs a user to install that package.
  • data, or code to load (or “read”), data if it is used.

Scripts, directories, and data

In general, assume the user will put the script and any necessary data into the same directory or folder. If you use data or more than one script, include a comment at the beginning explaining that.

For example, a person’s first script, “script1.R”, might look

# Modeling lake ecosytem fluxes 
# 4 April 2018
# Johnny Smith, Miami University

# To run this script, you will also need  the data file called
# envData.csv and the script named hiddenScript.R. Make sure to put
# this script, hiddenScript.R, and envData.csv in the R working
# directory.

# this script uses these packages
library( deSolve )
library( ggplot2 )
library( tidyr )

# more comments........
# code, etc.

# load data
envData <- read.csv("envData.csv")

# run a separate script
source("hiddenScript.R")

# the rest of my code follows below....

Testing your script

Test whether your script runs independently. Start by wiping your R environment clean that is removing all objects:

rm( list=ls() ); source("myScript.R")

This will remove the objects in the list (rm(list = )), and the objects are everything listed in my working environment (ls()).