Principles of resilient coding for plant ecophysiologists

Principle 1: standardized nomenclature.

Names vary wildly between functions with published code and data and even amongst instruments within the same company (e.g. for net CO₂ assimilation, ‘A’ is used in the Li-Cor 6800 and ‘PHOTO’ is used in the Li-Cor 6400). Ideally, we need both standardized nomenclature in the field (e.g. Reid et al. 2005) and standardized construction of variable and function names to enhance readability and reduce the burden for learning how to use new packages and functions or testing published code. For example, g is always in reference to conductance, where a subscript term would then describe the physical pathway (e.g. s for stomata, c for cuticle or m for mesophyll) as well as the gas (e.g. c for CO₂, w for water vapour). For example, g_sw would mean stomatal conductance to water vapour. Standardizing nomenclature across both mathematical models and data files can also streamline theory–data integration, but this also requires standard translation between mathematical and computer notation, which is beyond our scope here.

For example, in {photosynthesis}, every function is named in a descriptive manner: e.g. fit_t_response fits specified temperature responses model to data, while fit_gs_model fits specified models of stomatal conductance. Variable names are also standardized: e.g. ‘T_leaf’ always means leaf temperature in Kelvin (K), ‘A_net’ always means net CO₂ assimilation in μmol m⁻² s⁻¹. In this regard, standard units should also be imposed in the analysis (e.g. in R via the {units} package; Pebesma et al. 2016), to remove any ambiguities when interpreting the output. To allow for differences in variable names from the raw data (e.g. from using different machines), the ‘varnames’ list is used to translate input names (note that this convention is adopted from {plantecophys}; Duursma 2015). We propose adopting Wickham’s (Wickham 2019) style in that functions that do something have a verb name, e.g. fit_aci_response, while functions that act as objects within other functions (e.g. stomatal conductance models) should have a noun name, e.g. gs_model.

Principle 2: consistent style.

Consistent coding style makes reading code easier—certain conventions, e.g. commenting what the next line of code does, can make it easier to understand code documentation. Our preference is for the ‘tidy style’, which applies to both data and code structure, and much else (see the The tidyverse Style Guide: https://style.tidyverse.org/). For data, tidy style advocates that each column is a variable, and each row is an observation, since R is particularly suited for this style of data structure. Popular R packages like {dplyr} (Wickham et al. 2020) and {tidyr} (Wickham and Henry 2020) facilitate tidy data and many other packages, like {photosynthesis}, use them for consistent style (Notes S3 contains an example of tidy data organization). For code, computers do not care about style, as long as it is correctly formatted, but for humans reading code, adherence to well-designed style can be helpful, especially for beginners trying to learn from others. A benefit of tidy style in particular is that R packages {styler} (Müller and Walthert 2020), {lintr} (Hester et al. 2020) and {formatR} (Xie 2019) can automate conformity to style. Ideally, a consistent style would be adopted across the field; however, this may be too rigid. Style can be highly personal, and many experienced coders likely have developed their own style, formal or informal, that works for them. Our proposal is geared for beginning coders who are looking for guidance on an established and easy-to-implement style. At the very least, a consistent style within a project will make it easier to read, understand and modify the code.

Principle 3: modularity and extensibility.

Arguably, code written for plant ecophysiologists, whether formally trained in coding or not, should be written in a modular manner, much like Lego bricks, where one component (e.g. Arrhenius function) can be easily swapped with another (e.g. peaked Arrhenius function), or extended (e.g. hypothetical mechanistic temperature response model). Note that this may increase apparent complexity of software packages by creating more functions and make it more difficult to work with at first. However, it will make adding, subtracting or modifying code modules easier for researchers who need to make on-the-fly changes to code as new biological processes are discovered or old ones re-evaluated. To achieve modularity in the structure of photosynthesis, we used principles of functional programming to develop a set of key functions for processing data and running quality control checks: fit_many, analyze_sensitivity, compile_data and print_graphs. Both fit_many and analyze_sensitivity can be run with any function within and outside of {photosynthesis} to run multiple curve fits or sensitivity analyses on assumed input parameters. Meanwhile, compile_data is used for processing the list outputs from fit_many into a form usable for further analyses and export from R, and print_graphs is used to export all graphs from a list as either .jpeg or compiled as a .pdf.

For curve fitting functions with multiple models (e.g. temperature responses, g_s models), we use a basic function (e.g. fit_t_response), which contains fitting procedures for each of the seven temperature response models in the package. Meanwhile, a t_functions file contains all the temperature response functions. To extend the capabilities and add in a new temperature response model, we simply need to add the new model to t_functions, and the fitting procedure to fit_t_response. Currently, adding new functions requires modifying the source code, but future versions should increase extensibility by allowing users to supply any temperature response function. This principle of function building increases the extensibility of the code, while consistent style and standardized nomenclature provide the rules for writing the extended components.

Modularity also applies to modelling. The {photosynthesis} functions photo and photosynthesis model C3 photosynthesis using the Farquhar–von Caemmerer–Berry biochemical model (Farquhar et al. 1980). To account for temperature dependence, a user can specify leaf temperature, or they can provide additional inputs (e.g. air temperature, leaf size, wind speed, etc.) to model leaf temperature using energy balance in the R package {tealeaves} (Muir 2019). Both {photosynthesis} and {tealeaves} packages are modular in that they can work independently or be readily integrated [seeSupporting Information—Methods S1]. Ideally, future modelling packages would add modules to model environmental and plant parameters either on their own or integrated with these tools.

Principle 4: scalability.

A major advantage in using code to analyse data is the ability to scale up an analysis to reduce time spent on repetitive tasks common in spreadsheet-based methods such as copy-and-paste, selecting data, choosing menu options, etc. Functions allow the same model to be fit across groups within a data set using a consistent method. For this, our fit_many function and the principles of functional programming are how we achieve scalability within the package. Rather than writing functions for each type of model or curve, we have a single multiple fitting function, sensitivity analysis function and printing function. R even has generic functions for scaling such as apply (base R language) and map ({purrr} package; Henry and Wickham 2020) which can be easily parallelized for speed (e.g. {parallel} and {furrr}; Vaughan and Dancho 2018 packages). This makes it easy to scale a new function within the software to a large data set.

Principle 5: documented contingencies.

By documenting which functions are dependent on one another, it becomes easier to troubleshoot issues when modifying code and to pre-empt issues when adding or replacing a component. For example, fit_aq_response depends on aq_response—if we want to change from the non-rectangular hyperbola model to a rectangular hyperbolic model, then fit_aq_response needs to be modified in addition to aq_response. To document contingencies, we created a function, check_dependencies, which uses {pkgnet} (Burns et al. 2020) to generate an html report that automatically documents R package interdependencies and function interdependencies. This is particularly useful when adding, subtracting or modifying functions in the package, as it allows planning to minimize issues that could break code.

Principle 6: documentation.

Code annotations allow a new user to readily understand what a line of code is doing, how it is doing it and why the code is written in a particular way. By providing exhaustive line-by-line annotation of a function, a new user can more rapidly understand the blueprint of the function. This is especially useful for R scripts and code hosted on GitHub (unfortunately, comments are erased from code upon submission to CRAN). For example, in fit_t_response, we outline the need for running looped iterations for the starting values of non-linear least squares curve fitting (Fig. 1). In the case of R packages hosted on CRAN, R documentation files provide information on how to use a function, though as a terser set of instructions as per CRAN policies (https://cran.r-project.org/doc/manuals/r-devel/R-exts.html).

Open in a separate window

Figure 1.

Example of coding annotations to explain the given analytical approach.

Enough metadata and commenting should be provided for a new user to understand how to use the written code (which can be an issue that affects widespread use of a program; Mangul et al. 2019).

Principle 7: extensive tutorials.

As with any tool, software will only be used if potential users can understand how it works. Extensive tutorials, while providing function-by-function examples of how to use the software, should also incorporate basic data-wrangling examples and explanations of why a given approach to data analysis is used in the field. The benefits of this approach include: making the code easier to adopt into your own analysis, making it easier for new coders to learn enough of the language to use the package effectively, and help trainees learn the appropriate theory behind the measurements and analytical approach. The net effect should be to increase the inclusivity of the field by reducing barriers to success since not all individuals will have equal access to workshops or experienced colleagues.