Creates a vector of Gabelhouse lengths for each species in an entire data frame.
Source:R/psdAdd.R
psdAdd.RdCreates a vector of the Gabelhouse lengths specific to a species for all individuals in an entire data frame.
Usage
psdAdd(len, ...)
# Default S3 method
psdAdd(
len,
species,
group = NULL,
units = c("mm", "cm", "in"),
use.names = TRUE,
as.fact = ifelse(is.null(addLens), use.names, FALSE),
addLens = NULL,
verbose = TRUE,
...
)
# S3 method for class 'formula'
psdAdd(
len,
data = NULL,
group = NULL,
units = c("mm", "cm", "in"),
use.names = TRUE,
as.fact = ifelse(is.null(addLens), use.names, FALSE),
addLens = NULL,
verbose = TRUE,
...
)Arguments
- len
A numeric vector that contains lengths measurements or a formula of the form
len~specwhere “len” generically represents the length variable and “spec” generically represents the species variable. Note that this formula can only contain two variables and must have the length variable on the left-hand-side and the species variable on the right-hand-side.- ...
Not used.
- species
A character or factor vector that contains the species names. Ignored if
lenis a formula.- group
A named list that provides specific choices for
groupfor species for which more than one set of Gabelhouse lengths exists inPSDlit.- units
A string that indicates the type of units used for the lengths. Choices are
mmfor millimeters (DEFAULT),cmfor centimeters, andinfor inches.- use.names
A logical that indicates whether the vector returned is numeric (
=FALSE) or string (=TRUE; default) representations of the Gabelhouse lengths. See details.- as.fact
A logical that indicates that the new variable should be returned as a factor (
=TRUE) or not (=FALSE). Defaults to sameuse.namesunlessaddLensis notNULL, in which case it will default toFALSE. See details.- addLens
A named list with (possibly named) numeric vectors of lengths that should be used in addition to the Gabelhouse lengths for the species that forms the names in hte list. See examples.
- verbose
A logical that indicates whether detailed messages about species without Gabelhouse lengths or with no recorded values should be printed or not.
- data
A data.frame that minimally contains the length measurements and species names if
lenis a formula.
Details
This computes a vector that contains the Gabelhouse lengths specific to each species for all individuals in an entire data frame. The vector can be appended to an existing data.frame to create a variable that contains the Gabelhouse lengths for each individual. The Gabelhouse length value will be NA for each individual for which Gabelhouse length definitions do not exist in PSDlit. Species names in the data.frame must be the same as those used in PSDlit.
Some species have Gabelhouse lengths for sub-groups (e.g., “lentic” vs “lotic”). For these species, choose which sub-group to use with group.
Individuals shorter than “stock” length will be listed as substock if use.names=TRUE or 0 if use.names=FALSE.
Additional lengths to be used for a species may be included by giving a named list with vectors of additional lengths in addLens. Note, however, that as.fact will be reset to FALSE if addLens are specified, as there is no way to order the names (i.e., factor levels) for all species when additional lengths are used.
References
Ogle, D.H. 2016. Introductory Fisheries Analyses with R. Chapman & Hall/CRC, Boca Raton, FL.
Guy, C.S., R.M. Neumann, and D.W. Willis. 2006. New terminology for proportional stock density (PSD) and relative stock density (RSD): proportional size structure (PSS). Fisheries 31:86-87. [Was (is?) from http://pubstorage.sdstate.edu/wfs/415-F.pdf.]
Guy, C.S., R.M. Neumann, D.W. Willis, and R.O. Anderson. 2006. Proportional size distribution (PSD): A further refinement of population size structure index terminology. Fisheries 32:348. [Was (is?) from http://pubstorage.sdstate.edu/wfs/450-F.pdf.]
Willis, D.W., B.R. Murphy, and C.S. Guy. 1993. Stock density indices: development, use, and limitations. Reviews in Fisheries Science 1:203-222. [Was (is?) from http://web1.cnre.vt.edu/murphybr/web/Readings/Willis%20et%20al.pdf.]
Author
Derek H. Ogle, DerekOgle51@gmail.com
Examples
#===== Create random data for three species
set.seed(345234534)
dbg <- data.frame(species=factor(rep(c("Bluegill"),30)),
tl=round(rnorm(30,130,50),0))
dlb <- data.frame(species=factor(rep(c("Largemouth Bass"),30)),
tl=round(rnorm(30,350,60),0))
dbt <- data.frame(species=factor(rep(c("Bluefin Tuna"),30)),
tl=round(rnorm(30,1900,300),0))
df <- rbind(dbg,dlb,dbt)
str(df)
#> 'data.frame': 90 obs. of 2 variables:
#> $ species: Factor w/ 3 levels "Bluegill","Largemouth Bass",..: 1 1 1 1 1 1 1 1 1 1 ...
#> $ tl : num 42 73 152 184 167 94 138 169 86 157 ...
#===== Simple examples
#----- Add variable using category names -- non-formula notation
df$PSD <- psdAdd(df$tl,df$species)
#> Species in the data with no Gabelhouse (PSD) lengths in `PSDlit`:
#> "Bluefin Tuna".
peek(df,n=6)
#> species tl PSD
#> 1 Bluegill 42 substock
#> 18 Bluegill 120 stock
#> 36 Largemouth Bass 491 preferred
#> 54 Largemouth Bass 293 stock
#> 72 Bluefin Tuna 2476 <NA>
#> 90 Bluefin Tuna 1551 <NA>
#----- Add variable using category names -- formula notation
df$PSD1 <- psdAdd(tl~species,data=df)
#> Species in the data with no Gabelhouse (PSD) lengths in `PSDlit`:
#> "Bluefin Tuna".
peek(df,n=6)
#> species tl PSD PSD1
#> 1 Bluegill 42 substock substock
#> 18 Bluegill 120 stock stock
#> 36 Largemouth Bass 491 preferred preferred
#> 54 Largemouth Bass 293 stock stock
#> 72 Bluefin Tuna 2476 <NA> <NA>
#> 90 Bluefin Tuna 1551 <NA> <NA>
#----- Add variable using length values as names
df$PSD2 <- psdAdd(tl~species,data=df,use.names=FALSE)
#> Species in the data with no Gabelhouse (PSD) lengths in `PSDlit`:
#> "Bluefin Tuna".
peek(df,n=6)
#> species tl PSD PSD1 PSD2
#> 1 Bluegill 42 substock substock 0
#> 18 Bluegill 120 stock stock 80
#> 36 Largemouth Bass 491 preferred preferred 380
#> 54 Largemouth Bass 293 stock stock 200
#> 72 Bluefin Tuna 2476 <NA> <NA> NA
#> 90 Bluefin Tuna 1551 <NA> <NA> NA
#----- Same as above but using dplyr
if (require(dplyr)) {
df <- df %>%
mutate(PSD1A=psdAdd(tl,species)) %>%
mutate(PSD2A=psdAdd(tl,species,use.names=FALSE))
peek(df,n=6)
}
#> Species in the data with no Gabelhouse (PSD) lengths in `PSDlit`:
#> "Bluefin Tuna".
#> Species in the data with no Gabelhouse (PSD) lengths in `PSDlit`:
#> "Bluefin Tuna".
#> species tl PSD PSD1 PSD2 PSD1A PSD2A
#> 1 Bluegill 42 substock substock 0 substock 0
#> 18 Bluegill 120 stock stock 80 stock 80
#> 36 Largemouth Bass 491 preferred preferred 380 preferred 380
#> 54 Largemouth Bass 293 stock stock 200 stock 200
#> 72 Bluefin Tuna 2476 <NA> <NA> NA <NA> NA
#> 90 Bluefin Tuna 1551 <NA> <NA> NA <NA> NA
#===== Adding lengths besides the Gabelhouse lengths
#----- Add a "minimum length" for Bluegill
df$PSD3 <- psdAdd(tl~species,data=df,addLens=list("Bluegill"=c("minLen"=175)))
#> Species in the data with no Gabelhouse (PSD) lengths in `PSDlit`:
#> "Bluefin Tuna".
df$PSD3A <- psdAdd(tl~species,data=df,addLens=list("Bluegill"=175))
#> Species in the data with no Gabelhouse (PSD) lengths in `PSDlit`:
#> "Bluefin Tuna".
df$PSD3B <- psdAdd(tl~species,data=df,addLens=list("Bluegill"=c("minLen"=175)),
use.names=FALSE)
#> Species in the data with no Gabelhouse (PSD) lengths in `PSDlit`:
#> "Bluefin Tuna".
head(df,n=6)
#> species tl PSD PSD1 PSD2 PSD1A PSD2A PSD3 PSD3A PSD3B
#> 1 Bluegill 42 substock substock 0 substock 0 substock substock 0
#> 2 Bluegill 73 substock substock 0 substock 0 substock substock 0
#> 3 Bluegill 152 quality quality 150 quality 150 quality quality 150
#> 4 Bluegill 184 quality quality 150 quality 150 minLen 175 175
#> 5 Bluegill 167 quality quality 150 quality 150 quality quality 150
#> 6 Bluegill 94 stock stock 80 stock 80 stock stock 80
#----- Add add'l lengths and names for Bluegill and Largemouth Bass
addls <- data.frame(species=c("Bluegill","Largemouth Bass","Largemouth Bass"),
lens=c(175,254,356))
df$psd4 <- psdAdd(tl~species,data=df,
addLens=list("Bluegill"=175,
"Largemouth Bass"=c(254,356)))
#> Species in the data with no Gabelhouse (PSD) lengths in `PSDlit`:
#> "Bluefin Tuna".
peek(df,n=20)
#> species tl PSD PSD1 PSD2 PSD1A PSD2A PSD3
#> 1 Bluegill 42 substock substock 0 substock 0 substock
#> 5 Bluegill 167 quality quality 150 quality 150 quality
#> 9 Bluegill 86 stock stock 80 stock 80 stock
#> 14 Bluegill 124 stock stock 80 stock 80 stock
#> 19 Bluegill 155 quality quality 150 quality 150 quality
#> 24 Bluegill 108 stock stock 80 stock 80 stock
#> 28 Bluegill 94 stock stock 80 stock 80 stock
#> 33 Largemouth Bass 433 preferred preferred 380 preferred 380 preferred
#> 38 Largemouth Bass 293 stock stock 200 stock 200 stock
#> 43 Largemouth Bass 396 preferred preferred 380 preferred 380 preferred
#> 47 Largemouth Bass 268 stock stock 200 stock 200 stock
#> 52 Largemouth Bass 279 stock stock 200 stock 200 stock
#> 57 Largemouth Bass 345 quality quality 300 quality 300 quality
#> 62 Bluefin Tuna 2064 <NA> <NA> NA <NA> NA <NA>
#> 66 Bluefin Tuna 2273 <NA> <NA> NA <NA> NA <NA>
#> 71 Bluefin Tuna 1785 <NA> <NA> NA <NA> NA <NA>
#> 76 Bluefin Tuna 1596 <NA> <NA> NA <NA> NA <NA>
#> 81 Bluefin Tuna 1692 <NA> <NA> NA <NA> NA <NA>
#> 85 Bluefin Tuna 1997 <NA> <NA> NA <NA> NA <NA>
#> 90 Bluefin Tuna 1551 <NA> <NA> NA <NA> NA <NA>
#> PSD3A PSD3B psd4
#> 1 substock 0 substock
#> 5 quality 150 quality
#> 9 stock 80 stock
#> 14 stock 80 stock
#> 19 quality 150 quality
#> 24 stock 80 stock
#> 28 stock 80 stock
#> 33 preferred 380 preferred
#> 38 stock 200 254
#> 43 preferred 380 preferred
#> 47 stock 200 254
#> 52 stock 200 254
#> 57 quality 300 quality
#> 62 <NA> NA <NA>
#> 66 <NA> NA <NA>
#> 71 <NA> NA <NA>
#> 76 <NA> NA <NA>
#> 81 <NA> NA <NA>
#> 85 <NA> NA <NA>
#> 90 <NA> NA <NA>
#===== Example for a species with sub-groups
dbt <- data.frame(species=factor(rep(c("Brown Trout"),30)),
tl=round(rnorm(30,230,50),0))
dlt <- data.frame(species=factor(rep(c("Lake Trout"),30)),
tl=round(rnorm(30,550,60),0))
df2 <- rbind(dbt,dlt)
str(df2)
#> 'data.frame': 60 obs. of 2 variables:
#> $ species: Factor w/ 2 levels "Brown Trout",..: 1 1 1 1 1 1 1 1 1 1 ...
#> $ tl : num 194 227 165 262 278 239 277 213 191 191 ...
df2$psd <- psdAdd(tl~species,data=df2,group=list("Brown Trout"="lotic"))
peek(df2,n=6)
#> species tl psd
#> 1 Brown Trout 194 stock
#> 12 Brown Trout 215 stock
#> 24 Brown Trout 241 quality
#> 36 Lake Trout 629 quality
#> 48 Lake Trout 536 quality
#> 60 Lake Trout 571 quality