% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cal.kc.R
\name{cal.kc}
\alias{cal.kc}
\title{Calibration of crop coefficients}
\usage{
cal.kc(
  ETo,
  P,
  RHmin,
  soil,
  crop,
  I = 0,
  CNII = c(30, 100, 1),
  u2 = 2,
  FC = NULL,
  WP = NULL,
  h = NULL,
  Zr = NULL,
  Ze = c(0.1, 0.15, 0.01),
  kc = c(c(0.1, 0.3, 0.05), c(0.1, 1, 0.1), c(0.1, 1, 0.1)),
  p = c(0.1, 1, 0.1),
  lengths = NULL,
  fw = 0.8,
  fc = NULL,
  kctype = "dual",
  region = NULL,
  regexpr = "sweet",
  initgw = 50,
  LAI = 3,
  rc = NULL,
  Kb = 0,
  Rn = NULL,
  hmodel = "gaussian",
  Zrmodel = "linear",
  xydata = NULL,
  REW = c(2, 12, 0.5),
  a1 = 360,
  b1 = c(-1, 1, 0.1),
  a2 = 240,
  b2 = c(-1, 1, 0.1),
  a3 = c(-2, 1, 0.1),
  b3 = 6.6,
  a4 = 4.6,
  b4 = c(-1.5, 1, 0.1),
  ETa = NULL,
  report = "stages",
  time = "06:00",
  HWR = 1,
  latitude = NULL,
  density = "full",
  DOY = NULL,
  slope = NULL,
  y = NULL,
  r1 = 100,
  nongrowing = "weeds",
  theta = NULL,
  profile = "variable",
  Kcmin = 0.15,
  Ky = NULL
)
}
\arguments{
\item{ETo}{Numeric. Reference evapotranspiration [mm]. This can be estimated with \code{\link{ETo}}}

\item{P}{numeric. Precipitation [mm]}

\item{RHmin}{numeric. Minimum Relative Humidity [per cent]}

\item{soil}{character. Name of soil texture as written in FAO56 TABLE 19}

\item{crop}{character. Name of the crop as written on 
FAO56 Table 11, TABLE 12 and TABLE 17}

\item{I}{numeric. Irrigation [mm]}

\item{CNII}{numeric. The initial Curve Number of the study site. 
This can be calibrated with \code{cal.kc}.}

\item{u2}{numeric. Wind speed of the nearby weather station [m/s] measured at 2m}

\item{FC}{numeric. soil water content at field capacity [-][m3 m-3]. 
This can be calibrated with \code{cal.kc}.}

\item{WP}{numeric. soil water content at wilting point [-][m3 m-3]. 
This can be calibrated with \code{cal.kc}.}

\item{h}{numeric. Maximum crop height [m]. See details below.
This can be calibrated with \code{cal.kc}}

\item{Zr}{numeric. Rooting depth.  See details below.
This can be calibrated with \code{cal.kc}}

\item{Ze}{numeric. The depth of the surface soil layer that is subject to drying 
by way of evaporation [0.10-0.15 m]. This can be calibrated with \code{\link{cal.kc}}}

\item{kc}{list. The tabulated Kc values for single crop c(kcini,kcmid,kcend)
or  dual crop model c(kcbini,kcbmid,kcbend). To use with \code{\link{sebal}} or 
any of the Surface Energy Balance models, it should be linked as list(model1,model2,model3) or
 c(model1$EF,model2$EF,model3$EF) but not a mixture of both. 
This can be calibrated with \code{\link{cal.kc}}}

\item{p}{The depletion coefficient. This can be calibrated with \code{\link{cal.kc}}}

\item{lengths}{list. The lengths of the crop growth stages. It can take dates in the form of 
c(start of planting ('YYYY-mm-dd), start of rapid growth, 
start of mid season, start of maturity, harvesting) 
or in the form number of days: c(initial days, dev days, mid days, late days). 
See FAO56 TABLE 11. If performing time series simulation, different dates or 
one season dates can be set; for instance two seasons simulation can be of the form 
c(initial days, dev days, mid days, late days, initial days, dev days, mid days, late days) 
or just c(initial days, dev days, mid days, late days)}

\item{fw}{list or numeric or character. This can take different fw values
throughout the growing season. It can also take one numeric value and this will
be transform depending on the type of wetting. If the wetting event is only Precipitation,
it is set to 1; if it is only Irrigation it is set to the provided fw value. If it is
both Precipitation and Irrigation weights are assigned for calculation of fw. 
fw can also take a character such as "Drip", "Sprinkler", "Basin", "Border", 
"alternated furrows", "Trickle", "narrow bed" and "wide bed". 
In this case fw values from FAO56 are assigned.}

\item{fc}{numeric. fraction of ground covered by tree canopy}

\item{kctype}{character. The type of model either "single" or "double". In spatial modelling involving
Evaporation Fraction, kctype can be set to "METRIC" or "SSEB" so that 
Actual Evapotranspiration will be estimated as ETo*EF else it will be
estimated with Rn as ETa=(EF*Rn)/2.45. Note that Rn is in MJm-2 day-1.}

\item{region}{character. The region of the crop as on FAO56 TABLE 11}

\item{regexpr}{character. Extra term that can be used to search crop names on FAO56 Tables}

\item{initgw}{numeric. Initial ground water level [m]}

\item{LAI}{numeric. Leaf Area Index}

\item{rc}{numeric Runoff coefficient [0-1]. 
This must be used if there is no information on Curve Number.
This can be calibrated with \code{\link{cal.kc}}}

\item{Kb}{ground water (base flow) recession parameter. 
The default is zero where no baseflow occurs}

\item{Rn}{Net daily radiation [w/m2]. Estimated this with  \code{\link{ETo}}}

\item{hmodel}{character. The type of crop growth model during the simulation. 
It takes "gaussian","linear", "exponential"}

\item{Zrmodel}{character. The type of root growth model during the simulation. 
It takes "gaussian","linear", "exponential"}

\item{xydata}{list c(longitude, latitude). The observation points of the model. 
This should be set only if the model is spatial.}

\item{REW}{numeric Readily Evaporable Water. It can be calibrated with \code{\link{cal.kc}}}

\item{a1}{soil water storage to maximum root depth (Zr) at field capacity}

\item{b1}{Liu et al. (2006) parameter for computing capillary rise [-0.17]. It can calibrated with
\code{\link{cal.kc}}}

\item{a2}{Liu et al. (2006) parameter for computing capillary rise [240]. It can be calibrated with
\code{\link{cal.kc}}}

\item{b2}{Liu et al. (2006) parameter for computing capillary rise [-0.27]. It can be calibrated with
\code{\link{cal.kc}}}

\item{a3}{Liu et al. (2006) parameter for computing capillary rise [-1.3]. It can be calibrated with
\code{\link{cal.kc}}}

\item{b3}{Liu et al. (2006) parameter for computing capillary rise [6.6]. It can be calibrated with
\code{\link{cal.kc}}}

\item{a4}{Liu et al. (2006) parameter for computing capillary rise [4.6]. It can be calibrated with
\code{\link{cal.kc}}}

\item{b4}{Liu et al. (2006) parameter for computing capillary rise [-0.65]. It can be calibrated with
\code{\link{cal.kc}}}

\item{ETa}{Measured Actual Evapotranspiration [mm]}

\item{report}{list. In case of spatial modelling, which days' map should be reported. 
The default is "stages" where the periods of stages maps are reported as values. 
In an ascending order it can take values such as 1:12 days or c(1,3,6:12) days.}

\item{time}{character. Time of the occurrence Irrigation or Precipitation.}

\item{HWR}{numeric. Default is 1. Height to width ratio of individual plants or groups of 
plants when viewed from the east or from the west [-].}

\item{latitude}{geographical coordinates in decimal degrees. It should be negative
for southern hemisphere}

\item{density}{character. density factor for the trees, 
vines or shrubs on how they are arranged.
It can take "full", "row" or "random" or "round".}

\item{DOY}{Numeric or Date [YYYY-mm-dd]. Day of the Year. 
If you give data in the form of date [YYYY-mm-dd], it will be converted to DOY}

\item{slope}{numeric. slope of saturation vapour pressure curve at air temperature T [kPa oC-1].}

\item{y}{numeric. psychometric constant  [kPa oC-1]}

\item{r1}{leaf resistance FOR STOMATAL CONTROL [s/m]}

\item{nongrowing}{character. The type of surface during non-growing season. 
It can take "weeds", "bare", or "mulch"}

\item{theta}{numeric. The measured soil water content [m3/m3] in the 
profile. Leave those days without measured data blank.}

\item{profile}{numeric or character. The profile depth to perform water balance.
It takes "variable" when updating the depth with root growth (default). Or taking "fixed" when
the maximum root zone is used. It can also take numeric value and this can be longer than
maximum root length.}

\item{Kcmin}{Minimum  Kc value}

\item{Ky}{list or array. yield response factor [-] in the form of 
c(initial Ky,crop dev't Ky, mid season Ky, late season Ky, total season Ky). 
For instance Maize Ky is c(0.4,0.4,1.3,0.5,1.25). Ky values for other crops
are tabulated in FAO Irrigation and Drainage Paper 33 (Doorenbos and Kassam,
1979) and Paper 56 (Allen et al., 1998).
If only one Ky value is supplied it will be repeated for all the seasons.}
}
\value{
The function returns optimised parameters as "parameters", goodness of fit 
as "fit", and calibrated model as "mod". It also prints candidates of parameters and 
goodness of fit of the local optimum values. For the explanation of calibrated model 
output and optimised parameters see the return values of \code{\link{kc}}. Here, only
goodness of fit tests explanations are given.
\describe{
\item{mod:}{ The optimised model. See return of \code{\link{kc}} for more details}
\item{parameters:}{ parameters of the optimised model}
\item{fit:}{  Goodness of fit tests. See \code{\link{fitting}} for explanation of variables}
}
}
\description{
This function can estimate up to 23 parameters of FAO single and dual crop
parameters. The parameters include soil parameters: WP,FC, REW; 
crop parameters: kcini,kcmid,kcend,kcbini,kcbmid,kcbend,h,Zr; 
the evaporation parameters: p and Ze, 
runoff coefficients: CNII or rc, as well as groundwater and capillary rise 
parameters: initgw,a1,b1,a2,b2,a3,b3,a4,b4. For each parameter initial, maximum and range 
values must be provided if one wants to optimise it.
There are also 12 goodness of fit tests for the evaluation of the model with
\code{\link{fitting}} :r-square, index of agreement, F-value, p-value, sse,sst, AIC,
BIC, RMSE, NRMSE and nashSutcliffe coefficients. A calibrated model that uses more 
parameters gets punished by AIC and BIC as well as adjusted R2, RMSE, NRMSE.

Both point and spatial model can be calibrated. The actual model is available at \code{\link{kc}}
}
\details{
\describe{
There are several ways  to use cal.kc:
 \item{\strong{Measured Data}}{The kc model can be calibrated against either Actual Evapotranspiration (ETa) or
 Available Soil Water; the user must specify theta. If the calibration is done on a point data then time series for
 that location must be provided. If multiple locations are provided with xydata and corresponding 
 multiple locations as input data, then ETa or theta must be provided for all locations. See also \code{kc} 
 for more details on locations.     }
 \item{\strong{Number of optimised parameters and Goodness of fit}}{ 
 There is a need to limit the number of calibrated parameters.
  One can compare models by observing the adjusted goodness of fit tests. 
  The more parameters that one uses the less are the values of R-square but
  RMSE, BIC, AIC increases. Unadjusted and adjusted goodness of fit tests
   are provided with this function.
    }
  }
}
\examples{
\dontrun{
#fewer iteration
file=system.file("extdata","sys","irrigation.txt",package="sebkc")
data=read.table(file,header=TRUE)  
P=data$P
rc=0
I=data$I
ETo=data$ETo
Zr=data$Zr
p=0.6
FC=0.23
WP=0.10
u2=1.6  
RHmin=35
soil="sandy loam"
crop="Broccoli"
#single kc calibration with fewer iteration
cal=cal.kc(ETo,P,RHmin,soil,crop,I=0,kc=NULL,CNII=67,
u2=2,FC=NULL,WP=NULL,h=NULL,Zr=NULL,lengths=NULL,fc=NULL,
kctype="single",region=NULL,regexpr=NULL,initgw=50,LAI=3,
rc=NULL,Rn=NULL,hmodel="gaussian",Zrmodel="linear",
xydata=NULL,ETa=ETo,a1=360,b1=-0.17,a2=240,b2=-0.27,
a3=-1.3,b3=6.6,a4=4.6,b4=-0.65)
parameters=cal$parameters
output=cal$mod$output
gof=cal$fit
ETc=cal$mod$output$ETc
TAW=cal$mod$output$TAW

#Single kc with different kcs. kc uses default values
#RMSE_adj and NRMSE_adj equal to NAN because the number of parameters more than time steps(days)
cal=cal.kc(ETo,P,RHmin,soil,crop,I=0,CNII=67,u2=2,FC=NULL,WP=NULL,
h=NULL,Zr=NULL,lengths=NULL,fc=NULL,kctype="single",region=NULL,
regexpr=NULL,initgw=50,a1=c(100,400,10),b1=c(-1,-0.1,0.1),
a2=c(100,400,10),b2=c(-1,1,0.1),a3=c(-2,1,0.1),b3=c(1,10,1),
a4=c(1,10,1),b4=c(-1.5,1,0.1),LAI=3,rc=NULL,
Rn=NULL,hmodel="gaussian",Zrmodel="linear",xydata=NULL,ETa=ETo)

#Example with fixed kcs
cal=cal.kc(ETo,P,RHmin,soil,crop,I=0,CNII=67,kc=c(0.1,1.15,1),
u2=2,FC=NULL,WP=NULL,h=NULL,Zr=NULL,lengths=NULL,
fc=NULL,kctype="single",region=NULL,regexpr=NULL,initgw=50,
b1=c(-1,-0.1,0.1),b2=c(-1,1,0.1),LAI=3,rc=NULL,Rn=NULL,
hmodel="gaussian",Zrmodel="linear",xydata=NULL,ETa=ETo)

#Example with spatial kcs
#landsat folder with original files but a subset
folder=system.file("extdata","stack",package="sebkc") 
sebiauto=sebi(folder=folder,welev=317,Tmax=31,Tmin=28) #sebi model
kc2=stack(sebiauto$EF/2,sebiauto$EF,sebiauto$EF/3) #assign EF to kc
xydata=data.frame(cbind(longitude=data$longitude,latitude=data$latitude))
modEF=kc(ETo,P=P,RHmin,soil,crop,I,kc=kc2,Rn=8,lengths = c(4,4,2,2),xydata=xydata)
ETa=modEF$ETcxy[3:14]

calsp=cal.kc(ETo,P,RHmin,soil,crop,I=0,CNII=67,kc=kc2,u2=2,FC=NULL,
 WP=WP,h=NULL,Zr=NULL,lengths = c(4,4,2,2),fc=NULL,kctype="single",
 region=NULL,regexpr=NULL,initgw=50,b1=c(-1,-0.1,0.1),b2=c(-1,1,0.1),
 LAI=3,rc=NULL,Rn=7,hmodel="gaussian",Zrmodel="linear",xydata=xydata,ETa=ETa)
 gof=cal$fit
r2=cal$fit$r2
AIC=cal$fit$AIC
ETcxy=cal$mod$ETcxy
TAW=cal$mod$TAW
}
}
\seealso{
\code{\link{kc}}
}
\author{
George Owusu
}
