--- title: "Convert EwE to Rpath" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Convert EwE to Rpath} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` ```{r setup} library(Rpath) ``` 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 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) ``` 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 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 ``` ## Differences between Rpath and EwE balances 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.