fcs2JointEQR: Joint EQR
In aquaMetrics/fcs2: Fisheries Classification Scheme 2 For SNIFFER

Description Usage Arguments Value Warning See Also Examples

Produces Monte Carlo samples of the joint Ecological Quality Ratio (EQR) that combines multiple species and optionally multiple surveys within a group (such as a water body). This provides a single EQR variable that is found by comparing the observed fish catches with the model's predictions at reference conditions for a number of species and optionally a number of surveys.
This function can be used to provide a single EQR variable for each water body that can be passed to fcs2Classify to produce probabilistic WFD classifications.

fcs2JointEQR(
  fit1,
  ...,
  newData,
  joinByVar = NULL,
  subset = 1:nrow(newData),
  na.action,
  n.samples = 1000,
  n.sims = 1000,
  both = FALSE,
  showProgress = TRUE,
  seed = NULL
)

`fit1`	an `"fcs2Fit"` object containing a full FCS2 model fit, as returned from `fcs2FitModel` with `runBUGS = TRUE`.
`...`	further `"fcs2Fit"` objects, each resulting from a full FCS2 model fit with a different species.
`newData`	a data frame with surveys as rows and variables as columns. It should contain all variables required by each of the model fits. Covariates which are related to human disturbance (pressure variables) should have their values set to the value expected at the site if it were undisturbed (reference conditions) rather than the observed value for each of these variables.
`joinByVar`	the name of a column in `dataFrame` to be used for joining multiple surveys together when calculating the EQR. For example, `joinByVar = "WBId"` would produce EQR samples for each water body, with every survey in a water body contributing towards its EQR. If `NULL` (the default), EQR samples are calculated for each survey.
`subset`	an optional vector specifying a subset of surveys to calculate EQR samples for.
`na.action`	a function which indicates what should happen when the data contain missing values (`NA`s). The default is set by the `na.action` setting of `options` and this is usually set to `na.omit`. This setting removes surveys that contain missing data in any required variables. A vector indicating the rows that were removed can be extracted from the returned object using `na.action.fcs2EQR` if surveys are not joined. Alternatively, `na.pass` can be used to ignore missing values (where possible) or `na.fail` can be given to signal an error if missing values are found.
`n.samples`	the number of Monte Carlo EQR samples to produce for each survey (or joining variable).
`n.sims`	the number of Monte Carlo simulations to make for each EQR sample. These internal samples are used for approximating the probability that defines the joint EQR.
`both`	if `TRUE` and `joinByVar` is provided, EQR samples are produced both for each survey and also for each level of the joining variable. This allows for efficient calculation of the joint EQR for each survey and also the joint EQR that also joins surveys.
`showProgress`	whether to display the current progress while generating EQR samples.
`seed`	set random seed to allow repeatable results.

If both = FALSE (the default), a single "fcs2EQR" object containing Monte Carlo EQR samples is returned. The "fcs2EQR" object is essentially a matrix with Monte Carlo samples as rows and columns corresponding to either surveys, if joinByVar is missing, or to different levels of the joining variable, e.g. different water bodies.

If both = TRUE and joinByVar is provided, a list containing both of these "fcs2EQR" objects is returned.

Although this function has been written in C for speed, it can still take a long time to produce a large number n.samples of EQR samples when the number n.sims of simulations is also high.

print.fcs2EQR, summary.fcs2EQR and fcs2EQRSummaryMatrix for summarising "fcs2EQR" objects;
plot.fcs2EQR for plotting EQR variables;
mean.fcs2EQR and quantile.fcs2EQR for calculating means and quantiles of EQR variables respectively;

fcs2FitModel for producing the required FCS2 model fits;
fcs2Classify for using EQR samples to produce probabilistic WFD classifications.

fcs2SingleEQR for producing EQR samples for a single species and survey;
fcs2JointAndSingleEQR for calculating joint and single EQR samples simultaneously.

## Not run: 

### Example 1: Simple example with two model fits and no covariates
###

# simulate random dataset for example
Data <- data.frame(SurveyArea=rlnorm(100, 4.6, 0.5))   # random survey area
# a single salmon catch per survey
Data$Salmon <- rzinbinom(100, size=1.1,
                         zeroprob=0.3, nbmean=0.3 * Data$SurveyArea)
# a single trout catch per survey
Data$Trout <- rzinbinom(100, size=0.87,
                        zeroprob=0.19, nbmean=0.42 * Data$SurveyArea)

# fit full model for salmon with OpenBUGS
salmonFit <- fcs2FitModel("Salmon", dataFrame=Data, surveyAreaVar="SurveyArea",
                          runBUGS=TRUE, n.iter=1000, bugsProgram="OpenBUGS")

# fit full model for trout with OpenBUGS
troutFit <- fcs2FitModel("Trout", dataFrame=Data, surveyAreaVar="SurveyArea",
                         runBUGS=TRUE, n.iter=1000, bugsProgram="OpenBUGS")

# calculate samples of EQR that combines salmon and trout for each survey,
#   using same dataset as no pressure variables to adjust to reference values
eqr <- fcs2JointEQR(salmonFit, troutFit, newData=Data,
                    n.samples=100, n.sims=100)

# plot EQR variables for first 9 surveys
plot(eqr, 1:9, boundaries=NULL)

# calculate mean EQR values
mean(eqr)



### Example 2: Joining surveys as well as species to create water body EQRs
###

# extend dataset to include water body indicator
# randomly assign water body A, B or C to each survey
Data$WaterBody <- sample(c("A", "B", "C"), 100, replace=TRUE)

# calculate samples of EQR that combines salmon and trout
#   as well as combining all surveys within each water body
eqr <- fcs2JointEQR(salmonFit, troutFit, newData=Data,
                    n.samples=100, n.sims=100, joinByVar="WaterBody")

# plot EQR variables for all 3 water bodies
plot(eqr, 1:3, boundaries=NULL)

# calculate mean EQR values
mean(eqr)

## End(Not run)