psdAdd: Creates a vector of Gabelhouse lengths for each species in an...

In FSA: Simple Fisheries Stock Assessment Methods

Creates a vector of Gabelhouse lengths for each species in an entire data frame.

Description

Creates 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,
  thesaurus = NULL,
  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,
  thesaurus = 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~spec where “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 len is a formula.
thesaurus	A named list for providing alternative species names (the values in the list) that correspond to specific names in PSDlit (the names in the list). See details and examples.
group	A named list that provides specific choices for group for species for which more than one set of Gabelhouse lengths exists in PSDlit.
units	A string that indicates the type of units used for the lengths. Choices are mm for millimeters (DEFAULT), cm for centimeters, and in for 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 same as use.names unless addLens is not NULL, in which case it will default to FALSE. 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 form the names in the 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 len is 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 (i.e., same spelling and capitalization; use psdVal() to see the list of species).

The thesaurus argument may be used to relate alternate species names to the species names used in PSDlit. For example, you (or your data) may use “Bluegill Sunfish”, but “Bluegill” is used in PSDlit. The alternate species name can be used here if it is defined in a named vector (or list) given to thesarus=. The alternate species name is the value and the species name in PSDlit is the name in this vector/list - e.g., c("Bluegill"="Bluegill Sunfish"). See the examples for a demonstration.

Some species have length categories separated by sub-group. For example, length categories exist for both lentic and lotic populations of Brown Trout. The length values for a sub-group may be obtained by either including the species name in species and the sub-group name in group or by using the combined species and sub-group name, with the sub-group name in parentheses, in species. Both methods are demonstrated in the examples. Note that an error is returned if a species has sub-groups but neither method is used to define the sub-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.

See examples and this article for a demonstration.

Value

A numeric or factor vector that contains the Gabelhouse length categories.

IFAR Chapter

6-Size Structure.

Author(s)

Derek H. Ogle, [e-mail]

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.]

See Also

psdVal, psdCalc, psdPlot, PSDlit, and wrAdd for related functions. See mapvalues for help in changing species names to match those in PSDlit.

Examples

#===== Simple examples -- 2 species, no groups, names as in PSDlit
#----- Isolate simple data from PSDWRtest
tmp <- subset(PSDWRtest,
              species %in% c("Yellow Perch","Largemouth Bass"),
              select=c("species","len"))
peek(tmp,n=6)

#----- Add variable using category names -- non-formula notation
tmp$PSD <- psdAdd(tmp$len,tmp$species)
peek(tmp,n=6)

#----- Add variable using category names -- formula notation
tmp$PSD1 <- psdAdd(len~species,data=tmp)
peek(tmp,n=6)

#----- Add variable using length values as names
tmp$PSD2 <- psdAdd(len~species,data=tmp,use.names=FALSE)
peek(tmp,n=6)

#----- Same as above but using dplyr
if (require(dplyr)) {
  tmp <- tmp %>%
    mutate(PSD1A=psdAdd(len,species),
           PSD2A=psdAdd(len,species,use.names=FALSE))
  peek(tmp,n=6)
}

#===== Add lengths besides Gabelhouse lengths (start over with same simple data)
tmp <- subset(PSDWRtest,
              species %in% c("Yellow Perch","Largemouth Bass"),
              select=c("species","len"))

#----- Add a "minimum length" for one species
tmp$PSD3 <- psdAdd(len~species,data=tmp,
                   addLens=list("Yellow Perch"=c("minLen"=225)))
tmp$PSD3A <- psdAdd(len~species,data=tmp,
                    addLens=list("Yellow Perch"=225))
tmp$PSD3B <- psdAdd(len~species,data=tmp,
                    addLens=list("Yellow Perch"=c("minLen"=225)),use.names=FALSE)
head(tmp,n=6)

#----- Add add'l lengths and names for multiple species
tmp$psd4 <- psdAdd(len~species,data=tmp,
                   addLens=list("Yellow Perch"=175,
                                "Largemouth Bass"=c(254,306)))
peek(tmp,n=20)

#===== Handle additional species in PSDlit but named differently
#----- Isolate different species data from PSDWRtest
tmp <- subset(PSDWRtest,
              species %in% c("Bluegill Sunfish","Lean Lake Trout"),
              select=c("species","len"))

#----- No "Bluegill Sunfish" in PSDlit, use thesaurus to note this is "Bluegill"
#        Note: "Lean Lake Trout" not processed as not in PSDlit
tmp$psd5 <- psdAdd(len~species,data=tmp,
                   thesaurus=c("Bluegill"="Bluegill Sunfish"))
peek(tmp,n=6)

#----- Process multiple species in PSDlit with different names
#        Note: Can still use addLens=, but with original name
thes <- c("Bluegill"="Bluegill Sunfish","Lake Trout"="Lean Lake Trout")
tmp$psd6 <- psdAdd(len~species,data=tmp,thesaurus=thes)
tmp$psd7 <- psdAdd(len~species,data=tmp,thesaurus=thes,
                   addLens=list("Bluegill Sunfish"=c("minLen"=175)))
peek(tmp,n=20)

#===== Example for a species with sub-groups but only one sub-group in data
#----- Isolate species data from PSDWRtest ... only Brook Trout has sub-group
tmp <- subset(PSDWRtest,
              species %in% c("Yellow Perch","Brook Trout"),
              select=c("species","len"))

#----- This will err as Brook Trout has sub-groups in PSDlit (as message notes)
# tmp$psd8 <- psdAdd(len~species,data=tmp)

#----- Can choose "overall" sub-group with group=
tmp$psd8 <- psdAdd(len~species,data=tmp,
                   group=list("Brook Trout"="overall"))
peek(tmp,n=10)

#----- Or can create species name with sub-group name in parentheses
#        Note: this is more useful in next examples
tmp$species2 <- ifelse(tmp$species=="Brook Trout","Brook Trout (overall)",
                       tmp$species)
tmp$psd8A <- psdAdd(len~species2,data=tmp) # note use of species2
peek(tmp,n=10)

#===== Example for species with more than one sub-group in data
#----- Isolate species data from PSDWRtest ... Brown Trout has two sub-groups
tmp <- subset(PSDWRtest,
              species %in% c("Yellow Perch","Largemouth Bass","Brown Trout"),
              select=c("species","len","location"))
peek(tmp,n=10)

#----- Must create a species name variable with sub-groups in parentheses
#        Note: there are likely many ways to do this specific to each use-case
tmp$species2 <- tmp$species
tmp$species2[tmp$species=="Brown Trout" & 
             tmp$location=="Trout Lake"] <- "Brown Trout (lotic)"
tmp$species2[tmp$species=="Brown Trout" & 
             tmp$location=="Brushy Creek"] <- "Brown Trout (lentic)"
peek(tmp,n=10)

tmp$psd9 <- psdAdd(len~species2,data=tmp)
peek(tmp,n=10)

FSA documentation built on Jan. 10, 2026, 9:07 a.m.