Solve for leaf temperature using energy balance
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
R
README_files/figure-markdown_strict
data
hex-sticker
man
tests
vignettes
.Rbuildignore
.gitignore
.travis.yml
CONDUCT.md
DESCRIPTION
LICENSE
LICENSE.md
NAMESPACE
README.Rmd
README.md
tealeaves.Rproj

README.md

tealeaves

Project Status: WIP - Initial development is in progress, but there has not yet been a stable, usable release suitable for the public. Build Status

Solve for leaf temperature using energy balance

Description

{tealeaves} is a lightweight R package to model leaf temperature using leaf energy balance. It uses the R package units to ensure that parameters are properly specified and transformed before calculations. It allows separate lower and upper surface conductances to heat and water vapour, so sensible and latent heat loss are calculated for each surface separately. It's straightforward to model leaf temperature over environmental gradients such as light, air temperature, humidity, and wind, or trait gradients such as leaf size or stomatal conductance.

Get tealeaves

GitHub

install.packages("devtools")
devtools::install_github("cdmuir/tealeaves")

And load tealeaves

library("tealeaves")

Vignette

The {tealeaves} package solves for leaf temperature given a set of environmental conditions and leaf traits by balancing the leaf energy budget. There are two main steps to using {tealeaves}:

  1. define leaf parameters, environmental parameters, and physical constants; and
  2. solve for the a leaf temperature that balances its energy budget (tleaf and tleaves for single and multiple parameter sets, respectively).

In this vignette, I'll show you how to:

  • run a minimum worked example using default parameters
  • replace default parameters
  • solve for leaf temperature along an environmental gradient

Minimum worked example

You can use the default parameter settings and solve for leaf temperature in a single leaf using the make_*() functions and tleaf().

library(magrittr)
library(tealeaves)

# Leaving the make_* functions empty will automatically default to defaults
# parameters.
leaf_par   <- make_leafpar()   # leaf parameters
enviro_par <- make_enviropar() # environmental parameters
constants  <- make_constants() # physical constants

T_leaf <- tleaf(leaf_par, enviro_par, constants, quiet = TRUE, unitless = FALSE)

T_leaf %>% knitr::kable()
T_leaf value convergence R_abs S_r H L E
305.8332 [K] -1e-07 0 1723.813 [W/m^2] 962.3284 [W/m^2] 251.413 [J/m^2/s] 510.0715 [W/m^2] 0.01168319 [mol/m^2/s]

Replace default parameters

You can look at default parameters settings in the manual (run ?make_parameters). These defaults are reasonable, but of course you will probably want to use different choices and allow some parameters to vary. Here, I'll demonstrate how to replace a default. In the next section, I'll show you how to set up a gradient of parameter values over which to solve for leaf temperature.

# Use the `replace` argument to replace defaults. This must be a named list, and
# each named element must have the proper units specified. See `?make_parameters`
# for all parameter names and proper units.

# First, we'll change stomatal conductance to 4 umol / (m^2 s Pa)
leaf_par <- make_leafpar(
  replace = list(
    g_sw = set_units(4, "umol/m^2/s/Pa")
    )
  )

# Next, we'll change the air temperature to 25 degree C (= 298.15 K)
enviro_par <- make_enviropar(
  replace = list(
    T_air = set_units(298.15, "K")
    )
  )

# Physical constants probably do not need to be replaced in most cases,
# that's why we call them 'constants'!
constants  <- make_constants()

T_leaf <- tleaf(leaf_par, enviro_par, constants, quiet = TRUE, unitless = FALSE)

T_leaf %>% knitr::kable()
T_leaf value convergence R_abs S_r H L E
306.7574 [K] 1.66e-05 0 1723.813 [W/m^2] 974.014 [W/m^2] 281.4289 [J/m^2/s] 468.3699 [W/m^2] 0.01073782 [mol/m^2/s]

Environmental gradients

In the previous two examples, I used the tleaf function to solve for a single parameter set. In most cases, you'll want to solve for many parameter sets. The function tleaves generalizes tleaf and makes it easy to solve for multiple parameter sets using the same argument structure. All you need to do is specify multiple values for one or more leaf or environmental parameters and tleaves uses the tidyr::crossing function to fit all combinations[1].

# As before, use the `replace` argument to replace defaults, but this time we
# enter multiple values

# First, we'll change stomatal conductance to to 2 and 4 umol / (m^2 s Pa)
leaf_par  <- make_leafpar(
  replace = list(
    g_sw = set_units(c(2, 4), "umol/m^2/s/Pa")
    )
  )

# Next, we'll change the air temperature to 20 and 25 degree C (= 293.15 and 298.15 K)
enviro_par <- make_enviropar(
  replace = list(
    T_air = set_units(c(293.15, 298.15), "K")
    )
  )

constants  <- make_constants()

# Now there should be 4 combinations (high and low g_sw crossed with high and low T_air)
T_leaves <- tleaves(leaf_par, enviro_par, constants, progress = FALSE, 
                    quiet = TRUE, unitless = FALSE)

T_leaves %>% 
  dplyr::select(T_air, g_sw, T_leaf) %>%
  knitr::kable()
T_air g_sw T_leaf
293.15 [K] 2 [umol/m^2/Pa/s] 305.9599
298.15 [K] 2 [umol/m^2/Pa/s] 309.6194
293.15 [K] 4 [umol/m^2/Pa/s] 303.3411
298.15 [K] 4 [umol/m^2/Pa/s] 306.7574

Parallel processing

It can take a little while to model many different parameter sets. If you have multiple processors available, you can speed things up by running simulations in parallel. In the tealeaves function, simply use the parallel = TRUE argument to simulate in parallel. Here I'll provide an example looking at how leaf-to-air temperature differentials change with air temperature.

# We'll use the `replace` argument to enter multiple air temperatures and two light levels

leaf_par  <- make_leafpar()

enviro_par <- make_enviropar(
  replace = list(
    S_sw = set_units(c(300, 1000), "W/m^2"),
    T_air = set_units(seq(273.15, 313.15, length.out = 10), "K")
    )
  )

constants  <- make_constants()

tl <- tleaves(leaf_par, enviro_par, constants, progress = FALSE, quiet = TRUE,
              parallel = TRUE)
tl$T_air %<>% drop_units() # for plotting
tl %<>% dplyr::mutate(Light = dplyr::case_when(
 round(drop_units(S_sw), 0) == 300 ~ "Shade",
 round(drop_units(S_sw), 0) == 1000 ~ "Sun"
))

# Plot T_air versus T_leaf - T_air at different light levels
library(ggplot2)
ggplot(tl, aes(T_air, T_leaf - T_air, color = Light)) +
  geom_line() +
  xlab("Air Temperature [K]") +
  ylab("Leaf - Air Temperature [K]") +
  theme_minimal() +
  NULL

Contributors

Comments and contributions

I welcome comments, criticisms, and especially contributions! GitHub issues are the preferred way to report bugs, ask questions, or request new features. You can submit issues here:

https://github.com/cdmuir/tealeaves/issues

Meta

[1] Since optimization is somewhat time-consuming, be careful about crossing too many combinations. Use progress = TRUE to show progress bar with estimated time remaining.