agePrecision: Compute measures of precision among sets of ages.

View source: R/ageComparisons.R

agePrecisionR Documentation

Compute measures of precision among sets of ages.

Description

Computes overall measures of precision for multiple age estimates made on the same individuals. Ages may be from two or more readers of the same structure, one reader at two or more times, or two or more structures (e.g., scales, spines, otoliths). Measures of precision include ACV (Average Coefficient of Variation), APE (Average Percent Error), AAD (Average Absolute Deviation), and ASD (Average Standard Deviation), and various percentage difference values.

Usage

agePrecision(formula, data)

## S3 method for class 'agePrec'
summary(
  object,
  what = c("precision", "difference", "absolute difference", "details"),
  percent = TRUE,
  trunc.diff = NULL,
  digits = 4,
  show.prec2 = FALSE,
  ...
)

Arguments

formula

A formula of the form ~var1+var2+var3+... or, alternatively, var1~var2+var3+..., where the varX generically represent the variables that contain the age estimates. The alternative formula allows for similar code as used in ageBias and can have only one variable on the left-hand side.

data

A data.frame that minimally contains the variables in formula.

object

An object of class agePrec, usually from agePrecision.

what

A string (or vector of strings) that indicates what type of summary to print. See details.

percent

A logical that indicates whether the difference table (see details) should be represented as percentages (TRUE; default) or frequency (FALSE) of fish.

trunc.diff

A single integer that identifies the age for which all values that age and greater are combined into one category. See the examples.

digits

A single numeric that indicates the minimum number of digits to print when using summary.

show.prec2

A logical that indicates whether the precision metrics that use the median (i.e., ACV2 and APE2) should be shown when only two age estimates were made (in this instance they will be exactly equal to ACV and APE). Default is to not show these values in this situation.

...

Additional arguments for methods.

Details

If what="precision" in summary then a summary table that contains the following items will be printed:

  • n Number of fish in data.

  • validn Number of fish in data that have non-NA data for all R age estimates.

  • R Number of age estimates given in formula.

  • PercAgree The percentage of fish for which all age estimates perfectly agree.

  • ASD The average (across all fish) standard deviation of ages within a fish.

  • ACV The average (across all fish) coefficient of variation of ages within a fish using the mean as the divisor. See the IFAR chapter for calculation details.

  • ACV2 The average (across all fish) coefficient of variation of ages within a fish using the median as the divisor. This will only be shown if R>2 or show.prec2=TRUE.

  • AAD The average (across all fish) absolute deviation of ages within a fish.

  • APE The average (across all fish) percent error of ages within a fish using the mean as the divisor. See the IFAR chapter for calculation details.

  • APE2 The average (across all fish) percent error of ages within a fish using the median as the divisor. This will only be shown if R>2 or show.prec2=TRUE.

  • AD The average (across all fish) index of precision (D).

Note that ACV2 and APE2 will not be printed when what="precision" if only two sets of ages are given (because mean=median such that ACV=ACV2 and APE=APE2). If what="difference" is used in summary, then a table that describes either the percentage (if percent=TRUE, DEFAULT) or frequency of fish by the difference in paired age estimates. This table has one row for each possible pair of age estimates.

If what="absolute difference" is used in summary, then a table that describes either the percentage (if percent=TRUE, DEFAULT) or frequency of fish by the absolute value of the difference in paired age estimates. This table has one row for each possible pair of age estimates. The “1” column, for example, represents age estimates that disagree by one year (in either direction).

If what="detail" is used in summary, then a data.frame of the original data along with the intermediate calculations of the mean age, median age, modal age (will be NA if a mode does not exist (e.g., all different ages) or multiple modes exist), standard deviation of age (SD), coefficient of variation using the mean as the divisor (CV), coefficient of variation using the median as the divisor (CV2), absolute deviation using the mean as the divisor (AD), absolute deviation using the median as the divisor (AD2), average percent error (PE), and index of precision (D) for each individual will be printed.

All percentage calculations above use the validn value in the denominator.

Value

The main function returns a list with the following items:

  • detail A data.frame with all data given in data and intermediate calculations for each fish. See details

  • rawdiff A frequency table of fish by differences for each pair of ages.

  • absdiff A frequency table of fish by absolute differences for each pair of ages.

  • AAD The average absolute deviation.

  • APE The average percent error (using the mean age as the divisor).

  • APE2 The average percent error (using the median age as the divisor).

  • ASD The average standard deviation.

  • ACV The average coefficient of variation (using the mean age as the divisor).

  • ACV2 The average coefficient of variation (using the median age as the divisor).

  • AD The average index of precision.

  • R The number of readings for each individual fish.

  • n Number of fish in data.

  • validn Number of fish in data that have non-NA data for all R age estimates.

The summary returns the result if what= contains only one item, otherwise it returns nothing. See details for what is printed.

Testing

Tested all precision results against published results in Herbst and Marsden (2011) for the WhitefishLC data and the results for the AlewifeLH data set from FSAdata against results from the online resource at http://www.nefsc.noaa.gov/fbp/age-prec/.

IFAR Chapter

4-Age Comparisons.

Author(s)

Derek H. Ogle, DerekOgle51@gmail.com

References

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

Beamish, R.J. and D.A. Fournier. 1981. A method for comparing the precision of a set of age determinations. Canadian Journal of Fisheries and Aquatic Sciences 38:982-983. [Was (is?) available from http://www.pac.dfo-mpo.gc.ca/science/people-gens/beamish/PDF_files/compareagecjfas1981.pdf.]

Campana, S.E. 1982. Accuracy, precision and quality control in age determination, including a review of the use and abuse of age validation methods. Journal of Fish Biology 59:197-242. [Was (is?) available from http://www.denix.osd.mil/nr/crid/Coral_Reef_Iniative_Database/References_for_Reef_Assessment_files/Campana,%202001.pdf.]

Campana, S.E., M.C. Annand, and J.I. McMillan. 1995. Graphical and statistical methods for determining the consistency of age determinations. Transactions of the American Fisheries Society 124:131-138. [Was (is?) available from http://www.bio.gc.ca/otoliths/documents/Campana%20et%20al%201995%20TAFS.pdf.]

Chang, W.Y.B. 1982. A statistical method for evaluating the reproducibility of age determination. Canadian Journal of Fisheries and Aquatic Sciences 39:1208-1210. [Was (is?) available from http://www.nrcresearchpress.com/doi/abs/10.1139/f82-158.]

McBride, R.S. 2015. Diagnosis of paired age agreement: A simulation approach of accuracy and precision effects. ICES Journal of Marine Science, 72:2149-2167.

See Also

See ageBias for computation of the full age agreement table, along with tests and plots of age bias.

Examples

## Example with just two age estimates
ap1 <- agePrecision(~otolithC+scaleC,data=WhitefishLC)
summary(ap1)
summary(ap1,what="precision")
summary(ap1,what="difference")
summary(ap1,what="difference",percent=FALSE)
summary(ap1,what="absolute")
summary(ap1,what="absolute",percent=FALSE)
summary(ap1,what="absolute",trunc.diff=4)
summary(ap1,what=c("precision","difference"))
summary(ap1,what="detail")

barplot(ap1$rawdiff,ylab="Frequency",xlab="Otolith - Scale Age")
plot(AD~mean,data=ap1$detail,pch=19,col=col2rgbt("black",1/5),
     xlab="Mean Age",ylab="Absolute Deviation Age")
plot(SD~mean,data=ap1$detail,pch=19,col=col2rgbt("black",1/5),
     xlab="Mean Age",ylab="Standard deviation Age")
plot(SD~AD,data=ap1$detail,pch=19,col=col2rgbt("black",1/5),
     xlab="Absolute Deviation Age",ylab="Standard deviation Age")
plot(CV~PE,data=ap1$detail,pch=19,col=col2rgbt("black",1/5),
     xlab="Percent Error Age",ylab="Coefficient of Variation Age")

## Example with three age estimates
ap2 <- agePrecision(~otolithC+finrayC+scaleC,data=WhitefishLC)
summary(ap2,digits=3)
summary(ap2,what="precision")
summary(ap2,what="difference")
summary(ap2,what="absolute",percent=FALSE,trunc.diff=4)
summary(ap2,what="detail",digits=3)

plot(AD~mean,data=ap2$detail,pch=19,col=col2rgbt("black",1/5),
     xlab="Mean Age",ylab="Absolute Deviation Age")
plot(SD~mean,data=ap2$detail,pch=19,col=col2rgbt("black",1/5),
     xlab="Mean Age",ylab="Standard Deviation Age")
plot(SD~AD,data=ap2$detail,pch=19,col=col2rgbt("black",1/5),
     xlab="Absolute Deviation Age",ylab="Standard Deviation Age")
plot(CV~PE,data=ap2$detail,pch=19,col=col2rgbt("black",1/5),
     xlab="Percent Error Age",ylab="Coefficient of Variation Age")
plot(median~mean,data=ap2$detail,pch=19,col=col2rgbt("black",1/5),
     xlab="Mean Age",ylab="Median Age")


droglenc/FSA documentation built on Aug. 30, 2023, 12:51 a.m.