# soiltillr 0.1.0

## Initial CRAN release

### New functions

**Validation**

* `validate_soil_data()` — checks a data frame for missing columns, negative
  values, missing rows, and implausible year values before passing it to
  any analysis function.

**Tillage analysis**

* `summarise_tillage()` — computes year × field summary statistics including
  number of operations, mean depth, maximum depth, total depth, and dominant
  operation type.
* `tillage_depth_trend()` — calculates the year-on-year change in mean tillage
  depth per field and classifies each year as `"baseline"`, `"increasing"`,
  `"decreasing"`, or `"stable"`.
* `detect_compaction()` — estimates compaction risk (`"high"`, `"moderate"`,
  `"low"`) and plow pan depth from tillage records, using a user-specified
  depth threshold (default 20 cm).

**Erosion analysis**

* `track_erosion_depth()` — tracks annual erosion depth, year-on-year change,
  and cumulative erosion loss per field; classifies trend as `"baseline"`,
  `"improving"`, `"worsening"`, or `"stable"`.
* `estimate_soil_loss()` — estimates soil loss in t/ha using a standard
  mass-balance formula with an optional slope correction via the McCool et al.
  (1987) simplified LS factor: `LS = (slope% / 9)^0.6`.
* `compare_fields()` — produces a wide-format year-by-year comparison of
  erosion depth and organic matter between two or more fields, including
  absolute difference columns.

**Visualisation**

* `plot_tillage_timeline()` — line plot of mean annual tillage depth by field.
* `plot_erosion_trend()` — line plot of annual erosion depth by field, with an
  optional second panel showing cumulative erosion (`show_cumulative = TRUE`).
* `plot_om_trend()` — line plot of soil organic matter (%) by field with a
  3.5% reference line.
* `plot_tillage_erosion()` — dual-panel ggplot2 figure comparing mean tillage
  depth and erosion depth side by side.

### Built-in datasets

* `tillage_operations` — 20-row hypothetical tillage records for Field_A and
  Field_B across 2018–2023 (6 variables).
* `erosion_profile` — 12-row hypothetical annual erosion and soil health
  measurements for the same fields (8 variables).

### 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. et al. (1987). Revised slope steepness factor for the USLE.
  *Transactions of the ASAE*, 30(5), 1387–1396.
  <https://doi.org/10.13031/2013.30576>
* Renard, K. G. et al. (1997). *Predicting Soil Erosion by Water: A Guide to
  Conservation Planning with the Revised Universal Soil Loss Equation
  (RUSLE)*. USDA Agriculture Handbook No. 703.
