# soiltillr <img src="man/figures/logo.png" align="right" height="139" alt="" />

<!-- badges: start -->
[![CRAN status](https://www.r-pkg.org/badges/version/soiltillr)](https://CRAN.R-project.org/package=soiltillr)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
<!-- badges: end -->

## Overview

**soiltillr** provides tools to record, validate, and analyse soil tillage
depth and erosion across years and field treatments. It is designed for
agronomists, soil scientists, and conservation researchers who need to:

- Summarise year-wise tillage operations by field
- Detect trends in tillage depth over time
- Identify soil compaction risk from tillage records
- Track annual erosion depth and cumulative soil loss
- Estimate soil loss using a mass-balance approach
- Visualise tillage and erosion changes over time

Methods follow Lal (2001) and Renard et al. (1997) RUSLE guidelines.

## Installation

Install the released version from CRAN:

```r
install.packages("soiltillr")
```

Or install the development version from GitHub:

```r
# install.packages("devtools")
devtools::install_github("sadikul-islam/soiltillr")
```

## Functions

| Function | Category | Description |
|---|---|---|
| `validate_soil_data()` | Validation | Check data quality before analysis |
| `summarise_tillage()` | Tillage | Year × field operation summary |
| `tillage_depth_trend()` | Tillage | Year-on-year depth change and trend |
| `detect_compaction()` | Tillage | Compaction risk and plow pan depth |
| `track_erosion_depth()` | Erosion | Annual erosion tracking and cumulative loss |
| `estimate_soil_loss()` | Erosion | Mass-balance soil loss in t/ha |
| `compare_fields()` | Erosion | Side-by-side field comparison |
| `plot_tillage_timeline()` | Visualisation | Line plot of tillage depth by year |
| `plot_erosion_trend()` | Visualisation | Erosion depth trend (+ optional cumulative panel) |
| `plot_om_trend()` | Visualisation | Organic matter trend by field |
| `plot_tillage_erosion()` | Visualisation | Dual-panel tillage vs erosion comparison |

## Built-in Datasets

- **`tillage_operations`** — 20 rows, 6 columns. Hypothetical year-wise tillage
  records for Field_A and Field_B (2018–2023).
- **`erosion_profile`** — 12 rows, 8 columns. Annual erosion depth, soil loss,
  bulk density, organic matter, rainfall, and slope.

## Usage

```r
library(soiltillr)

# Load built-in data
data(tillage_operations)
data(erosion_profile)

# Validate data quality
chk <- validate_soil_data(tillage_operations, "year", "field_id", "depth_cm")
chk$valid  # TRUE

# Summarise tillage operations by year and field
till_sum <- summarise_tillage(tillage_operations, "year", "field_id",
                              "depth_cm", op_col = "operation")
print(till_sum)

# Detect year-on-year depth trends
till_trend <- tillage_depth_trend(tillage_operations, "year",
                                  "field_id", "depth_cm")
till_trend[till_trend$trend == "decreasing", ]

# Detect compaction risk
risk <- detect_compaction(tillage_operations, "year", "field_id",
                          "depth_cm", compaction_threshold_cm = 20)
risk[risk$compaction_risk == "high", ]

# Track erosion depth
erosion <- track_erosion_depth(erosion_profile, "year",
                               "field_id", "erosion_depth_mm")

# Estimate soil loss (mass-balance with McCool LS factor)
loss <- estimate_soil_loss(erosion_profile, "year", "field_id",
                           "erosion_depth_mm", "bulk_density_g_cm3",
                           slope_col = "slope_pct")

# Compare fields side by side
comp <- compare_fields(erosion_profile, "year", "field_id",
                       "erosion_depth_mm", "organic_matter_pct")

# 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>

## License

MIT © Sadikul Islam
