In Burke-Lauenroth-Lab/rSFSW2: Simulation Framework for SOILWAT2

Frequently asked questions and answers

How do I set up a new simulation project?

1) Install and attach rSFSW2 if not already done so (Note: required version of rSOILWAT2 must already be installed on your computer). 2) Create a skeleton project by calling the function setup_rSFSW2_project_infrastructure(dir_prj = "path/to/project_folder"). This function will copy a default version of input data to '1_Input' and three demo R files to your directory. 3) Work your way through the file 'SFSW2_project_code.R', i.e., define paths and actions, and provide simulation project description in 'SFSW2_project_descriptions.R' and run settings in 'SFSW2_project_settings.R'

Should I be concerned about the following warnings?

Warning: 'SFSW2_project_code.R': Modify/reset input tracker status 'SFSW2_prj_meta[['input_status']]', if needed (see help ?update_intracker) and re-run project.

This warning attempts to tell to you that everything is fine, but it gives information on how to modify/reset the 'input tracker' status if you needed to (e.g., because you changed one of the inputs), but it is usually easier for small projects like yours to simply delete the .rds files.

Warning message: call dbDisconnect() when finished working with a connection

This warning tells you that the rSFSW2 package code should be improved -- you don't need to care about this: it works fine, but it doesn't follow best community practices.

How do I define experimental treatments?

Or more specifically, what is the difference between the input files 'SWRuns_InputData_TreatmentDesign.csv' and 'SWRuns_InputData_ExperimentalDesign.csv'?

All the input data spreadsheets, except the experimental design file, represent sites by rows. All these files have to have the same number of rows or none. Row x in the master input file represents site_id x which is the same site_id x for soil layers input file, treatment design input file, vegetation input file, etc.

The experimental design input file is different. Each row of this file is applied to all of the rows/sites of the other files.

For example, a project has 827 sites and would like to apply six treatments to every site:

• The master input file has 827 rows; one row for each site.
• The treatment design file has 827 rows (or none); one row for each site.
• All other input files have 827 rows (or none); one row for each site.
• The experimental design file has six rows; one row for each of the six treatments.

The master input file requires values for the 'Label' column. If the other input files have different values for their 'Label' columns (but the same number of rows), then their 'Label's will get overwritten by the values of the master input file (with a warning). If the other input files have zero rows, then the number of rows from the master input file is generated for them (with NA values). If they contain a different number of rows than the master input file contains, then the code stops. See function fix_rowlabels.

How does rSFSW2/SOILWAT2 handle missing soil data?

SOILWAT2 will fail if soil data are missing. rSFSW2 distinguishes three cases:

1) The topmost/first soil layer has missing data: rSFSW2 marks the 'create' section of this run as failed. 2) A continuous number of bottommost/deepest soil layer(s) have missing data: If opt_sim[["fix_depth_to_layers"]] is TRUE, then the simulated soil depth is reduced to the maximal depth for which soil data are available; if opt_sim[["fix_depth_to_layers"]] is FALSE (default), then simulated soil depth is the maximal value of 'depth_LX' which is <= 'SoilDepth_cm' and missing soil data are imputed with the LOCF method 'last-observation-carried-forward' (from shallow to deep layers). 3) Soil layer(s) within the soil profile have missing data: rSFSW2 imputes soil data with the LOCF method.

Is the simulated soil depth the value entered in file 'SWRuns_InputData_SoilLayers_v9.csv'?

The columns 'SoilDepth_cm' and 'depth_LX', with X = 1, 2, 3, ... the soil layer numbers, in the file 'SWRuns_InputData_SoilLayers_v9.csv', whether or not the corresponding columns (density, sand, clay, etc.) in the file 'SWRuns_InputData_soils_v12.csv' have appropriate values (e.g., not NA), and the value of the flag opt_sim[["fix_depth_to_layers"]] as read in from the file 'SFSW2_project_descriptions.R' determine together the simulated soil depth at a site. If every 'depth_LX' <= 'SoilDepth_cm' is not NA and every corresponding soil data column from 'SWRuns_InputData_soils_v12' is not NA, then simulated soil depth is the maximal value of 'depth_LX' which is <= 'SoilDepth_cm'. See also point 2 in the missing soil FAQ in case of missing data.

Does percolation stop or become impeded at the simulated soil depth?

SOILWAT2 percolates soil moisture to the bottom of the deepest soil layer from where further percolation is considered 'deep drainage', i.e., water leaves the simulated system and is no longer potentially accessible by plant roots. If you set impermeability of the deepest soil layer to a value > 0, then you could simulate impeded percolation. However, impermeability is set by default to 0.

How does soil depth affect soil water?

Soil depth determines total available soil moisture. For example, let's say we have two identical soils where volumetric water content at field capacity is 0.3 and VWC at the limit of moisture extraction for a vegetation is 0.15, but one soil profile is 1 m deep and the other is 2 m deep. Soil depth causes the first soil to have a total of 15 cm of available water whereas the second, deeper soil has 30 cm of available water. That is an important difference for vegetation. Please, consider that soil layers will not affect the simulation outcome (besides for deep drainage rates) unless you include plant roots in those layers in the simulation.

What is the difference between 'Label' and 'site_id' in the file 'SWRuns_InputMaster_YOURPROJECT_v11.csv'?

The field 'site_id' is a consecutive running integer serving as index for all the rows in the master input file. The field 'Label' takes character values and can be used to provide human readable site names.

How can I calculate available soil water?

SOILWAT2 does not calculate available soil water content because it cannot do it properly. The variable 'swcBulk' that you see in the structure 'SW_SOILWAT_OUTPUTS' (defined in SW_SoilWater.h) is a stub that is left over from old versions of SoilWat. It and the associated code could be removed without harm.

Available soil water content (SWA) is defined as the soil water content (SWC) which can be extracted, i.e., it is calculated as SWC - SWC[crit]. Where SWC[crit] is the soil water content at a critical soil water potential (SWP[crit]) which is the lower pressure limit an extraction agent can suck up water. The relationship between SWP and SWC can be described by so called 'pedotransfer' functions and is dependent on the soil texture. For agronomical application with well-watered crops, it was historically assumed that SWC[crit] at SWP[crit] = -1.5 MPa. However, we are working in arid and semiarid systems where most/all plant species can extract water well below -1.5 MPa. Hence, SWC[crit] is species-specific - or at least plant-group specific; thus, the simple interpretation of the concept of SWA is tenuous or useless in vegetation that is composed of species with differing SWC[crit].

Historically, SOILWAT2 was treating vegetation as one type of green slime which had one value for SWC[crit] and thus could provide one output of SWA. More recently, SOILWAT2 represents vegetation as composed of four functional plant types (grasses, shrubs, forbs, and trees). These groups are known to vary considerably in their values of SWP[crit]. Thus, SOILWAT2 cannot calculate one SWA that is valid for the simulated vegetation and it stopped providing SWA output. This is to prevent the need to output a separate SWA for each functional group and because calculating SWA is simple and based on the provided output of SWC and separate information on SWC[crit] for a specific plant species/objective.

However, rSFSW2 calculates SWA for each user-requested SWP value.

Burke-Lauenroth-Lab/rSFSW2 documentation built on Aug. 14, 2020, 5:20 p.m.