Simulating reflectance

Available radiative transfer models are called by passing a vector of their parameters. Similar models with different versions (e.g. PROSPECT 4, 5, 5B) also have a “version” argument. These models return a matrix of reflectance, transmittance, and/or absorption spectra (depending on the model) at 1 nm resolution over the wavelength range 400 to 2500 nm.

The PROSPECT family of models returns the reflectance (column 1) and transmittance (column 2) for an individual leaf as a function of 4 to 6 parameters (depending on the version).

library(PEcAnRTM)

## 
## Attaching package: 'PEcAnRTM'

## The following object is masked from 'package:graphics':
## 
##     matplot

wl <- 400:2500
params <- c(
  "N" = 1.4, "Cab" = 40, "Car" = 15,
  "Cbrown" = 0.5, "Cw" = 0.002, "Cm" = 0.004
)

p4 <- prospect(params[c(-3, -4)], version = 4)
p4

##     reflectance transmittance
## 400  0.04099898  0.0001814716
## 401  0.04103723  0.0001699630
## 402  0.04106248  0.0001575602
## 403  0.04111370  0.0001452140
## 404  0.04120401  0.0001348522
## ...
##      reflectance transmittance
## 2496   0.1422667     0.2801837
## 2497   0.1417965     0.2792691
## 2498   0.1420623     0.2795135
## 2499   0.1413868     0.2782765
## 2500   0.1418849     0.2788870

Notice only the first and last few lines of the spectra are printed, and the wavelength is annotated on the side. This is is because all RTM simulations in this package are of a special matrix class spectra.

class(p4)

## [1] "spectra" "matrix"

This class allows traditional subsetting via index with single brackets ([]), as well as subsetting by wavelength with double brackets.

p4[1:50, 1]

##     reflectance
## 400  0.04099898
## 401  0.04103723
## 402  0.04106248
## 403  0.04111370
## 404  0.04120401
## ...
##     reflectance
## 445  0.04545556
## 446  0.04542921
## 447  0.04540287
## 448  0.04537665
## 449  0.04533726

p4[[500:520, 2]]

##     transmittance
## 500   0.008937186
## 501   0.010279518
## 502   0.011772740
## 503   0.013438540
## 504   0.015276985
## ...
##     transmittance
## 516    0.05336301
## 517    0.05776873
## 518    0.06224375
## 519    0.06679217
## 520    0.07136411

The package also provides special plotting (plot, matplot) and combining (cbind) methods. Note that the cbind method automatically matches wavelengths, which facilitates working with spectra with different wavelengths.

p5 <- prospect(params[-4], version = 5)
p5b <- prospect(params, version = "5B")
p_multi <- cbind(p4, p5, p5b)
matplot(p_multi[, c(1, 3, 5)], lty = 1:3, col = 2, ylim = c(0, 1))
matplot(1 - p_multi[, c(2, 4, 6)], lty = 1:3, col = 3,  add = TRUE)
legend("topright", c("Reflectance", "Transmittance"), col=c(2, 3), lty = 1)
legend("top", c("4", "5", "5B"), lty = 1:3)

The SAIL family of models returns the bidirectional (1), hemispherical directional (2), directional hemispherical (3), and bidirectional hemispherical (4) reflectance factors for a canopy with a given set of approximately 20 parameters. It is often coupled to the PROSPECT model as PRO4SAIL. (Again, note that the return type is a spectra, which leads matplot to automatically put wavelengths on the x axis.)

sail.params <- defparam("pro4sail")
print(sail.params)

##        N      Cab      Car   Cbrown       Cw       Cm    LIDFa    LIDFb 
##    1.500   40.000    8.000    0.000    0.010    0.009   -0.350   -0.150 
## TypeLIDF      LAI        q      tts      tto      psi    psoil 
##    1.000    3.000    0.010   30.000   10.000    0.000    1.000

p4s <- pro4sail(sail.params)
matplot(p4s, xlab="Wavelength (nm)", ylab="Reflectance")
legend("topright", as.character(1:4), col=1:4, lty=1:4)

The above example illustrates the use of defparam to get the default parameters for a particular model. Similarly, model.list is a data.frame containing all currently available models.

print(model.list)

##          modname modcode         fullname
## 1     prospect_d    1153       PROSPECT D
## 2    prospect_5b    1152      PROSPECT 5B
## 3     prospect_5    1151       PROSPECT 5
## 4     prospect_4    1141       PROSPECT 4
## 5       pro4sail    2111         PRO4SAIL
## 6      pro4saild    2113        PRO4SAILD
##                                                                          par.names
## 1                                                     N Cab Car Canth Cbrown Cw Cm
## 2                                                           N Cab Car Cbrown Cw Cm
## 3                                                                  N Cab Car Cw Cm
## 4                                                                      N Cab Cw Cm
## 5            N Cab Car Cbrown Cw Cm LIDFa LIDFb TypeLIDF_r LAI q tts tto psi psoil
## 6      N Cab Car Canth Cbrown Cw Cm LIDFa LIDFb TypeLIDF_r LAI q tts tto psi psoil
##                                                                                                                         par.default
## 1                                                                              N=1.5 Cab=40 Car=8 Canth=8 Cbrown=0 Cw=0.01 Cm=0.009
## 2                                                                                      N=1.5 Cab=40 Car=8 Cbrown=0 Cw=0.01 Cm=0.009
## 3                                                                                               N=1.5 Cab=40 Car=8 Cw=0.01 Cm=0.009
## 4                                                                                                     N=1.5 Cab=40 Cw=0.01 Cm=0.009
## 5          N=1.5 Cab=40 Car=8 Cbrown=0 Cw=0.01 Cm=0.009 LIDFa=-0.35 LIDFb=-0.15 TypeLIDF=1 LAI=3 q=0.01 tts=30 tto=10 psi=0 psoil=1
## 6  N=1.5 Cab=40 Car=8 Canth=1 Cbrown=0 Cw=0.01 Cm=0.009 LIDFa=-0.35 LIDFb=-0.15 TypeLIDF=1 LAI=3 q=0.01 tts=30 tto=10 psi=0 psoil=1

Inversion

A novel feature of this package is the ability to perform a Bayesian inversion of a Radiative Transfer Model. Here are several advantages of the Bayesian approach:

• Parameter uncertainty: The output of a Bayesian analysis is a full joint probability distribution of the model parameters, which includes a robust estimate of their uncertainy and covariance between parameters.
• Prior knowledge: If previous, independent estimates of parameters are available, these can be used to inform the model.
• Partitioning variability: Random effects models provide a powerful framework for understanding the sources of variability and uncertainty in a data set.

An inversion can be performed using the invert.auto function, which uses the Metropolis Hastings MCMC algorithm to invert an arbitrary model. There are a lot of configuration options to invert.auto, so the recommended way to perform an inversion is to start with a default settings list, provided by the package itself. In the following sample, we demonstrate the default inversion of the PROSPECT model.

invert.options <- default.settings.prospect

The model to be inverted is, in this case, just a one-line call to the PROSPECT 5 model with the params vector. It returns a vector of reflectance values. The requirement is that the “model” output be as long as the length (or number of rows) of the observation vector (or matrix). In this case, the PROSPECT model returns 2101 reflectance values, so our observation also has to have this many points.

invert.options$model

## function (params, seed = NULL) 
## prospect(params, 5)[, 1]
## <bytecode: 0x555e5f9795a0>
## <environment: namespace:PEcAnRTM>

The recommended way to set settings is to start with a default object and modify it. For example, in the following block, we reduce the length of the run to make it go a little faster. threshold = ... sets the maximum value of the multivariate Gelman Diagnostic used to assess convergence – it defaults to 1.1, but we set it higher here for demonstrative purposes).

invert.options$n.tries <- 1      # Number of attempts
invert.options$nchains <- 2      # Number of MCMC chains
invert.options$ngibbs <- 5000    # Number of iterations per chain
invert.options$burnin <- 1000    # Length of burnin period
invert.options$do.lsq.first <- TRUE # Initialize with results from a fast least-squares optimization algorithm
invert.options$threshold <- 1.3  # Maximum value for Gelman diagnostic

The full list of inversion options is below. See the documentation for invert.auto for a full description of each of these.

names(invert.options)

##  [1] "model"          "inits.function" "prior.function" "param.mins"    
##  [5] "param.maxs"     "ngibbs"         "nchains"        "burnin"        
##  [9] "ngibbs.max"     "ngibbs.min"     "ngibbs.step"    "return.samples"
## [13] "target"         "do.lsq"         "save.samples"   "quiet"         
## [17] "adapt"          "adj_min"        "n.tries"        "do.lsq.first"  
## [21] "threshold"

Now, we load some test data (for Acer rubrum leaves (testspec_ACRU, accessible through data(testspec)).

data(testspec)
observed <- testspec_ACRU[,1]
plot(wl, observed, xlab="Wavelength", ylab="Reflectance", type='l')

To perform an inversion, just pass the observation matrix and the inversion settings into invert.auto. quiet = TRUE suppresses the progress bar, which is done here to clean up the knitted document. We also set parallel = FALSE here because this vignette is rebuilt on shared hardware where only one processor might be available; for runs on your own machine, you will probably want to set it TRUE to use all the cores on your machine.

if(file.exists("inversion.output.rds")){
    inversion.output <- readRDS("inversion.output.rds")
} else {
    inversion.output <- invert.auto(observed = observed,
                                    invert.options = invert.options,
                                    quiet = TRUE,
                                    parallel = FALSE)
    saveRDS(inversion.output, "inversion.output.rds")
}

## [1] "Running chain 1 of 2"

## Loading required namespace: MASS

## [1] "Running chain 2 of 2"
## [1] "The following parameters did not converge: Cw (1.786), Cm (2.405)"
## [1] "The following parameters did not converge: Cm (1.618)"
## [1] "The following parameters did not converge: Car (1.974)"
## [1] "The following parameters did not converge: Car (1.900)"
## [1] "The following parameters did not converge: Cab (1.384), Car (2.111)"
## [1] "The following parameters did not converge: Car (1.877)"
## [1] "The following parameters did not converge: Car (1.608)"
## [1] "The following parameters did not converge: Car (1.320)"
## [1] "Converged with all Gelman diag <= 1.011"

##           N      Cab      Car       Cw       Cm residual PSRF N > 1.10
## 46 1.072179 1.125868 1.458619 1.097076 1.240783 1.011808         FALSE
## 47 1.049782 1.091799 1.330281 1.108746 1.236612 1.015243         FALSE
## 48 1.030912 1.096263 1.270390 1.094419 1.196242 1.001592         FALSE
## 49 1.033093 1.082859 1.275357 1.126367 1.244725 1.005757         FALSE
## 50 1.035617 1.065378 1.277591 1.103828 1.227514 1.006571         FALSE
## 51 1.023581 1.063136 1.256436 1.093052 1.192926 1.010488         FALSE
##    PSRF Cab > 1.10 PSRF Car > 1.10 PSRF Cw > 1.10 PSRF Cm > 1.10
## 46            TRUE            TRUE          FALSE           TRUE
## 47           FALSE            TRUE           TRUE           TRUE
## 48           FALSE            TRUE          FALSE           TRUE
## 49           FALSE            TRUE           TRUE           TRUE
## 50           FALSE            TRUE           TRUE           TRUE
## 51           FALSE            TRUE          FALSE           TRUE
##    PSRF residual > 1.10
## 46                FALSE
## 47                FALSE
## 48                FALSE
## 49                FALSE
## 50                FALSE
## 51                FALSE
## [1] "The following parameters did not converge: Cm (1.314)"
## [1] "Converged with all Gelman diag <= 1.011"

##           N      Cab      Car       Cw       Cm residual PSRF N > 1.10
## 46 1.021743 1.039693 1.195683 1.079860 1.250872 1.002772         FALSE
## 47 1.019181 1.059313 1.160919 1.089041 1.294062 1.002063         FALSE
## 48 1.017278 1.064036 1.115487 1.085465 1.311736 1.002359         FALSE
## 49 1.013991 1.064179 1.061614 1.080716 1.332908 1.002591         FALSE
## 50 1.021612 1.044732 1.042372 1.075715 1.360974 1.002486         FALSE
## 51 1.012049 1.044294 1.021920 1.052051 1.287070 1.010967         FALSE
##    PSRF Cab > 1.10 PSRF Car > 1.10 PSRF Cw > 1.10 PSRF Cm > 1.10
## 46           FALSE            TRUE          FALSE           TRUE
## 47           FALSE            TRUE          FALSE           TRUE
## 48           FALSE            TRUE          FALSE           TRUE
## 49           FALSE           FALSE          FALSE           TRUE
## 50           FALSE           FALSE          FALSE           TRUE
## 51           FALSE           FALSE          FALSE           TRUE
##    PSRF residual > 1.10
## 46                FALSE
## 47                FALSE
## 48                FALSE
## 49                FALSE
## 50                FALSE
## 51                FALSE
## [1] "Converged with all Gelman diag <= 1.003"

##           N      Cab      Car       Cw       Cm residual PSRF N > 1.10
## 46 1.013974 1.064340 1.061687 1.081431 1.334556 1.002596         FALSE
## 47 1.021171 1.043936 1.039845 1.075215 1.357446 1.002580         FALSE
## 48 1.011526 1.046107 1.021964 1.058216 1.295816 1.010314         FALSE
## 49 1.009866 1.052311 1.016592 1.073058 1.310529 1.011488         FALSE
## 50 1.004487 1.048843 1.017916 1.072634 1.254559 1.035751         FALSE
## 51 1.003449 1.043365 1.013611 1.079339 1.263989 1.034046         FALSE
##    PSRF Cab > 1.10 PSRF Car > 1.10 PSRF Cw > 1.10 PSRF Cm > 1.10
## 46           FALSE           FALSE          FALSE           TRUE
## 47           FALSE           FALSE          FALSE           TRUE
## 48           FALSE           FALSE          FALSE           TRUE
## 49           FALSE           FALSE          FALSE           TRUE
## 50           FALSE           FALSE          FALSE           TRUE
## 51           FALSE           FALSE          FALSE           TRUE
##    PSRF residual > 1.10
## 46                FALSE
## 47                FALSE
## 48                FALSE
## 49                FALSE
## 50                FALSE
## 51                FALSE
## [1] "The following parameters did not converge: Cm (1.312)"
## [1] "Converged with all Gelman diag <= 1.016"

##           N      Cab      Car       Cw       Cm residual PSRF N > 1.10
## 46 1.002531 1.049638 1.011873 1.071090 1.262599 1.027407         FALSE
## 47 1.002466 1.042166 1.006245 1.064043 1.238889 1.031390         FALSE
## 48 1.002154 1.052036 1.003726 1.077181 1.291308 1.023175         FALSE
## 49 1.010363 1.057411 1.004526 1.074448 1.353389 1.019152         FALSE
## 50 1.012540 1.050988 1.005342 1.065045 1.288212 1.025459         FALSE
## 51 1.023381 1.057572 1.015725 1.054080 1.259575 1.035393         FALSE
##    PSRF Cab > 1.10 PSRF Car > 1.10 PSRF Cw > 1.10 PSRF Cm > 1.10
## 46           FALSE           FALSE          FALSE           TRUE
## 47           FALSE           FALSE          FALSE           TRUE
## 48           FALSE           FALSE          FALSE           TRUE
## 49           FALSE           FALSE          FALSE           TRUE
## 50           FALSE           FALSE          FALSE           TRUE
## 51           FALSE           FALSE          FALSE           TRUE
##    PSRF residual > 1.10
## 46                FALSE
## 47                FALSE
## 48                FALSE
## 49                FALSE
## 50                FALSE
## 51                FALSE
## [1] "Converged with all Gelman diag <= 1.031"

##           N      Cab      Car       Cw       Cm residual PSRF N > 1.10
## 46 1.003730 1.056357 1.003622 1.080423 1.331343 1.020431         FALSE
## 47 1.009709 1.055839 1.002492 1.083765 1.325071 1.026123         FALSE
## 48 1.018336 1.058951 1.010584 1.059678 1.277651 1.032199         FALSE
## 49 1.031695 1.042341 1.027483 1.038901 1.232568 1.041266         FALSE
## 50 1.044384 1.039255 1.032976 1.029161 1.207929 1.037464         FALSE
## 51 1.039226 1.048413 1.046652 1.031319 1.153766 1.060404         FALSE
##    PSRF Cab > 1.10 PSRF Car > 1.10 PSRF Cw > 1.10 PSRF Cm > 1.10
## 46           FALSE           FALSE          FALSE           TRUE
## 47           FALSE           FALSE          FALSE           TRUE
## 48           FALSE           FALSE          FALSE           TRUE
## 49           FALSE           FALSE          FALSE           TRUE
## 50           FALSE           FALSE          FALSE           TRUE
## 51           FALSE           FALSE          FALSE           TRUE
##    PSRF residual > 1.10
## 46                FALSE
## 47                FALSE
## 48                FALSE
## 49                FALSE
## 50                FALSE
## 51                FALSE
## [1] "Converged with all Gelman diag <= 1.012"

The output of invert.auto is a list of two objects: A list of summary statistics for each parameter and an mcmc.list object of the samples for diagnostic purposes or calculation of other summary statistics.

par(mfrow=c(2,2))
plot(inversion.output$samples, auto.layout=FALSE)

par(mfrow=c(1,1))
samples.mat <- as.matrix(inversion.output$samples)[-(2000:0),1:5]
colnames(samples.mat) <- params.prospect5
pairs(samples.mat, pch=".")

means <- unlist(inversion.output$results[grep("mu", names(inversion.output$results))])[1:5]
prospect.sim <- prospect(means, 5)[,1]  # reflectance

plot(wl, observed, type='l', col=1, xlab="wavelength (nm)", ylab="reflectance")
lines(wl, prospect.sim, type='l', col=2)
legend("topright", c("observed", "predicted"), lty=1, col=1:2)