LRIBI: Computes the Wisconsin large rivers IBI
In droglenc/fishWiDNR: Support for Wisconsin DNR Fisheries Analyses

Description Usage Arguments Details Value Note Author(s) Source See Also Examples

Computes the Wisconsin large rivers IBI as described in Lyons et al. (2001). Also provides a variety of summary information and interpretative plots.

LRIBI(fmdb, agg, effort, region = NULL, round = TRUE,
  excludeSuckers = FALSE)

## S3 method for class 'LRIBI'
summary(object, intermediate = TRUE, show.data = TRUE,
  show.title = TRUE, ...)

## S3 method for class 'LRIBI'
coef(object, ...)

## S3 method for class 'LRIBI'
plot(x, type = c("dashboard", "counts", "weights", "biomass",
  "ratings", "scores"), y = NULL, label.mar = 9, axis.mult = 1.25,
  rating.col = FSA::col2rgbt(c("red", "yellow", "green"), 1/2), xlab = NULL,
  main = NULL, ...)

problemsLRIBI(object, type = c("counts", "weights"))

`fmdb`	A data.frame of raw fish data from the Fisheries Management Database. This data.frame should be created with `read.FMDB` and filtered to include only the survey or visit number for which the IBI should be computed. See Details.
`agg`	A data.frame of aggregate counts and weights from XXXX. This data.frame should be filtered to include only the survey or visit number for which the IBI should be computed. See Details.
`effort`	A single numeric value that represents the effort (in miles) expended on the survey or visit represented in `fmdb` and `agg`.
`region`	A single character string that indicates the ecoregion (must be either `"North"` or `"South"`) in which the survey was conducted. See Notes.
`round`	A logical that indicates whether the metric values should be rounded before comparing to Table 3 to define ratings. See Notes.
`excludeSuckers`	A single logical that indicates that the two “sucker” metrics should be excluded or not (DEFAULT) from the IBI calculation. See Notes.
`object, x`	An `LRIBI` object returned from `LRIBI`.
`intermediate`	A logical that indicates whether intermediate results should be returned with `summary`. See Details.
`show.data`	A logical that indicates whether summary data results should be returned with `summary`. See Details.
`show.title`	A logical that indicates whether the title and IBI result should be returned with `summary`. See Details.
`type`	A single character string that indicates the type of plot to construct (in `plot`) or problems to report (in `problemsLRIBI`). See details.
`y`	Not used. Included here because required by main `plot`.
`label.mar`	A single numeric that indicates the size of y-axis margin to be used for all `plot`s except for `type="dashboard"`. This margin holds the metric names and, thus, likely needs to be fairly large. Likely only need to change from default when the overall graphic size changes.
`axis.mult`	A single numeric used when `type="dashboard"` to extend the y-axes so that all values or metric cutoff values are shown. Generally, should only be slightly greater than 1 (and likely does not need to change from the default).
`rating.col`	Either a single or vector of length three that contains colors use to represent “"Poor"”, “"Fair"”, or “"Good"” metric ratings. Use a vector of length three for different colors for the ratings or a single color to not distinguish among the ratings. See Examples.
`xlab`	A single numeric used to label the x-axis of the plots.
`main`	A single numeric used to produce a main title for the plots. If `NULL` (the DEFAULT) a title that includes the survey number, waterbody name, county, ecoregion, and year is produced. Use `main=""` to suppress the title.
`...`	Optional additional arguments used in `plot`. Not yet implemented in `summary` or `coef` (needed here to match default function).

This function derives the Wisconsin large rivers index of biotic integrity (IBI) value using the calculations described in Lyons et al. (2001). This function requires data collected in a specific Wisconsin DNR survey and stored in two CSV files reported from WiDNR databases. The first is a "raw fish data" file from the Fisheries Management Database (hereafter, called the FMDB file) that is obtained from XXX FMDB DETAILS HERE XXX and can be read by read.FMDB. The second file is an "aggregate data" file (hereafter, called the aggregate file) that is obtained from XXX AGGREGATE FILES DETAILS HERE XXX. After reading both files should be filtered to include only data from the specific survey (could be a specific “Survey.Seq.No” or “Visit.Fish.Seq.No”) for which the IBI should be calculated. The main LRIBI function will automatically restrict the FMDB data.frame to only those surveys where the “TARGET SPECIES” field is equal to “ALL SPECIES”.

Some discrepancies may exist between the FMDB and aggregate files. For example, the total counts or biomass of a species may differ between the files. Warning messages will be issued when these discrepancies are discovered. The main LRIBI function will continue with the counts from the FMDB file and the weights from the aggregate file when discrepancies occur. Help with determining the species for which the discrepancies occur is obtained by submitting the LRIBI object to problemsLRIBI.

The overall IBI is returned by either coef (or summary with show.metrics=FALSE, show.data=FALSE, and show.title=FALSE). The intermediate metrics may be seen by including show.metrics=TRUE (DEFAULT) in summary or with type="dashboard", type="ratings", or type="score" in plot. The summarized data that led to the metrics may be seen by including show.data=TRUE (DEFAULT) in summary or with type="counts" or type="weights" in plot.

The main LRIBI functions returns a list of class LRIBI with the following items:

survey The survey number given in survey.
region The ecoregion in which the survey was conducted (as determined from the county or as sent in region).
effort The number of miles samples (currently as given in effort).
short.title A character string title that includes the survey number, visit number, waterbody name, and year. Used with plot.
long.title A character string title that includes the survey number, visit number, waterbody name, county, ecoregion, and year. Used with summary
IBI The overall IBI score.
n.fish The total number (count) of fish sampled.
ttl.Biomass The total biomass (kg) of fish sampled.
sum.data A data.frame of species counts, biomasses, and DELT number, along with categories required for computing the IBI metrics.
IBI.data A data.frame of metric name, value, rating, and score for the 10 individual metrics in Lyons et al. (2001) IBI.
noProblems A logical that is TRUE if there were no discrepancies between the FMDB and aggregate data files.
countsProblems A vector of species names for which there was a discrepancy in the counts between the FMDB and aggregate data files.
weightsProblems A vector of species names for which there was a discrepancy in the weights between the FMDB and aggregate data files.
fmdb.data A data.frame that contains the species name, total count, and total biomass for species in the FMDB data file.
agg.data A data.frame that contains the species name, total count, total biomass, and total DELT number for species in the aggregate data file.

summary prints a variety of items (see Details) and returns the overall IBI value.

coef returns the overall IBI value.

plot produces a number of plots but does not return any value.

problemsLRIBI prints a variety of items (see Details) but does not return any value.

It is expected that the FMDB and aggregate files (see Details) will include the survey number in the file name and that number will be at the end of the file name (with the exception of the CSV extension). The filenames may have other text prior to the survey number. It is suggested to not change the filenames from those returned by the WiDNR database reports (e.g., “fish_raw_data_Survey375049456.csv” and “aggdata_Survey375049456.csv”). However, if the text prior to the survey number is changed from the default then that text should be entered into fmdb.prefix and agg.prefix as appropriate.

The ecoregion can be automatically detected from the county in which the survey took place. However, there are a handful of counties that exist in both the North and South ecoregions. In these instances, the automatic detection of ecoregion will throw an error asking the user to supply the specific ecoregion in region. Alternatively the user may over-ride the automatically determined ecoregion by supplying a specific ecoregion in region.

The values in Table 3 of Lyons et al. (2001) imply that most metric values were rounded to whole numbers (“WPUE” and “%DELT” were rounded to one decimal) for converting to IBI ratings. Metric values are rounded prior to comparing to Table 3 if round=TRUE (the DEFAULT) or are not rounded if round=FALSE.

Lyons et al. (2001) noted that the diversity of sucker species in tributaries to Lake Superior and some tributaries to Green Bay, Lake Michigan had very low diversities of sucker species. Thus, the two sucker metrics (“Sucker species” and “% Round suckers (wt)”) should be excluded from the overall IBI calculation. The sum of the other eight metrics should be multipled by 1.25 (=10/8) to compensate for the use of fewer metrics and produce a result on a similar scale. By default the two sucker metrics are used in the overall IBI calculation, but the two metrics can be excluded (and the corrective multiplier applied) by using excludeSuckers=TRUE.

Derek H. Ogle (derek@derekogle.com) and Joseph T. Mrnak

Lyons, J., R.R. Piette, and K.W. Niermeyer. 2001. Development, validation, and application of a fish-based index of biotic integrity for Wisconsin's large warmwater rivers. Transactions of the American Fisheries Society 130:1077-1094.

LRIBI_AppendixA, LRIBI_Table3, and LRIBI_Ecoregions.

## Get location of external data files
dir <- dirname(system.file("extdata","aggdata_Survey375049456.csv",package="fishWiDNR"))

## Example of one survey
fmdb1 <- read.FMDB(paste0(dir,"/fish_raw_data_Survey375049456.csv"),expandCounts=TRUE)
agg1 <- read.csv(paste0(dir,"/aggdata_Survey375049456.csv"),stringsAsFactors=FALSE)
res <- LRIBI(fmdb1,agg1,effort=0.9)

coef(res)
summary(res)
summary(res,show.data=FALSE)
summary(res,intermediate=FALSE)
summary(res,show.data=FALSE,intermediate=FALSE)
summary(res,show.data=FALSE,intermediate=FALSE,show.title=FALSE)

plot(res)
plot(res,rating.col=NULL)
plot(res,rating.col="lightblue")
plot(res,rating.col=c("lightcyan","lightsalmon","lightblue"))
plot(res,type="counts",xlim=c(0,80))
plot(res,type="biomass",xlim=c(0,25))
plot(res,type="weights",xlim=c(0,25))  # same
plot(res,type="ratings")
plot(res,type="ratings",rating.col=NULL)
plot(res,type="ratings",rating.col="lightblue")
plot(res,type="ratings",rating.col=c("lightcyan","lightsalmon","lightblue"))

problemsLRIBI(res)

## Another example of one survey
fmdb2 <- read.FMDB(paste0(dir,"/fish_raw_data_Survey375334018.csv"),expandCounts=TRUE)
agg2 <- read.csv(paste0(dir,"/aggdata_Survey375334018.csv"),stringsAsFactors=FALSE)

res2 <- LRIBI(fmdb2,agg2,effort=0.9)
summary(res2)
plot(res2)
problemsLRIBI(res2)
problemsLRIBI(res2,type="count")
problemsLRIBI(res2,type="weight")

# uses not rounded metric values
res2a <- LRIBI(fmdb2,agg2,effort=0.9,round=FALSE)
coef(res2); coef(res2a)   # rounding can make a difference