Type:	Package
Title:	Estimating Water Retention and Infiltration Model Parameters using Experimental Data
Version:	2.1.2
Description:	Estimates the parameters of infiltration and water retention models using the curve-fitting methods as shown in Omuto and Gumbe (2009) <doi:10.1016/j.cageo.2008.08.011>. The models considered are those that are commonly used in soil science. Version 2 of the package has new models for water retention characteristic curves.
License:	GPL-2 | GPL-3 [expanded from: GPL]
Depends:	R (≥ 3.5.0)
Imports:	stats
Suggests:	minpack.lm, nlme
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.3.3
NeedsCompilation:	no
Packaged:	2026-02-26 10:29:44 UTC; Cthine
Author:	Christian Thine Omuto [aut, cre]
Maintainer:	Christian Thine Omuto <thineomuto@yahoo.com>
Repository:	CRAN
Date/Publication:	2026-02-26 11:00:08 UTC

Brook-Corey water retention model

Description

This is a four-parameter function to determine water retention hydraulic parameters contained in the Brooks-Corey water retention model

Usage

Brook(x, thr, ths, alp, nscal)

Arguments

Details

A Brooks-Corey model is a type of nonlinear curve fitting model for fitting water retention characteristics using experimental data. It requires initial parameter estimates for the model to work. This can be obtained using Dstart function (e.g. thr=Dstart(data)[1]). If warnings are given during the estimation process, try to increase the iteration limit using control function. Sometimes the warnings can be suppressed using (warn=-1)/ignored since they do not terminate the process

Value

A list of objects returned by standard R regression functions such as nls and lm

Author(s)

Christian Thine Omuto

References

Brooks RH and Corey AT.1964. Hydraulic properties of porous medium. Hydrology Paper Number 3. Colorado State University, USA

See Also

SSvgm, SSgard, Campbel

Examples

## Attach sample data (isric data) from the package
data(isric)
pf <- subset(isric, Sample=="Benin2")
library(minpack.lm)
a=Dstart(pf)[1];b=Dstart(pf)[2]; j=Dstart(pf)[3]; k=Dstart(pf)[4]-1
brook.ns <- nlsLM(y ~ Brook(x,thr,ths,alp,nscal), data=pf,
                  control = nls.lm.control(maxiter=200),
                  start = c(thr= a, ths = b, alp= j, nscal= k))
summary(brook.ns)## To produce a summary of modelling results

Campbell water retention model

Description

This is a three-parameter function to determine water retention hydraulic parameters contained in the Campbell water retention model

Usage

Campbel(x, ths, alp, nscal)

Arguments

Details

A Campbell model is a type of nonlinear curve fitting model for fitting water retention characteristics using experimental data. It requires initial parameter estimates for the model to work. This can be obtained using Dstart function (e.g. thr=Dstart(data)[1]). If warnings are given during the estimation process, try to increase the iteration limit using control function. Sometimes the warnings can be suppressed using (warn=-1)/ignored since they do not terminate the process

Value

A list of objects returned by standard R regression functions such as nls and lm

Note

Warnings: Choice of starting values for Campbel function parameter estimation needs a careful thought. Sometimes it may be necessary to use alp=1/Dstart(data)[3] or Dstart(data)[3] and nscal=Dstart(data)[4]-1 or nscal=Dstart(data)[4]. One has to try the starting variables that will work for the given data

Author(s)

Christian Thine Omuto

References

Campbell GS. 1974. A simple method for determining unsaturated conductivity from moisture retention data. Soil Science 117: 311-314

See Also

Brook, SSvgm, SSfredlund

Examples

data(isric)
pf <- subset(isric, Sample=="Nicaragua38")
require("minpack.lm")
campbel.ns <- nlsLM(y ~ Campbel(x,ths,alp,nscal), data=pf,
                  control = nls.lm.control(maxiter=200),
                  start = c(ths = Dstart(pf)[2],
                            alp=Dstart(pf)[3], nscal=-1*(Dstart(pf)[4]-1)))
plot(fitted(campbel.ns),pf$y)
coef(campbel.ns)

Determine starting values for nonlinear parameter estimation in the water retention models

Description

This function determines the starting values for estimation of parameters in the water retention models. The input data must contain at least the x (suction potential) and y(moisture contents) variables. It gives the starting values as close to the expected estimates as possible.

Usage

Dstart(data)

Arguments

Details

The data contains x columns and y columns which are used by the function. The initial x value should not be zero but something close like 0.001

Value

A vector of five values: pars[1]: thr- The residual moisture content, pars[2]: ths- The saturated moisture content, Pars[3]: alp- Inverse of air entry potential, pars[4]: nscal-index of pore-size distribution, and pars[5]: mscal-scaling parameter related to nscal

Author(s)

Christian Thine Omuto

See Also

SSkosugi, SSvgm,SSgard

Examples

data(isric)
pf=subset(isric, Sample=="Benin3")
Dstart(pf)[1]## thr initial value

Exponential water retention model

Description

This is a three- parameter function to determine water retention hydraulic parameters contained in the Exponential water retention model

Usage

Expo(x, thr, ths, alp)

Arguments

Details

An exponential model is a type of nonlinear curve fitting model for fitting water retention characteristics using experimental data. It requires initial parameter estimates for the model to work. This can be obtained using Dstart function (e.g. thr=Dstart(data)[1]). If warnings are given during the estimation process, try to increase the iteration limit using control function. Sometimes the warnings can be suppressed using (warn=-1)/ignored since they do not terminate the process

Value

A list of objects returned by standard R regression functions such as nls and lm

Author(s)

Christian Thine Omuto

References

Omuto CT. 2009. Biexponential model for water retention characteristics. Geoderma 149:235-242

See Also

SSomuto, SSfredlund,SSgard

Examples

##Attach sample data (isric data) from the package
data(isric)
pf <- subset(isric, Sample=="Benin2")
require("minpack.lm")
expo.ns <- nlsLM(y ~ Expo(x,thr,ths,alp), data=pf,
                 control = nls.lm.control(maxiter=200),
                 start = c(thr=Dstart(pf)[1],ths=Dstart(pf)[2], alp=Dstart(pf)[3]))
cor(fitted(expo.ns),pf$y)^2

McKee and Bumb water retention model

Description

This is a three- parameter function to determine water retention hydraulic parameters contained in the McKee and Bumb water retention model

Usage

MB(x,thr,ths,alp)

Arguments

Details

McKee and Bumb model is a type of nonlinear curve fitting model for fitting water retention characteristics using experimental data. It requires initial parameter estimates for the model to work. This can be obtained using Dstart function (e.g. thr=Dstart(data)[1]). If warnings are given during the estimation process, try to increase the iteration limit using control function. Sometimes the warnings can be suppressed using (warn=-1)/ignored since they do not terminate the process

Value

A list of objects returned by standard R regression functions such as nls and lm

Note

Warnings: Choice of starting values for SSMB function parameter estimation needs a careful thought. Sometimes it may be necessary to use alp=1/Dstart(data)[3] or Dstart(data)[3]. One has to try the starting variables that will work for the given data.

Author(s)

Christian Thine Omuto

References

McKee CR and Bumb AC.1987. Flow-testing coalbed methane production wells in presence of water and gas. SPE Formation Evaluation,vol. 2, no. 4, pp. 599–608

See Also

SSomuto, Expo, Campbel

Examples

##Attach sample data (isric data) from the package
data(isric)
require("minpack.lm")
pf <- subset(isric, Sample=="Italy5")
mb.ns=nlsLM(y~MB(x,thr,ths,alp),data=pf, control=nls.lm.control(maxiter=200),
            start=c(thr=Dstart(pf)[1],ths=Dstart(pf)[2], alp=Dstart(pf)[3]))
summary(mb.ns)
coef(mb.ns)

A Russo water retention model

Description

This is a four- parameter function to determine water retention hydraulic parameters contained in the Russo water retention model

Usage

Ruso(x, thr, ths, alp, nscal)

Arguments

Details

A Russo model is a type of nonlinear curve fitting model for fitting water retention characteristics using experimental data. It requires initial parameter estimates for the model to work. This can be obtained using Dstart function (e.g. thr=Dstart(data)[1]). If warnings are given during the estimation process, try to increase the iteration limit using control function. Sometimes the warnings can be suppressed using (warn=-1)/ignored since they do not terminate the process

Value

A list of objects returned by standard R regression functions such as nls and lm

Author(s)

Christian Thine Omuto

References

Russo D. 1988. Determining soil hydraulic properties by parameter estimation: on the selection of a model for the hydraulic properties. Water Resources Research 24(3): 453-459

See Also

Brook, Tani, Campbel

Examples

## Attach sample data (isric data) from the package
data(isric)
pf <- subset(isric, Sample=="Italy5")
require("minpack.lm")
ruso.ns <- nlsLM(y ~ Ruso(x,thr,ths,alp,nscal), data=pf,
                 control = nls.lm.control(maxiter=200),
                 start = c(thr= Dstart(pf)[1], ths = Dstart(pf)[2],
                           alp= Dstart(pf)[3], nscal=Dstart(pf)[4]))
coef(ruso.ns)

A Fredlund-Xing water retention model

Description

This is a five- parameter function to determine water retention hydraulic parameters contained in the Fredlund-Xing water retention model

Usage

SSfredlund(x, thr, ths, alp, nscal, mscal)

Arguments

Details

A Fredlund-Xing model is a self-starting type of nonlinear curve fitting model for fitting water retention characteristics using experimental data. If warnings are given during the estimation process, try to increase the iteration limit using control function. Sometimes the warnings can be suppressed using (warn=-1)/ignored since they do not terminate the process

Value

A list of objects returned by standard R regression functions such as nls and lm

Author(s)

Christian Thine Omuto

References

Fredlund DG and Xing A. 1994. Equations for the soil-water characteristic curve. Canadian Geotechnical Journal 31: 521-532

See Also

SSomuto, SSvgm, SSkosugi

Examples

## Attach sample data (isric data) from the package
data(isric)
pf <- subset(isric, Sample=="Benin2")
require("minpack.lm")
fredlund.ns <- nlsLM(y ~ SSfredlund(x,thr,ths,alp,nscal,mscal), data=pf,
                     control = nls.lm.control(maxiter=200,options(warn=-1)))
coef(fredlund.ns)
plot(fitted(fredlund.ns)~pf$y)

A Green-Ampt water infiltration model

Description

This is a two- parameter function to determine water infiltration parameters contained in the Green-Ampt infiltration model

Usage

SSgampt(input, ks, A)

Arguments

Details

This is a self-starting model for estimating Green-Ampt infiltration model using instantaneous and cumulative infiltration data

Value

A list of objects returned by standard R regression functions such as nls and lm

Author(s)

Christian Thine Omuto

References

Green WA and Ampt GA. 1911. Studies on soil physics: 1. The flow of air and water through soils. Journal of Agricultural Science 4: 1-24

See Also

SSphilip, SShorton

Examples

## Load the data
data(infilt)
require("minpack.lm")
gamp.ns <- nlsLM(Cumrate ~ SSgampt(Rate,ks,A), infilt)
summary(gamp.ns)

'Gardner' Water Retention Model for Grouped Data

Description

This is a four-parameter function to determine water retention hydraulic parameters contained in the Gardner water retention model

Usage

SSgard(input, Thr, Ths, alp, scal)

Arguments

Details

A Gardner model is a type of self-starting nonlinear curve fitting model for fitting water retention characteristics using grouped experimental data. If warnings are given during the estimation process, try to increase the iteration limit using control function. Sometimes the warnings can be suppressed using (warn=-1)/ignored since they do not terminate the process

Value

A list of objects returned by standard R regression functions such as nls and lm

Author(s)

Christian Thine Omuto

References

Gardner WR. 1958. Some steady state solutions of the unsaturated moisture flow equation with application to evaporation from a water table. Soil Science 85, 228-232

See Also

SSomuto, SSvgm, Campbel

Examples

data(isric)
isric1 <- isric[1:32,]
require("nlme")
require("minpack.lm")
gardner <- nlsLM(y ~ SSgard(x,thr,ths,alp,nscal), isric1)
gardner
gard <- nlsList(y ~ SSgard(x,thr,ths,alp,scal) | Sample, isric1)
coef(gard)

A Gardner water retention model

Description

This is a four- parameter function to determine water retention hydraulic parameters contained in the Gardner water retention model

Usage

SSgardner(x, thr, ths, alp, nscal)

Arguments

Details

A Gardner model is a type of nonlinear curve fitting model for fitting water retention characteristics using experimental data. It requires initial parameter estimates for the model to work. This can be obtained using Dstart function (e.g. thr=Dstart(data)[1]). If warnings are given during the estimation process, try to increase the iteration limit using control function. Sometimes the warnings can be suppressed using (warn=-1)/ignored since they do not terminate the process

Value

A list of objects returned by standard R regression functions such as nls and lm

Author(s)

Christian Thine Omuto

References

Gardner WR. 1958. Some steady state solutions of the unsaturated moisture flow equation with application to evaporation from a water table. Soil Science 85: 228-232

See Also

SSomuto, SSvgm, Campbel

Examples

data(isric)
isric1 <- isric[1:32,]
require("minpack.lm")
gardner <- nlsLM(y ~ SSgardner(x,thr,ths,alp,nscal), isric1)
gardner

A Horton water infiltration model

Description

This is a three- parameter function to determine water infiltration parameters contained in the Horrton infiltration model

Usage

SShorton(input, fc, f0, lrk)

Arguments

Details

This is a self-starting model for estimating parameters in the Horton infiltration model using instantaneous infiltration rates (here known as Rate) and time data (Time)

Value

A list of objects returned by standard R regression functions such as nls and lm

Author(s)

Christian Thine Omuto

References

Horton RE. 1940. An approach towards a physical interpretation of infiltration capacity. Soil Science Society of America Proceedings 5: 227-237

See Also

SSphilip, SSgampt

Examples

data(infilt)
infil <- infilt[319:751,]
require("nlme")
hort.lis <- nlsList(log(Rate) ~ SShorton(Time,fc,f0,lrk) | PlotNo,
                    infil) # Rate is the y variable
hort.lis

A Kosugi water retention model

Description

This is a four- parameter function to determine water retention hydraulic parameters contained in the Kosugi water retention model

Usage

SSkosugi(x, thr, ths, alp, nscal)

Arguments

Details

A Kosugi model is a type of self-starting nonlinear curve fitting model for fitting water retention characteristics using experimental data. If warnings are given during the estimation process, try to increase the iteration limit using control function. Sometimes the warnings can be suppressed using (warn=-1)/ignored since they do not terminate the process

Value

A list of objects returned by standard R regression functions such as nls and lm

Author(s)

Christian Thine Omuto

References

Kosugi, K. 1996. Lognormal distribution model for unsaturated soil hydraulic properties. Water Resources Research 32: 2697-2703

See Also

SSomuto, SSvgm, SSgard

Examples

data(isric)
require("minpack.lm")
kosugi.ns <- nlsLM(y ~ SSkosugi(x,thr,ths,alp,nscal),
                   data = subset(isric, Sample=="Benin2"),
                   control = nls.lm.control(maxiter=200,options(warn=-1)))
summary(kosugi.ns)

'Omuto' Water Retention Model

Description

This is a four- parameter function to determine water retention hydraulic parameters contained in a bimodal pore-size distribution developed by Omuto. The parameters are for the first and second compartments

Usage

SSomuto(input, Ths1, alp1, Ths2, alp2)

Arguments

Details

Omuto model is a self-starting biexponential model for nonlinear curve fitting model to water retention data. If warnings are given during the estimation process, try to increase the iteration limit using control function. Sometimes the warnings can be suppressed using (warn=-1)/ignored since they do not terminate the process

Value

A list of objects returned by standard R regression functions such as nls and lm

Note

This function can also be used to fit water retention characteristics for a grouped dataset as well as with mixed-effects modelling

Author(s)

Christian Thine Omuto

References

Omuto CT. 2009. Biexponential model for water retention characteristics. Geoderma 149:235-242

See Also

SSvgm, SSgard

Examples

data(isric)
isric1 <- isric[1:32,]
require("nlme")
omuto <- nlsList(y ~ SSomuto(x,ths1,alp1,ths2,alp2) | Sample,  isric1)
omuto.nlme <- nlme(omuto)## for fitting mixed-effects models
summary(omuto.nlme)

A Philip's water infiltration model

Description

This is a two- parameter function to determine water infiltration parameters contained in the Philip's infiltration model

Usage

SSphilip(input, fc, S)

Arguments

Details

This is a self-starting model for estimating Philip's infiltration model using instantaneous infiltration rates (here known as Rate) and time (Time) data

Value

A list of objects returned by standard R regression functions such as nls and lm

Author(s)

Christian Thine Omuto

References

Philip JR. 1957. The theory of infiltration.: 4 Sorptivity and algebraic infiltration equations. Soil Science 84: 257-264

See Also

SShorton, SSgampt

Examples

data(infilt)
require("nlme")
philip.nis <- nlsList(log(Rate) ~ SSphilip(Time,fc,S) | PlotNo, data=infilt)
coef(philip.nis)

A five-parameter van Genuchten water retention model

Description

This is a five- parameter function to determine water retention hydraulic parameters contained in the van Genuchten water retention model

Usage

SSvgm(input, thr, ths, alp, nscal, mscal)

Arguments

Details

Van Genuchten model is a type of self-starting nonlinear curve fitting model for fitting water retention characteristics using experimental data. In this model, the restriction of m=1-1/n has been relaxed so that m is estimated as an independent parameter of the water retention characteristics. If warnings are given during the estimation process, try to increase the iteration limit using control function. Sometimes the warnings can be suppressed using (warn=-1)/ignored since they do not terminate the process

Value

A list of objects returned by standard R regression functions such as nls and lm

Author(s)

Christian Thine Omuto

References

van Genuchten MT. 1980. A closed-form equation for predicting the hydraulic conductivity of unsaturated soils. Soil Science Society of America Journal 44: 892-898

See Also

SSomuto, Brook, Campbel

Examples

data(isric)
require("minpack.lm")
pf1=subset(isric,Sample=="Nicaragua21")
vn.ns <- nlsLM(y ~ SSvgm(x,thr,ths,alp,nscal,mscal),
               data = pf1,
               control = nls.lm.control(maxiter=200,options(warn=-1)))
coef(vn.ns)
plot(fitted(vn.ns)~pf1$y)
abline(a=0,b=1,lty=20, col="blue")

A four-parameter van Genuchten water retention model

Description

This is a four-parameter function to determine water retention hydraulic parameters contained in the van Genuchten water retention model

Usage

SSvgm4(input, Thr, Ths, alp, nscal)

Arguments

Details

Van Genuchten model is a type of self-starting nonlinear curve fitting model for fitting water retention characteristics using experimental data. In this model, the restriction of m=1-1/n has been imposed on the water retention characteristics. Air-entry potential = exp(alp). If warnings are given during the estimation process, try to increase the iteration limit using control function. Sometimes the warnings can be suppressed using (warn=-1)/ignored since they do not terminate the process

Value

A list of objects returned by standard R regression functions such as nls and lm

Author(s)

Christian Thine Omuto

References

van Genuchten MT. 1980. A closed-form equation for predicting the hydraulic conductivity of unsaturated soils. Soil Science Society of America Journal 44: 892-898

See Also

SSomuto, Brook, Campbel

Examples

data(isric)
require("nlme")
require("minpack.lm")
pfdata=subset(isric,Country=="Benin")
vn4.ns <- nlsList(y ~ SSvgm4(x,thr,ths,alp,nscal)|Sample,
               data = pfdata,
               control = nls.lm.control(maxiter=200,options(warn=-1)))
coef(vn4.ns)
plot(fitted(vn4.ns)~pfdata$y)
cor(fitted(vn4.ns),pfdata$y)^2

A Tani water retention model

Description

This is a three- parameter function to determine water retention hydraulic parameters contained in the Tani water retention model

Usage

Tani(x, thr, ths, alp)

Arguments

Details

Tani model is a type of nonlinear curve fitting model for fitting water retention characteristics using experimental data. It requires initial parameter estimates for the model to work. This can be done using Dstart function (e.g. thr=Dstart(data)[1]). If warnings are given during the estimation process, try to increase the iteration limit using control function. Sometimes the warnings can be suppressed using (warn=-1)/ignored since they do not terminate the process

Value

A list of objects returned by standard R regression functions such as nls and lm

Author(s)

Christian Thine Omuto

References

Tani M. 1982. The properties of water-table rise produced by a one-dimensional, vertical, unsaturated flow. Journal of Japan Forestry Society 64: 409-418

See Also

Brook, Ruso, Campbel

Examples

data(isric)
pf <- subset(isric, Sample=="Italy4")
require("minpack.lm")
tani.ns <- nlsLM(y ~ Tani(x,thr,ths,alp), data = pf,
                 control = nls.lm.control(maxiter=200),
                 start = c(thr=Dstart(pf)[1],ths=Dstart(pf)[2], alp=Dstart(pf)[3]))
coef(tani.ns)

Water infiltration characteristics data

Description

This is part of a dataset from a PhD study which measured water infiltration characteristics from the Upper Athi River basin in Eastern Kenya. It contains rate of infiltration (y) at different levels of cummulative Time intervals (x)

Usage

data(infilt)

Format

A data frame with 1105 observations on the following 6 variables.

Sample

which is a numeric vector

PlotNo

which is a factor with levels such as: 10lP3 11lP3 12lP3 13lP3 14lP3 15lP3 16lP3 17lP3 18lP3 19lP3 1lP3 20lP3 21lP3 22lP3 23lP3 24lP3 25lP3 26lP3 27lP3 28lP3 29lP3 2lP3 30lP3 3lP3 4lP3 5lP3 6lP3 7lP3 8lP3 9lP3

Erosion

which is a factor with levels such as: E0 E1 E2

Time

which is a numeric vector of cumulative infiltration time

Rate

which is a numeric vector of instantaneous infiltration rate

Cumrate

which is a numeric vector of cumulative infiltration rate

Details

The data is grouped according to plots (given the name PlotNo) from where the data were collected

Source

Omuto CT. 2006. Large-area soil physical degradation assessment using gis, remote sensing, and infrared spectroscopy in arid and semi-arid Kenya. PhD Dissertation, University of Nairobi, Kenya

References

Omuto CT. 2006. Large-area soil physical degradation assessment using gis, remote sensing, and infrared spectroscopy in arid and semi-arid Kenya.PhD Dissertation, University of Nairobi, Kenya

Examples

data(infilt)
str(infilt) 

Water Retention World Dataset from ISRIC

Description

This is part of world dataset of measured water retention characteristics. It contains soil moisture contents (y) at eight (8) levels of suction pressure heads (x).

Usage

data(isric)

Format

A data frame with 320 observations on the following 6 variables.

Sample

which is a factor with levels such as: Benin1 Benin2 Benin3 Italy4 Italy5 Italy6 Italy7 Nicaragua21 Nicaragua22 Nicaragua23 Nicaragua24 Nicaragua25 Nicaragua26 Nicaragua27 Nicaragua28 Nicaragua29 Nicaragua30 Nicaragua31 Nicaragua32 Nicaragua33 Nicaragua34 Nicaragua35 Nicaragua36 Nicaragua37 Nicaragua38 Nicaragua39 Nicaragua40 Poland10 Poland11 Poland8 Poland9 Rwanda16 Rwanda17 Rwanda18 Rwanda19 Rwanda20 Togo12 Togo13 Togo14 Togo15

Country

which is a factor with levels such as: Benin Italy Nicaragua Poland Rwanda Togo

BD

which is a numeric vector for bulk density

x

which is a numeric vector for suction potential

lnx

which is a numeric vector for log(e)

y

which is a numeric vector of moisture contents

Details

The data is grouped according to samples from each country from where the data were collected. In addition, it also contains surface bulk density (BD) for each sample. The whole dataset can be obtained from www.isric.org

Source

https://isric.org/explore/wosis/

References

Batjes, N. H., Ribeiro, E. & van Oostrum, A. Standardised soil profile data to support global mapping and modelling (WoSIS snapshot 2019). Earth Syst. Sci. Data 12, 299–320 (2020).

Examples

data(isric)
str(isric)