SimFish: Simulate a Fish Population
In JVAdams/artiFISHal: A Pelagic Fish Community Simulator

Description Usage Arguments Details Value References See Also Examples

Create a simulated population of pelagic fish in an artificial lake.

1
2
3

SimFish(LakeName, LkWidth, LkLength, BotDepMin, BotDepMax, BotDepVertex = 2 *
  BotDepMax, FishParam, TotNFish, TSRange = c(-65, -20), PlotsPdf = FALSE,
  Seed = NULL)

`LakeName`	A character scalar, full name for artificial lake to be used in plot titles.
`LkWidth`	A numeric scalar, the width of the lake in the west-east direction (in m).
`LkLength`	A numeric scalar, the length of the lake in the south-north direction (in m).
`BotDepMin`	A numeric scalar, the minimum bottom depth of the lake, at both the west and east shorelines (in m).
`BotDepMax`	A numeric scalar, the maximum bottom depth of the lake (in m).
`BotDepVertex`	A numeric scalar, the vertical distance from the surface to the "vertex" of the lake bottom (in m), default `2*BotDepMax`. The "vertex" of the lake bottom is the point at which the angled lake beds along the west and east shores would intersect, were they not cut off first by the specified `BotDepMax`. View this figure [link] for a diagram of the artificial lake.
`FishParam`	A data frame with 18 columns in which each row describes a sub-population of fish to be placed in the artificial lake. The first 11 columns must be completely filled in (no missing values). The last 8 columns may have some missing values. However, in each row, either water depth (`WD` and `WDE`) or distance to bottom (`D2B` and `D2BE`) must be filled in, but not both. Column names and descriptions: `G` = character, a one-letter nickname for the group (e.g., fish species and life stage) used in plotting `Z` = numeric, mean length (in mm) `ZE` = numeric, error around mean length, expressed as SD/mean `LWC1`, `LWC2` = numeric, length-weight regression coefficients, where wt = LWC1len^LWC2, (wt in g, len in mm) `LWCE` = numeric, error around weight estimate, expressed as SD(estimate)/estimate `TSC1`, `TSC2` = numeric, target strength and length relation coefficients, ts = TSC1 + TSC2log10(len/10), (ts in db, len in mm) `TSCE` = numeric, error around target strength estimate, expressed as SD(estimate)/estimate `PropN` = numeric, approximate proportion of population that the row represents (automatically adjusted to ensure they sum to 1) `E` = numeric, mean easting (m) `EE` = numeric, error around easting, expressed as SD/mean `N` = numeric, mean northing (m) `NE` = numeric, error around northing, expressed as SD/mean `WD` = numeric, mean water depth (m) `WDE` = numeric, error around water depth, expressed as SD/mean `D2B` = numeric, mean distance to bottom (m) `D2BE` = numeric, error around distance to bottom, expressed as SD/mean
`TotNFish`	A numeric scalar indicating the target number of fish to put in the lake. The actual number of fish in the population will likely be smaller than `TotNFish`, because the process used to populate the lake with fish ends up with some fish out of water (beyond the boundaries of the artificial lake), which are then removed from the population. Memory on your computer limits the size of `TotNFish` (see Details).
`TSRange`	A numeric vector of length 2, the range of target strengths to use for the fish (in db), default c(-65, -20).
`PlotsPdf`	A character scalar, name of pdf file to store the diagnostic plots in. If FALSE, the default, no plots are created.
`Seed`	An integer scalar, starting seed for stochasticity incorporated in fish population generation. Use `Seed` to ensure the same population is generated with each call to `SimFish`. Otherwise, if set to NULL, the default, a random seed is used, resulting in a different population with each call to `SimFish`.

The artificial lake can be imagined as a rectangular subset of a "real" lake. The east and west boundaries of the artificial lake do not reach the shoreline of the "real" lake, unless BotDepMin is set to zero. The north and south boundaries of the artificial lake do not ascend to a shoreline, instead the bottom depth remains constant in the south-north direction (i.e., for a given easting). The angle of the western lake bed is twice as steep as the angle of the eastern lake bed. View the top and side views of the artificial lake in this diagram [link].

You may wish to cap the total number of fish at 5 million if your computer has a memory of about 2 GB (2047 MB). This limit can be increased if you have more memory available in R. You can check the memory available with memory.limit.

The diagnostic plots produced, if PlotsPdf is not FALSE, include scatterplots of 1,000 fish randomly selected from the population, scatterplots of 250 fish randomly selected from each group, and histograms of the size and spatial distribution of all the fish in the lake.

A list with 6 elements:

Truth, a data frame with the total number and weight of each fish group in the population;
LakeInfo, a list with the lake inputs supplied as arguments to SimFish as well as a few additional objects which are used by SampFish in surveying the population,
- ints = a numeric vector of length 2, the intercepts of the angled lake beds along the west and east shores of the lake (in m)
- slopes = a numeric vector of length 2, the slopes of the angled lake beds along the west and east shores of the lake (unitless)
- d2shr.we = a numeric vector of length 2, distance (in the west-east direction) from west and east shores excluded from lake (in m);
FishInfo, a list with the fish inputs supplied as arguments to SimFish;
FishParam, the data frame supplied as an argument to SimFish;
FishPop, a data frame in which each row is a fish, and 10 columns describe the fish group (G), location (easting f.east, northing f.north, distance to shore f.d2sh, bottom depth f.botdep, water depth f.wdep, distance to bottom f.d2bot, all in m), and fish size (total length in mm len, weight in g wt, and target strength in db ts); and
PropExcluded, a numeric vector showing the proportion of the requested number of fish, TotNFish, that were eliminated from the population based on their size (len, wt, ts) or location (f.east, f.north, f.d2sh, f.botdep, f.wdep). If you end up with far fewer fish than requested, this can be useful in troubleshooting where the problems might lie.

Yule, DL, JV Adams, DM Warner, TR Hrabik, PM Kocovsky, BC Weidel, LG Rudstam, and PJ Sullivan. 2013. Evaluating analytical approaches for estimating pelagic fish biomass using simulated fish communities. Canadian Journal of Fisheries and Aquatic Sciences 70:1845-1857. http://www.nrcresearchpress.com/doi/abs/10.1139/cjfas-2013-0072#.U1KYxPldXTQ

SampFish

## Not run: 

# parameters for small (a) and large (A) alewife as input to the simulator
fishp <- data.frame(
  G = c("a", "A", "A"),
  Z = c(50, 140, 140), ZE = c(0.25, 0.2, 0.2),
  LWC1 = 0.000014, LWC2 = 2.8638, LWCE = 0.18,
  TSC1 = -64.2, TSC2 = 20.5, TSCE = c(0.02, 0.07, 0.07),
  PropN = c(0.55, 0.25, 0.20),
  E = c(NA, 900, 2800), EE = c(NA, 4.5, 0.3),
  N = NA, NE = NA,
  WD = c(5, 15, 15), WDE = c(0.5, 0.7, 0.7),
  D2B = NA, D2BE = NA
)

# simulate the fish population
res <- SimFish(LakeName="Clear Lake", LkWidth=3000, LkLength=2000,
 BotDepMin=20, BotDepMax=100, FishParam=fishp, TotNFish=1000, Seed=667)

# look at the results
res$Truth
res$LakeInfo
res$FishInfo
head(res$FishParam)
head(res$Fish)
res$PropExcluded


## End(Not run)