An example data file

Description

The file's columns are:

• country

• station

• pop

• stockID

• day

• month

• year

• lat

• lon

• fishno

• length_cm

• weight_g

• age

• sex

• maturity

• folder

• picname

• cal

Usage

data(FISH)

Format

An example data file

Source

https://github.com/lisalibungan/shapeR

Plot data clusters

Description

Plots data clusters

Usage

cluster.plot( ddata, classes, main="", col.stock=NULL,
              plotCI = FALSE, conf.level = 0.68, ...)

Arguments

Value

None

Author(s)

Lisa Anne Libungan

References

Oksanen, J., Blanchet, F.G., Kindt, R., Legendre, P., Minchin, P.R., O'Hara, R.B., Simpson, G.L., Solymos, P., Stevens, M.H.H. and Wagner, H. (2013). vegan: Community Ecology Package. R package version 2.0-10.

Examples

data(shape)
library(vegan)
cap.res = capscale(getStdWavelet(shape) ~ getMasterlist(shape)$pop)

eig=eigenvals(cap.res,constrained=TRUE)
eig.ratio = eig/sum(eig)

cluster.plot(scores(cap.res)$sites[,1:2],getMasterlist(shape)$pop
,plotCI=TRUE
,xlab=paste("CAP1 (",round(eig.ratio[1]*100,1),"%)",sep="")
,ylab=paste("CAP2 (",round(eig.ratio[2]*100,1),"%)",sep="")
,main="Canonical clustering"
)

Detect otolith outline

Description

Determine the outline of otolith images in jpeg format which have been stored in the Fixed folder.

Usage

detect.outline(object, threshold=0.2, mouse.click=FALSE,
           display.images=FALSE, write.outline.w.org=FALSE)

Arguments

Details

Based on the Conte function (Claude 2008)

Value

A shapeR object with otolith outlines in the slot outline.list

Author(s)

Lisa Anne Libungan & Snaebjorn Palsson

References

Claude, J. (2008). Morphometrics with R. Springer. 316 p.

Urbanek, S. (2014). jpeg: Read and write JPEG images. R package version 0.1-8.

Bivand, R., Leisch, F. & Maechler, M. (2011) pixmap: Bitmap Images (”Pixel Maps”). R package version 0.4-11.

Libungan LA and Palsson S (2015) ShapeR: An R Package to Study Otolith Shape Variation among Fish Populations. PLoS ONE 10(3): e0121102. https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0121102

Examples

## Not run: 
#Use test data from Libungan and Palsson (2015):
shape = shapeR("ShapeAnalysis/","FISH.csv")
shape = detect.outline(shape, threshold=0.2,write.outline.w.org = TRUE)
## End(Not run)

Link information in the info.file to the coefficients obtained from the otolith images

Description

Link the original info file to the otolith coefficients

Usage

enrich.master.list(object, folder_name = "folder", pic_name = "picname",
                   calibration = "cal", include.wavelet = TRUE, include.fourier = TRUE,
                   n.wavelet.levels = 5, n.fourier.freq = 12,...)

Arguments

Value

A shapeR object with values in slots:

• wavelet.coef

• fourier.coef

• shape

• filter

• master.list

Author(s)

Lisa Anne Libungan

Examples

data(shape)
shape = generateShapeCoefficients(shape)

shape = enrich.master.list(shape)

Estimate the outline reconstruction based on Fourier/wavelet compared to the outlines that have not been transformed

Description

Estimate outline reconstruction using a different number of coefficients of wavelet and Fourier compared to the original otolith

Usage

estimate.outline.reconstruction(object, ...)

Arguments

Value

A list containing values

• w.dev.m a list for number of coefficients for mean error of wavelet reconstruction

• w.dev.sd a list for number of coefficients for standard deviation of wavelet reconstruction

• f.power.total Fourier power for number of Fourier harmonics

Author(s)

Lisa Anne Libungan

References

Claude, J. (2008) Morphometrics with R. Springer. 316 p.

Examples

## Not run: 
data(shape)
estimate.outline.reconstruction(shape)
## End(Not run)

Get wavelet/Fourier coefficients and basic shape variables

Description

Generates shape variables based on Fourier/wavelet reconstruction. Wavelet coefficients for wavelet. Basic shape parameters are also collected (area, length, width, perimeter).

Usage

generateShapeCoefficients(object,...)

Arguments

Value

A shapeR object with values in slots:

• wavelet.coef.raw

• fourier.coef.raw

• shape.coef.raw

Author(s)

Lisa Anne Libungan & Snaebjorn Palsson

References

Nason, G. (2012). wavethresh: Wavelets statistics and transforms. R package, version 4.5.

Claude, J. (2008). Morphometrics with R. Springer. 316 p.

See Also

wavethresh

Examples

data(shape)
shape = generateShapeCoefficients(shape)

Get Fourier coefficients, filtered according to filter

Description

Returns the Fourier coefficients determined in stdCoefs. Returns only values as set in setFilter

Usage

getFourier(object)

Arguments

Value

The Fourier coefficients for all fish as determined by setFilter

Author(s)

Lisa Anne Libungan

Get filtered master.list values

Description

Returns selected values from master.list

Usage

getMasterlist(object, useFilter = TRUE)

Arguments

Value

The master.list is filtered by the slot filter if the useFilter is TRUE, else no filtering is done.

Author(s)

Lisa Anne Libungan

Get simple shape variables, filtered according to filter

Description

Returns shape variables length, width, perimeter and area determined in generateShapeCoefficients. Returns only values as set in the slot filter. These variables can only be obtained if the calibration measurements in pixels have been registered in the csv data file in a column labelled 'cal' (see example data file). To get the calibration measurements, use a image manipulation program and measure 1mm on the calibration measurement stick (that was taken for that particular dataset) and register how many pixels 1mm is into the column 'cal'.

Usage

getMeasurements(object)

Arguments

Value

A data frame with all valid fish as determined by the slot filter and with columns:

• otolith.area

• otolith.length

• otolith.width

• otolith.perimeter

Author(s)

Lisa Anne Libungan

Examples

data(shape)
# Calculate the mean otolith area for each fish population
# The results are in square mm since the calibration ('cal') column
# in the data file is in pixels (1 mm/pixel).
tapply(getMeasurements(shape)$otolith.area, getMasterlist(shape)$pop,mean)

Get standardized Fourier coefficients, filtered according to filter

Description

Returns the standardized Fourier coefficients determined in stdCoefs. Returns only values as set in the slot filter

Usage

getStdFourier(object)

Arguments

Value

The standardized Fourier coefficients for all valid fish as determined by the slot filter

Author(s)

Lisa Anne Libungan

Get simple shape variables after standardization, filtered according to filter

Description

Returns the simple shape variables determined in stdCoefs. Returns only values as set in the slot filter

Usage

getStdMeasurements(object)

Arguments

Value

A data frame with all valid fish as determined by the slot filter. Returns only variables that have not been removed after standardization.

Author(s)

Lisa Anne Libungan

Examples

data(shape)
#Calculate the mean standardized otolith length for each fish population
tapply(getStdMeasurements(shape)$otolith.length,
getMasterlist(shape)$pop,mean)

Get standardized wavelet coefficients, filtered according to filter

Description

Returns the standardized wavelet coefficients determined in stdCoefs. Returns only values as set in the slot filter

Usage

getStdWavelet(object)

Arguments

Value

The standardized wavelet coefficients for all valid fish as determined by the slot filter

Author(s)

Lisa Anne Libungan

Get wavelet coefficients, filtered according to filter

Description

Returns the wavelet coefficients determined in generateShapeCoefficients. Returns only values as set in the slot filter

Usage

getWavelet(object)

Arguments

Value

The wavelet coefficients for all valid fish as determined by the slot filter

Author(s)

Lisa Anne Libungan

Plot outline reconstruction

Description

Show graphs of the reconstruction using different number of levels of wavelet reconstruction and Fourier power using different number of Fourier harmonics. Uses the output from estimate.outline.reconstruction

Usage

outline.reconstruction.plot(outline.rec.list,ref.w.level=5,
                            ref.f.harmonics=12,max.num.harmonics=32,...)

Arguments

Value

None

Author(s)

Lisa Anne Libungan

Examples

## Not run: data(shape)
est.list = estimate.outline.reconstruction(shape)
outline.reconstruction.plot(est.list,panel.first = grid())
## End(Not run)

Mean and standard deviation of the Fourier coefficients

Description

The mean and standard deviation of the Fourier coefficients

Usage

plotFourier(object, coef.index=NULL,class.name=NULL,useStdcoef=FALSE, ...)

Arguments

Value

None

Author(s)

Lisa Anne Libungan

Examples

data(shape)
shape = stdCoefs(shape,classes="pop","length_cm")
plotFourier(shape,class.name= "pop",useStdcoef=TRUE)

Mean otolith shape based on Fourier reconstruction

Description

A function for showing the mean otolith shape based on Fourier reconstruction

Usage

plotFourierShape(object, class.name, show.angle = FALSE,lty=1:5,col=1:6, ...)

Arguments

Value

None

Author(s)

Lisa Anne Libungan

References

Libungan LA and Palsson S (2015) ShapeR: An R Package to Study Otolith Shape Variation among Fish Populations. PLoS ONE 10(3): e0121102. https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0121102

Examples

data(shape)
plotFourierShape(shape, "pop",show.angle = TRUE,lwd=2,lty=1)

Mean and standard deviation of the wavelet coefficients

Description

The mean and standard deviation of tdhe wavelet coefficients

Usage

plotWavelet(object, level, start.angle = 0, class.name=NULL,useStdcoef=FALSE,...)

Arguments

Value

None

Author(s)

Lisa Anne Libungan

Examples

data(shape)
shape = stdCoefs(shape,classes="pop","length_cm")
plotWavelet(shape,level=5,class.name= "pop",useStdcoef=TRUE)

Mean otolith shape based on wavelet reconstruction

Description

A function for showing the mean otolith shape based on wavelet reconstruction

Usage

plotWaveletShape(object, class.name,show.angle=FALSE,lty=1:5,col=1:6,...)

Arguments

Value

None

Author(s)

Lisa Anne Libungan

References

Nason, G. (2012) wavethresh: Wavelets statistics and transforms, version 4.5. R package.

Examples

data(shape)
plotWaveletShape(shape, "pop",show.angle = TRUE,lwd=2,lty=1)

Read updated master list

Description

Reads an updated master list. This is important to run if you want to ensure that a updated master list is used in the analysis.

Usage

read.master.list(object, ...)

Arguments

Value

shapeR object with values in slots:

• master.list.org

Author(s)

Lisa Anne Libungan

Remove otolith outline

Description

A function for removing an otolith outline from the file 'outline.list'. Typically done if the image is of bad quality and needs to be enhanced in a image processing software

Usage

remove.outline(object, folder = "", fname = "")

Arguments

Value

shapeR object

Author(s)

Lisa Anne Libungan

References

Libungan LA and Palsson S (2015) ShapeR: An R Package to Study Otolith Shape Variation among Fish Populations. PLoS ONE 10(3): e0121102. https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0121102

Examples

## Not run: 
#Use test data from example in Libungan and Palsson (2015):
shape = shapeR("ShapeAnalysis/","FISH.csv")
shape = detect.outline(shape)
#If otolith outline in folder IC named 403_1 needs to be removed
shape = remove.outline(shape, "IC", "403_1")
## End(Not run)

Set a filter to analyze the shape data

Description

Sets a filter on master.list. Here it is possible to filter the master.list by specific ages, maturity stages, areas, etc. If no value is set, all data with shape parameters are used

Usage

setFilter(object, filter)

Arguments

Value

A shapeR object with the slot filter set.

Author(s)

Lisa Anne Libungan

Examples

data(shape)
#Filter only Icelandic and Norwegian samples
shape = setFilter(shape,
getMasterlist(shape, useFilter = FALSE)$pop %in% c("NO","IC"))
table(getMasterlist(shape)$pop)
#Reset filter
shape = setFilter(shape)
table(getMasterlist(shape)$pop)

An example shapeR instance including 160 images.

Description

The shape coefficients have been generated. The wavelet coefficients have been standardized using pop and length_cm.

Usage

data(shape)

Format

A shapeR class including 160 images

Details

The class slot's are as follows:

• project.path. A path as "ShapeAnalysis/"

• info.file. A file as FISH.csv. The information is stored in the data frame master.list

• outline.list. A list with three elements (IC, NO, SC) which give a list of the otolith outlines

• filter. A logical vector showing which elements of the master list have valid otoliths

• fourier.coef. A matrix of the Normalized Elliptic Fourier coefficients

• wavelet.coef. A matrix of the wavelet coefficients

• shape. A matrix of shape variables after scaling according to calibration otolith.area, otolith.length, otolith.width, otolith.perimeter.

• fourier.coef.std. A matrix which will contain standardized Fourier coefficients

• wavelet.coef.std. A matrix which will contain standardized wavelet coefficients

• shape.coef.raw. A matrix of shape variables before scaling according to calibration otolith.area, otolith.length, otolith.width, otolith.perimeter.

• master.list. The contents of the info.file

Source

https://github.com/lisalibungan/shapeR

shapeR

Description

Collection and analysis of otolith shape data

a shapeR class

Usage

shapeR(project.path, info.file, ...)

Arguments

Value

a shapeR object

Slots

project.path

Path to the project where the images are stored

info.file

Info file containing fish and otolith information

master.list.org

The contents of the info.file

master.list

The contents of the info.file with added shape parameters and descriptors

outline.list.org

A list of all the original otolith outlines

outline.list

A list of all the otolith outlines. It returns a list of smoothed if contour smoothing (usingsmoothout) has been conducted.

filter

A logical vector selecting the otoliths used for analysis

wavelet.coef.raw

The wavelet coefficients for all the otolith outlines

wavelet.coef

The wavelet coefficients after aligning with the info.file. The data is generated when enrich.master.list is run

wavelet.coef.std

The standardized wavelet coefficients. The data is generated when stdCoefs is run

wavelet.coef.std.removed

The index of the removed wavelet coefficients after standardization. The data is generated when stdCoefs is run

fourier.coef.raw

The Fourier coefficients for all the otolith outlines

fourier.coef

The Fourier coefficients for after aligning with the info file. The data is generated when enrich.master.list is run

fourier.coef.std

The standardized Fourier coefficients. The data is generated when stdCoefs is run

fourier.coef.std.removed

The index of the removed Fourier coefficents after standardization. The data is generated when stdCoefs is run

shape.coef.raw

The uncalibrated shape measurements for all the otoliths. The shape parameters are: otolith.area, otolith.length, otolith.width, otolith.perimeter

shape.coef

The shape measurements for after aligning with the info file. The shape parameters have been calibrated using the calibration parameter as registered in the datafile as the column 'cal'.

shape.std

The standardized shape measurements. The data is generated when stdCoefs is run

shape.std.removed

The index of the removed shape measurements after standardization. The data is generated when stdCoefs is run

Author(s)

Lisa Anne Libungan & Snaebjorn Palsson

References

Libungan LA and Palsson S (2015) ShapeR: An R Package to Study Otolith Shape Variation among Fish Populations. PLoS ONE 10(3): e0121102. https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0121102

See Also

https://github.com/lisalibungan/shapeR

plotWavelet

plotFourier

plotWaveletShape

plotFourierShape

capscale

cluster.plot

setFilter

lda

detect.outline

generateShapeCoefficients

enrich.master.list

Examples

## Not run: 

# This example has two sections: (1) Demonstration of how a shapeR object
# is analyzed and (2) How to create a shapeR object from an archive of
# image files.

#-----------------------------------------
# Section 1: Analyzing a shapeR object

data(shape)

#Standardize coefficients
shape = stdCoefs(shape,"pop","length_cm")

#Visualize Wavelet and Fourier coefficients
plotWavelet(shape,level=5,class.name= "pop",useStdcoef=TRUE)
plotFourier(shape,class.name= "pop",useStdcoef=TRUE)

#Examine the mean shapes
plotWaveletShape(shape, "pop",show.angle = TRUE,lwd=2,lty=1)
plotFourierShape(shape, "pop",show.angle = TRUE,lwd=2,lty=1)

#Canonical analysis
library(vegan)
cap.res = capscale(getStdWavelet(shape) ~ getMasterlist(shape)$pop)
anova(cap.res)

#Visualize the canonical scores
eig=eigenvals(cap.res,constrained=TRUE)
eig.ratio = eig/sum(eig)

cluster.plot(scores(cap.res)$sites[,1:2],getMasterlist(shape)$pop
,plotCI=TRUE
,xlab=paste("CAP1 (",round(eig.ratio[1]*100,1),"%)",sep="")
,ylab=paste("CAP2 (",round(eig.ratio[2]*100,1),"%)",sep="")
,main="Canonical clustering"
)

#Only analyze Icelandic and Norwegian samples
shape = setFilter(shape, getMasterlist(shape, useFilter = FALSE)$pop %in% c("NO","IC"))

#Classifier on standardized wavelet
lda.res.w = lda(getStdWavelet(shape),getMasterlist(shape)$pop,CV=TRUE)
ct.w = table(getMasterlist(shape)$pop,lda.res.w$class)

diag(prop.table(ct.w, 1))

# Total percent correct
sum(diag(prop.table(ct.w)))

cap.res = capscale(getStdWavelet(shape) ~ getMasterlist(shape)$pop)
anova(cap.res)

#Classifier on canoncial values
lda.res.w = lda(scores(cap.res)$sites,getMasterlist(shape)$pop,CV=TRUE)
ct.w = table(getMasterlist(shape)$pop,lda.res.w$class)

diag(prop.table(ct.w, 1))

# Total percent correct
sum(diag(prop.table(ct.w)))

#-----------------------------------------
# Section 2: Creating a shapeR object from image files

# The following example requires the user to download an archive of JPEG
# files from https://github.com/lisalibungan/shapeR/
# place the ShapeAnalysis directory inside the working directory.

shape = shapeR("~/ShapeAnalysis/","FISH.csv")
shape = detect.outline(shape,write.outline.w.org = TRUE)

shape = generateShapeCoefficients(shape)
shape = enrich.master.list(shape)

## End(Not run)

Show a shapeR object

Description

Show the project.path and info.file, the number of outlines that have been read and which fundamental methods have been run.

Usage

## S4 method for signature 'shapeR'
show(object)

Arguments

Value

None

Show the extracted outline on top of the original image

Description

A function which displayes the outlines which were extracted from the image in the "Fixed" folder on top of the corresponding image in the "Original" folder.

Usage

show.original.with.outline(object, folder, fname)

Arguments

Value

None

Author(s)

Lisa Anne Libungan

References

Libungan LA and Palsson S (2015) ShapeR: An R Package to Study Otolith Shape Variation among Fish Populations. PLoS ONE 10(3): e0121102. https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0121102

Examples

## Not run: 
#Follow the example in Libungan and Palsson (2015) and run the following lines:
show.original.with.outline(shape,"IC","403_2")
## End(Not run)

Contour smoothing

Description

Remove high frequency pixel noise around the otolith outline

Usage

smoothout(object, n)

Arguments

Value

A shapeR object with smoothed otolith outlines in the slot outline.list

Author(s)

Lisa Anne Libungan

References

Haines, A.J., Crampton, J.S. (2000). Improvements to the method of Fourier shape analysis as applied in morphometric studies. Palaeontology 43: 765-783.

Claude, J. (2008) Morphometrics with R. Springer. 316 p.

Examples

data(shape)
shape = smoothout(shape,n=100)

# Plot smoothed outline on top of original outline for comparison
outline.org=shape@outline.list.org[["IC"]][["403_2"]]
outline=shape@outline.list[["IC"]][["403_2"]]
plot(outline.org$X,outline.org$Y,type='l',xlab="",ylab="",lwd=2,axes=FALSE)
lines(outline$X,outline$Y,col="red",lwd=2)
legend("bottomleft",c('Original','Smoothed'),lty=1,col=c('black','red'),lwd=2)

Standardize coefficients

Description

Function to standardized the wavelet and Fourier coefficients for a specific parameter such as the fish length. For each country/population a regression coefficient is calculated as a function of fish length. If the slope is significantly different from zero, a correction is made according to Lleonart et al 2000. First ANCOVA is performed: variable ~ pop*length_cm, following a method by Longmore et al 2010. If there is a significant interaction between population and length_cm, then the coefficients are not used and automatically discarded. If there is no interaction, the coefficients are kept and standardized with regards to fish length.

Usage

stdCoefs(object, classes=NA, std.by, std.type = "mean", p.crit = 0.05,bonferroni= FALSE)

Arguments

Value

A shapeR object with standardized shape coefficients in the slot shape.std

Author(s)

Lisa Anne Libungan

References

Lleonart, J., Salat, J. & Torres, G.J. (2000) Removing allometric effects of body size in morphological analysis. Journal of Theoretical Biology, 205, 85-93.

Longmore, C., Fogarty, K., Neat, F., Brophy, D., Trueman, C., Milton, A. & Mariani, S. (2010) A comparison of otolith microchemistry and otolith shape analysis for the study of spatial variation in a deep-sea teleost, Coryphaenoides rupestris. Environmental Biology of Fishes, 89, 591-605.

Reist, J.D. (1985) An Empirical-Evaluation of Several Univariate Methods That Adjust for Size Variation in Morphometric Data. Canadian Journal of Zoology-Revue Canadienne De Zoologie, 63, 1429-1439.

Examples

data(shape)
shape = stdCoefs(shape,classes="pop","length_cm")

Write outlines on top of the original images for quality checking

Description

A function which writes the outlines which were extracted from the images in the folder "Fixed" on top of the corresponding images in the "Original" folder. Viewing the resulted images in the folder "Original_with_outlines" is a good quality check to ensure the correct outline has been extracted. If the outline is not correct, then the image can be fixed in an image software, such as GIMP (www.gimp.org), placed in the "Fixed" folder and then the detect.outline step is repeated. The function detect.outline calls this function if the parameter write.outline.w.org is set to TRUE.

Usage

write.image.with.outline(object, folder = NA, fname = NA, doProgress = TRUE)

Arguments

Value

None

Author(s)

Lisa Anne Libungan

References

Libungan LA and Palsson S (2015) ShapeR: An R Package to Study Otolith Shape Variation among Fish Populations. PLoS ONE 10(3): e0121102. https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0121102

Examples

## Not run: 
#Use test data from Libungan and Palsson (2015) and run the following lines:
shape = shapeR("ShapeAnalysis/","FISH.csv")
shape = detect.outline(shape,write.outline.w.org = FALSE)
write.image.with.outline(shape)
## End(Not run)