---
title: "The soilphysics package: an overview"
author: "A.R. da Silva and R.P. de Lima"
date: "Dec 6, 2020"
output: html_document
vignette: >
  %\VignetteIndexEntry{"The soilphysics package: an overview"}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

# About soilphysics
In this package you will find a series of functions for soil physics data analysis. These functions includes five models of water retention curve, seven methods of soil precompression stress, least limiting water range (LLWR), Integral Water Capacity (IWC), soil penetration resistance curve by Busscher's model, calculation of Soil Aggregate-Size Distribution, S Index, critical soil moisture and maximum bulk density using data from Proctor test, calculation of equivalent pore radius as a function of soil water tension, simulation of sedimentation time of soil particles through Stokes' law, simulation of soil pore size distribution, calculation of the hydraulic cut-off introduced by  Dexter et al. (2008) and simulation of soil compaction induced by agricultural field traffic. Other utilities like functions to calculate the void ratio and to determine the maximum curvature point are available. 

# Instalation

From CRAN:

```{r eval=FALSE}
install.packages("soilphysics")
```

Or you can install the development version from GitHub:

```{r, eval=FALSE}
install.packages("devtools")
devtools::install_github("arsilva87/soilphysics")
```

Then, load it

```{r warning=FALSE}
library(soilphysics) 
```

## Soil compaction tools

Using the function stressTraffic, it it possible calculate the contact area, stress distribuition and stress propagation based on the SoilFlex model. 

```{r}
stress <- stressTraffic(inflation.pressure=200, 
	   recommended.pressure=200, 
	   tyre.diameter=1.8, 
	   tyre.width=0.4, 
	   wheel.load=4000, 
	   conc.factor=c(4,5,5,5,5,5),
           layers=c(0.05,0.1,0.3,0.5,0.7,1), 
	   plot.contact.area = TRUE)

```

Unsing the funtion soilDeformation, it is possible calculates the bulk density variation as a function of the applied mean normal stress using critical state theory, by O'Sullivan and Robertson (1996). 

```{r}
soilDeformation(stress = 300,
                p.density = 2.67,
	        iBD = 1.55, 
                N = 1.9392, 
                CI = 0.06037, 
                k = 0.00608, 
                k2 = 0.01916,
                m = 1.3,graph=TRUE,ylim=c(1.4,2.0))

```


## Critical soil moisture and maximum bulk density (Proctor test)

```{r}
mois <- c(0.083, 0.092, 0.108, 0.126, 0.135)
bulk <- c(1.86, 1.92, 1.95, 1.90, 1.87)
criticalmoisture(theta = mois, Bd = bulk)
```

## Soil water availability tools

Quantifying the soil water availability for plants through the IWC approach:

```{r}
iwc(theta_R = 0.166, theta_S = 0.569, alpha = 0.029, n = 1.308, 
    a = 0.203, b = 0.256, hos = 200, graph = TRUE)
```

Quantifying the soil water availability for plants through the LLWR approach:

```{r}
# Usage
data(skp1994)
with(skp1994,
	llwr(theta = W, h = h, Bd = BD, Pr = PR,
		particle.density = 2.65, air = 0.1,
		critical.PR = 2, h.FC = 100, h.WP = 15000))
```		

Quantifying the LLWR using van Genuchten's parameters:

```{r}
par(mfrow=c(1,2))
llwr_llmpr(thetaR=0.1180, thetaS=0.36, alpha=0.133, n=1.30, 
        d=0.005, e=-2.93, f=3.54, PD=2.65,
        critical.PR=4, h.FC=100, h.PWP=15000, air.porosity=0.1,
        labels=c("AFP", "FC","PWP", "PR"),
        graph1=TRUE,graph2=FALSE, ylab=expression(LLMPR~(hPa)), ylim=c(15000,1))
mtext(expression("Bulk density"~(Mg~m^-3)),1,line=2.2, cex=0.8)

llwr_llmpr(thetaR=0.1180, thetaS=0.36, alpha=0.133, n=1.30, 
        d=0.005, e=-2.93, f=3.54, PD=2.65,
        critical.PR=4, h.FC=100, h.PWP=15000, air.porosity=0.1,
        labels=c("AFP", "FC","PWP", "PR"),
        graph1=FALSE,graph2=TRUE, ylab=expression(LLMPR~(hPa)), ylim=c(0.1,0.5))
mtext(expression("Bulk density"~(Mg~m^-3)),1,line=2.2, cex=0.8)
```

## Precompression stress

Estimating the precompression stress by several methods:

```{r}
pres <- c(1, 12.5, 25, 50, 100, 200, 400, 800, 1600)
VR <- c(0.846, 0.829, 0.820, 0.802, 0.767, 0.717, 0.660, 0.595, 0.532)
sigmaP(VR, pres, method = "casagrande", n4VCL = 2)
```

## Soil water retention curve

Fitting (interactive!) water retention curve using van Genuchten's model

```{r, echo=FALSE}
h <- c(0.001, 50.65, 293.77, 790.14, 992.74, 5065, 10130, 15195)
w <- c(0.5650, 0.4013, 0.2502, 0.2324, 0.2307, 0.1926, 0.1812, 0.1730)
# fitsoilwater(theta=w, x=h, ylim=c(0.1,0.6))  # requires rpanel
```

## S Index

```{r}
Sindex(theta_R=0, theta_S=0.395, alpha=0.0217, n=1.103, xlim = c(0, 1000))
```

## Soil Aggregate-Size Distribution

```{r}
data(SoilAggregate)
head(SoilAggregate)
classes <- c(3, 1.5, 0.75, 0.375, 0.178, 0.053)
out <- aggreg.stability(sample.id = SoilAggregate[ ,1], 
                        dm.classes = classes, 
                        aggre.mass = SoilAggregate[ ,-1])
head(out)
```

 
# Citation and references
De Lima, R.P.; Da Silva, A.R.; Da Silva, A.P. (2021) soilphysics: An R package for simulation of soil compaction induced by agricultural field traffic. *SOIL and TILLAGE RESEARCH*, 206: 104824. DOI: <https://doi.org/10.1016/j.still.2020.104824>

De Lima, R.P.; Tormena, C.A.; Figueiredo, G.C; Da Silva, A.R.; Rolim, M.M. (2020) Least limiting water and matric potential ranges of agricultural soils with calculated physical restriction thresholds. *Agricultural Water Management*, 240: 106299. DOI: <https://doi.org/10.1016/j.agwat.2020.106299>

Da Silva, A.R.; De Lima, R.P. (2017) Determination of maximum curvature point with the R package soilphysics. *International Journal of Current Research*, 9: 45241-45245.  

De Lima, R.P.; Da Silva, A.R.; Da Silva, A.P.; Leao, T.P.; Mosaddeghi, M.R. (2016) soilphysics: an R package for calculating soil water availability to plants by different soil physical indices. *Computers and Eletronics in Agriculture*, 120: 63-71. DOI: <https://doi.org/10.1016/j.compag.2015.11.003>

Da Silva, A.R.; De Lima, R.P. (2015) soilphysics: an R package to determine soil preconsolidation pressure. *Computers and Geosciences*, 84: 54-60. DOI: <https://doi.org/10.1016/j.cageo.2015.08.008>


# Contributions and bug reports

soilphysics is an ongoing project. Then, contributions are very welcome. If you have a question or have found a bug, please open an ![Issue](<https://github.com/arsilva87/soilphysics/issues>) or reach out directly by e-mail: <anderson.silva@ifgoiano.edu.br> or <renato_agro_@hotmail.com>.

