vignette draft

Author: kerim aydin

inst/extdata/xml/Western Bering Sea-Basic estimates.csv

@@ -0,0 +1,37 @@
+,"Group name","Trophic level","Hab area (proportion)","Biomass in habitat area (t/km^2)","Biomass (t/km^2)","Production / biomass (/year)","Consumption / biomass (/year)","Ecotrophic Efficiency","Production / consumption (/year)","Biomass accumulation (t/km^2)","BA rate (/year)"
+1,"Baleen whales",3.77382302,1.00000000,0.39100000,0.39100000,0.020000000,8.31200027,0.98913050,0.00240616,,
+2,"Toothed whales",4.15545177,1.00000000,0.041999999,0.041999999,0.020000000,17.5000000,0.00000000,0.00114286,,
+3,"Sperm whales",4.70328903,1.00000000,0.020000000,0.020000000,0.020000000,9.80000019,0.00000000,0.00204082,,
+4,"Walrus& bearded seals",3.15126300,1.00000000,0.26199999,0.26199999,0.059999999,13.8999996,0.42843521,0.00431655,,
+5,Seals,3.91453004,1.00000000,0.097000003,0.097000003,0.059999999,13.3400002,0.59622002,0.00449775,,
+6,"Steller sea lions",3.99049592,1.00000000,0.035000000,0.035000000,0.059999999,18.0000000,0.35000011,0.00333333,,
+7,Seabirds,3.95844197,1.00000000,0.0099999998,0.0099999998,0.80000001,87.0000000,0.00000000,0.00919540,,
+8,"Adult pollock",3.41674399,1.00000000,15.0000000,15.0000000,0.50000000,10.00000000,0.94974858,0.05000000,,
+9,"Juvenile pollock",3.35486889,1.00000000,3.75699997,3.75699997,2.50000000,13.0000000,0.48001531,0.19230770,,
+10,"Pacific cod",4.02525377,1.00000000,3.18700004,3.18700004,0.52100003,3.29999995,0.35416141,0.15787880,,
+11,P.halibut,4.55041885,1.00000000,0.082999997,0.082999997,0.25000000,3.50000000,0.98781377,0.07142857,,
+12,"Greenland turbot",4.45009899,1.00000000,0.057999998,0.057999998,0.20000000,3.59999990,0.94655168,0.05555556,,
+13,"Arrowtooth flounder",4.27181721,1.00000000,0.052000001,0.052000001,0.31999999,4.50000000,0.88955140,0.07111111,,
+14,"Small flatfish",3.20804310,1.00000000,0.99199998,0.99199998,0.28799999,6.84899998,0.73974621,0.04204993,,
+15,Skates,4.34995079,1.00000000,0.27100000,0.27100000,0.40000001,4.00000000,0.37822881,0.10000000,,
+16,"Sculpins& Rockfish",3.75946808,1.00000000,0.67699999,0.67699999,0.40000001,3.50000000,0.94447428,0.11428570,,
+17,Macrouridae,3.90579796,1.00000000,1.15600002,1.15600002,0.30000001,3.70000005,0.67480099,0.08108108,,
+18,Zoarcidae,4.08010292,1.00000000,0.89999998,0.89999998,0.30000001,2.51999998,0.98806512,0.11904760,,
+19,"Tanner crab",2.99084091,1.00000000,0.082999997,0.082999997,0.80000001,5.00000000,0.39797691,0.16000000,,
+20,"Snow crab",2.99084091,1.00000000,0.24900000,0.24900000,0.80000001,5.00000000,0.87123322,0.16000000,,
+21,"King crab",2.99432397,1.00000000,0.11900000,0.11900000,0.60000002,2.70000005,0.82682788,0.22222219,,
+22,Shrimp,2.40576601,1.00000000,2.10575294,2.10575294,2.03999996,10.1999998,0.90000021,0.20000000,,
+23,Epifauna,2.15079594,1.00000000,114.961998,114.961998,1.15900004,5.08699989,0.24500690,0.22783570,,
+24,Infauna,2.00000000,1.00000000,125.686996,125.686996,1.97000003,12.0000000,0.27408451,0.16416670,,
+25,"Benthic amphipods",2.00502491,1.00000000,13.8120003,13.8120003,2.50000000,14.0000000,0.99449003,0.17857140,,
+26,"Pacific herring",3.33645201,1.00000000,0.78700000,0.78700000,0.69999999,14.6000004,0.82282239,0.04794521,,
+27,"Pacific salmon",3.67482901,1.00000000,0.039000001,0.039000001,4.00000000,16.0000000,0.39076331,0.25000000,,
+28,Cephalopods,3.67573190,1.00000000,4.82999992,4.82999992,3.20000005,10.6700001,0.91090471,0.29990631,,
+29,"Forage fish",3.28703189,1.00000000,19.41937065,19.41937065,0.94999999,3.50000000,0.89999992,0.27142861,,
+30,Jellyfish,3.14681292,1.00000000,1.39999998,1.39999998,1.50000000,3.00000000,0.01646648,0.50000000,,
+31,"Large Zooplankton",2.63895106,1.00000000,120.739998,120.739998,4.39900017,14.4569998,0.55201441,0.30428171,,
+32,Copepods,2.05263209,1.00000000,122.620003,122.620003,9.50000000,26.2000008,0.97425568,0.36259541,,
+33,Phytoplankton,1.00000000,1.00000000,15.0000000,15.0000000,234.000000,,0.73821777,,,
+34,"Pelagic detritus",1.00000000,1.00000000,,,,,,,,
+35,"Benthic detritus",1.00000000,1.00000000,,,,,,,,
+36,"Detrital pool",1.00000000,1.00000000,,,,,0.00015627,,,

vignettes/Convert_EwE_to_Rpath.Rmd

@@ -18,62 +18,119 @@ knitr::opts_chunk$set(
 library(Rpath)
 ```
 
-If you have developed your model in Ecopath and you now want to bring it in to R and use Rpath for analysis, there are tools available in `Rpath` to do just that. First, you need to export your model from EwE to XML format. This will result in multiple files being exported to your machine. You will just need to locate the file with the extension `eiixml` and let `Rpath` do its magic!
+If you have developed your model in the Ecopath with Ecosim (EwE) software package and you now want to bring it into Rpath for analysis, there are tools available in `Rpath` to do just that. First, you need to export your model from EwE to XML format, using EwE's `File -> Export Model -> To XML` menu option to create a .eiixml file (all EwE functionality described here was tested using EwE version 6.7.0).  
 
-For example, take the model `Western_Bering_Sea.eiixml` exported from Ecobase. We can read in this file and convert it to an `Rpath` object using the function `create.rpath.from.eiixml()`
+For this example, the Western Bering Sea EwE model available for download on EcoBase (Aydin et al. 2002) was first imported into EwE, using EwE's Import Model menu option, then exported to the file `Western_Bering_Sea.eiixml`. We can read in this file and convert it to an `Rpath` object using the function `create.rpath.from.eiixml()`. 
 
 ```{r convert1, echo = TRUE, eval = TRUE}
 # Read in the model
 eiixml_file <- system.file("extdata/xml", "Western_Bering_Sea.eiixml", package = "Rpath")
 model <- create.rpath.from.eiixml(eiixml_file)
 ```
 
-The variable `model` is a list object containing the data objects required to balance your model and run simulations. There are 4 objects that comprise an `Rpath` object
-
-* model - 
-* diet - 
-* pedigree - 
-* stanzas - 
+Currently, the `create.rpath.from.eiixml()` will only import input parameters related to the unbalanced
+Ecopath model, and will not import Ecosim information or other supplementary tables.  However, the full
+set of tables in an .eiixml file can be examined (or manually imported) using the `import.eiixml()` 
+helper function. 
+
+The variable `model` is a list object (an unbalanced Ecopath model) containing the data objects required to balance your model and run simulations. There are 4 objects that comprise an `Rpath` object:
+
+* model - including basic inputs, detritus fate, other production, and fishery landings/discards.
+* diet - a diet matrix, including diet import.
+* stanzas - parameters for multi-stanza functional groups.
+* pedigree - data pedigree (quality) for the model.
+
+Prepare your imported model for balancing by first calculating
+multistanza parameters that are based on age structure (such as B and Q/B), using the 
+`rpath.stanzas()` function, then using the `check.rpath.params()` function to ensure all of the
+model's parameters are entered (If your model has no multistanza groups, `rpath.stanzas()`
+can be called but will not change the model). The `check.rpath.params()` function will
+make sure the data was read in correctly, and produce warnings in situations that might
+prevent the model from balancing; for example, if a functional group is missing too many
+parameters to be balanced, or if diet compositions for a predator do not sum to 1.
+
+```{r check, echo = TRUE, eval = TRUE}
+model <- rpath.stanzas(model)
+check.rpath.params(model)
+```
 
 ## Model parameters
 
-```{r group, echo = FALSE, eval = TRUE}
-model$model |> 
-  DT::datatable(options = list(
-    scrollX = TRUE, 
-    paging = TRUE,   
-    pageLength = 20
-  ))
-
+To compare Rpath balance results with EwE, first balance the model in EwE and use 
+EwE's "Save to a csv" icon on EwE's Outputs -> Basic estimates tab (upper right
+corner).  It is recommended that you first increase the precision (digits displayed)
+in EwE to 8 digits.  The following script, using the dplyr library, can then compare the
+resulting balances.
+
+```{r compare, echo = TRUE, eval = TRUE}
+
+# dplyr is used to match the Rpath and EwE balance results
+  library(dplyr, warn.conflicts=F)
+
+# EwE output files - eiixml file and Basic Estimates csv
+  eiifile <- system.file("extdata/xml", "Western_Bering_Sea.eiixml", package = "Rpath")
+  csvfile <- system.file("extdata/xml", "Western Bering Sea-Basic estimates.csv", package = "Rpath")
+
+# Load and balance the model in Rpath  
+  unbal  <- create.rpath.from.eiixml(eiifile)
+  unbal <- rpath.stanzas(unbal)
+  check.rpath.params(unbal)
+  bal <- rpath(unbal)
+  
+# Load the csv file and clean up the format
+  csv.out <- read.csv(csvfile)
+  # If there's no stanzas, the total mortality column will be missing from the CSV - add an extra column
+  if(length(csv.out)<13){csv.out <- data.frame(append(csv.out, list(tm=NA), after=6))}
+  # cleaned column names matching EwE output
+  names(csv.out)<-  c("X", "Group.name", "Trophic.level", "Hab.area", "Biomass.in.habitat.area",
+                    "Biomass", "Total.mortality", "Production.biomass", "Consumption.biomass",   
+                    "Ecotrophic.Efficiency", "Production.consumption", "Biomass.accumulation",
+                    "BA.rate")  
+  # Drop placeholder lines that head stanza groups
+  csv.out <- csv.out[!is.na(csv.out$X),]
+  # Clean names to rpath standard
+  csv.out$group <- janitor::make_clean_names(csv.out$Group.name)
+  
+# Create a data frame of rpath (balanced model) output 
+  rpath.dat <- data.frame(group=bal$Group,type=bal$type, tl=bal$TL, biomass=bal$Biomass,
+                          pb=bal$PB,qb=bal$QB, EE=bal$EE, pc=bal$GE, 
+                          ba=bal$BA)[c(rpath.living(bal), rpath.detrital(bal)),]
+  
+# Join rpath and EwE balance outputs, using dplyr
+  rpath_ewe_table <- rpath.dat %>% 
+    dplyr::left_join(csv.out, by="group") %>%
+    dplyr::mutate( biomass_test = abs(biomass-Biomass)/Biomass, 
+                   ee_test      = abs(EE-Ecotrophic.Efficiency)) %>%
+    dplyr::select(group, rpath.biomass=biomass, ewe.biomass=Biomass, prop.bio.diff=biomass_test,
+                  rpath.EE=EE, ewe.EE=Ecotrophic.Efficiency, EE.diff=ee_test)
+
+  rpath_ewe_table 
+  
 ```
 
-## Diet parameters
+## Differences between Rpath and EwE balances
 
-```{r diet, echo = FALSE, eval = TRUE}
-model$diet |> 
-  DT::datatable(options = list(
-    scrollX = TRUE,
-    paging = TRUE,  
-    pageLength = 20
-  ))
+Rpath was tested using the 150+ models available on EcoBase.  In general, differences
+between Rpath and EwE were within 1.0e-7 of each other for any given estimated EE, B,
+or P/B, with differences due to
+numerical precision of inputs.  Stanza groups may show differences of up to 1.0e-3
+due to accumulated differences summing across age groups.  However, there are
+some specific differences in functionality in some models:
 
-```
+* Q/B - Rpath does not currently estimate Q/B as part of the main balancing (i.e. to 
+estimate Q/B, both P/B and PC must be supplied).
+* Interdetrital flows - For models with three or more stages of interdetrital
+flows (that is, if detritus fate specifies thart Detritus A -> Detritus B -> Detritus C),
+results may differ between Rpath and EwE.  Two-stage detrital flows (Detritus A -> Detritus B)
+give matching results.
+* Rpath will not currently estimate BA.  In cases where all of B, EE, and P/B are
+supplied, Rpath will not estimate BA or make changes to the model, and may produce
+inconsistent results if one of those paramters isn't set to NA.
+* Rpath does not currently support BA rate, only total BA.  If your model has a BA rate,
+it is recommended that you calculate the total BA in EwE (as an output), and enter
+that value into Rpath.
 
-## Pedigree parameters
-
-```{r pedigree, echo = FALSE, eval = TRUE}
-model$pedigree |> 
-  DT::datatable(options = list(
-    scrollX = TRUE, 
-    paging = TRUE, 
-    pageLength = 20
-  ))
-
-```
 
-## Stanza parameters
 
-Some models also contain stanza information. This West Bering Sea model does not.
-However the `Rpath` object will contain an empty stanzas field as a place holder.