Type:	Package
Title:	Estimation and Prediction of Wet Season Calendar and Soil Water Balance for Agriculture
Version:	1.4.0
Author:	Robel Takele [aut, cre], Matteo Dell'Acqua [aut, ctb]
Maintainer:	Robel Takele <takelerobel@gmail.com>
Description:	Computes and integrates daily potential evapotranspiration (PET) and a soil water balance model. It allows users to estimate and predict the wet season calendar, including onset, cessation, and duration, based on an agroclimatic approach for a specified period. This functionality helps in managing agricultural water resources more effectively. For detailed methodologies, users can refer to Allen et al. (1998, ISBN:92-5-104219-5); Allen (2005, ISBN:9780784408056); Doorenbos and Pruitt (1975, ISBN:9251002797); Guo et al. (2016) <doi:10.1016/j.envsoft.2015.12.019>; Hargreaves and Samani (1985) <doi:10.13031/2013.26773>; Priestley and Taylor (1972) https://journals.ametsoc.org/view/journals/apme/18/7/1520-0450_1979_018_0898_tptema_2_0_co_2.xml.
License:	GPL (≥ 3)
URL:	https://github.com/RobelTakele/AquaBEHER, https://robeltakele.github.io/AquaBEHER/
BugReports:	https://github.com/RobelTakele/AquaBEHER/issues
Depends:	R (≥ 3.5.0)
Imports:	dplyr, lubridate, magrittr, rlang, sp, terra, zoo
Suggests:	ggplot2, ggrepel, knitr, learnr, prettydoc, rmarkdown, scales, stringr, testthat (≥ 3.0.0)
VignetteBuilder:	knitr
Config/testthat/edition:	3
Encoding:	UTF-8
Language:	en-US
LazyData:	true
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2024-09-24 16:55:30 UTC; robel
Repository:	CRAN
Date/Publication:	2024-09-24 22:10:05 UTC

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

Value

The result of calling rhs(lhs).

Daily Surface Meteorological Data (1982-2022) Extracted from AgERA5

Description

The AgERA5 dataset provides daily surface meteorological data for the period from 1979 to present as input for agriculture and agro-ecological studies. This dataset is based on the hourly ECMWF ERA5 data at surface level, with data from January 1, 1982, through December 31, 2022, extracted for a grid located in Angochen, Nampula province of Mozambique.

Usage

data(AgroClimateData)

Format

A data frame containing daily observations of weather variables:

• GridID: Grid ID of the location.

• Lat: Latitude of the grid in decimal degrees.

• Lon: Longitude of the grid in decimal degrees.

• Elev: Elevation above sea level in meters.

• WHC: Water holding capacity in millimeters (mm).

• Year: Year of record ("YYYY").

• Month: Month of record ("MM").

• Day: Day of record ("DD").

• Rain: Daily precipitation in millimeters (mm/day).

• Tmax: Daily maximum temperature at 2 meters height in degrees Celsius (°C).

• Tmin: Daily minimum temperature at 2 meters height in degrees Celsius (°C).

• Rs: Total amount of energy provided by solar radiation at the surface over the period 00-24h local time per unit area and time (MJ/m^2/day).

• Tdew: Mean dew point temperature at a height of 2 meters above the surface over the period 00h-24h local time (°C).

• Uz: Mean wind speed at a height of 2 meters above the surface over the period 00h-24h local time (m/s).

Source

https://cds.climate.copernicus.eu/cdsapp#!/dataset/sis-agrometeorological-indicators?tab=overview

References

AgERA5, 2021, Copernicus Climate Change Service (C3S), Fifth generation of ECMWF atmospheric reanalysis of the global climate for agriculture and agro-ecological studies. Copernicus Climate Change Service Climate Data Store (CDS), July 2021.

See Also

climateData, calcEto

Examples

## Load the agroclimate data
data(AgroClimateData)

## Get the structure of the data frame
str(AgroClimateData)

## Get the head of the data frame
head(AgroClimateData)

Potential Evapotranspiration

Description

Calculates Penman-Monteith, Priestley Taylor and Hargreaves-Samani Potential Evapotranspiration using the method described by Allen et al, (1998)

Usage

calcEto(data, method = "PM", crop = "short", Zh = NULL)

Arguments

Details

Penman-Monteith: If all variables of Tmax, Tmin, Rs, either U2 or Uz, and either RHmax and RHmin or RH or Tdew are available and crop surface (short or tall) is specified, the Penman-Monteith FAO56 formulation is used (Allen et al. 1998).

Priestley-Taylor: If all variables of Tmax, Tmin, Rs, and either RHmax and RHmin or RH or Tdew are available, the Priestley-Taylor formulation is used (Priestley and Taylor, 1972).

Hargreaves-Samani: If only Tmax and Tmin are available, the Hargreaves-Samani formulation is used for estimating reference crop evapotranspiration (Hargreaves and Samani, 1985).

Value

A list containing:

• ET.Daily: Daily estimations of reference crop evapotranspiration (mm/day).

• Ra.Daily: Daily estimations of extraterrestrial radiation (MJ/m^2/day).

• Slope.Daily: Daily estimations of slope of vapor pressure curve (kPa/°C).

• ET.type: Type of the estimation obtained.

References

Allen, R.G., L.S. Pereira, D. Raes, and M. Smith. 1998. Crop evapotranspiration-Guidelines for Computing Crop Water requirements FAO Irrigation and Drainage Paper 56. FAO, Rome 300: 6541.

Allen, R. G. 2005. The ASCE standardized reference evapotranspiration equation. Amer Society of Civil Engineers.

Guo, D., Westra, S., & Maier, H. (2016). An R package for modelling actual, potential and reference evapotranspiration. Environmental Modelling & Software, 78, 216-224. doi:10.1016/j.envsoft.2015.12.019.

Hargreaves, G.H., & Samani, Z.A. (1985). Reference crop evapotranspiration from ambient air temperature. American Society of Agricultural Engineers.

Priestley, C., & Taylor, R. (1972). On the assessment of surface heat flux and evaporation using large-scale parameters. Monthly Weather Review, 100(2), 81-92.

See Also

climateData, calcWatBal, calcSeasCal

Examples

## Load sample data:
data(climateData)
PET.HS <- calcEto(climateData, method = "HS")

## Load sample data:
data(AgroClimateData)
PET.PM <- calcEto(AgroClimateData, method = "PM", crop = "short")

Wet Season Calendar

Description

Estimates the wet season calendar, including the onset date, cessation date, and duration, based on an agroclimatic approach. The function relies on daily soil water balance parameters.

Usage

calcSeasCal(data, onsetWind.start, onsetWind.end, cessaWind.end, soilWHC)

Arguments

Details

The agroclimatic approach defines the wet season based on the balance between precipitation and potential evapotranspiration (PET). The wet season begins when the moisture available to crops exceeds their evapotranspiration demands, ensuring optimal growth conditions.

Onset: The wet season onset is defined as the first day after onsetWind.start when the ratio of actual evapotranspiration (AET) to potential evapotranspiration (PET) exceeds 0.5 for at least 5 consecutive days, and the soil moisture remains above 25% of the available soil water holding capacity (soilWHC) for a minimum of 20 consecutive days, ensuring sufficient moisture availability for plant growth.

Cessation: The wet season ends on the first day after onsetWind.end when the AET/PET ratio falls below 0.5 for at least 5 consecutive days, and the soil moisture remains below 25% of the available soil water holding capacity (soilWHC) for a minimum of 12 consecutive days.

Duration: The total duration of the wet season is the number of days between onset and cessation.

Value

A dataframe containing the following columns:

Year

The year of the season (YYYY).

OnsetDate

The onset date, formatted as "YYYY-MM-DD".

OnsetDOY

The Julian day (DOY) of the onset.

OnsetValue

The number of days since onsetWind.start.

CessationDate

The cessation date, formatted as "YYYY-MM-DD".

CessationDOY

The Julian day (DOY) of the cessation.

CessationValue

The number of days since onsetWind.start.

Duration

The duration of the wet season (in days).

References

FAO, 1977. Crop water requirements. FAO Irrigation and Drainage Paper No. 24, by Doorenbos J. and W.O. Pruitt. FAO, Rome, Italy.

FAO, 1978. Forestry for Local Community Development. FAO Forestry Paper No. 7, FAO, Rome.

FAO, 1986. Early Agrometeorological Crop Yield Forecasting. FAO Plant Production and Protection Paper No. 73, by M. Frère and G.F. Popov. FAO, Rome.

See Also

calcEto, calcWatBal

Examples

## Load example data:
data(AgroClimateData)

## Estimate daily PET:
PET <- calcEto(AgroClimateData, method = "PM", Zh = 10)

## Add the estimated PET 'ET.Daily' to a new column in AgroClimateData:
AgroClimateData$Eto <- PET$ET.Daily

## Estimate daily water balance for the soil having 100mm of WHC:
watBal.list <- calcWatBal(data = AgroClimateData, soilWHC = 100)
watBal <- watBal.list$data

## seasonal calendar is estimated for the onset window ranges from
## 01 September to 31 January having a soil with 100mm of WHC:

soilWHC <- 100
onsetWind.start <- "09-01"
onsetWind.end <- "01-31"
cessaWind.end <- "06-30"

seasCal.dF <- calcSeasCal(
  data = watBal, onsetWind.start, onsetWind.end,
  cessaWind.end, soilWHC
)

str(seasCal.dF)

Daily Soil Water Balance Estimation

Description

Estimates the daily soil water balance based on a simple mass balance budget approach. It calculates the amount of water available in the root zone of a homogeneous grass canopy growing on a well-drained, homogeneous soil.

Usage

calcWatBal(data, soilWHC)

Arguments

Value

A list with the following components:

data

A data frame containing the results of the water balance calculations, with the following columns:

• DRAIN: Deep drainage (mm).

• TRAN: Water lost by transpiration (mm).

• RUNOFF: Surface runoff (mm).

• AVAIL: Available soil moisture storage (mm).

• R: Ratio of actual to potential evapotranspiration.

warnings

A list of warnings related to any unrealistic or adjusted values in the input data or parameters used during the water balance calculations.

References

Allen, R.G.; Pereira, L.S.; Raes, D.; Smith, M. (1998). Crop Evapotranspiration: Guidelines for Computing Crop Water Requirements. FAO Irrigation and Drainage Paper no. 56, FAO: Rome, Italy. ISBN 92-5-104219-5.

Doorenbos, J., & Pruitt, W.O. (1975). Guidelines for Predicting Crop Water Requirements. Irrigation and Drainage Paper 24, Food and Agriculture Organization of the United Nations, Rome, 179 p.

See Also

calcEto, calcSeasCal

Examples

## Load sample data
data(AgroClimateData)

# Estimate daily PET using the Penman-Monteith method
PET.PM <- calcEto(AgroClimateData, method = "PM", Zh = 10)

# Add the estimated PET to the AgroClimateData frame
AgroClimateData$Eto <- PET.PM$ET.Daily

# Estimate daily soil water balance for a soil with 100 mm WHC
watBal <- calcWatBal(data = AgroClimateData, soilWHC = 100)

Daily Weather Data (1996-2020) from Angochen Weather Observing Station, Mozambique

Description

Contains daily weather data obtained from Instituto Nacional de Meteorologia (INAM). The sample data includes daily raw weather data from January 1, 1996, to December 31, 2020, from a weather station located in Angochen, Nampula province of Mozambique.

Usage

data(climateData)

Format

A data frame containing daily values of weather variables:

• Station_Name: Name of the weather station.

• Lat: Latitude of the site in decimal degrees.

• Lon: Longitude of the site in decimal degrees.

• Elev: Elevation above sea level in meters.

• Year: Year of the record (YYYY).

• Month: Month of the record (MM).

• Day: Day of the record (DD).

• Rain: Daily rainfall in millimeters (mm).

• Tmax: Daily maximum temperature at 2 meters height in degrees Celsius (°C).

• Tmin: Daily minimum temperature at 2 meters height in degrees Celsius (°C).

Source

INAM - Instituto Nacional de Meteorologia, Mozambique

See Also

AgroClimateData, calcEto

Examples

## Load the climate data
data(climateData)

## Get the structure of the data frame
str(climateData)

## Get the head of the data frame
head(climateData)

Seasonal Forecast of Wet Season Calendar (WSC) from Tercile Rainfall Probabilities using Quantile Bin Resampling (QBR)

Description

Generates seasonal forecasts for Wet Season Calendar (WSC) variables (onset or cessation) using tercile seasonal rainfall probabilities

Usage

seasFcstQBR(
  hisYearStart,
  hisYearEnd,
  rainTerc,
  seasRain,
  hisWSCvar,
  fcstVarName,
  tercileMethod
)

Arguments

Details

Uses QBR (Quantile Bin Resampling) to produce forecasts for onset or cessation of the rainy season. It first categorizes historical WSC simulations based on seasonal rainfall terciles and then resamples based on given rainfall probabilities to generate ensemble forecasts.

Value

A data frame containing the tercile probabilities for the WSC variable ("BelowNormal", "Normal", and "AboveNormal").

References

• MacLeod D, Quichimbo EA, Michaelides K, Asfaw DT, Rosolem R, Cuthbert MO, et al. (2023) Translating seasonal climate forecasts into water balance forecasts for decision making. PLOS Clim 2(3): e0000138. https://doi.org/10.1371/journal.pclm.0000138

• van den Dool HM. A New Look at Weather Forecasting through Analogues. Monthly Weather Review. 1989; 117(10):2230–2247. https://doi.org/10.1175/1520-0493(1989)117%3C2230:ANLAWF%3E2.0.CO;2

See Also

calcSeasCal, calcWatBal

Examples

library(dplyr)

## Load example data:
data(AgroClimateData)

## Estimate daily PET:
PET <- calcEto(AgroClimateData, method = "PM", Zh = 10)

## Add the estimated PET 'ET.Daily' to a new column in AgroClimateData:
AgroClimateData$Eto <- PET$ET.Daily

## Estimate daily water balance for the soil having 100mm of WHC:
watBal.list <- calcWatBal(data = AgroClimateData, soilWHC = 100)
watBal <- watBal.list$data

## seasonal calendar is estimated for the onset window ranges from
## 01 September to 31 January having a soil with 100mm of WHC:

soilWHC <- 100
onsetWind.start <- "09-01"
onsetWind.end <- "01-31"
cessaWind.end <- "06-30"

seasCal.dF <- calcSeasCal(
  data = watBal, onsetWind.start, onsetWind.end,
  cessaWind.end, soilWHC
)

## Tercile Rainfall Probabilities of seasonal Forecast for OND, 2023:
rainTerc <- data.frame(T1 = 0.15, T2 = 0.10, T3 = 0.75)

## Summarize rainfall data for October to December:
seasRain <- AgroClimateData %>%
  filter(Month %in% c(10, 11, 12)) %>%
  group_by(Year) %>%
  summarize(sRain = sum(Rain))

## Start of the historical resampling year
hisYearStart <- 1991

## End of the historical resampling year
hisYearEnd <- 2022

## Historical WSC Simulations:
hisWSCvar <- seasCal.dF

## WSC variable to forecast:
fcstVarName <- "Onset"
tercileMethod <- "quantiles"

SeasFcst.dF <- seasFcstQBR(
  hisYearStart, hisYearEnd, rainTerc,
  seasRain, hisWSCvar, fcstVarName,
  tercileMethod
)