fcs2JointAndSingleEQR: Joint And Single 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 and single EQRs that can be calculated individually using fcs2JointEQR and fcs2SingleEQR respectively.

fcs2JointAndSingleEQR(
  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 for multiple fits is returned. The "fcs2EQR" object is essentially an array 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. The third dimension of each object corresponds to a individual model fit/species, with the first element corresponding to all species (as produced by fcs2JointEQR).

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.

## Not run: 

### Simple example with two model fits and no covariates
###

# simulate random dataset
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)
# randomly assign water body A, B or C to each survey
Data$WaterBody <- sample(c("A", "B", "C"), 100, replace=TRUE)

# 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 single and joint EQRs for salmon and trout
#   per survey and per water body, using same dataset as no pressure variables
eqrs <- fcs2JointAndSingleEQR(salmonFit, troutFit, newData=Data,
                              n.samples=100, n.sims=100,
                              joinByVar="WaterBody", both=TRUE)

# calculate mean values of EQRs per survey
mean(eqrs[[1]])

# calculate mean values of EQRs per water body
mean(eqrs[[2]])

# plot salmon, trout and combined EQR variables for water body A
plot(eqrs[[2]], data.frame("A", 1:3), boundaries=NULL)

## End(Not run)