Version: 0.2.7
Date: 2023-12-18
Title: Back-Calculation of Fish Length
Description: Helps fisheries scientists collect measurements from calcified structures and back-calculate estimated lengths at previous ages using standard procedures and models. This is intended to replace much of the functionality provided by the now out-dated 'fishBC' software (https://fisheries.org/bookstore/all-titles/software/70317/).
URL: https://fishr-core-team.github.io/RFishBC/
BugReports: https://github.com/fishR-Core-Team/RFishBC/issues
License: GPL-3
LazyData: true
Depends: R (≥ 3.2.0)
Imports: graphics, grDevices, cli, clisymbols, crayon, readbitmap, rlang, settings, stringr, tidyr, withr
Suggests: FSA, covr, pkgdown, testthat
Encoding: UTF-8
RoxygenNote: 7.2.3
NeedsCompilation: no
Packaged: 2023-12-19 23:22:31 UTC; derek
Author: Derek H. Ogle ORCID iD [aut, cre]
Maintainer: Derek H. Ogle <DerekOgle51@gmail.com>
Repository: CRAN
Date/Publication: 2023-12-20 08:30:02 UTC

RFishBC.

Description

The RFishBC package helps fisheries scientists collect growth data from calcified structures and back-calculate estimated lengths at previous ages. The package is intended to replace much of the functionality provided by the now out-date fishBC software. See the package webpage at [https://fishr-core-team.github.io/RFishBC/].

Author(s)

Maintainer: Derek H. Ogle DerekOgle51@gmail.com (ORCID)

See Also

Useful links:

Internal functions.

Description

Internal functions.

Usage

.onAttach(lib, pkg, ...)

See or set arguments for common RFishBC functions

Description

The digitizeRadii and showDigitizedImage functions have a variety of arguments that create great flexibility. Default values for these arguments can be seen with this function.

Additionally, a user may want to change a number of these arguments from their default values and use those new values in a large number of function calls (e.g., processing a larger number of structures with the same characteristics). Changing the argument values from the defaults during each function call is inefficient. Thus, default values for these arguments may be changed for the SESSION with this function.

Usage

RFBCoptions(reset = FALSE, ...)

Arguments

reset

A logical that will reset the values to their “factory-fresh” defaults if TRUE.

...

An arbitrary number of argument=value pairs where argument is one of the argument names and value is the new value for the argument. See details and examples.

Details

The arguments that can be set with this function are:

reading:

A single character string (or an object that can be coerced to a character) that identifies the reading for a structure. If the structure will be read multiple times, then this may be used to specify the particular reading. Defaults to NULL. Used in digitizeRadii.

description:

A single character string that contains a short (but more detailed than in reading) description for a reading of a structure. Defaults to NULL. Used in digitizeRadii.

suffix:

A single character string that will be added to the RData file name. If NULL and reading is not NULL, then this will be replaced with the value in reading. Defaults to NULL. Used in digitizeRadii.

edgeIsAnnulus:

A single logical that indicates whether the structure margin should be considered an annulus (TRUE) or not (FALSE). Use FALSE if growth between the last annulus and the structure margin is not a complete year's worth of growth (i.e., “plus-growth”). Defaults to NULL which means that the user must set this value. Used in digitizeRadii.

windowSize:

A single numeric used to set the size of the largest dimension for the window in which the structure image is opened. This size will be the width for wider images and the height for taller images. The other dimension will be set relative to this so that the image is displayed in its native aspect ratio. Defaults to 7 inches. Used in digitizeRadii and findScalingFactor.

deviceType:

A single character that identifies the type of graphic device in which the image will be shown. Defaults to deviceType="windows" which should be used with a Windows OS, but can be set to deviceType="X11" which should be used with a Mac OS.

popID:

A single logical that indicates if the fish ID dialog box (only on Windows if no ID is given in digitizeRadii) is populated with a guess at the fish ID. The guess is from using the pattern in IDpattern (see below) on the image file name sans the extension. This may be useful for when the image name contains the fish ID (and no other numbers). Defaults to TRUE. Used in digitizeRadii.

IDpattern:

A single regular expression that indicates how to extract a possible fish ID from an image file name. Defaults to selecting all characters after the last underscore in the image file name (sans extension). Used in digitizeRadii and getID.

IDreplace:

A string to replace the expression matched in IDpattern. Used in digitizeRadii and getID.

scalingFactor:

A single numeric used to convert measurements on the structure image to actual measurements on the structure. Measurements on the structure image will be multiplied by this value. Ignored if scaleBar=TRUE. Defaults to 1. Used in digitizeRadii.

scaleBar:

A single logical that indicates whether the user will be prompted to select the endpoints of a scale-bar on the structure image. If TRUE, then must also use scaleBarLength. If FALSE, then consider using scalingFactor. Defaults to FALSE. Used in digitizeRadii.

scaleBarLength:

A single numeric that represents the actual length of the scale-bar. Ignored if scaleBar=FALSE. Defaults to NULL; thus, the user must enter a value if scaleBar=TRUE. Used in digitizeRadii.

scaleBarUnits:

A single character that represents the units of measurement for the actual length of the scale-bar. Ignored if scaleBar=FALSE. Defaults to NULL; thus, the user must enter a value if scaleBar=TRUE. Used in digitizeRadii.

col.scaleBar:

The color of the scale-bar line if scalebar=TRUE. Defaults to "yellow". Used in digitizeRadii, showDigitizedImage, and findScalingFactor.

lwd.scaleBar:

The line width of the scale-bar line if scalebar=TRUE. Defaults to 2. Used in digitizeRadii, showDigitizedImage, and findScalingFactor.

showScaleBarLength:

A single logical that indicates whether the length of the scale-bar line should be shown on the image. Used in showDigitizedImage.

makeTransect:

A single logical that indicates whether a transect between the points selected at the structure center and margin should be made. Defaults to TRUE. Used in digitizeRadii.

snap2Transect:

A single logical that indicates whether the coordinates of the selected points that represent annuli should be moved to fall exactly on the transect from the structure center to margin. If TRUE then the points will be moved perpendicularly to the transect (and the original user-selected point will not be seen on the image). If FALSE then the points will be where the user selected them. Defaults to TRUE. Used in digitizeRadii.

col.transect:

The color of the transect line if makeTransect=TRUE in digitizeRadii. Defaults to "cyan".

lwd.transect:

The width of the transect line if makeTransect=TRUE in digitizeRadii. Defaults to 2.

connect:

A single logical that indicates whether the selected points should be connected with a line. Defaults to TRUE. Used in showDigitizedImage.

col.connect:

The color of the connecting line if connect=TRUE in showDigitizedImage. Defaults to "cyan".

lwd.connect:

The width of the connecting line if connect=TRUE in showDigitizedImage. Defaults to 2.

pch.sel:

The plotting character of points for selected annuli in digitizeRadii. Defaults to 20 (a small solid circle).

col.sel:

The color of points for selected annuli in digitizeRadii. Defaults to "yellow".

cex.sel:

The character expansion value of points for selected annuli in digitizeRadii. Defaults to 1.

pch.del:

The plotting character of points for DEselected annuli in digitizeRadii. Defaults to 13 (a circle with an X in it).

col.del:

The color of points for DEselected annuli in digitizeRadii. Defaults to "red".

pch.show:

The plotting character for points shown in showDigitizedImage. Defaults to 19 (a solid circle).

col.show:

The color of points shown in showDigitizedImage. Defaults to "yellow".

cex.show:

The character expansion value of points shown in showDigitizedImage. Defaults to 1.

showInfo:

A single logical that indicates whether the ID information should be shown on the image in digitizeRadii. Defaults to TRUE.

pos.info:

A single character that indicates where the ID information should be placed when showInfo=TRUE. See legend for position choices. Defaults to "topleft". Used in digitizeRadii.

cex.info:

The character expansion for the ID information when showInfo=TRUE. Defaults to 1.2 Used in digitizeRadii.

col.info:

The color for the ID information when showInfo=TRUE. Defaults to "yellow". Used in digitizeRadii.

showAnnuliLabels:

A single logical that indicates whether annulus labels should be shown on the image from showDigitizedImage. Defaults to TRUE, but is ignored if more than one set of annuli will be plotted.

annuliLabels:

A numeric vector that indicates the numbers for which annuli should be labeled when showAnnuliLabels=TRUE. Defaults to NULL which indicates that all annuli should be labeled. Used in showDigitizedImage.

col.ann:

The color of the annuli number text when showAnnuliLabels=TRUE in showDigitizedImage. Defaults to "yellow".

cex.ann:

The character expansion value of the annuli number text when showAnnuliLabels=TRUE in showDigitizedImage. Defaults to 1.2.

offset.ann:

A numeric value that specifies the offset (in proportions of a character width) of the annuli labels from the point when showAnnuliLabels=TRUE in showDigitizedImage. Defaults to 0.5.

addNote:

A logical for whether the user can add or will be prompted to add a special note to the RData file when using digitizeRadii. Example notes may indicate that the image was poor, some annuli were suspect, or the image should be re-read.

The user will likely only use this function to change arguments at the start of a script, so that those values will be used throughout the analyses in the script. If the values for the arguments need to be changed in any instance of digitizeRadii or showDigitizedImage, then it is more efficient to change the argument within the call to those functions.

The argument values can be reset to the original defaults by using reset=TRUE. See examples.

Value

None, but the list in RFBCoptions will be modified.

Author(s)

Derek H. Ogle, DerekOgle51@gmail.com

See Also

digitizeRadii and showDigitizedImage

Examples

## Show all options
RFBCoptions()

## Show how to see and set one option
RFBCoptions()$makeTransect
RFBCoptions(makeTransect=FALSE)
RFBCoptions()$makeTransect
RFBCoptions(reset=TRUE)
RFBCoptions()$makeTransect

## Multiple options can also be set at once
RFBCoptions(pch.show=3,col.show="blue",cex.show=3)

Fish-specific data for West Bearskin Lake Smallmouth Bass.

Description

Fish-specific data for West Bearskin Lake Smallmouth Bass.

Usage

SMBassWB1

Format

A data frame with 445 rows and 10 variables:

id

An identification number unique to each fish.

species

Fish species (all are “SMB”).

lake

Lake (all are “WB”).

gear

Capture gear (E=electrofishing, T=trapnet).

yearcap

Year of capture.

lencap

Total length-at-capture (mm)

Source

Originally from SMBassWB in FSA. Rearranged to demonstrate functions in this package.

See Also

SMBassWB2

Radial measurements for for West Bearskin Lake Smallmouth Bass.

Description

Radial measurement data for West Bearskin Lake Smallmouth Bass. Data are in “wide” or one-fish-per-line (with radial measurements in separate variables) format.

Usage

SMBassWB2

Format

A data frame with 181 rows and 13 variables:

id

An identification number unique to each fish.

reading

A reading specific identifier (all are “DHO”).

agecap

Age-at-capture.

radcap

Total structure radius at capture (magnified mm).

rad1

Structure radius to annulus 1.

rad2

Structure radius to annulus 2.

rad3

Structure radius to annulus 3.

rad4

Structure radius to annulus 4.

rad5

Structure radius to annulus 5.

rad6

Structure radius to annulus 6.

rad7

Structure radius to annulus 7.

rad8

Structure radius to annulus 8.

rad9

Structure radius to annulus 9.

Source

Originally from SMBassWB in FSA. Rearranged to demonstrate functions in this package.

See Also

SMBassWB1

Standard intercepts for Fraser-Lee model by species.

Description

Standard intercepts (in mm) for Fraser-Lee model for all species for which the standard has been defined.

Usage

StdIntLit

Format

A data frame with 1 rows and 3 variables:

species

Fish species.

a

Standard intercept value (in mm).

source

Source of the standard.

References

Beck, H.D., D.W. Willis, and J.M. Francis. 1997. A proposed standard intercept for the White Bass body length-scale relationship. North American Journal of Fisheries Management 32:239-248.

Carlander, K.D. 1982. Standard intercepts for calculating lengths from scale measurements for some centrarchid and percid fishes. Transactions of the American Fisheries Society 111:333-336.

See Also

aStandard

Finds standard intercept (a) for Fraser-Lee back-calculation model for a particular species.

Description

Finds standard intercept (a; mm) for Fraser-Lee back-calculation model for a particular species for all species for which a value of a has been defined.

Usage

aStandard(species)

Arguments

species

A string that contains the species name for which to find teh standard intercept value.

Value

A single value from StdIntLit that is the standard intercept value (a; mm) for the species provided in species.

Author(s)

Derek H. Ogle, DerekOgle51@gmail.com

See Also

StdIntLit

Examples

aStandard("Bluegill")
aStandard("Walleye")

Add a note to an existing RData file

Description

Use this to add a note to a saved R data file that was created with digitizeRadii. Can be used to flag the reading for some reason.

Usage

addNote(nms, note)

Arguments

nms

A string that indicates the R data file created with digitizeRadii (in the current directory) to which the note should be added.

note

The note (as a string) to be added to the R data file. If missing the user will be provided a dialog box in which to enter the note.

Details

A detailed description of its use is in the "Other Features" vignette on the RFishBC website.

Value

None, but the note object in the R Data file(s) given in nms will be modified.

Author(s)

Derek H. Ogle, DerekOgle51@gmail.com

Examples

## See the link to the extensive documentation in the Details.

Add total radius-at-capture to wide increments data.

Description

Add a total radius-at-capture variable to a data.frame that contains one-fish-per-line (i.e., “wide” format) increments data.

Usage

addRadCap(df, in.pre = NULL, in.var = NULL, var.name = "radcap")

Arguments

df

A data.frame that contains the growth increment data in one-fish-per-line (i.e., “wide”) format.

in.pre

A string that represents the common part of the increment variable names. See details.

in.var

A vector of variables in df that do not change. See details.

var.name

A string that indicates the name for the new total radius-at-capture variable in the new data.frame. Defaults to “radcap”.

Details

The columns that contain the original increment data can specified in a variety of ways. First, if all columns begin with the same prefix (and no other columns contain that prefix), then the prefix string may be given to in.pre=. Second, a sequence of column numbers may be given to in.var= with #:# (if the columns are contiguous) or as a vector (if the columns are not contiguous). Third, a vector of column names may be given to in.var=. Note that one, but not both, of in.var= or in.pre= must be specified by the user.

Note that the computed total radius-at-capture will only be the actual total radius-at-capture if all growth, including “plus-growth” in the current season, is recorded in the input data frame.

Value

A data.frame of increments in one-fish-per-line (i.e., “wide”) format with the total radius-at-capture appended in a variable named as given in var.name.

Author(s)

Derek H. Ogle, DerekOgle51@gmail.com

See Also

See gConvert for related functionality.

Examples

## Get data with radial measurements
data(SMBassWB,package="FSA")
head(SMBassWB)

## convert radial measurements to increments
SMBi1 <- gConvert(SMBassWB,in.pre="anu",out.type="inc")
head(SMBi1)

## add the radius-at-capture measurement
SMBi1a <- addRadCap(SMBi1,in.pre="inc",var.name="radcap2")
head(SMBi1a)

Back-calculate length at previous ages from standard data format.

Description

Back-calculates length at previous ages from a data.frame that was primarily created from combineData and digitizeRadii. One of several back-calculation models, described in bcFuns and Vigliola and Meekan (2009), can be used. Parameter estimates from various models of fish length on structure radius or structure radius on fish length are computed internally and used in the back-calculations. This function is intended to make back-calculation of fish length at previous ages as streamlined as possible.

Usage

backCalc(
  dat,
  lencap,
  BCM,
  inFormat,
  outFormat = inFormat,
  a = NULL,
  L0p = NULL,
  R0p = NULL,
  L0 = NULL,
  R0 = NULL,
  deletePlusGrowth = TRUE,
  digits = getOption("digits")
)

Arguments

dat

A data.frame created with combineData that MUST have at least the length-at-capture appended as a variable. See Details.

lencap

The unquoted name of the length-at-capture variable.

BCM

A single numeric between 1 and 22 or a string that indicates which model to use (based on numbers and names in Vigliola and Meekan (2009)). See Details in bcFuns for the list of available models.

inFormat

The format of the data in dat. The two choices are "long" with one radial measurement per line (and all radial measurements for a fish in separate rows) and "wide" with one fish per line (and all radial measurements in separate variables). Defaults to "long".

outFormat

The format for the returned data.frame. Choices are as described for inFormat. Defaults to be the same as inFormat.

a

The fish length when the structure first forms as used in the Fraser-Lee model (i.e., BCM=1 or BCM="FRALE"). If this is missing then a will be estimated as the intercept from the fish length on structure radius linear regression.

L0p

The length at the “Biological Intercept” point. Only used in the “Biological Intercept” (BCM=3), “Watanabe and Kuroki” (BCM=12), and “Modified Fry” (BCM=14) models.

R0p

The structure radius at the “Biological Intercept” point. Only used in the “Biological Intercept” (BCM=3), “Watanabe and Kuroki” (BCM=12), and “Modified Fry” (BCM=14) models.

L0

The length at the arbitrarily selected point in the “Fry” (BCM=13) model.

R0

The structure radius at the arbitrarily selected point in the “Fry” (BCM=13) model.

deletePlusGrowth

A logical that indicates whether the radial measurement that corresponds to “plus-growth” on the structure should be deleted (TRUE; Default) or not (FALSE).

digits

Number of digits to which the back-calculated lengths should be rounded. Defaults to the value returned by getOptions("digits"), which is generally 7 digits.

Value

A data.frame similar to dat but with the radial measurements replaced by back-calculated lengths at previous ages.

Author(s)

Derek H. Ogle, DerekOgle51@gmail.com

Examples

## Get some data
data(SMBassWB1,package="RFishBC") ## fish data
data(SMBassWB2,package="RFishBC") ## rad data

# Simplify to 3 fish so we can see what is going on
tmp1 <- subset(SMBassWB1,id %in% c(377,378,379))
tmp2 <- subset(SMBassWB2,id %in% c(377,378,379))

# Combine data frames to form a wide data frame (i.e., a left join)
wdat1 <- merge(tmp1,tmp2,by="id",all.x=TRUE)
wdat1
 
# Make a long data frame for examples (remove annuli with NA rads)
ldat1 <- tidyr::pivot_longer(wdat1,rad1:rad9,names_to="ann",names_prefix="rad",
                             values_to="rad")
ldat1 <- subset(ldat1,!is.na(rad))
ldat1 <- as.data.frame(ldat1)
ldat1

## Back-calculate using Dahl-Lea method
# wide in and wide out
wwres1 <- backCalc(wdat1,lencap,BCM="DALE",inFormat="wide",digits=0)
wwres1

# wide in and long out
wlres1 <- backCalc(wdat1,lencap,BCM="DALE",inFormat="wide",
                   outFormat="long",digits=0)
wlres1

# long in and wide out
lwres1 <- backCalc(ldat1,lencap,BCM="DALE",inFormat="long",digits=0)
lwres1

# wide in and long out
llres1 <- backCalc(ldat1,lencap,BCM="DALE",inFormat="long",
                   outFormat="long",digits=0)
llres1

## Situation with no radial measurements for some fish
# Create an extra fish with length (tmp1) but no rad
tmp1a <- rbind(tmp1,
               data.frame(id=999,
               species="SMB",lake="WB",gear="E",
               yearcap=1990,lencap=225))
wdat2 <- merge(tmp1a,tmp2,by="id",all.x=TRUE)
wdat2
                
# wide in and wide out
wwres2 <- backCalc(wdat2,lencap,BCM="DALE",inFormat="wide",digits=0)
wwres2

Creates a function for a specific model.

Description

Creates a function for a specific model based on definitions in Vigliola and Meekan (2009).

Usage

bcFuns(BCM)

Arguments

BCM

A single numeric between 1 and 22 or a string that indicates which model to use (based on numbers and names in Vigliola and Meekan (2009)).

Details

The following models, based on definitions with abbreviations and model numbers from Vigliola and Meekan (2009), are supported.

Abbreviation Number Model
DALE 1 Dahl-Lea
FRALE 2 Fraser-Lee
BI, LBI 3 (Linear) Biological Intercept
BPH, LBPH 4 (Linear) Body Proportional Hypothesis
TVG 5 Time-Varying Growth
SPH, LSPH 6 (Linear) Scale Proportional Hypothesis
AE, AESPH 7 (Age Effect) Scale Proportional Hypothesis
AEBPH 8 (Age Effect) Body Proportional Hypothesis
MONA 9 Monastyrsky
MONA-BPH 10 Monastyrsky Body Proportional Hypothesis
MONA-SPH 11 Monastyrsky Scale Proportional Hypothesis
WAKU 12 Watanabe and Kuroki
FRY 13 Fry
MF, ABI 14 Modified Fry, Allometric Biological Intercept
FRY-BPH, ABPH 15 Fry, Allometric Body Proportional Hypothesis
FRY-SPH, ASPH 16 Fry, Allometric Scale Proportional Hypothesis
QBPH 17 Quadratic Body Proportional Hypothesis
QSPH 18 Quadratic Scale Proportional Hypothesis
PBPH 19 Polynomial Body Proportional Hypothesis
PSPH 20 Polynomial Scale Proportional Hypothesis
EBPH 21 Exponential Body Proportional Hypothesis
ESPH 22 Exponential Scale Proportional Hypothesis

Value

A function that can be used to predict length at previous age (Li) given length-at-capture (Lcap), hard-part radius-at-age i (Ri), and hard-part radius-at-capture (Rcap). In addition, some functions/models may require the previous age (agei) and the age-at-capture (agec), certain parameters related to the biological intercept (R0p & L0p), or certain parameters estimated from various regression models (a,b,c,A,B,C). See source for more information.

IFAR Supplement

https://derekogle.com/IFAR/supplements/backcalculation.html

Author(s)

Derek H. Ogle, DerekOgle51@gmail.com

References

Vigliola, L. and M.G. Meekan. 2009. The back-calculation of fish growth from otoliths. pp. 174-211. in B.S. Green et al. (editors). Tropical Fish Otoliths: Information for Assessment, Management and Ecology. Review: Methods and Technologies in Fish Biology and Fisheries 11. Springer. [Was (is?) available from https://www.researchgate.net/publication/226394736_The_Back-Calculation_of_Fish_Growth_From_Otoliths.]

Examples

## Simple Examples
( bcm1 <- bcFuns(1) )
bcm1(20,10,40)

## Example with dummy length-at-cap, radii-at-cap, and radii-at-age
lencap <- c(100,100,100,150,150)
radcap <- c(20,20,20,30,30)
rad    <- c( 5,10,15,15,25)
bcm1(lencap,rad,radcap)

( bcm2 <- bcFuns("FRALE") )
bcm2(lencap,rad,radcap,2)  # demonstrated with a=2

Combines radii data from multiple files into one data.frame

Description

Combines radial measurements made on calcified structures and saved to an R data file with digitizeRadii into a single data.frame that can then be post-processed (e.g., back-calculate length at a previous age).

Usage

combineData(
  nms,
  formatOut = c("long", "wide"),
  typeOut = c("radii", "increments"),
  deletePlusGrowth = TRUE
)

Arguments

nms

A string (or vector of strings) that indicates the R data file(s) created with digitizeRadii. If missing the user will be provided a dialog box from which to choose the file(s). The file(s) must be in the current working directory (see getwd result). May also be a single RFishBC object created with digitizeRadii.

formatOut

A string that indicates the output format for the combined data. The "wide" (DEFAULT) format has one-radius-per-line (i.e., each radial measurement for a fish in on a separate row), whereas the "long" format has one-fish-per-line (i.e., each radial measurement for a fish is in a separate column).

typeOut

A string that indicated output type for the combined data. The "radii" (DEFAULT) type will output the radial measurements, whereas the "increments" will output incremental measurements.

deletePlusGrowth

A logical that indicates whether the radial measurement that corresponds to “plus-growth” should be deleted from the returned data.frame (TRUE; DEFAULT) or not (FALSE).

Details

A detailed description of its use is in this vignette on the RFishBC website. The list of R data file names may be efficiently created with listFiles as described in that vignette. The R data file names may also be selected from a dialog box if using Windows.

Value

A data.frame that contains the radii data created with digitizeRadii for all files given in nms.

Author(s)

Derek H. Ogle, DerekOgle51@gmail.com

Examples

## See the link to the extensive documentation in the Details.

Collect radial measurements from a calcified structure by interactively selecting annuli

Description

The user interactively select points on an image of a calcified structure. When finished, radial measurements (from the structure focus to the selected points) are calculated (either with arbitrary units or actual units if a scale-bar is included on the image) and written to an external file for later use.

Usage

digitizeRadii(
  img,
  id,
  reading,
  suffix,
  description,
  edgeIsAnnulus,
  popID,
  IDpattern,
  IDreplace,
  windowSize,
  deviceType,
  closeWindow,
  scaleBar,
  scaleBarLength,
  scaleBarUnits,
  col.scaleBar,
  lwd.scaleBar,
  scalingFactor,
  makeTransect,
  snap2Transect,
  col.transect,
  lwd.transect,
  pch.sel,
  col.sel,
  cex.sel,
  pch.del,
  col.del,
  showInfo,
  pos.info,
  cex.info,
  col.info,
  addNote,
  note
)

Arguments

img

A vector of strings that indicates the image (must be PNG, JPG, BMP, or TIFF) to be loaded and plotted. By default the user will be provided a dialog box from which to choose the file(s). Alternatively the user can supply the name(s) of the file(s). Either way the file(s) must be in the current working directory.

id

A vector of unique identifiers for the fish or structure(s) being examined. Will be coerced to a character. If length of img is greater than 1, then the length of id must be the same. If missing then you will be prompted to enter a value.

reading

See details in RFBCoptions.

suffix

See details in RFBCoptions.

description

See details in RFBCoptions.

edgeIsAnnulus

See details in RFBCoptions.

popID

See details in RFBCoptions.

IDpattern

See details in RFBCoptions.

IDreplace

See details in RFBCoptions.

windowSize

See details in RFBCoptions.

deviceType

See details in RFBCoptions.

closeWindow

See details in RFBCoptions.

scaleBar

See details in RFBCoptions.

scaleBarLength

See details in RFBCoptions.

scaleBarUnits

See details in RFBCoptions.

col.scaleBar

See details in RFBCoptions.

lwd.scaleBar

See details in RFBCoptions.

scalingFactor

See details in RFBCoptions.

makeTransect

See details in RFBCoptions.

snap2Transect

See details in RFBCoptions.

col.transect

See details in RFBCoptions.

lwd.transect

See details in RFBCoptions.

pch.sel

See details in RFBCoptions.

col.sel

See details in RFBCoptions.

cex.sel

See details in RFBCoptions.

pch.del

See details in RFBCoptions.

col.del

See details in RFBCoptions.

showInfo

See details in RFBCoptions.

pos.info

See details in RFBCoptions.

cex.info

See details in RFBCoptions.

col.info

See details in RFBCoptions.

addNote

See details in RFBCoptions.

note

A specific note about this reading (e.g., a note that the image was poor, some annulus were suspect, or the image should be re-read.). If missing then the user will be prompted to include a note if addNote=TRUE.

Details

This function requires interaction from the user. A detailed description of its use is in the vignettes on the RFishBC website.

Value

NULL if more than one file was given in img; otherwise (i.e., only one file was given) a list with the following:

image:

The full filename given in img.

datanm:

The R data filename.

description:

The description given in description.

edgeIsAnnulus:

The logical given in edgeIsAnnulus that identified whether the structure edge/margin should be considered as an annulus.

snap2Transect:

The logical from snap2Transect that identified whether the selected points were “snapped” to the transect or not.

scalingFactor:

A single numeric used to convert measurements on the structure image to actual measurements on the structure. Measurements on the structure image were multiplied by this value.

sfSource:

A character string that identifies whether the scaling factor was "Provided" through the scalingFactor argument or derived from a "scaleBar".

sbPts:

A data.frame of x and y coordinates for the endpoints of the scale-bar if the scaling factor was derived from a scale-bar.

sbLength:

A single numeric that is the known (actual) length of the scale-bar if the scaling factor was derived from a scale-bar.

sbUnits:

A single character that is the units of measurement for the known (actual) length of the scale-bar if the scaling factor was derived from a scale-bar.

slpTransect:

The slope of the transect.

intTransect:

The intercept of the transect.

slpPerpTransect:

The slope of the line perpendicular to the transect.

windowSize:

A numeric of length two that contains the width and height of the window used to display the structure image. One of these units was set by the given windowSize value.

pixW2H:

The ratio of pixel width to height. This is used to correct measurements for when an image is not square.

pts:

A data.frame that contains the x and y coordinates on the image for the selected annuli. These points may have been “snapped” to the transect if snap2Transect==TRUE.

radii:

A data.frame that contains the unique id, the reading code, the age-at-capture in agecap, the annulus number in ann, the radial measurements in rad, and the radial measurement at capture in radcap.

note:

A string that contains a note about the reading (e.g., a note that the image was poor, some annulus were suspect, or the image should be re-read.)

Author(s)

Derek H. Ogle, DerekOgle51@gmail.com.

See Also

showDigitizedImage and RFBCoptions.

Examples

## None because this requires interaction from the user.
## See the link to the extensive documentation in the Details.

Returns the notes from the chosen R Data files

Description

Returns the notes from the chosen R data files created with digitizeRadii.

Usage

findNotes(nms)

Arguments

nms

A string (or vector of strings) that indicates the R data file(s) created with digitizeRadii. If missing the user will be provided a dialog box from which to choose the file(s). The file(s) must be in the current working directory (see getwd result). May also be a single RFishBC object created with digitizeRadii.

Details

A detailed description of its use is in the "Other Features" vignette on the RFishBC website.

Value

A data.frame that contains the id, reading, and notes from the chosen R Data files.

Author(s)

Derek H. Ogle, DerekOgle51@gmail.com

Examples

## See the link to the extensive documentation in the Details.

Find scaling factor from object of known length

Description

This computes a scaling factor (i.e., a multiplier that is used to convert image lengths to actual lengths) from user selected endpoints of an object of known length on the image given in img and the actual known length given in knownLength. See Details.

Usage

findScalingFactor(
  img,
  knownLength,
  windowSize,
  deviceType,
  closeWindow,
  col.scaleBar,
  lwd.scaleBar,
  pch.sel,
  col.sel,
  cex.sel,
  pch.del,
  col.del
)

Arguments

img

A string that indicates the image (must be PNG, JPG, BMP, or TIFF) to be loaded and plotted. By default the user will be provided a dialog box from which to choose the file. Alternatively the user can supply the name of the file (will look for this file in the current working directory).

knownLength

See details in RFBCoptions.

windowSize

See details in RFBCoptions.

deviceType

See details in RFBCoptions.

closeWindow

See details in RFBCoptions.

col.scaleBar

See details in RFBCoptions.

lwd.scaleBar

See details in RFBCoptions.

pch.sel

See details in RFBCoptions.

col.sel

See details in RFBCoptions.

cex.sel

See details in RFBCoptions.

pch.del

See details in RFBCoptions.

col.del

See details in RFBCoptions.

Details

To apply the scaling factor determined with this function to images opened in digitizeRadii is is important that the images were created with the EXACT same magnification, are saved with the EXACT same dimensions (and aspect ratio), and the EXACT same value for windowSize= is used.

Value

A single numeric that is the scaling factor (a multiplier that is used to convert image lengths to actual lengths).

Author(s)

Derek H. Ogle, DerekOgle51@gmail.com

Examples

## None yet

Converts between types of measurements.

Description

Converts one-fish-per-line (i.e., “wide”) format growth data from radial to incremental or incremental to radial measurements.

Usage

gConvert(
  df,
  in.pre = NULL,
  in.var = NULL,
  out.type = c("inc", "rad"),
  out.pre = out.type
)

Arguments

df

A data.frame that contains the growth measurement data in one-fish-per-line (i.e., “wide”) format.

in.pre

A string that indicates the prefix for all variable names in the input data.frame that contain the measurements from the calcified structures. See details.

in.var

A vector of column numbers or variable names in the input data.frame that contain the measurements from the calcified structures. See details.

out.type

A string that identifies the output format data type (i.e., the format to convert to). If "inc" (the default) the output data frame will be incremental measurements. If "rad" the output data frame will be radial measurements.

out.pre

A string that indicates the prefix to use for the newly computed measurements in the output data frame. Defaults to the same string as out.type.

Details

The data must be in one-fish-per-line (i.e., “wide”) format where each row contains all information (including all measurements from the calcified structure) for an individual fish. It is assumed that the input data.frame is of the opposite data type given in out.type (i.e., that a conversion is needed). It does not check to see if this is true.

The columns that contain the original measurement data can specified in a variety of ways. First, if all columns begin with the same prefix (and no other columns contain that prefix), then the prefix string may be given to in.pre=. Second, a sequence of column numbers may be given to in.var= with the #:# (if the columns are contiguous) or as a vector (if the columns are not contiguous). Third, a vector of column names may be given to in.var=. Note that one, but not both, of in.var= or in.pre= must be specified by the user.

The newly computed data will be labeled with a prefix the same as out.type= (i.e., "rad" or "inc") unless out.pre= is set by the user. For example, if the data are converted to radial measurements, then the output variables will be “rad1”, “rad2”, etc. unless out.pre= was changed from the default. This function assumes that the measurements start with age-1.

Value

A data.frame with all columns, except for those defined by in.pre or in.var, from the df retained as the left-most columns and the original data in the in.var columns converted to the out.type type as the remaining columns.

Author(s)

Derek H. Ogle, DerekOgle51@gmail.com

See Also

See addRadCap for related functionality.

Examples

## Get data with radial measurements
data(SMBassWB,package="FSA")
head(SMBassWB)

## Use in.pre= to convert to increments
SMBi1 <- gConvert(SMBassWB,in.pre="anu",out.type="inc")
head(SMBi1)

## Use in.var= with column names to convert to increments
SMBi2 <- gConvert(SMBassWB,in.var=c("anu1","anu2","anu3","anu4",
                                    "anu5","anu6","anu7","anu8",
                                    "anu9","anu10","anu11","anu12"),
                           out.type="inc")
head(SMBi2)

## Use in.var with column numbers to convert to increments
SMBi3 <- gConvert(SMBassWB,in.var=8:19,out.type="inc")
head(SMBi3)

## Convert back to radial measurements
SMBr1 <- gConvert(SMBi1,in.pre="inc",out.type="rad")
head(SMBr1)

Extracts a fish identification from a vector of image file names

Description

This returns a vector of fish identification values from a vector of image file names.

Usage

getID(x, IDpattern, IDreplace, ...)

Arguments

x

A charachter vector of image file names.

IDpattern

A regular expression used to extract the fish identification value from the image file names in x. Defaults to extracting all values after the last underscore in the image file name (sans extension). Can be set with RFBCoptions.

IDreplace

A string to replace the expression matched in IDpattern. Can be set with RFBCoptions.

...

Parameters to be given to sub.

Details

By default it is assumed that the ID value follows an underscore at the end/tail of image file name (sans extension). Other patterns can be used by giving a suitable regular expression to IDpattern and possibly a replacement (usually a group identifier such as “\1”) in IDreplace. You may find the webpage at spannbaueradam.shinyapps.io/r_regex_tester/ useful for identifying the necessary regular expression pattern for your situation.

If the pattern in IDpattern does not exist in each element of x then an error will be returned. In other words, the fish identification value must be in the same “place” (based on IDpattern) in EVERY image filename.

If the vector of returned IDs contains any duplicated values then a warning will be issued.

The list of image file names in a given folder/directory may be obtained with listFiles.

Value

Character vector.

Author(s)

Derek H. Ogle, DerekOgle51@gmail.com

See Also

listFiles and digitizeRadii.

Examples

## These are possible vectors of image file names with the fish ID after
##   the last underscore ... which is the default behavior
ex1 <- c("Scale_1.jpg","Scale_2.jpg")
ex2 <- c("Kiyi_472.bmp","Kiy_567.jpg")
ex3 <- c("PWF_MI345.tiff","PWF_WI567.tiff")
ex4 <- c("LKT_oto_23.jpg","LKT_finray_34.jpg")

## These are extracted fish IDs
getID(ex1)
getID(ex2)
getID(ex3)
getID(ex4)

## These are possible vectors of image file names with the fish ID NOT after
##   the last underscore. This requires judicious use of IDpattern= and
##   IDreplace= (similar to pattern= and replacement- as used in sub()).

### fish ID at the beginning of the name
ex5 <- c("1_Scale.jpg","2_Scale.jpg")
getID(ex5,IDpattern="\\_.*")

### fish ID between two underscores (might be used if multiple images for one ID)
ex6 <- c("DWS_100_1.jpg","DWS_101_2,jpg")
getID(ex6,IDpattern=".*\\_(.+?)\\_.*",IDreplace="\\1")
ex7 <- c("DWS_MI100_1.jpg","DWS_MI100_2,jpg")
getID(ex7,IDpattern=".*\\_(.+?)\\_.*",IDreplace="\\1")

### Will be warned if the returned IDs are not unique
## Not run: 
ex8 <- c("Ruffe_456.jpg","Ruffe_456.jpg","Ruffe_567.jpg")
getID(ex8)

## End(Not run)

List files with a specific extension in a folder/directory

Description

This returns a vector with all file names with the ext extension in the path folder/directory. In RfishBC this is used primarily to create a list of image file names for use in digitizeRadii or RData file names created with digitizeRadii and to be given to combineData.

Usage

listFiles(ext, other = NULL, path = ".", ignore.case = TRUE, ...)

Arguments

ext

A single string that contains the file extension pattern to match.

other

Other strings to match in file names that were already matched by the extension in ext.

path

A single string that contains the full path name for the folder/directory for which to list files. Defaults to the current working directory (see getwd result).

ignore.case

A logical for whether pattern matching should be case sensitive (=FALSE) or not (TRUE; DEFAULT).

...

Parameters to be given to list.files.

Details

An example of using this function is in this vignette and this vignette on the RFishBC website.

Value

Character vector.

Author(s)

Derek H. Ogle, DerekOgle51@gmail.com

See Also

digitizeRadii and combineData; and list.files in base R.

Examples

## See the link to the extensive documentation in the Details.

Save to a file the structure image saved in an R data file with selected points.

Description

Save to a file the structure image with points to represent annuli that were saved to an R data file using digitizeRadii. This allows the user to create a file of their selections that could be printed.

Usage

saveDigitizedImage(
  nms,
  fileType = c("jpeg", "png", "pdf"),
  suffix = "_marked",
  res = 72,
  pch.show,
  col.show,
  cex.show,
  connect,
  col.connect,
  lwd.connect,
  col.scaleBar,
  lwd.scaleBar,
  showScaleBarLength,
  cex.scaleBar,
  showAnnuliLabels,
  annuliLabels,
  col.ann,
  cex.ann,
  offset.ann
)

Arguments

nms

A string (or vector of strings) that indicates the R data file(s) created with digitizeRadii. If missing the user will be provided a dialog box from which to choose the file(s). The file(s) must be in the current working directory (see getwd result). May also be a single RFishBC object created with digitizeRadii.

fileType

Choose file type to be jpeg, png, or pdf.

suffix

A string that will be appended to each saved filename prior to the extension. Defaults to “_marked”.

res

Device (for jpeg and png) resolution. Defaults to 72.

pch.show

See details in RFBCoptions.

col.show

See details in RFBCoptions.

cex.show

See details in RFBCoptions.

connect

See details in RFBCoptions.

col.connect

See details in RFBCoptions.

lwd.connect

See details in RFBCoptions.

col.scaleBar

See details in RFBCoptions.

lwd.scaleBar

See details in RFBCoptions.

showScaleBarLength

See details in RFBCoptions.

cex.scaleBar

See details in RFBCoptions.

showAnnuliLabels

See details in RFBCoptions.

annuliLabels

See details in RFBCoptions.

col.ann

See details in RFBCoptions.

cex.ann

See details in RFBCoptions.

offset.ann

See details in RFBCoptions.

Details

None.

Value

None, but a file is created in the working directory.

Author(s)

Derek H. Ogle, DerekOgle51@gmail.com

See Also

showDigitizedImage, digitizeRadii, RFBCoptions, and jpeg, png, and pdf.

Examples

## None because this requires interaction from the user.
## See the link to the extensive documentation in the Details.

Show points selected on a structure image and saved in an R data file

Description

Show points selected on a structure image to represent annuli that were saved to an R data file using digitizeRadii. This allows the user to reexamine the selected points or overlay selected points from multiple readings of the structure.

Usage

showDigitizedImage(
  nms,
  deviceType,
  pch.show,
  col.show,
  cex.show,
  connect,
  col.connect,
  lwd.connect,
  col.scaleBar,
  lwd.scaleBar,
  showScaleBarLength,
  cex.scaleBar,
  showAnnuliLabels,
  annuliLabels,
  col.ann,
  cex.ann,
  offset.ann
)

Arguments

nms

A string (or vector of strings) that indicates the R data file(s) created with digitizeRadii. If missing the user will be provided a dialog box from which to choose the file(s). The file(s) must be in the current working directory (see getwd result). May also be a single RFishBC object created with digitizeRadii.

deviceType

See details in RFBCoptions.

pch.show

See details in RFBCoptions.

col.show

See details in RFBCoptions.

cex.show

See details in RFBCoptions.

connect

See details in RFBCoptions.

col.connect

See details in RFBCoptions.

lwd.connect

See details in RFBCoptions.

col.scaleBar

See details in RFBCoptions.

lwd.scaleBar

See details in RFBCoptions.

showScaleBarLength

See details in RFBCoptions.

cex.scaleBar

See details in RFBCoptions.

showAnnuliLabels

See details in RFBCoptions.

annuliLabels

See details in RFBCoptions.

col.ann

See details in RFBCoptions.

cex.ann

See details in RFBCoptions.

offset.ann

See details in RFBCoptions.

Details

This function requires interaction from the user. A detailed description of its use is in this vignette on the RFishBC website.

Value

A list that contains the size of the window in windowSize and the pixel width to height ratio in pixW2H. In addition, an image is plotted with, at least, the selected points.

Author(s)

Derek H. Ogle, DerekOgle51@gmail.com

See Also

digitizeRadii and RFBCoptions.

Examples

## None because this requires interaction from the user.
## See the link to the extensive documentation in the Details.