--- title: "SoilManageR" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{SoilManageR} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ![](../inst/logos/hex-SoilManageR.png){width="150"} # SoilManageR ![](../vignettes/Graphical_Abstract.png){width="700"} \ *Fig. 1: SoilManageR calculates numerical indicators for soil management intensities from soil management information. The management indicators can be used to compare soil management across contexts, space, and time.* ## Introduction This R package is a compilation of functions to calculate numerical agricultural soil management indicators from a management timeline of an arable field. The functions can also be used independently of the management timeline to calculate some indicators or parts thereof. Throughout the package, many assumptions were made (e.g. on time to crop establishment). These assumptions are, whenever possible, based on the literature that is cited within the function descriptions. The assumptions are considered to be representative for temperate agro-ecosystems, i.e. in the Swiss midlands. A scientific publication describing the package and its functions was published in the *European Journal of Soil Science* [(Heller et al., 2025)](http://doi.org/10.1111/ejss.70102). Please cite this publication when using the package in your work. ![](../vignettes/SoilManager_graphic.png){width="700"} \ *Fig. 2: Functions and content of the SoilManageR package* SoilManageR organizes management data in management data frames `management_df()`, from this the indicators can then be calculated. For the calculations there are main functions and helper functions that are called by the main functions (Fig. 2). Both type of functions rely on reference data for their calculations. The package is distributed with some supporting documents. Further documents, e.g. the illustrated guide to identify soil management operations, can be found on [Zenodo](https://zenodo.org/communities/soilmanager/). ## Installation You can install the current release version of SoilManageR from [CRAN](https://cran.r-project.org/) with: ``` r # install released version install.packages("SoilManageR") ``` or you can install the development version of SoilManageR from [GitLab](https://about.gitlab.com/) with: ``` r # install development version install.packages("remotes") remotes::install_gitlab("SoilManageR/SoilManageR") ``` ## Suggested Workflow ### Load and check management data frame We suggest to start the workflow with importing a `management_df()` from a XLSX template. ``` library(SoilManageR) # define path to excel template in the SoilManageR package internal_path <- "/extdata/SoilManageR_mgmt_data_template.xlsx" # create local path path_to_xlsx_template <- system.file(internal_path, package = "SoilManageR") # load management_df mgmt_data <- management_df_from_excel(path_to_xlsx_template) ``` The template suggests products for many operations (sheet *Products*). Mineral fertilizers of this list can be entered as product amount (kg/ha or l/ha) and their N input is derived from their composition, organic fertilizers can also be entered as plant-available N (kg N_available/ha), and seed mixtures can be entered as one sowing record. Then the `management_df()` can be checked for internal consistency with the `check_management_df()` function. ``` # create management_df from example data (delivered with the package) mgmt_data <- EXAMPLE_data # arrange the example data by date and order of operations mgmt_data <- arrange_management_df(mgmt_data) # check the consistency of the example data check_management_df(mgmt_data) ``` Single operations can be excluded from the `management_df()` with `filter_management_df()`, based on a pattern in the comments column (e.g. to exclude a specific cover crop mixture). ``` # exclude all lines that contain "UFA 330" in the comments mgmt_data_filtered <- filter_management_df(mgmt_data, "UFA 330") ``` The `management_df()` can be visualized too. ``` # visualise the example data (the default plot of a management_df) plot(mgmt_data) # the same, with a custom title plot_management_df(mgmt_data, title = "Example field") ``` ![](../vignettes/plot_managment_df.png){width="500"} \ *Fig. 3: Visualisation of a management_df. T: tillage, P: crop protection, F: mineral fertilization; the values are C inputs in Mg C/ha by crops (C), residue removal (R), cover crops (CC) and organic amendments (OA). For further information please call `?plot_management_df`.* ### Calculate indicators per year or by crop When the `management_df()` shows no relevant issues, then all indicators can be calculated with `calculate_indicators()` per year or with `calculate_indicators_by_crop()` by crop. Furthermore, indicators can be calculated by a specific date, e.g. by a sampling date. ``` # calculate indicators by year calculate_indicators(mgmt_data) # calculate indicators by crop calculate_indicators_by_crop(mgmt_data) # calculate indicators by date calculate_indicators_by_date(mgmt_data, "2020-08-01") ``` Alternatively, the indicators could be calculated individually ``` # estimate carbon input C_input(mgmt_data) # calculate tillage intensity tillage_intensity(mgmt_data) # calculate soil cover soil_cover(mgmt_data) # calculate nitrogen input and livestock intensity N_input(mgmt_data) # calculate plant diversity indication plant_diversity(mgmt_data,2013,2023) # count number of pesticide applications count_pesticide_applications(mgmt_data) # estimate relative yields (productivity) productivity_indicator(mgmt_data) ``` The stable organic matter of organic amendments (organic matter input times the indicator of organic matter stability, ISMO) is calculated separately, it is not part of `calculate_indicators()`. ``` # estimate the stable organic matter of organic amendments per year and per crop stable_OM_amended(mgmt_data) stable_OM_amended_by_crop(mgmt_data) ``` Users can also customize the calculation of the indicators by using the extended output of the indicator calculation functions. ``` # extended output for the estimate carbon input C_input(mgmt_data, extended.output = TRUE) # extended output for the calculate tillage intensity tillage_intensity(mgmt_data, extended.output = TRUE) # extended output for the calculate soil cover soil_cover(mgmt_data, extended.output = TRUE) # visualize the extended output for the soil cover soil_cover_data <- soil_cover(mgmt_data, extended.output = TRUE) plot(soil_cover_data) # extended output for the calculate nitrogen input and livestock intensity N_input(mgmt_data, extended.output = TRUE) # extended output for the productivity indicator productivity_indicator(mgmt_data, extended.output = TRUE) # extended output for the stable organic matter of organic amendments stable_OM_amended(mgmt_data, extended.output = TRUE) ``` Batch wise calculations for multiple fields could be done in parallel to save computing time, for example with the workflow below. ``` # create a list of 3 EXAMPLE_data managment_df list_input <- list(EXAMPLE_data, EXAMPLE_data, EXAMPLE_data) # load packages for parallel computation (and install if not already installed) # install.packages("future") # install future for parallel computation # install.packages("furrr") # install furrr for parallel computation with purrr syntax library(furrr) library(future) # parallel computation with furrr plan(multisession) list_output_parallel <- future_map(list_input, calculate_indicators) ``` ### Access helper functions All helper functions can be called directly, please check Fig. 2 and the description of the functions for more information on them. ## About the Package ### Acknowledgments This R package was developed by following the book [R Packages (2nd Edition)](https://r-pkgs.org/) by [Hadley Wickham](https://hadley.nz/) and [Jennifer Bryan](https://jennybryan.org/). Our work is based on the accomplishments of many others. In particular, we would like to thank Sonja Keel (Agroscope, Switzerland), Martin Bolinder (SLU, Sweden), Giulio Feruzzi (USDA-NRCS, USA), Lucie Büchi (University of Greenwich, United Kingdom) for their advice and support. ### Contact For further information on SoilManageR please contact [olivier.heller\@soilmanager.ch](mailto:olivier.heller@soilmanager.ch) or [raphael.wittwer\@agroscope.admin.ch](mailto:raphael.wittwer@agroscope.admin.ch). ### License SoilManageR is released under the [MIT License](https://opensource.org/license/mit). You are free to use, modify, and redistribute the package, provided that the copyright notice and license text are retained. See the `LICENSE` file of the package for details. ### Funding information The development of this R package was supported by EJP SOIL. [![](../vignettes/EJP_SOIL.png){width="300"}](https://ejpsoil.eu/) ![](../vignettes/EJP_H2020_EU.jpg){width="200"}