wsVal: Finds standard weight equation coefficients for a particular...

In FSA: Simple Fisheries Stock Assessment Methods

Finds standard weight equation coefficients for a particular species.

Description

Returns a vector that contains information about the standard weight equation for a given species, including type of measurement units, reference percentile, method used to derive the equation, and literature source.

Usage

wsVal(
  species = "List",
  group = NULL,
  units = c("metric", "English"),
  ref = NULL,
  method = NULL,
  simplify = FALSE,
  dat = NULL
)

Arguments

species	A string that contains the species name for which to find Ws coefficients. See details.
group	A string that contains the sub-group of species for which to find the Ws coefficients; e.g., things like “lotic”, “lentic”, “female”, “male”.
units	A string that indicates whether the coefficients for the standard weight equation to be returned are in "metric" (DEFAULT; mm and g) or "English" (in and lbs) units.
ref	A numeric that indicates which percentile the equation should be returned for. Note that the vast majority of equations only exist for the 75th percentile (DEFAULT).
method	A string that indicates which equation-derivation method should be used (one of "RLP", "EmP", or "Other"). Defaults to NULL which will result in the only method available being returned or an error asking the user to choose a method for equations for which more than one method is available (which is the case for very few species).
simplify	A logical that indicates whether the ‘units’, ‘ref’, ‘measure’, ‘method’, ‘comments’, and ‘source’ fields should be included (=FALSE) or not (=TRUE; DEFAULT). See details.
dat	Data.frame of Gabelhouse length categories for all species. Defaults to 'WSlit' and is generally not used by the user (this simplifies use of this function in wrAdd).

Details

This function extracts all known information from WSlit about the following standard weight equation,

log_{10}(Ws) = log_{10}(a) + blog_{10}(L) + blog_{10}(L)^{2}

See WSlit for more information about the meaning of each value returned.

Note from above that the coefficients are returned for the TRANSFORMED model. Thus, to obtain the standard weight (Ws), the returned coefficients are used to compute the common log of Ws which must then be raised to the power of 10 to compute the Ws.

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.

See examples and this article for a demonstration.

Value

A one row data frame from WSlit that contains all known information about the standard weight equation for a given species, type of measurement units, and reference percentile if simplify=FALSE. If simplify=TRUE then only the species; minimum and maximum length for which the standard equation should be applied; and intercept, slope, and quadratic coefficients for the standard weight equation. Note that the maximum length and the quadratic coefficient will not be returned if they do not exist in WSlit for the species.

If no arguments are given to this function then a list of available species names in WSlit will be printed. If the species name is mis-spelled (or mis-capitalized), multiple standard weight equations exist for the species (such that group, ref, or method should be used), or if a standard weight equation does not exist for the species in WSlit, then an error will be issued.

IFAR Chapter

8-Condition.

Author(s)

Derek H. Ogle, [e-mail]

References

Ogle, D.H. 2016. Introductory Fisheries Analyses with R. Chapman & Hall/CRC, Boca Raton, FL.

See Also

See wrAdd and WSlit for related functionality.

Examples

#===== List all available Ws equations
wsVal()

#===== Find equations for Yellow Perch, in different formats
wsVal("Yellow Perch")
wsVal("Yellow Perch",units="metric")   # same as default
wsVal("Yellow Perch",units="English")
wsVal("Yellow Perch",units="English",simplify=TRUE)

#===== Find equation for Ruffe, demonstrating quadratic formula
wsVal("Ruffe",units="metric",ref=75,simplify=TRUE)
wsVal("Ruffe",units="metric",ref=50,simplify=TRUE)

#===== Find equation for Brown Trout, which has equations for sub-groups
#-----   demonstrating use of group= argument
wsVal("Brown Trout",group="lotic")
wsVal("Brown Trout",group="lentic")
#-----   demonstrating group combined in species name, so no group= arg
wsVal("Brown Trout (lotic)")
wsVal("Brown Trout (lentic)")

#===== Add Ws & Wr values to a data frame (for one species) ... also see wrAdd()
#----- Example data from PSDWRtest, simplify variables for this example
yepdf <- subset(PSDWRtest,species=="Yellow Perch",select=c("species","len","wt"))
str(yepdf)

#----- Get Ws equation info
( wsYEP <- wsVal("Yellow Perch",units="metric") )

#----- Add Ws (eqn is on log10-log10 scale ... so log10 length, 10^ result)
yepdf$ws <- 10^(wsYEP[["int"]]+wsYEP[["slope"]]*log10(yepdf$len))

#----- Change Ws for fish less than min.TL to NA
yepdf$ws[yepdf$len<wsYEP[["min.TL"]]] <- NA

#----- Add Wr
yepdf$wr <- yepdf$wt/yepdf$ws*100

#----- Examine results
peek(yepdf,n=6)

#----- Same as above but using dplyr
if (require(dplyr)) {
  yepdf <- PSDWRtest %>% filter(species=="Yellow Perch") %>% select(species,len,wt) %>%
    mutate(ws=10^(wsYEP[["int"]]+wsYEP[["slope"]]*log10(len)),
           ws=ifelse(len<wsYEP[["min.TL"]],NA,ws),
           wr=wt/ws*100)
  peek(yepdf,n=6)
}

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