---
title: "Introduction to soiltillr"
author: "Sadikul Islam"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to soiltillr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse  = TRUE,
  comment   = "#>",
  fig.width = 7,
  fig.height = 4
)
```

## Overview

**soiltillr** provides a complete workflow for analysing soil tillage depth
and erosion data across years and field treatments. It covers data validation,
tillage summaries, compaction detection, erosion tracking, soil loss
estimation, and visualisation.

This vignette walks through the full analysis pipeline using the two built-in
datasets: `tillage_operations` and `erosion_profile`.

```{r load}
library(soiltillr)
```

---

## 1. Built-in datasets

```{r datasets}
data(tillage_operations)
data(erosion_profile)

head(tillage_operations)
head(erosion_profile)
```

`tillage_operations` contains 20 records of tillage events across two fields
(Field_A and Field_B) from 2018 to 2023. Field_A transitions from conventional
deep tillage (moldboard plowing at 30+ cm) to conservation tillage and no-till
by 2023. Field_B maintains reduced tillage throughout.

`erosion_profile` contains annual soil erosion depth, soil loss, bulk density,
organic matter, rainfall, and slope for the same two fields and period.

---

## 2. Data validation

Always validate your data before analysis. `validate_soil_data()` checks for
missing columns, negative values, empty data frames, and implausible years.

```{r validate}
chk <- validate_soil_data(
  data      = tillage_operations,
  year_col  = "year",
  field_col = "field_id",
  value_col = "depth_cm"
)

chk$valid    # TRUE = data is clean
chk$issues   # critical errors
chk$warnings # informational notices
```

---

## 3. Tillage analysis

### 3.1 Summarise tillage operations

`summarise_tillage()` computes year × field statistics: number of operations,
mean, maximum, and total depth, plus dominant operation type.

```{r summarise}
till_sum <- summarise_tillage(
  data      = tillage_operations,
  year_col  = "year",
  field_col = "field_id",
  depth_col = "depth_cm",
  op_col    = "operation"
)
print(till_sum)
```

Field_A shows mean depth declining from 22.0 cm in 2018 to 7.5 cm in 2023,
reflecting the shift toward conservation tillage.

### 3.2 Tillage depth trend

`tillage_depth_trend()` calculates the year-on-year change in mean depth per
field and classifies each year as `"baseline"`, `"increasing"`,
`"decreasing"`, or `"stable"`.

```{r trend}
till_trend <- tillage_depth_trend(
  data      = tillage_operations,
  year_col  = "year",
  field_col = "field_id",
  depth_col = "depth_cm"
)
print(till_trend)

# Years with decreasing tillage depth
till_trend[till_trend$trend == "decreasing", ]
```

### 3.3 Compaction detection

`detect_compaction()` classifies compaction risk as `"high"`, `"moderate"`,
or `"low"` based on a user-defined depth threshold (default 20 cm) and
estimates the depth of potential plow pan formation.

```{r compaction}
risk <- detect_compaction(
  data                    = tillage_operations,
  year_col                = "year",
  field_col               = "field_id",
  depth_col               = "depth_cm",
  op_col                  = "operation",
  compaction_threshold_cm = 20
)
print(risk)

# High-risk years only
risk[risk$compaction_risk == "high", ]
```

---

## 4. Erosion analysis

### 4.1 Track erosion depth

`track_erosion_depth()` computes annual erosion depth, year-on-year change,
and cumulative erosion per field. Trend is classified as `"baseline"`,
`"improving"`, `"worsening"`, or `"stable"`.

```{r erosion_track}
eros <- track_erosion_depth(
  data        = erosion_profile,
  year_col    = "year",
  field_col   = "field_id",
  erosion_col = "erosion_depth_mm"
)
print(eros)
```

Both fields show consistently improving erosion trends. Field_A's cumulative
loss (20.6 mm) is higher than Field_B's (12.7 mm), reflecting its historically
more intensive tillage.

### 4.2 Estimate soil loss

`estimate_soil_loss()` uses a mass-balance approach to estimate soil loss
in t/ha. The optional slope correction applies the McCool et al. (1987)
simplified LS factor: `LS = (slope% / 9)^0.6`.

```{r soil_loss}
loss <- estimate_soil_loss(
  data             = erosion_profile,
  year_col         = "year",
  field_col        = "field_id",
  erosion_col      = "erosion_depth_mm",
  bulk_density_col = "bulk_density_g_cm3",
  slope_col        = "slope_pct"
)
print(loss)
```

> **Note:** `estimated_loss_t_ha` is a physics-based estimate from erosion
> depth and bulk density. It will differ from independently measured
> `soil_loss_t_ha` values in the dataset. For full RUSLE prediction, all five
> factors (R, K, LS, C, P) should be considered (Renard et al., 1997).

### 4.3 Compare fields

`compare_fields()` produces a wide-format year-by-year comparison showing
erosion depth and organic matter for each field, plus difference columns.

```{r compare}
comp <- compare_fields(
  data        = erosion_profile,
  year_col    = "year",
  field_col   = "field_id",
  erosion_col = "erosion_depth_mm",
  om_col      = "organic_matter_pct"
)
print(comp)
```

The `erosion_diff_mm` column confirms Field_A consistently has higher erosion
than Field_B, with the gap narrowing from 1.9 mm in 2018 to 0.5 mm in 2023.
The `om_diff_pct` column shows Field_B maintaining higher organic matter
throughout, with Field_A recovering under conservation management.

---

## 5. Visualisation

### 5.1 Tillage depth timeline

```{r plot_tillage, fig.cap = "Mean annual tillage depth by field, 2018-2023."}
plot_tillage_timeline(
  data      = tillage_operations,
  year_col  = "year",
  field_col = "field_id",
  depth_col = "depth_cm",
  title     = "Tillage Depth Transition: Conventional to Conservation"
)
```

### 5.2 Erosion depth trend

```{r plot_erosion, fig.cap = "Annual erosion depth and cumulative loss by field."}
plot_erosion_trend(
  data            = erosion_profile,
  year_col        = "year",
  field_col       = "field_id",
  erosion_col     = "erosion_depth_mm",
  show_cumulative = TRUE,
  title           = "Erosion Depth and Cumulative Loss 2018-2023"
)
```

### 5.3 Organic matter trend

```{r plot_om, fig.cap = "Soil organic matter recovery under conservation tillage."}
plot_om_trend(
  data      = erosion_profile,
  year_col  = "year",
  field_col = "field_id",
  om_col    = "organic_matter_pct",
  title     = "Soil Organic Matter Recovery"
)
```

The dashed line at 3.5% represents a commonly cited threshold for adequate
soil organic matter in agricultural soils. Field_A crosses this threshold
by 2023 under conservation management.

### 5.4 Tillage vs erosion comparison

```{r plot_comparison, fig.cap = "Dual-panel comparison of mean tillage depth and erosion depth."}
plot_tillage_erosion(
  tillage_data = tillage_operations,
  erosion_data = erosion_profile,
  year_col     = "year",
  field_col    = "field_id",
  depth_col    = "depth_cm",
  erosion_col  = "erosion_depth_mm",
  title        = "Impact of Tillage Management on Soil Erosion"
)
```

---

## 6. Full analysis pipeline

The functions are designed to chain together naturally:

```{r pipeline, eval = FALSE}
library(soiltillr)
data(tillage_operations)
data(erosion_profile)

# Step 1: validate
stopifnot(validate_soil_data(tillage_operations,
                             "year", "field_id", "depth_cm")$valid)

# Step 2: tillage
till_sum   <- summarise_tillage(tillage_operations, "year", "field_id",
                                "depth_cm", op_col = "operation")
till_trend <- tillage_depth_trend(tillage_operations, "year",
                                  "field_id", "depth_cm")
compact    <- detect_compaction(tillage_operations, "year", "field_id",
                                "depth_cm", op_col = "operation")

# Step 3: erosion
eros_track <- track_erosion_depth(erosion_profile, "year",
                                  "field_id", "erosion_depth_mm")
eros_loss  <- estimate_soil_loss(erosion_profile, "year", "field_id",
                                 "erosion_depth_mm", "bulk_density_g_cm3",
                                 slope_col = "slope_pct")
field_comp <- compare_fields(erosion_profile, "year", "field_id",
                              "erosion_depth_mm", "organic_matter_pct")

# Step 4: visualise
plot_tillage_timeline(tillage_operations, "year", "field_id", "depth_cm")
plot_erosion_trend(erosion_profile, "year", "field_id",
                   "erosion_depth_mm", show_cumulative = TRUE)
plot_om_trend(erosion_profile, "year", "field_id", "organic_matter_pct")
plot_tillage_erosion(tillage_operations, erosion_profile,
                     "year", "field_id", "depth_cm", "erosion_depth_mm")
```

---

## References

Lal, R. (2001). Soil degradation by erosion. *Land Degradation and
Development*, 12(6), 519–539. <https://doi.org/10.1002/ldr.472>

McCool, D. K., Brown, L. C., Foster, G. R., Mutchler, C. K., & Meyer, L. D.
(1987). Revised slope steepness factor for the Universal Soil Loss Equation.
*Transactions of the ASAE*, 30(5), 1387–1396.
<https://doi.org/10.13031/2013.30576>

Renard, K. G., Foster, G. R., Weesies, G. A., McCool, D. K., & Yoder, D. C.
(1997). *Predicting Soil Erosion by Water: A Guide to Conservation Planning
with the Revised Universal Soil Loss Equation (RUSLE)*. USDA Agriculture
Handbook No. 703.
<https://ntrl.ntis.gov/NTRL/dashboard/searchResults/titleDetail/PB97153704.xhtml>
