The present document describes how to run the soil plant water balance model described in De Cáceres et al. (2015) using package medfate
. The document illustrates how to prepare the inputs, use the simulation functions and inspect the outputs. All the details of the model design and formulation can be found at https://emf-creaf.github.io/medfatebook/index.html. Because it introduces many basic features of simulations with package medfate
, this document should be read before addressing advanced topics of water balance simulations or growth simulations.
Model inputs are explained in greater detail in vignette ‘Simulation inputs’. Here we only review the different steps required to run function spwb()
.
Soil information needs to be entered as a data frame
with soil layers in rows and physical attributes in columns. Soil physical attributes can be initialized to default values, for a given number of layers, using function defaultSoilParams()
:
= defaultSoilParams(2) spar
The soil input for water balance simulation is actually a list of class soil
that is created using a function with the same name:
= soil(spar) examplesoil
As explained in the package overview, models included in medfate
were primarily designed to be ran on forest inventory plots. Here we use the example object provided with the package:
data(exampleforestMED)
exampleforestMED
## $ID
## [1] "1"
##
## $patchsize
## [1] 10000
##
## $treeData
## Species N DBH Height Z50 Z95
## 1 54 168 37.55 800 750 3000
## 2 68 384 14.60 660 750 3000
##
## $shrubData
## Species Cover Height Z50 Z95
## 1 65 3.75 80 300 1500
##
## $herbCover
## [1] 10
##
## $herbHeight
## [1] 20
##
## attr(,"class")
## [1] "forest" "list"
In the basic water balance, only mean temperature, precipitation and potential evapotranspiration is required, but radiation may also be necessary to simulate snow melt.
data(examplemeteo)
head(examplemeteo)
## MeanTemperature MinTemperature MaxTemperature Precipitation
## 2001-01-01 3.57668969 -0.5934215 6.287950 4.869109
## 2001-01-02 1.83695972 -2.3662458 4.569737 2.498292
## 2001-01-03 0.09462563 -3.8541036 2.661951 0.000000
## 2001-01-04 1.13866156 -1.8744860 3.097705 5.796973
## 2001-01-05 4.70578690 0.3288287 7.551532 1.884401
## 2001-01-06 4.57036721 0.5461322 7.186784 13.359801
## MeanRelativeHumidity MinRelativeHumidity MaxRelativeHumidity
## 2001-01-01 78.73709 65.15411 100.00000
## 2001-01-02 69.70800 57.43761 94.71780
## 2001-01-03 70.69610 58.77432 94.66823
## 2001-01-04 76.89156 66.84256 95.80950
## 2001-01-05 76.67424 62.97656 100.00000
## 2001-01-06 89.01940 74.25754 100.00000
## Radiation WindSpeed WindDirection PET
## 2001-01-01 12.89251 2.000000 172 1.3212770
## 2001-01-02 13.03079 7.662544 278 2.2185985
## 2001-01-03 16.90722 2.000000 141 1.8045176
## 2001-01-04 11.07275 2.000000 172 0.9200627
## 2001-01-05 13.45205 7.581347 321 2.2914449
## 2001-01-06 12.84841 6.570501 141 1.7255058
Finally, simulations in medfate
require a data frame with species parameter values, which we load using defaults for Catalonia (NE Spain):
data("SpParamsMED")
Apart from data inputs, the behaviour of simulation models can be controlled using a set of global parameters. The default parameterization is obtained using function defaultControl()
:
= defaultControl("Granier") control
Some parameters deserve explanation here:
verbose = FALSE
.soilFunctions
.transpirationMode = "Sperry"
. Most of the other options apply in the case of advanced soil water balance only.A last object is needed before calling simulation functions, called spwbInput
. It consists in the compilation of aboveground and belowground parameters and the specification of additional parameter values for each plant cohort. This is done by calling function spwbInput()
, but if one has a forest
object, the object can be generated more directly using function forest2spwbInput()
:
= forest2spwbInput(exampleforestMED, examplesoil, SpParamsMED, control) x
Different parameter variables will be drawn depending on the value of transpirationMode
. For the simple water balance model (transpirationMode = "Granier"
), relatively few parameters are needed. All the input information for forest data and species parameter values can be inspected by accessing the different elements of this object, whose names are.
names(x)
## [1] "control" "soil" "canopy"
## [4] "cohorts" "above" "below"
## [7] "belowLayers" "paramsPhenology" "paramsInterception"
## [10] "paramsTranspiration" "internalPhenology" "internalWater"
Note that (since ver 2.0) the water balance input object contains an element soil
with the soil input.
It is important to remember that, unlike normal objects in R, any water balance simulation will modify the spwbInput
object. For example, the state of the soil at the end of the simulated process (i.e. W
) will be stored. Hence, one can use the same object to simulate water balance sequentially and the final state of one simulation is the initial state of the next. In the case of soil water balance, these modifications are small, for example concerning LAI_expanded
, but in the case of growth simulations the object is used to store the status of vegetation during and at the end of simulations.
Finally, note that users can set cohort-specific parameters for soil water balance (instead of using species-level values) by modifying manually the parameter values in this object. Since some parameters may be coordinated by design, however, it is better to use specific package functions for this purpose.
Soil water balance simulations will normally span periods of several months or years, but since the model operates at a daily temporal scale, it is possible to perform soil water balance for one day only. This is done using function spwb_day()
. In the following code we select day 100 from the meteorological input data and perform soil water balance for that day only:
= 100
d <-spwb_day(x, rownames(examplemeteo)[d],
sd1$MinTemperature[d], examplemeteo$MaxTemperature[d],
examplemeteo$MinRelativeHumidity[d], examplemeteo$MaxRelativeHumidity[d],
examplemeteo$Radiation[d], examplemeteo$WindSpeed[d],
examplemeteolatitude = 41.82592, elevation = 100,
slope= 0, aspect = 0, prec = examplemeteo$Precipitation[d])
Function spwb_day()
is most useful when working with the complex transpiration model. This is why so many meteorological variables are required. The output of spwb_day()
is a list with five elements:
names(sd1)
## [1] "cohorts" "WaterBalance" "Soil" "Stand" "Plants"
sd1
## $cohorts
## SP Name
## T1_54 54 Pinus halepensis
## T2_68 68 Quercus ilex
## S1_65 65 Quercus coccifera
##
## $WaterBalance
## PET Rain Snow NetRain Snowmelt
## 5.023347 0.000000 0.000000 0.000000 0.000000
## Runon Infiltration Runoff DeepDrainage SoilEvaporation
## 0.000000 0.000000 0.000000 0.000000 0.500000
## PlantExtraction Transpiration
## 1.035869 1.035869
##
## $Soil
## SoilEvaporation PlantExtraction psi
## 1 4.999998e-01 0.2084683 -0.03479316
## 2 1.529512e-07 0.8274009 -0.03421151
##
## $Stand
## LAI LAIlive LAIexpanded LAIdead Cm LgroundPAR
## 1.6626714 1.6626714 1.6626714 0.0000000 1.2276425 0.4174317
## LgroundSWR
## 0.5235428
##
## $Plants
## LAI AbsorbedSWRFraction Transpiration GrossPhotosynthesis
## T1_54 0.81670117 0.2332606 0.50713360 2.02853442
## T2_68 0.79779523 0.2328195 0.50617489 2.02469956
## S1_65 0.04817502 0.0103770 0.02256073 0.09024291
## PlantPsi DDS StemPLC
## T1_54 -0.03324984 9.436921e-07 1.876311e-07
## T2_68 -0.03324984 4.229957e-07 7.029520e-08
## S1_65 -0.03370783 4.274963e-07 5.311238e-08
##
## attr(,"class")
## [1] "spwb_day" "list"
Most often, users will use function spwb()
to run the soil water balance model. This function requires the spwbInput
object and the meteorological data frame. However, function spwb_day()
modified the state variables of the input objects. In particular, the values of soil moisture are now:
$soil$W x
## [1] 0.9896215 0.9929165
We simply reset state variables to their default values so that new simulations are not affected by the end state of the previous simulation:
resetInputs(x)
$soil$W x
## [1] 1 1
Now we are ready to call function spwb()
:
= spwb(x, examplemeteo, latitude = 41.82592, elevation = 100) S
## Initial soil water content (mm): 185.069
## Initial snowpack content (mm): 0
## Performing daily simulations
## Year 2001:....................................done.
## Final soil water content (mm): 165.758
## Final snowpack content (mm): 0
## Change in soil water content (mm): -19.3112
## Soil water balance result (mm): -19.3112
## Change in snowpack water content (mm): 0
## Snowpack water balance result (mm): 0
## Water balance components:
## Precipitation (mm) 513
## Rain (mm) 462 Snow (mm) 51
## Interception (mm) 85 Net rainfall (mm) 377
## Infiltration (mm) 418 Runoff (mm) 10 Deep drainage (mm) 106
## Soil evaporation (mm) 41 Transpiration (mm) 290
Function spwb()
returns an object of class with the same name, actually a list:
class(S)
## [1] "spwb" "list"
If we inspect its elements, we realize that the output is arranged differently than in spwb_day()
:
names(S)
## [1] "latitude" "topography" "spwbInput" "WaterBalance" "Soil"
## [6] "Stand" "Plants" "subdaily"
In particular, element spwbInput
contains a copy of the input parameters that were used to run the model:
names(S$spwbInput)
## [1] "control" "soil" "canopy"
## [4] "cohorts" "above" "below"
## [7] "belowLayers" "paramsPhenology" "paramsInterception"
## [10] "paramsTranspiration" "internalPhenology" "internalWater"
As before, WaterBalance
contains water balance components, but in this case in form of a data frame with days in rows:
head(S$WaterBalance)
## PET Precipitation Rain Snow NetRain Snowmelt
## 2001-01-01 1.3212770 4.869109 4.869109 0 3.560167 0
## 2001-01-02 2.2185985 2.498292 2.498292 0 1.219585 0
## 2001-01-03 1.8045176 0.000000 0.000000 0 0.000000 0
## 2001-01-04 0.9200627 5.796973 5.796973 0 4.498843 0
## 2001-01-05 2.2914449 1.884401 1.884401 0 0.786609 0
## 2001-01-06 1.7255058 13.359801 13.359801 0 11.789016 0
## Infiltration Runoff DeepDrainage Evapotranspiration Interception
## 2001-01-01 3.560167 0 2.8240704 2.0814039 1.308942
## 2001-01-02 1.219585 0 0.9385782 2.2362061 1.278707
## 2001-01-03 0.000000 0 0.0000000 0.5549906 0.000000
## 2001-01-04 4.498843 0 2.5629573 1.9695492 1.298130
## 2001-01-05 0.786609 0 0.6212876 2.0703135 1.097792
## 2001-01-06 11.789016 0 8.7085446 2.4266028 1.570785
## SoilEvaporation PlantExtraction Transpiration
## 2001-01-01 0.5000000 0.2724618 0.2724618
## 2001-01-02 0.5000000 0.4574994 0.4574994
## 2001-01-03 0.1828793 0.3721113 0.3721113
## 2001-01-04 0.4816922 0.1897270 0.1897270
## 2001-01-05 0.5000000 0.4725211 0.4725211
## 2001-01-06 0.5000000 0.3558183 0.3558183
Element Plants
is in turn a list with several dataframes with plant output variables, for example plant water potentials are in:
head(S$Plants$PlantPsi)
## T1_54 T2_68 S1_65
## 2001-01-01 -0.03243320 -0.03243320 -0.03327504
## 2001-01-02 -0.03297370 -0.03297370 -0.03356033
## 2001-01-03 -0.03353559 -0.03353559 -0.03419312
## 2001-01-04 -0.03249687 -0.03249687 -0.03328616
## 2001-01-05 -0.03306652 -0.03306652 -0.03360978
## 2001-01-06 -0.03086391 -0.03086391 -0.03247332
Package medfate
provides a simple plot
function for objects of class spwb
. It can be used to show meteorological inputs, snow dynamics, and different components of the water balance:
plot(S, type = "PET_Precipitation")
plot(S, type = "Snow")
plot(S, type = "Export")
plot(S, type = "Evapotranspiration")
Function plot
is also allows displaying soil moisture dynamics by layer, which can be done in four different ways (the first two only imply a change in axis units):
plot(S, type="SoilTheta")
plot(S, type="SoilRWC")
plot(S, type="SoilPsi")
plot(S, type="SoilVol")
Finally, the same function can also be used to draw the dynamics of plant variables by cohorts, such as transpiration, gross photosynthesis, water potential or drought stress:
plot(S, type="Transpiration")
plot(S, type="GrossPhotosynthesis")
plot(S, type="PlantPsi")
plot(S, type="PlantStress")
While the simulation model uses daily steps, users will normally be interested in outputs at larger time scales. The package provides a summary
for objects of class spwb
. This function can be used to summarize the model’s output at different temporal steps (i.e. weekly, annual, …). For example, to obtain the average soil moisture and water potentials by months one can use:
summary(S, freq="months",FUN=mean, output="Soil")
## W.1 W.2 ML.1 ML.2 MLTot WTD SWE
## 2001-01-01 0.9919758 0.9993608 67.71553 116.73141 184.4469 997.3991 1.64411506
## 2001-02-01 0.9712917 0.9514976 66.30357 111.14070 177.4443 1000.0000 0.27332813
## 2001-03-01 0.9747563 0.9711807 66.54007 113.43980 179.9799 998.4110 0.01762496
## 2001-04-01 0.9563937 0.8600466 65.28658 100.45867 165.7452 1000.0000 0.57692969
## 2001-05-01 0.9496820 0.8636995 64.82842 100.88535 165.7138 1000.0000 0.00000000
## 2001-06-01 0.8384499 0.6193338 57.23535 72.34195 129.5773 1000.0000 0.00000000
## 2001-07-01 0.9615369 0.6777608 65.63767 79.16657 144.8042 1000.0000 0.00000000
## 2001-08-01 0.9641077 0.7659379 65.81316 89.46620 155.2794 1000.0000 0.00000000
## 2001-09-01 0.9644831 0.8141998 65.83879 95.10348 160.9423 1000.0000 0.00000000
## 2001-10-01 0.9768656 0.8437319 66.68406 98.55301 165.2371 1000.0000 0.00000000
## 2001-11-01 0.9714069 0.9386074 66.31143 109.63505 175.9465 997.7365 2.57765032
## 2001-12-01 0.9396816 0.9265141 64.14576 108.22248 172.3682 1000.0000 0.00000000
## PlantExt.1 PlantExt.2 psi.1 psi.2
## 2001-01-01 0.05953526 0.2362926 -0.03449771 -0.03322069
## 2001-02-01 0.12418860 0.4928983 -0.03859855 -0.04400715
## 2001-03-01 0.12904086 0.5121569 -0.03753813 -0.03868544
## 2001-04-01 0.16467055 0.6535658 -0.04163009 -0.07377719
## 2001-05-01 0.19436686 0.7714244 -0.04414952 -0.07613442
## 2001-06-01 0.27710193 1.0936042 -0.08333872 -0.52419445
## 2001-07-01 0.23389496 0.9176964 -0.04102834 -0.48590120
## 2001-08-01 0.23630421 0.9378239 -0.03982567 -0.13926219
## 2001-09-01 0.18545835 0.7360648 -0.03998251 -0.09613623
## 2001-10-01 0.13302977 0.5279805 -0.03738441 -0.08651127
## 2001-11-01 0.09608920 0.3813730 -0.03845381 -0.04723316
## 2001-12-01 0.08987196 0.3566973 -0.04579853 -0.05000816
Parameter output
is used to indicate the element of the spwb
object for which we desire summaries. Similarly, it is possible to calculate the average stress of plant cohorts by months:
summary(S, freq="months",FUN=mean, output="PlantStress")
## T1_54 T2_68 S1_65
## 2001-01-01 9.405111e-07 4.215699e-07 4.286702e-07
## 2001-02-01 2.086303e-06 9.351542e-07 7.838030e-07
## 2001-03-01 1.481427e-06 6.640276e-07 6.166294e-07
## 2001-04-01 8.634595e-06 3.870339e-06 2.424946e-06
## 2001-05-01 1.187198e-05 5.321480e-06 3.289508e-06
## 2001-06-01 5.786976e-03 2.613518e-03 1.400365e-03
## 2001-07-01 1.223434e-02 5.579089e-03 2.984307e-03
## 2001-08-01 7.001135e-05 3.138301e-05 1.708757e-05
## 2001-09-01 1.879309e-05 8.423787e-06 4.824152e-06
## 2001-10-01 1.841170e-05 8.252853e-06 4.667312e-06
## 2001-11-01 2.806167e-06 1.257823e-06 9.615869e-07
## 2001-12-01 3.088898e-06 1.384553e-06 1.220074e-06
The summary
function can be also used to aggregate the output by species. In this case, the values of plant cohorts belonging to the same species will be averaged using LAI values as weights. For example, we may average the daily drought stress across cohorts of the same species (here there is only one cohort by species, so this does not modify the output):
head(summary(S, freq="day", output="PlantStress", bySpecies = TRUE))
## Pinus halepensis Quercus coccifera Quercus ilex
## 2001-01-01 8.758524e-07 4.112402e-07 3.925876e-07
## 2001-01-02 9.203744e-07 4.219088e-07 4.125439e-07
## 2001-01-03 9.682319e-07 4.462270e-07 4.339953e-07
## 2001-01-04 8.810208e-07 4.116527e-07 3.949043e-07
## 2001-01-05 9.281687e-07 4.237765e-07 4.160376e-07
## 2001-01-06 7.547697e-07 3.822257e-07 3.383141e-07
Or we can combine the aggregation by species with a temporal aggregation (here monthly averages):
summary(S, freq="month", FUN = mean, output="PlantStress", bySpecies = TRUE)
## Pinus halepensis Quercus coccifera Quercus ilex
## 2001-01-01 9.405111e-07 4.286702e-07 4.215699e-07
## 2001-02-01 2.086303e-06 7.838030e-07 9.351542e-07
## 2001-03-01 1.481427e-06 6.166294e-07 6.640276e-07
## 2001-04-01 8.634595e-06 2.424946e-06 3.870339e-06
## 2001-05-01 1.187198e-05 3.289508e-06 5.321480e-06
## 2001-06-01 5.786976e-03 1.400365e-03 2.613518e-03
## 2001-07-01 1.223434e-02 2.984307e-03 5.579089e-03
## 2001-08-01 7.001135e-05 1.708757e-05 3.138301e-05
## 2001-09-01 1.879309e-05 4.824152e-06 8.423787e-06
## 2001-10-01 1.841170e-05 4.667312e-06 8.252853e-06
## 2001-11-01 2.806167e-06 9.615869e-07 1.257823e-06
## 2001-12-01 3.088898e-06 1.220074e-06 1.384553e-06
The package provides some functions to extract or transform specific outputs from soil plant water balance simulations. In particular, function spwb_stress()
allows calculating several plant stress indices, such as the number of days with drought stress > 0.5 or the maximum drought stress:
spwb_stress(S, index = "NDD", freq = "years", draw=FALSE)
## T1_54 T2_68 S1_65
## 2001-01-01 0 0 0
spwb_stress(S, index = "MDS", freq = "years", draw=FALSE)
## T1_54 T2_68 S1_65
## 2001-01-01 0.07106152 0.03266369 0.01747673
As the general summary function, spwb_stress()
allows calculating stress indices at several temporal scales. For example the water stress index (integral of water potential values) can be calculated and drawn for every month:
spwb_stress(S, index = "WSI", freq = "months", draw=TRUE)
Another specific summary function is spwb_waterUseEfficiency()
. This is most useful with advanced water and energy balance modeling, but for simple water balance it calculates the ratio between photosynthesis and transpiration at the desired scale. In this case it is equal to the value of the input species parameter WUE
:
spwb_waterUseEfficiency(S, type = "Stand Ag/E", freq = "months", draw=FALSE)
## 2001-01-01 2001-02-01 2001-03-01 2001-04-01 2001-05-01 2001-06-01 2001-07-01
## 4 4 4 4 4 4 4
## 2001-08-01 2001-09-01 2001-10-01 2001-11-01 2001-12-01
## 4 4 4 4 4