Background

In 2021, a committee of experts associated with the National Academies of Sciences, Engineering, and Medicine (NASEM) published a consensus report entitled “Nutrient Requirements of Dairy Cattle.” The consensus report is available to purchase online (https://nap.nationalacademies.org/catalog/25806/nutrient-requirements-of-dairy-cattle-eighth-revised-edition). Additionally, the committee provided free software to run the nutritional model associated with the consensus report on Windows. The publisher recommends the consensus report and software be used by nutritionists and other professionals to evaluate dairy cattle diets.

Along with the consensus report and software release, the NASEM (2021) committee published R source code. This code calculates model parameters for a single simulation and returns output in tables. Because the source code was intended for translation into the graphical NASEM software, it is functional but not user-friendly when run in R.

Advantages of dairynasem package

This vignette discusses the dairynasem package, an R package designed to facilitate using the NASEM (2021) model in R. The dairynasem package builds on the source code developed by NASEM (2021) through several “wrapper functions” (i.e., these functions “wrap around” the original code without modifying it). When compared to the NASEM (2021) software and source code, the dairynasem package provides several advantages. These are compared below:

NASEM graphical software

  • Can run one set of inputs (diet and one scenario) at a time
  • Some default inputs, e.g., target amino acid efficiencies are provided
  • User must type and select inputs in graphical interface, which is time-consuming and error-prone if many simulations must be run
  • Output is written to tables in Word, which is good for archival but makes it difficult to do further analysis in R
  • Program is only compatible with Windows OS

NASEM R Source code

  • Can run one set of inputs (diet and one scenario) at a time
  • No default inputs are provided, each argument requires a value
  • Users enter and edit inputs in R, so it requires many lines of code per simulation
  • Output is a nested list returned to R that can be used in further analysis, the code can also generate XML for tabular output in Word with additional effort
  • Cross-platform compatible: can be run on Mac or Windows OS

dairynasem package

  • Many sets of inputs can be batched into the same run, i.e., multiple diets and multiple scenarios can be run with minimal code
  • Default inputs are provided for infusions and target amino acid efficiencies
  • Batches of inputs can be edited in a spreadsheet editor (e.g., Excel, Google Sheets) and uploaded to R
  • Output is returned as a nested list to R
  • dairynasem functions enable users to further manipulate output in R across simulations, or to quickly write a .txt file for each simulation for archival purposes
  • Cross-platform compatible: can be run on Mac or Windows OS

Potential features

In addition to these advantages, eventually, the dairynasem package may include other features beyond NASEM (2021):

  1. Descriptive warnings - the package may be updated to provide warnings for selected user errors related to feed and diet parameters (e.g., unusual feed or diet composition). This functionality will assist in catching any problematic inputs.

  2. Extensions - the package may be updated to provide extensions to the code published by NASEM (2021), e.g., to estimate other quantities related to NASEM outputs

Please note that this package was NOT developed or reviewed by anyone affiliated with the NASEM (2021) committee and is a beta version. Check all output against the NASEM (2021) program.

Citing NASEM (2021) and this package

If using this package, please remember to cite the NASEM (2021) consensus report and the dairynasem package.

NASEM (2021) consensus report:

National Academies of Sciences, Engineering, and Medicine (NASEM). 2021. Nutrient Requirements of Dairy Cattle: Eighth Revised Edition. Washington, DC: The National Academies Press.

The dairynasem package:

Erickson, M.G. 2022. The dairynasem package.*****URL****

Install and load the package

# From local: 
install.packages("dairynasem_0.1.0.tar.gz", repos = NULL, type="source")
# From cran (eventually): 
# install.packages("dairynasem")
library(dairynasem) 

# Other packages used for the vignette
library(dplyr)
library(kableExtra)

Running NASEM (2021) simulations

Required inputs

Inputs required for dairynasem are the same as those required for the NASEM (2021) graphical software. However, dairynasem allows the user to input batches of diets and scenarios. For example, several diets can be stacked into the same dataframe as an input. Several scenarios can also be stacked into one input dataframe.

The run_dn() function requires two inputs: 1) diet_comp, a dataframe with diet IDs, diet ingredients, and the proportion of DM supplied by each ingredient, and 2) scenario, a dataframe with scenario identifiers and the remaining required inputs describing the animal and situation. Examples are provided within the package. These can be loaded into the Global Environment as shown below:

data("diet_comp_ex_1")
diet_comp_ex_1
## # A tibble: 15 × 3
##    DietID Fd_Name                      Fd_DMInp
##    <chr>  <chr>                           <dbl>
##  1 d1     Legume silage, mid-maturity     0.311
##  2 d1     Corn silage, typical            0.319
##  3 d1     Corn grain dry, medium grind    0.214
##  4 d1     Soybean meal, solvent 48CP      0.13 
##  5 d1     VitTM Premix, generic           0.026
##  6 d2     Legume silage, mid-maturity     0.33 
##  7 d2     Corn silage, typical            0.33 
##  8 d2     Corn grain dry, medium grind    0.15 
##  9 d2     Soybean meal, solvent 48CP      0.15 
## 10 d2     VitTM Premix, generic           0.04 
## 11 d3     Legume silage, immature         0.2  
## 12 d3     Corn silage, typical            0.53 
## 13 d3     Corn grain, steam-flaked        0.1  
## 14 d3     Soybean meal, extruded          0.15 
## 15 d3     VitTM Premix, generic           0.02
data("scenario_ex_1")
head(scenario_ex_1)
## # A tibble: 6 × 38
##   Scenari…¹ An_Br…² An_Ag…³ An_BW An_BW…⁴ Trg_F…⁵ Trg_R…⁶ An_Pa…⁷ An_BCS An_Ge…⁸
##   <chr>     <chr>     <dbl> <dbl>   <dbl>   <dbl>   <dbl>   <dbl>  <dbl>   <dbl>
## 1 s1        Holste…    1095  651.     650       0    0.75       2    3.5     283
## 2 s2        Holste…    1095  652.     650       0    0.75       2    3.5     283
## 3 s3        Holste…    1095  652.     650       0    0.75       2    3.5     283
## 4 s4        Holste…    1095  653      650       0    0.75       2    3.5     283
## 5 s5        Holste…    1095  654.     650       0    0.75       2    3.5     283
## 6 s6        Holste…    1095  654.     650       0    0.75       2    3.5     283
## # … with 28 more variables: An_AgeConcept1st <lgl>, An_DIMConcept <dbl>,
## #   Fet_BWbrth <dbl>, An_StatePhys <chr>, An_LactDay <dbl>, An_GestDay <dbl>,
## #   Env_TempCurr <dbl>, Env_DistParlor <dbl>, Env_TripsParlor <dbl>,
## #   Env_Topo <dbl>, Trg_MilkProd <dbl>, Trg_MilkLacp <dbl>, Trg_MilkTPp <dbl>,
## #   Trg_MilkFatp <dbl>, Trg_Dt_DMIn <dbl>, An_AgeDryFdStart <lgl>,
## #   DMIn_eqn <dbl>, Use_DNDF_IV <dbl>, RUP_eqn <dbl>, MiN_eqn <dbl>,
## #   mProd_eqn <dbl>, mLac_eqn <dbl>, mPrt_eqn <dbl>, An_305RHA_MlkTP <dbl>, …

Users must provide diet_comp and scenario information using a similar structure to the examples shown above. At minimum, one diet and one scenario must be provided. It is straightforward to export the examples above as a csv, save renamed copies, modify them in a spreadsheet editor, and upload them to the Global Environment.

Diet Editor Google Sheet

Because selecting feed names that match the NASEM (2021) library can be challenging, the Google Sheet below can be used as a diet editor. Please allow a moment after entering information in Column 1 for Column 2 to update. Diets created in this sheet can be pasted into diet_comp information. https://docs.google.com/spreadsheets/d/14lhNtNi64uAkn4N1zoIq37QNJ37Ayyn235jaJiphb2g/copy?usp=sharing

Figure 1. Diet editing in Google Sheet

Optional inputs

In addition to diets and scenarios, there are three optional inputs that can be exported and modified First, feed_library defaults to the NASEM (2021) library but can be edited to add custom feeds. Second, default_eff gives the target efficiencies in NASEM (2021). Third, the vector infus gives any information on infusions in a given location (options: “Rumen”,“Abomasum”,“Duodenum”,“Jugular”,“Arterial”,“Iliac Artery”,“Blood”). The default is no infusions. Users can export each of these to see which parameters are modifiable.

Using dn_run

Running simulations produces a nested list (dn_out_1) where the highest level indexes each possible diet and scenario combination supplied in the inputs. For example, diet_comp_ex_1 and scenario_ex_1 had 3 diets and 10 scenarios, respectively, resulting in 30 simulations.

To run these 30 simulations, it requires the following line of code:

dn_out_1 = dn_run(diet_comp = diet_comp_ex_1, scenario = scenario_ex_1)

The output is a nested list. For each simulation, the standard NASEM (2021) output is returned in a series of sub-lists as shown below.

# level 2
names(dn_out_1)
##  [1] "d1__s1"  "d2__s1"  "d3__s1"  "d1__s2"  "d2__s2"  "d3__s2"  "d1__s3" 
##  [8] "d2__s3"  "d3__s3"  "d1__s4"  "d2__s4"  "d3__s4"  "d1__s5"  "d2__s5" 
## [15] "d3__s5"  "d1__s6"  "d2__s6"  "d3__s6"  "d1__s7"  "d2__s7"  "d3__s7" 
## [22] "d1__s8"  "d2__s8"  "d3__s8"  "d1__s9"  "d2__s9"  "d3__s9"  "d1__s10"
## [29] "d2__s10" "d3__s10"
# level 1
dn_out_1[[1]] %>% names()
##  [1] "an"     "dmi"    "dt"     "dig"    "enrg"   "micr"   "abs"    "inf"   
##  [9] "mp"     "main"   "gest"   "bod"    "mlk"    "MV"     "excr"   "eff"   
## [17] "imb"    "f"      "Tbl1_1" "Tbl1_2" "Tbl1_3" "Tbl2_1" "Tbl2_2" "Tbl3_1"
## [25] "Tbl4_1" "Tbl4_2" "Tbl4_3" "Tbl5_1" "Tbl6_1" "Tbl6_2" "Tbl6_3" "Tbl6_4"
## [33] "Tbl7_1" "Tbl7_2" "Tbl7_3" "Tbl8_1" "Tbl8_2"

Working with results

The dairynasem package allows two options for working with results. Users can choose from these options, which are detailed below:

dn_export

dn_extract

Export

For each simulation, export writes the tables in a typical NASEM (2021) report to a .txt file in the working directory. Figure 2 shows the 30 files written for 30 simulations in the example, plus a glimpse at the appearance of the tables in each .txt file.

dn_export(dn_out_1)
Figure 2. Example of exported NASEM results in working directory

Figure 2. Example of exported NASEM results in working directory

Tables given in a NASEM (2021) report

  • “Tbl1_1” Physiological State/Management

  • “Tbl1_2” Entered Performance

  • “Tbl1_3” Predicted Production Variables

  • “Tbl2_1” Macronutrients

  • “Tbl2_2” Diet Ingredients

  • “Tbl3_1” Ingredient macronutrient contributions

  • “Tbl4_1” Energy Supply

  • “Tbl4_2” NEL and ME requirements

  • “Tbl4_3” Nutrient contributions to DE

  • “Tbl5_1” Fatty Acid supply

  • “Tbl6_1” Animal inputs

  • “Tbl6_2” Net protein and metabolizable protein

  • “Tbl6_3” Predicted and target supply of metabolizable protein and amino acids

  • “Tbl6_4” EAA partitioning using predicted Milk NP, g/d

  • “Tbl7_1” Minerals

  • “Tbl7_2” Vitamin supply and requirements

  • “Tbl7_3” Water, volatile solids, and methane

  • “Tbl8_1” Nitrogen and mineral excretion

  • “Tbl8_2” Ingredient mineral contributions

Extract

Because the nested list returned by dn_run is somewhat difficult to work with, the function dn_extract is designed to facilitate extracting desired results into dataframes. It takes two arguments: 1) the dn_run output, in the example assigned to dn_out_1; and 2) the desired results to return.

dn_extr_1 = dn_extract(dn_out_1, "mp")
head(dn_extr_1)
##   DietID ScenarioID An_CPIn_g An_MPIn_g  An_MPIn    An_MP  Dt_MPIn    Dt_MP
## 1     d1         s1  5372.019  2831.916 2.831916 9.439720 2.831916 9.439720
## 2     d2         s1  5733.732  2917.705 2.917705 9.725682 2.917705 9.725682
## 3     d3         s1  4704.723  2611.147 2.611147 8.703822 2.611147 8.703822
## 4     d1         s2  5339.787  2816.942 2.816942 9.446486 2.816942 9.446486
## 5     d2         s2  5699.330  2902.228 2.902228 9.732489 2.902228 9.732489
## 6     d3         s2  4676.495  2597.586 2.597586 8.710887 2.597586 8.710887
##   An_NPuse_g An_NPxprt_g Fe_MPendUse_g Scrf_MPUse_g Ur_MPendUse_g
## 1   1417.593    1415.710      633.3662     15.46504      215.5609
## 2   1420.830    1418.947      658.8375     15.93680      215.5609
## 3   1425.177    1423.294      589.4500     14.08181      215.5609
## 4   1394.481    1392.101      635.6534     15.71155      217.7969
## 5   1397.698    1395.318      661.2281     16.19111      217.7969
## 6   1402.019    1399.639      591.5024     14.30443      217.7969
##   Body_MPUse_g_Trg Gest_MPUse_g_Trg Mlk_MPUse_g An_MPuse_g An_MPuse_g_Trg
## 1               85         5.706559    1880.937   2836.036       2294.456
## 2               85         5.706559    1938.315   2919.357       2299.147
## 3               85         5.706559    1712.701   2622.500       2305.447
## 4               85         7.210469    1858.907   2820.280       2263.980
## 5               85         7.210469    1915.647   2903.073       2268.643
## 6               85         7.210469    1692.424   2608.238       2274.905
##   An_NPBal_g  An_MPBal_g An_MPIn_MEIn An_MPuse_MEuse
## 1 -2.0592362  -4.1197062     35.81847       45.90385
## 2 -0.8042302  -1.6524394     37.21956       47.25248
## 3 -6.1701608 -11.3538535     31.35725       42.44758
## 4 -1.6502975  -3.3376583     35.83439       46.07649
## 5 -0.4068709  -0.8450867     37.23683       47.42913
## 6 -5.7254681 -10.6513413     31.37290       42.61224

Results that can be requested with dn_extract:

  • “an” information about the animal and scenario entered by the user

  • “dmi” dry matter intake, target and predicted

  • “dt” diet composition and predictions

  • “dig” nutrient digestibility for rumen, duodenum, and total-tract

  • “enrg” energetics

  • “micr” microbial protein and amino acids (AA)

  • “abs” absorbed protein and AA

  • “inf” infusions (if any)

  • “mp” protein intake and use

  • “main” protein and AA summary

  • “gest” gestation

  • “bod” body gain/loss

  • “mlk” milk

  • “MV” minerals and vitamins

  • “excr” nutrient and energy excretion

  • “eff” protein and energy use efficiencies

  • “imb” imbalance in AA

  • “f” entered diet composition

Other possibilities

Users can access nearly any model parameter in the nested lists returned by dn_run. Therefore, there are many possibilities to work with output besides those shown above.