APEXSENSUN is a package in R for performing uncertainty and sensitivity analysis (SA) for the APEX model.The package was primarily developed for USDA-ARS Grazinglands Research Laboratory to assist in parametrization of the APEX model. For more information on the structure of APEXSENSUN and citation, please refer to Talebizadeh et al. (2018).
An example folder containing an APEX project and other inputs is available for users to test the package. The rest of this manual provides details of implementing an SA project using the accompanying example folder which can be created through a call to:
# Loading APEXSENSUN package in R:
library(APEXSENSUN)
# Creating a copy of tutorial folder inside the working directory
getExampleFolder()After loading APEXSENSUN and generating a copy of the example folder, the following four steps, described in the next sections should be followed for performing SA.
# 1) Generating a list object with a predefined structure compatible to APEXSENSUN:
globalInput <- APEXSENSUN::inputGen()
# 2) Setting the required inputs (e.g. uncertainty boubds, SA method, sample size, ...)
#
# Setting uncertainty bounds:
globalInput$apexPARM$Root_growth_soil[1] = 0.15
globalInput$apexPARM$Root_growth_soil[2] = 0.2
globalInput$apexPARM$Soil_water_limit[1] = 0
globalInput$apexPARM$Soil_water_limit[2] = 1
globalInput$apexPARM$Soil_evap_coeff[1] = 1.5
globalInput$apexPARM$Soil_evap_coeff[2] = 2.5
globalInput$apexPARM$Soil_evap_plant_cover[1] = 0
globalInput$apexPARM$Soil_evap_plant_cover[2] = 0.5
globalInput$apexPARM$Runoff_CN_int_abs[1] = 0.05
globalInput$apexPARM$Runoff_CN_int_abs[2] = 0.4
globalInput$apexPARM$Max_rain_intercept[1] = 0
globalInput$apexPARM$Max_rain_intercept[2] = 15
globalInput$apexPARM$Rain_intercept_coeff[1] = 0.05
globalInput$apexPARM$Rain_intercept_coeff[2] = 0.3
globalInput$apexPARM$Microbial_top_soil_coeff[1] = 0.1
globalInput$apexPARM$Microbial_top_soil_coeff[2] = 1
globalInput$apexPARM$Microbial_decay_coeff[1] = 0.5
globalInput$apexPARM$Microbial_decay_coeff[2] = 1.5
# SA method and sample size:
globalInput$gsaType <- "SRC"
globalInput$sampleSize <- 1000
# 3) Performing Monte Carlo simulation using the setting in globalInput:
input4SA <- mc4APEX(globalInput)
# 4) Calculation of sensitivity indices:
sa4APEX(globalInput,input4SA = input4SA)APEXSENSUN can be used for computing performance matrix containing the performance of different Monte Carlo runs. The calculated performance matrix can be subsequently used for identifying simulations that meet a set of criteria.
# Calculation of performance matrix (containing RMSE, NASH, PBIAS, MEAN) for different Monte Carlo runs:
perfMat <- APEXSENSUN::dws2perf(observedFilePath ="Example/Observed_Files/observed.txt",
dwsFolderPath = "Example/Calculated_Outputs/DWS",
startDate="2002-01-01", endDate="2003-01-01",
captionDwsVar="ET", captionObsVar="ET",TW="week")
# Detecting simulation numbers meeting performance criteria:
acceptedSimulations <- perf2idx(perfMatrix = perfMat,
lowLimit = c(0, -25, 10, 0),
upLimit = c(10, 100, 25, 5)) This section provides 4 main tables containing the name of different parameters and their description.
Table: Table 1. General inputs
| Parameters | Description |
|---|---|
| sampleSize | Sample size or length of the discretization of parameter space. |
| captionVarSim | Simulated variable name as it appears inside .DWS APEX file. |
| captionVarObs | Observed variable names as appears inside observed file. |
| startDate | Start date for analysis with format: YYYY MM DD e.g., 2002 01 01 |
| endDate | End date for analysis with format: YYYY MM DD e.g., 2003 01 01 |
| labelAPEXExe | APEX executable file name excluding file's extension. |
| labelWatershedParam | APEX PARM file name excluding file's extension. |
| labelControlParam | APEXCONT file name excluding file's extension. |
| labelOutputVariableAWP | APEX .AWP file name excluding file's extension. |
| labelOutputVariableACY | APEX .ACY file name excluding file's extension. |
| labelOutputVariableDWS | APEX .DWS file name excluding file's extension. |
| labelObservedVar.txt | Observed file name containing observed time series. |
| backUpPARM0806.dat | Path to original APEX file containing PARM parameters. |
| backUpAPEXCONT.dat | Path to original APEX file containing APEXCONT parameters. |
| folderPathProject | Path to folder containing APEX model. |
| folderPathRCodes | No need to set! |
| folderPathObserved | Path to folder containing observed data file. |
| folderPathGsaOutputs | Path to folder storing SA results. |
| storeFolderPathWatershed | Path to folder storing generated PARM files for Monte Carlo runs. |
| storeFolderPathControl | Path to folder storing generated APEXCONT file for Monte Carlo runs. |
| calculatedOutputFolderAWP | Path to folder storing calculated .AWP files for Monte Carlo runs. |
| calculatedOutputFolderACY | Path to folder storing calculated .ACY files for Monte Carlo runs. |
| calculatedOutputFolderDWS | Path to folder storing calculated .DWS files for Monte Carlo runs. |
| gsaType | Type of SA method: MORRIS, SRC, SRRC, SOBOL, SOBOL2002, SOBOL2007, SOBOLEFF, SOBOLJANSEN, SOBOLMARA, SOBOLMARTINEZ, FAST99, KSTEST. |
Table: Table 2. SA-specific parameters
| Parameters | Description |
|---|---|
| morrisRFactor | an integer representing design repetition number (i.e. the number of elementary effect computed per factor). |
| morrisLevels | an integer specifying the number of levels of the design in OAT (Once At a Time) design. |
| sobolOrder | an integer representing maximum order in the ANOVA decomposition in Sobol method. |
| ksTestPerf | A performance function type for KSTEST method. Available options are: NASH, RMSE, PBIAS |
| ksTestThreshold | Threshold value for performance function for determining behavioral from non-behavioral simulations. |
| ksTestSigmaLevel | Significance level used in KSTEST |
Table: Table 3. APEX model parameters located inside PARM****.dat file
| Parameters | Description |
|---|---|
| Crop_canopy_PET | Crop canopy-PET |
| Root_growth_soil | Root growth-soil strength |
| Water_stress_harvest | Water stress-harvest index |
| Water_storage_N | Water storage N leaching |
| Soil_water_limit | Soil water lower limit |
| Winter_dormancy | Winter dormancy |
| N_fixation | N fixation |
| Soluble_P_runoff | Soluble phosphorus runoff coefficient |
| Pest_damage_moisture | Pest damage moisture threshold |
| Pest_damage_cover | Pest damage cover threshold |
| Moisture_req_seed_germ | Moisture required for seed germination |
| Soil_evap_coeff | Soil evaporation coefficient |
| Wind_erod_coeff | Wind erodibility coefficient |
| Nitrate_leac_ratio | Nitrate leaching ratio |
| Runoff_CN_Adj_parm | Runoff CN Residue Adjustment Parameter |
| Expand_CN_ret_parm | Expands CN retention parameter |
| Soil_evap_plant_cover | Soil evaporation – plant cover factor |
| Sedim_rout_exponent | Sediment routing exponent |
| Sedim_rout_coeff | Sediment routing coefficient |
| Runoff_CN_int_abs | Runoff curve number initial abstraction |
| Soluble_C_adsorp_coeff | Soluble Carbon adsorption Coefficient |
| CN_retention_frozen_soil | Reduces NRCS Runoff CN Retention Parameter for Frozen Soil |
| Harg_equation_parm | Hargreaves PET equation coefficient |
| Pest_leach_ratio | Pesticide leaching ratio |
| Expo_coeff_rainfall | Exponential coefficient used to account for rainfall intensity on curve number |
| Matur_frac_spring | Fraction of maturity at spring growth initiation |
| CEC_effect_nitrification | CEC effect on nitrification & volatilization |
| N_fixation_limit | Upper Nitrogen Fixation limit |
| Biological_mix_efficiency | Biological mixing efficiency |
| Soluble_P_exponent | Soluble phosphorus runoff exponent |
| Max_depth_bio_mixing | Maximum depth for biological mixing |
| OrgP_loss_exponent | Organic P loss exponent |
| MUST_coeff | Coefficient in MUST EQ |
| Harg_PET_exponent | Hargreaves PET equation exponent |
| Denit_soil_threshold | Denitrification soil-water threshold |
| Daily_denit_limit | Upper Limit of Daily Denitrification rate |
| SWAT_delivery_ratio_exponent | Exponent in Delivery Ratio for SWAT Output |
| Water_stress_coeff | Water stress weighting coefficient |
| Puddling_sat_conduct | Puddling Saturated conductivity |
| Groundwater_stor_threshold | Groundwater storage threshold |
| Root_temp_stress_exponent | Plant root temperature stress exponent |
| SCS_index_coeff | SCS curve number index coefficient |
| Plow_depth | Plow layer depth |
| CN_retention_param | Upper Limit of Curve Number Retention Parameter |
| sediment_rout_travel_coeff | Sediment routing travel time coefficient |
| RUSLE_c_factor_res | RUSLE C-factor coefficient |
| RUSLE_c_factor_height | RUSLE C-factor coefficient |
| Climate_stress_factor | Adjusts climatic stress factor |
| Max_rain_intercept | Maximum rainfall interception by plant canopy |
| Rain_intercept_coeff | Rainfall interception coefficient |
| Water_stor_residue_coeff | Water stored in litter (residue) coefficient |
| Tillage_residue_decay_rate_coeff | Exponential coefficient in EQUATION expressing tillage effect on residue decay rate |
| Microbial_soil_depth_coeff | Coefficient in oxygen EQUATION used in modifying microbial activity with soil depth |
| N_enrich_coeff | N enrichment ratio coefficient for routing |
| N_enrich_rout_exponent | N enrichment ratio exponent for routing |
| Fraction_destroyed_burn | Fraction destroyed by burn operation |
| P_enrich_rout_coeff | P enrichment ratio coefficient for routing |
| P_enrich_rout_exponent | P enrichment ratio exponent for routing |
| P_move_evap_coeff | P upward movement by evaporation coefficient |
| Max_days_grazed_rotation | Maximum number of days a pasture is grazed before rotation |
| Soil_water_up_flow_limit | Soil water Upward Flow Limit |
| Manure_erosion_equation_coeff | Manure erosion equation coefficient |
| N_enrich_ratio_delivery | N Enrichment Ratio for Delivery to SWAT |
| Dust_distribution_coeff | Dust distribution coefficient |
| RUSLE2_trans_capacity | RUSLE2 transport capacity parameter |
| RUSLE2_trans_capacity_threshold | RUSLE2 threshold transport capacity coefficient |
| Dust_distribution_exponent | Dust distribution dispersion exponent |
| Manure_erosion_exponent | Manure erosion exponent |
| Microbial_top_soil_coeff | Coefficient adjusts microbial activity function in the top soil layer |
| Microbial_decay_coeff | Microbial decay rate coefficient |
| Manure_erosion_coeff | Manure erosion coefficient |
| Volt_nitrification_partition_coeff | Volatilization/nitrification partitioning coefficient |
| Hydrograph_dev_param | Hydrograph development parameter |
| Partition_N_flow_groundwater | Partitions Nitrogen flow from groundwater |
| P_enrich_ratio_deliver_SWAT | P Enrichment Ratio for Delivery to SWAT |
| Stand_dead_fall_rate_coeff | Standing Dead fall rate coefficient |
| Runoff_2_delay_pest | Runoff amount to delay pest application |
| Soil_water_2_delay_tillage | Soil water value to delay tillage |
| Auto_mov_lower_limit | Auto mow lower limit |
| Nitrification_vol_upper_limit | Upper Limit of Nitrification-Volatilization |
| Tech_coeff | Technology Coefficient |
| Drainage_lateral_conduct | Estimates drainage system lateral hydraulic conductivity |
| P_flux_labile_active_coeff | Coefficient regulating P flux between labile and active pool |
| P_flux_active_stable_coeff | Coefficient regulating P flux between active and stable pool |
| N_salt_evap_coeff | Nitrogen and Salt Upward movement by evaporation coefficient |
| Water_table_recession_coeff | Water table recession coefficient |
| Water_table_move_limit | Limits daily water table movement |
| Water_table_recession_exponent | Water table recession |
| Subsurface_flow_factor | Subsurface flow factor |
| Flood_evap_limit | Flood Evaporation Limit |
| Runoff_adj_link | Runoff Volume Adjustment for Direct Link |
| Water_erosion_threshold | Water Erosion Threshold |
| Wind_erosion_threshold | Wind Erosion Threshold |
| Crop_stress_temp_exponent | Exponent of Crop Stress Temperature function |
| Soluble_P_leach_KD | Soluble Phosphorus Leaching KD value |
| Unknown1 | --- |
| Unknown2 | --- |
| Unknown3 | --- |
| Irrigation_cost | Cost of Irrigation Water |
| Lime_cost | Cost of Lime |
| Fuel_cost | Cost of Fuel |
| Labor_cost | Cost of Labor |
| Unknown4 | --- |
Table: Table 4. APEX control parameters located inside APEXCONT.dat file
| Parameters | Description |
|---|---|
| RFN | Average concentration of nitrogen in rainfall |
| CO2 | Carbon dioxide concentration in atmosphere |
| CQN | Concentration of NO3-N in irrigation water in ppm |
| PSTX | Pest damage scaling factor |
| YWI | Number years of maximum monthly 0.5 hour rainfall available |
| BTA | COEF (0-1) governing wet-dry probabilities given days of rain |
| EXPK | Parameter used to modify exponential rainfall amount distribution |
| QG | Channel Capacity Flow Rate |
| QCF | Exponent in watershed area flow rate equation |
| CHSO | Average upland slope (m/m) in watershed |
| BWD | Channel bottom width/depth in m/m; Channel flow rate (QG) > 0 |
| FCW | Floodplain width/channel width in m/m |
| FPSC | Floodplain saturated hydraulic conductivity in mm/h |
| GWSO | Maximum ground water storage in mm |
| RFTO | Ground water residence time in days |
| RFPO | Return Flow / (Return Flow + Deep Percolation) |
| SATO | Saturated Conductivity adjustment factor |
| FL | Field length (if wind erosion is to be considered) in kilometers |
| FW | Field width (if wind erosion is to be considered) in kilometers |
| ANG | Clockwise angle of field length from north (if wind erosion is to be considered) |
| UXP | Power Parameter of Modified Exponential Distribution of Wind Speed (if wind erosion is to be considered) |
| DIAM | Soil Particle Diameter(if wind erosion is to be considered) |
| ACW | Wind Erosion Adjustment Factor |
| GZL0 | Grazing limit |
| RTN0 | Number of years of cultivation at start of simulation |
| BXCT | Linear coefficient of change in rainfall from east to west (PI/PO/KM) |
| BYCT | Linear coefficient of change in rainfall from south to north (PI/PO/KM) |
| DTHY | Time interval for flood routing (hours) |
| QTH | Routing Threshold (mm) – VSC routing used when QVOL>QTH |
| STND | VSC Routing used when reach storage > STND |
| DRV | Equation for Water Erosion |
| PCO0 | Fraction of subareas controlled by ponds |
| RCC0 | USLE Crop Management Channel Factor |
| CSLT | Salt Concentration in Irrigation Water |
| BUS1 | Exponents of MUSI equation |
| BUS2 | Exponents of MUSI equation |
| BUS3 | Exponents of MUSI equation |