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