FSA (version 0.8.0)

ageBias: Compute and view possible biases between paired sets of ages.

Description

Constructs age-agreement tables, statistical tests to detect bias, and plots to visualize potential bias in paired age assignments. Ages may be from, for example, two readers of the same structure, one reader at two times, two stuctures (e.g., scales, spines, otoliths), or a structure and known ages, or one structure and known ages.

Usage

ageBias(formula, data, ref.lab = tmp$Enames, nref.lab = tmp$Rname,
  method = stats::p.adjust.methods, sig.level = 0.05, min.n.CI = 3)

## S3 method for class 'ageBias':
summary(object, what = c("table", "symmetry", "Bowker",
  "EvansHoenig", "McNemar", "bias", "diff.bias", "n"), flip.table = FALSE,
  zero.print = "-", digits = 3, cont.corr = c("none", "Yates", "Edwards"),
  ...)

## S3 method for class 'ageBias':
plot(x, what = c("bias", "sunflower", "numbers"),
  difference = FALSE, xlab = x$ref.lab, ylab = x$nref.lab,
  show.n = TRUE, nYpos = 1.03, cex.n = 0.75, lwd = 1,
  show.pts = FALSE, pch.pts = 19, col.pts = grDevices::rgb(0, 0, 0,
  transparency), transparency = 1/10, pch.mean = 95, cex.mean = lwd,
  col.CI = "black", col.CIsig = "red", lwd.CI = lwd, sfrac = 0,
  show.range = FALSE, col.range = "gray", lwd.range = lwd,
  col.agree = "black", lwd.agree = lwd, lty.agree = 2,
  cex.numbers = 0.9, xlim = NULL, ylim = NULL,
  yaxt = graphics::par("yaxt"), xaxt = graphics::par("xaxt"), ...)

Arguments

formula

A formula of the form nrefvar~refvar, where nrefvar and refvar generically represent the variables that contain the paired nonreference and reference age assignments, respectively.

data

A data.frame that minimally contains the paired age assignments given in formula.

ref.lab

A string that contains a label for the reference age assignments.

nref.lab

A string that contains a label for the nonreference age assignments.

method

A string that indicates which method to use for adjusting p-values for multiple comparisons. See ?p.adjust.methods.

sig.level

A numeric value used to determine whether a p-value indicates a significant result. The confidence level used in plot is 100*(1-sig.level).

min.n.CI

A numeric value (default is 3) that indicates the smallest sample size for which a confidence interval should be computed.

what

A string that indicates what type of summary to print or plot to construct. See details.

flip.table

A logical that indicates whether the age-agreement table should be flipped (i.e., rows are reversed so that younger ages are at the bottom of the table). This makes the table more directly comparable to the age-bias plot.

zero.print

A string that indicates what should be printed in place of the zeroes on an age-agreement table. The default is to print a single dash.

digits

A numeric value that indicates the minimum number of digits to print when showing what="bias" or what="diff.bias" in summary.

cont.corr

A string that indicates the continuity correction method to be used with (only) McNemar test. If "none" (default) then no continuity correction is used, if "Yates" then 0.5 is used, and if "Edwards" then 1 is used.

x,object

An object of class ageBias, usually a result from ageBias.

difference

A logical that indicates whether or not the difference between the two age assignments should be used. See details.

xlab,ylab

A string that contains a label for the x-axis (reference) or y-axis (non-reference) age assignments, respectively.

show.n

A logical that indicates whether the sample sizes for each level of the x-axis variable is shown (=TRUE, default) or not (=FALSE).

nYpos

A numeric value that indicates the relative Y position of the sample size values when show.n=TRUE. For example, if nYpos=1.03 then the sample size values will be centered at 3 percent above the top end of the y-axis.

cex.n

A character expansion value for the size of the sample size values.

lwd

A single numeric value that can be used to control the separate lwd argument (e.g., lwd.CI, lwd.range).

show.pts

A logical that indicates whether to show the raw data points.

pch.pts

A numeric value that indicates the plotting character to be used when plotting the raw data points.

col.pts

A string or numeric value that indicates the color to be used for plotting the raw data points. The default is to use black with the transparency found in transparency.

transparency

A numeric value (between 0 and 1) that indicates the level of transparency to use for plotting the raw data points. If expressed as 1/x, then x points plotted on top of each other will represent the color in col.pts.

pch.mean

A numeric value that indicates the plotting character to be used for the mean values (i.e., center of confidence interval bars).

cex.mean

A character expansion value for the size of the mean symbol in pch.mean.

col.CI

A string or numeric value that indicates the color to be used for confidence interval bars that are considered non-significant.

col.CIsig

A string or numeric value that indicates the color to be used for confidence interval bars that are considered significant.

lwd.CI

A numeric value that indicates the line width for the confidence interval bars.

sfrac

A numeric value that controls the size of the ends of the confidence interval bars. See sfrac in plotCI of plotrix.

show.range

A logical that indicates whether to show vertical bars that represent the range of the data points.

col.range

A string or numeric value that indicates the color to be used for the interval representing the range of the data.

lwd.range

A numeric value that indicates the line width for the interval representing the range of the data.

col.agree

A string or numeric value that indicates the color for the 1:1 or zero (if difference) reference line.

lwd.agree

A numeric value that indicates the line width for the 1:1 or zero (if difference) reference line.

lty.agree

A numeric value that indicates the line type for the 1:1 or zero (if difference) reference line.

cex.numbers

A character expansion value for the size of the numbers plotted when what="numbers" is used.

xlim,ylim

A numeric vector of length 2 that contains the limits of the x-axis (reference ages) or y-axis (non-reference ages), respectively.

xaxt,yaxt

A string which specifies the x- and y-axis types. Specifying n suppresses plotting of the axis. See ?par.

...

Additional arguments for methods.

Value

• ageBias returns a list with the following items:
  • data A data.frame with the original paired age assignments and the difference between those assignements.
  • agree The age-agreement table.
  • bias A data.frame that contains the bias statistics.
  • bias.diff A data.frame that contains the bias statistics for the differences.
  • ref.lab A string that contains an optional label for the age assignments in the columns (reference) of the age-agreement table.
  • nref.lab A string that contains an optional label for the age assignments in the rows (non-reference) of the age-agreement table.
  The summary returns the result if what= contains one item, otherwise it returns nothing. Nothing is returned by plot, but see details for a description of the plot that is produced.

code

what="n"

dQuote

• sunflower plot
• petals

Testing

Tested all symmetry test results against results in Evans and Hoenig (2008), the McNemar and Evans-Hoenig results against results from compare2 in fishmethods, and all results using the AlewifeLH data set from FSAdata against results from http://www.nefsc.noaa.gov/fbp/age-prec/.

IFAR Chapter

4-Age Comparisons.

Details

Generally, one of the two age assessments will be identified as the reference set. In some cases this may be the true ages, the ages from the more experience reader, the ages from the first reading, or the ages from the structure gnerally thought to provide the most accurate results. In other cases, such as comparing two novice readers, the choice may be arbitrary. The reference ages will form the columns of the age-agreement table and will be the constant age used in the t-tests and age-bias plots (i.e., the x-axis). See further details below. The age-agreement table is constructed with what="table" in summary. The agreement table can be flipped, i.e., the rows in descending rather than ascending order, with flip.table=TRUE. By default, the tables are shown with zeroes replaced by dashes. This behavior can be changed with zero.print. Three statistical tests of symmetry for the age-agreement table can be computed with what= in summary. The unpooled or Bowker test as described in Hoenig et al. (1995) is constructed with what="Bowker", the semi-pooled or Evans-Hoenig test as described in Evans and Hoenig (1998) is constructed with what="EvansHoenig", and the pooled or McNemar test as described in Evans and Hoenig (1998) is constructed with what="McNemar". All three tests are run simultaneously with what="symmetry". An age-bias plot, as defined by Campana et al. (1995), is constructed with what="bias" (the default) in plot. The reference variable from the ageBias call is plotted on the x-axis. Plotted confidence intervals are computed for the mean of the non-reference ages at each age of the reference ages. The level of confidence is controlled by sig.level= given in the original ageBias call (i.e., confidence level is 100*(1-sig.level). Confidence intervals are only shown if the sample size is greater than the value in min.n.CI=. Confidence intervals plotted in red do not contain the reference age (see discussion of t-tests below). Vertical lines that connect the minimum to the maximum observed value of the y-axis variable at each age of the x-axis variable are plotted in grey if show.range=TRUE. Individual points are plotted if show.pts=TRUE The 1:1 (45 degree) agreement line is shown for comparative purposes. The sample sizes at each age of the x-axis variable are shown if show.n=TRUE (the default). The position of the sample sizes is controlled with nYpos=. An age-bias plot, as defined by Muir et al. (2008), is constructed as defined above but by also including difference=TRUE in Rplot

References

Ogle, D.H. 2015. http://derekogle.com/IFAR{Introductory Fisheries Analyses with R}. Chapman & Hall/CRC, Boca Raton, FL. Campana, S.E., M.C. Annand, and J.I. McMillan. 1995. http://www.bio.gc.ca/otoliths/documents/Campana%20et%20al%201995%20TAFS.pdf{Graphical and statistical methods for determining the consistency of age determinations.} Transactions of the American Fisheries Society 124:131-138. Evans, G.T. and J.M. Hoenig. 1998. Testing and viewing symmetry in contingency tables, with application to readers of fish ages. Biometrics 54:620-629. Hoenig, J.M., M.J. Morgan, and C.A. Brown. 1995. Analysing differences between two age determination methods by tests of symmetry. Canadian Journal of Fisheries And Aquatic Systems 52:364-368. McBride, R.S. 2015. Diagnosis of paired age agreement: A simulation approach of accuracy and precision effects. ICES Journal of Marine Science, XX:XXX-XXX. Muir, A.M., M.P. Ebener, J.X. He, and J.E. Johnson. 2008. http://www.tandfonline.com/doi/abs/10.1577/M06-160.1{A comparison of the scale and otolith methods of age estimation for lake whitefish in Lake Huron.} North American Journal of Fisheries Management 28:625-635.

See Also

See agePrecision for measures of precision between pairs of age assignments. See compare2 in fishmethods for similar functionality.

Examples

data(WhitefishLC)
ab1 <- ageBias(scaleC~otolithC,data=WhitefishLC,ref.lab="Otolith Age",nref.lab="Scale Age")
summary(ab1)
summary(ab1,what="symmetry")
summary(ab1,what="Bowker")
summary(ab1,what="EvansHoenig")
summary(ab1,what="McNemar")
summary(ab1,what="McNemar",cont.corr="Yates")
summary(ab1,what="bias")
summary(ab1,what="diff.bias")
summary(ab1,what="n")
summary(ab1,what=c("n","symmetry","table"))
# show the zeroes (rather than dashes)
summary(ab1,what="table",zero.print="0")
# flip the table -- ease of comparison to age-bias plot
summary(ab1,what="table",flip.table=TRUE)

## default plot
plot(ab1)
## demonstrates squaring up the axes
plot(ab1,ylim=c(-1,23),xlim=c(-1,23))
## plot with the data points shown
plot(ab1,show.pts=TRUE,transparency=1/8)
## plot with the range shown
plot(ab1,show.range=TRUE)
## plot with no difference in significance bar colors
plot(ab1,col.CIsig="black")
## plot of differences (note could use same modifications as shown above)
plot(ab1,difference=TRUE)
## sunflower plot
plot(ab1,what="sunflower")
plot(ab1,what="sunflower",difference=TRUE)
## "Numbers" plot
plot(ab1,what="number",col.agree="gray50")