# Introduction to CropWaterBalance

# Introduction

Irrigated areas have increased throughout the globe to support the growing global population and to cope with climate change impacts (@Siyal2023). In this context, the {CropWaterBalance} allows users to keep track of the soil water deficit in the root zone through the crop water balance accounting (@Andales2012). The goal of the package is to assist users in making decisions about when and how much to irrigate. The most important function of the package is the `CWB()`, which calculates several parameters of the crop water balance, including crop evapotranspiration (ETc), actual crop evapotranspiration, stored water in the root zone and soil water deficit (D). The function also suggests when irrigate, considering the management allowed depletion (MAD) provided by the users. Although the FAO-Penman and Monteith equation is recognized as the standard method for estimating daily amounts of reference evapotranspiration (ETO) (@Allen1998), the high number of variables required for calculating this model limits its operational use in several regions in the world. Thus, the package includes the function `ETO_PM()`, which estimate daily ETO amounts through the FAO-Penman and Monteith equation, and the functions `ETO_PT()` and `ETO_HS()`), which calculates this agrometeorological parameter through other two alternative (and simpler) methods: Priestley-Taylor (@Priestley1972) and Hargreaves-Samani (@Hargreaves1985), respectively. Additionally, the {CropWaterBalance} has other two functions (`Compare()` and `Descriptive()`). The first calculates measures of accuracy and agreement between two data samples and the second calculates descriptive statistics for these samples. Therefore, these two functions assist users in selecting suitable ET0 estimating methods for a particular region or season.

# Getting Started

Load the library in your R session.

    library(CropWaterBalance)
    #>
    #> Attaching package: 'CropWaterBalance'
    #> The following object is masked from 'package:methods':
    #>
    #>     Compare

## Using ETO_PM() to calculate daily amounts of reference evapotranspiration

Reference evapotranspiration (ET0) is the combined process of evaporation and transpiration that occurs from well-fertilized and disease-free hypothetical grass reference crop, grown in large fields under no soil water restriction and achieving full production (@Allen1998). The `ETO_PM()` function calculates daily ETO amounts using the FAO-Penman and Monteith equation (in millimetres).

## Step 1: Applying `ETO_PM()` in Campinas-SP, Brazil

    Tavg <- DataForCWB[, 2]
    Tmax <- DataForCWB[, 3]
    Tmin <- DataForCWB[, 4]
    Rn <- DataForCWB[, 6]
    WS <- DataForCWB[, 7]
    RH <- DataForCWB[, 8]
    G <- DataForCWB[, 9]
    CpsET0PM <-
      ET0_PM(
        Tavg = Tavg,
        Tmax = Tmax,
        Tmin = Tmin,
        Rn = Rn,
        RH = RH,
        WS = WS,
        G = G,
        Alt = 700
      )
    head(CpsET0PM)
    #>        ET0_PM
    #> [1,] 2.440372
    #> [2,] 4.171917
    #> [3,] 4.290477
    #> [4,] 3.665459
    #> [5,] 4.848520
    #> [6,] 5.669878

By analyzing the `ET0_PM()` function, the user verify that the FAO-Penman and Monteith equation requires several inputs, which includes the soil heat flux (G). This latter variable is rarely measure. This is the reason why the {CropWaterBalance} has an auxiliary function (`Soil_Heat_Flux()`) that estimates G as function of daily average air temperature values. The users may use this auxiliary function to estimate G and then apply the `ET0_PM()` function. Alternatively, the users may simply run `ET0_PM()` without the G argument. In this case, this latter function will automatically use `Soil_Heat_Flux()` and then estimate ETO. See the example below.

    Tavg <- DataForCWB[, 2]
    Tmax <- DataForCWB[, 3]
    Tmin <- DataForCWB[, 4]
    Rn <- DataForCWB[, 6]
    WS <- DataForCWB[, 7]
    RH <- DataForCWB[, 8]
    G <- Soil_Heat_Flux(Tavg)
    #> Warning in Soil_Heat_Flux(Tavg): The first 3 G values were set to zero
    CpsET0PM_WithG <-
      ET0_PM(
        Tavg = Tavg,
        Tmax = Tmax,
        Tmin = Tmin,
        Rn = Rn,
        RH = RH,
        WS = WS,
        G = G,
        Alt = 700
      )
    CpsET0PM_WithoutG <-
      ET0_PM(
        Tavg = Tavg,
        Tmax = Tmax,
        Tmin = Tmin,
        Rn = Rn,
        RH = RH,
        WS = WS,
        Alt = 700
      )
    #> Warning in Soil_Heat_Flux(Tavg): The first 3 G values were set to zero
    head(cbind(CpsET0PM_WithG, CpsET0PM_WithoutG))
    #>        ET0_PM   ET0_PM
    #> [1,] 2.293183 2.293183
    #> [2,] 4.104242 4.104242
    #> [3,] 4.333359 4.333359
    #> [4,] 3.665304 3.665304
    #> [5,] 4.848440 4.848440
    #> [6,] 5.670052 5.670052

## Step 2: Applying `ETO_PT()` and `ET0_HS()` in Campinas-SP, Brazil

As described in the introduction, the users may need to estimate ETO using non-standard methods, which require less input than the FAO-Penman and Monteith. The {CropWaterBalance} allows users to estimate this agrometeorological parameter using the Priestley-Taylor (`ETO_PT()`) and Hargreaves-Samani (`ET0_HS()`) methods. Note that the same considerations made for G in respect to `ETO_PM()` are valid for `ETO_PT()`.

    Tavg <- DataForCWB[, 2]
    Tmax <- DataForCWB[, 3]
    Tmin <- DataForCWB[, 4]
    Ra <- DataForCWB[, 5]
    Rn <- DataForCWB[, 6]
    G <- DataForCWB[, 9]
    CpsET0PT <- ET0_PT(Tavg = Tavg, Rn = Rn, G = G)
    CpsET0HS <- ET0_HS(
      Ra = Ra,
      Tavg = Tavg,
      Tmax = Tmax,
      Tmin = Tmin
    )
    head(cbind(CpsET0PT, CpsET0HS))
    #>        ET0_PT      ET0
    #> [1,] 3.432709 4.703700
    #> [2,] 5.849554 5.331592
    #> [3,] 6.432616 5.664174
    #> [4,] 5.695334 6.163377
    #> [5,] 7.023900 5.291303
    #> [6,] 7.817355 6.251883

The estimation of CpsET0PT and/or CpsET0HS raises the following question: Can these alternative methods really replace the FAO-Penman and Monteith model? Although the answer to this question may be regarded as a complex function involving local weather conditions and users’ subjective choices, the (`Compare()`) and (`Descriptive()`) functions provide statistical information, which may assist users in such decision. In this context, the `Compare()` and `Descriptive()` functions may be used to verify how well an alternative ET0 estimating method approaches ET0_PM.

    Tavg <- DataForCWB[, 2]
    Tmax <- DataForCWB[, 3]
    Tmin <- DataForCWB[, 4]
    Ra <- DataForCWB[, 5]
    Rn <- DataForCWB[, 6]
    WS <- DataForCWB[, 7]
    RH <- DataForCWB[, 8]
    G <- DataForCWB[, 9]
    CpsET0PM <-
      ET0_PM(
        Tavg = Tavg,
        Tmax = Tmax,
        Tmin = Tmin,
        Rn = Rn,
        RH = RH,
        WS = WS,
        G = G,
        Alt = 700
      )
    CpsET0PT <- ET0_PT(Tavg = Tavg, Rn = Rn, G = G)
    CpsET0HS <- ET0_HS(
      Ra = Ra,
      Tavg = Tavg,
      Tmax = Tmax,
      Tmin = Tmin
    )
    PM_PT <- Compare(Sample1 = CpsET0PM, Sample2 = CpsET0PT)
    PM_PT
    #>       AME     RMSE     dorig     dmod        dref     RQuad
    #> 1 1.69222 1.813449 0.6403158 0.376103 -0.05737454 0.8675223
    Descrp_PM_PT <-
      cbind(Descriptive(Sample = CpsET0PM), Descriptive(Sample = CpsET0PT))
    Descrp_PM_PT
    #>   SampleSize  Avg  Med   SD   SE MaxValue MinValue FreqZero% SampleSize  Avg
    #> 1        129 3.37 3.46 0.97 0.09     5.76     1.26         0        129 5.06
    #>    Med   SD   SE MaxValue MinValue FreqZero%
    #> 1 5.22 1.46 0.13     8.15     2.14         0
    PM_HS <- Compare(Sample1 = CpsET0PM, Sample2 = CpsET0HS)
    PM_HS
    #>        AME     RMSE     dorig      dmod       dref     RQuad
    #> 1 1.468722 1.630292 0.6033421 0.3818204 0.07924634 0.5546701
    Descrp_PM_HS <-
      cbind(Descriptive(Sample = CpsET0PM), Descriptive(Sample = CpsET0HS))
    Descrp_PM_HS
    #>   SampleSize  Avg  Med   SD   SE MaxValue MinValue FreqZero% SampleSize  Avg
    #> 1        129 3.37 3.46 0.97 0.09     5.76     1.26         0        129 4.82
    #>    Med   SD  SE MaxValue MinValue FreqZero%
    #> 1 5.11 1.09 0.1     6.73     2.25         0

The results provided by the `Compare()` and `Descriptive()` functions, indicate that none of the two alternative methods can be used to replace the for calculating daily ET0 amounts. For instance, the values of the modified index of agreement (dmod) (@Willmott1985) remained below 0.4 for both comparisons (PM vs PT) and (PM vs HS). Additionally, the corresponding absolute mean errors (AME; 1.69222 and 1.468722) represents, approximately, 50% and 43% of the average value of the ET0_PM (3.367377).

## Step 3: The Crop Water Balance Accounting. Applying `InitialD()` and `CWB()` in Campinas-SP, Brazil

Considering the previous results, we applied the `CWB()` using daily values of rainfall and ET0_PM obtained/estimated from daily data of the weather station of Campinas. We included this meteorological data in the package (DataForCWB), along with parameters required for calculating the crop water balance: depth of the root zone (Drz), available water capacity (AWC; amount of water between field capacity and permanent wilting point), management allowed depletion (MAD), and crop coefficient (Kc). The example below loaded DataForCWB to apply `CWB()` in Campinas-SP. Only for the sake of simplicity, Kc values were set to 1 for the entire period. The initial D value (Dinitial) required for initiating the crop water balance account was obtained using function `DInitial()` with teta_FC and AWC values obtained from two data sets included in the package (DataForSWC.rda and DataForAWC). These data sets provide soil water content values (m3/m3) for the effective root zone at the field capacity and at permanent wilting point, and AWC values (mm/m), respectively (teta_obs was measured in the field). We applied the `CWB()` function considering two scenarios. Scenario 1 in which no irrigation was applied and scenario 2 in which the package’s recommendation about when and how much to irrigate was met.

    Tavg <- DataForCWB[, 2]
    Tmax <- DataForCWB[, 3]
    Tmin <- DataForCWB[, 4]
    Rn <- DataForCWB[, 6]
    WS <- DataForCWB[, 7]
    RH <- DataForCWB[, 8]
    G <- DataForCWB[, 9]
    ET0 <- ET0_PM(Tavg, Tmax, Tmin, Rn, RH, WS, G, Alt = 700)
    Dinitial <-
      Dinitial(teta_FC = 0.30,
               teta_Obs = 0.17,
               Drz = DataForCWB[1, 11])
    Rain <- DataForCWB[, 10]
    Drz <- DataForCWB[, 11]
    AWC <- DataForCWB[, 12]
    MAD <- DataForCWB[, 13]
    Kc <- DataForCWB[, 14]
    Irrig <- DataForCWB[, 15]
    Scenario1 <- CWB(
      Rain = Rain,
      ET0 = ET0,
      AWC = AWC,
      Drz = Drz,
      Kc = Kc,
      Irrig = Irrig,
      MAD = MAD,
      InitialD = Dinitial,
      start.date = "2011-11-23"
    )
    Scenario1[1:8, ]
    #>            DaysSeason Rain Irrig ET0 Kc WaterStressCoef_Ks ETc (P+Irrig)-ETc
    #> 2011-11-23          1 45.5     0 2.4  1                1.0 2.4          43.0
    #> 2011-11-24          2  0.3     0 4.2  1                1.0 4.2          -3.9
    #> 2011-11-25          3  0.0     0 4.3  1                1.0 4.3          -4.3
    #> 2011-11-26          4 11.4     0 3.7  1                1.0 3.7           7.8
    #> 2011-11-27          5  0.3     0 4.8  1                1.0 4.8          -4.6
    #> 2011-11-28          6  0.0     0 5.7  1                1.0 5.7          -5.7
    #> 2011-11-29          7  0.0     0 5.8  1                0.9 5.8          -5.8
    #> 2011-11-30          8  0.5     0 3.0  1                0.8 3.0          -2.5
    #>            NonStandardCropEvap ET_Defict  TAW SoilWaterDeficit d_MAD
    #> 2011-11-23                 2.4       0.0 45.7              0.0  13.7
    #> 2011-11-24                 4.2       0.0 45.7              3.9  13.7
    #> 2011-11-25                 4.3       0.0 45.7              8.2  13.7
    #> 2011-11-26                 3.7       0.0 45.7              0.4  13.7
    #> 2011-11-27                 4.8       0.0 45.7              5.0  13.7
    #> 2011-11-28                 5.7       0.0 45.7             10.7  13.7
    #> 2011-11-29                 5.3       0.5 45.7             16.5  13.7
    #> 2011-11-30                 2.5       0.5 45.7             19.0  13.7
    #>                        D>=dmad
    #> 2011-11-23                  No
    #> 2011-11-24                  No
    #> 2011-11-25                  No
    #> 2011-11-26                  No
    #> 2011-11-27                  No
    #> 2011-11-28                  No
    #> 2011-11-29 Yes. Irrigate 16 mm
    #> 2011-11-30 Yes. Irrigate 19 mm
    Irrig[7] <- 16
    Scenario2 <- CWB(
      Rain = Rain,
      ET0 = ET0,
      AWC = AWC,
      Drz = Drz,
      Kc = Kc,
      Irrig = Irrig,
      MAD = MAD,
      InitialD = Dinitial,
      start.date = "2011-11-23"
    )
    Scenario2[1:8, ]
    #>            DaysSeason Rain Irrig ET0 Kc WaterStressCoef_Ks ETc (P+Irrig)-ETc
    #> 2011-11-23          1 45.5     0 2.4  1                  1 2.4          43.0
    #> 2011-11-24          2  0.3     0 4.2  1                  1 4.2          -3.9
    #> 2011-11-25          3  0.0     0 4.3  1                  1 4.3          -4.3
    #> 2011-11-26          4 11.4     0 3.7  1                  1 3.7           7.8
    #> 2011-11-27          5  0.3     0 4.8  1                  1 4.8          -4.6
    #> 2011-11-28          6  0.0     0 5.7  1                  1 5.7          -5.7
    #> 2011-11-29          7  0.0    16 5.8  1                  1 5.8          10.2
    #> 2011-11-30          8  0.5     0 3.0  1                  1 3.0          -2.5
    #>            NonStandardCropEvap ET_Defict  TAW SoilWaterDeficit d_MAD D>=dmad
    #> 2011-11-23                 2.4         0 45.7              0.0  13.7      No
    #> 2011-11-24                 4.2         0 45.7              3.9  13.7      No
    #> 2011-11-25                 4.3         0 45.7              8.2  13.7      No
    #> 2011-11-26                 3.7         0 45.7              0.4  13.7      No
    #> 2011-11-27                 4.8         0 45.7              5.0  13.7      No
    #> 2011-11-28                 5.7         0 45.7             10.7  13.7      No
    #> 2011-11-29                 5.8         0 45.7              0.5  13.7      No
    #> 2011-11-30                 3.0         0 45.7              3.0  13.7      No

In both scenarios, the package suggested irrigating on 29/11/2011 because the soil water deficit had become larger than dmad. Since in scenario 1 we applied no irrigation, the Ks coefficient started to assume values smaller than 1 and the NonStandardCropEvap becomes smaller than ETc, which may prevent the crop from achieving its potential yield. In scenario 2, we followed the package’s recommendation and applied irrigation on day 29 (Irrig = 16 mm). In this case, no crop evapotranspiration deficit was observed, indicating no water shortage in the root zone.

## Step 3 (Alternative): The Crop Water Balance Accounting. Applying `InitialD()` and `CWB_fixedSchedule` in Campinas-SP, Brazil

Until now, we have assumed that the decision of when and how much to irrigate was solely dependent on soil-plant-atmosphere factors. However, it is well-known that this decision may also be significantly influenced by the design and operation of the irrigation system, as well as the availability of labor and water. This is why we included in the package the `CWB_fixedSchedule` fuction that, as the `CWB()`, also calculates the crop water balance in the root zone. However, it allows users to specify the number of days between consecutive irrigations.This is accompliched by setting the parameter Scheduling to the number of days defining this fixed interval between two consecutive irrigations. The estimation of how much to irrigate is performed on this specific days. This is why we included in the package the `CWB_fixedSchedule()` function that, as the `CWB`, also calculates the crop water balance in the root zone. However, it allows users to specify the number of days between consecutive irrigations.This is accomplished by setting the parameter Scheduling to the number of days defining this fixed interval between two consecutive irrigations. The estimation of how much to irrigate is performed on this specific days.

    Tavg <- DataForCWB[, 2]
    Tmax <- DataForCWB[, 3]
    Tmin <- DataForCWB[, 4]
    Rn <- DataForCWB[, 6]
    WS <- DataForCWB[, 7]
    RH <- DataForCWB[, 8]
    G <- DataForCWB[, 9]
    ET0 <- ET0_PM(Tavg, Tmax, Tmin, Rn, RH, WS, G, Alt = 700)
    Dinitial <-
      Dinitial(teta_FC = 0.30,
               teta_Obs = 0.17,
               Drz = DataForCWB[1, 11])
    Rain <- DataForCWB[, 10]
    Drz <- DataForCWB[, 11]
    AWC <- DataForCWB[, 12]
    MAD <- DataForCWB[, 13]
    Kc <- DataForCWB[, 14]
    Scheduling <- 5
    Irrig <- DataForCWB[, 15]
    Scenario_FixedSchedule <-
      CWB_FixedSchedule(
        Rain = Rain,
        ET0 = ET0,
        AWC = AWC,
        Drz = Drz,
        Kc = Kc,
        Irrig = Irrig,
        MAD = MAD,
        InitialD = Dinitial,
        Scheduling = Scheduling,
        start.date = "2011-11-23"
      )
    Scenario_FixedSchedule[1:15, ]
    #>            DaysSeason   Rain Irrig   ET0 Kc WaterStressCoef_Ks   ETc
    #> 2011-11-23          1 45.470     0 2.440  1              1.000 2.440
    #> 2011-11-24          2  0.254     0 4.172  1              1.000 4.172
    #> 2011-11-25          3  0.000     0 4.290  1              1.000 4.290
    #> 2011-11-26          4 11.430     0 3.665  1              1.000 3.665
    #> 2011-11-27          5  0.254     0 4.849  1              1.000 4.849
    #> 2011-11-28          6  0.000     0 5.670  1              1.000 5.670
    #> 2011-11-29          7  0.000     0 5.757  1              0.914 5.757
    #> 2011-11-30          8  0.508     0 3.009  1              0.836 3.009
    #> 2011-12-01          9 35.810     0 3.588  1              1.000 3.588
    #> 2011-12-02         10  0.000     0 3.929  1              1.000 3.929
    #> 2011-12-03         11 11.940     0 3.179  1              1.000 3.179
    #> 2011-12-04         12 21.340     0 3.180  1              1.000 3.180
    #> 2011-12-05         13  0.000     0 4.239  1              1.000 4.239
    #> 2011-12-06         14 10.920     0 3.925  1              1.000 3.925
    #> 2011-12-07         15  3.302     0 3.737  1              1.000 3.737
    #>            (P+Irrig)-ETc NonStandardCropEvap ET_Defict   TAW SoilWaterDeficit
    #> 2011-11-23        43.030               2.440     0.000 45.72            0.000
    #> 2011-11-24        -3.918               4.172     0.000 45.72            3.918
    #> 2011-11-25        -4.290               4.290     0.000 45.72            8.208
    #> 2011-11-26         7.765               3.665     0.000 45.72            0.444
    #> 2011-11-27        -4.595               4.849     0.000 45.72            5.038
    #> 2011-11-28        -5.670               5.670     0.000 45.72           10.708
    #> 2011-11-29        -5.757               5.263     0.495 45.72           16.465
    #> 2011-11-30        -2.501               2.516     0.494 45.72           18.967
    #> 2011-12-01        32.222               3.588     0.000 76.20            0.000
    #> 2011-12-02        -3.929               3.929     0.000 76.20            3.929
    #> 2011-12-03         8.761               3.179     0.000 76.20            0.000
    #> 2011-12-04        18.160               3.180     0.000 76.20            0.000
    #> 2011-12-05        -4.239               4.239     0.000 76.20            4.239
    #> 2011-12-06         6.995               3.925     0.000 76.20            0.000
    #> 2011-12-07        -0.435               3.737     0.000 76.20            0.435
    #>             d_MAD            Scheduling
    #> 2011-11-23 13.716                    No
    #> 2011-11-24 13.716                    No
    #> 2011-11-25 13.716                    No
    #> 2011-11-26 13.716                    No
    #> 2011-11-27 13.716 Time to Irrigate 5 mm
    #> 2011-11-28 13.716                    No
    #> 2011-11-29 13.716                    No
    #> 2011-11-30 13.716                    No
    #> 2011-12-01 22.860                    No
    #> 2011-12-02 22.860 Time to Irrigate 4 mm
    #> 2011-12-03 22.860                    No
    #> 2011-12-04 22.860                    No
    #> 2011-12-05 22.860                    No
    #> 2011-12-06 22.860                    No
    #> 2011-12-07 22.860 Time to Irrigate 0 mm

# References