Package 'morphErr' reference manual

Title:	Measurement Error Models for Morphometric Data
Description:	Morphometric data collected on animal populations can be subject to measurement error, which leads to biased estimators using line-fitting techniques such as linear regression and reduced major axis. The models implemented in this package were described by Stevenson, Smit, and Setyawan (2026) <DOI:10.1214/26-AOAS2164>. They explicitly accommodate measurement error, allow for multivariate data, estimate relationships between dimensions, allow missing data, and provide tests for isometric relationships between dimensions. Morphometric data of the reef manta ray, collected in Raja Ampat, Indonesia, are included.
Authors:	Ben C. Stevenson [aut, cre, cph], Elizabeth Smit [aut]
Maintainer:	Ben C. Stevenson <[email protected]>
License:	MIT + file LICENSE
Version:	1.0.0
Built:	2026-09-30 10:28:33 UTC
Source:	https://github.com/elismit01/morpherr

Bootstrapping for a Morphometric Model

Description

Simulates bootstrap resamples and re-fits the original morphometric model to each one. The resulting object can be used as an argument for summary.lme.morph() and plot.lme.morph() to provide standard errors, confidence intervals, and p-values based on bootstrapping rather than asymptotic approximations.

Usage

boot.morph(object, B = 1000, control = NULL, progressbar = TRUE, n.cores = 1)
boot.morph(object, B = 1000, control = NULL, progressbar = TRUE, n.cores = 1)

Arguments

object

An object of class lme.morph, returned by fit.morph().

B

An integer, providing the number of bootstrap resamples.

control

A list of control values for the estimation algorithm to replace the default values returned by the function nlme::lmeControl().

progressbar

Logical. If TRUE a progress bar will be displayed.

n.cores

Integer. The number of cores for parallel processing.

Value

The original object, with additional bootstrapping information that can be used by summary.lme.morph() and plot.lme.morph()

Examples


## Fitting model to manta ray data.
fit <- fit.morph(manta)
## Carrying out a parametric bootstrap.
fit.boot <- boot.morph(fit, B = 100)
## Standard errors based on a bootstrap will be a little different
## to those based on asymptotic approximations.
summary(fit)
summary(fit.boot)


## Fitting model to manta ray data.
fit <- fit.morph(manta)
## Carrying out a parametric bootstrap.
fit.boot <- boot.morph(fit, B = 100)
## Standard errors based on a bootstrap will be a little different
## to those based on asymptotic approximations.
summary(fit)
summary(fit.boot)

Extract Results from a Morphometric Simulation Study

Description

Extracts results from each model fitted in a simulation study conducted using sim.morph().

Usage

extract.sim.morph(sim.res, FUN = summary, n.cores = 1)
extract.sim.morph(sim.res, FUN = summary, n.cores = 1)

Arguments

sim.res

An object of class lme.morph.sim, returned by sim.morph()

FUN

A function to apply to each model fit. Defaults to summary.lme.morph(), which extracts parameter estimates and standard errors.

n.cores

Integer. The number of cores for parallel processing.

Value

An array containing the results of applying FUN to each model fit.

Examples

## Running a small simulation study.
sim.fits <- sim.morph(n.sims = 5,
                      n.animals = 10,
                      n.photos = 3,
                      mus = c(315, 150, 100),
                      sigmas = c(25, 15, 10),
                      rhos = c(0.85, 0.80, 0.75),
                      psis = c(10, 6, 4),
                      phis = c(0.5, 0.4, 0.3),
                      method = "REML",
                      progressbar = FALSE,
                      n.cores = 1)
## Extracting p-values from tests for isometry from each model
## fit.
iso.p <- function(x) summary(x, type = "isometric-pca")[, 3]
extract.sim.morph(sim.fits, FUN = iso.p)

## Running a small simulation study.
sim.fits <- sim.morph(n.sims = 5,
                      n.animals = 10,
                      n.photos = 3,
                      mus = c(315, 150, 100),
                      sigmas = c(25, 15, 10),
                      rhos = c(0.85, 0.80, 0.75),
                      psis = c(10, 6, 4),
                      phis = c(0.5, 0.4, 0.3),
                      method = "REML",
                      progressbar = FALSE,
                      n.cores = 1)
## Extracting p-values from tests for isometry from each model
## fit.
iso.p <- function(x) summary(x, type = "isometric-pca")[, 3]
extract.sim.morph(sim.fits, FUN = iso.p)

Fit Morphometric Model

Description

Fits the model described by Stevenson, Smit, and Setyawan (2026) to morphometric data.

Usage

fit.morph(
  data,
  log.transform = FALSE,
  method = "REML",
  control = list(maxIter = 1e+05, msMaxIter = 1e+05)
)
fit.morph(
  data,
  log.transform = FALSE,
  method = "REML",
  control = list(maxIter = 1e+05, msMaxIter = 1e+05)
)

Arguments

data

A data frame containing the morphometric data. See the section below on the correct formatting of this argument.

log.transform

Logical. If TRUE, the data are log-transformed prior to model fitting.

method

A character string indicating the objective function used to fit the model. Either "ML" for maximum likelihood or "REML" for restricted maximum likelihood.

control

A list of control values for the estimation algorithm to replace the default values returned by the function nlme::lmeControl().

Details

This is a special case of a linear mixed-effects model, and is fitted via a call to nlme::lme(). Some arguments of fit.morph() are directly passed to nlme::lme().

Value

An object of classes lme.morph (specific to this package) and lme (inherited from nlme::lme()). The object is the list returned by nlme::lme() with a couple of additional components.

Rather than inspecting the object directly, the best way to extract understandable output from the object is using the S3 methods summary.lme.morph(), plot.lme.morph(), and predict.lme.morph() via the generic functions summary(), plot(), and predict(). Other S3 methods for the lme class are availble via nlme, such as nlme::coef.lme().

Log transformations

To fit a model to log-transformed measurement data, provide the untransformed measurements in the data argument and specify log.transform = TRUE. This will allow the S3 method plot.lme.morph() to plot the original data with back-transformed estimates, and the S3 method summary.lme.morph() to carry out the correct test for isometric growth.

The `data` argument

The manta object is an example of a correctly formatted data argument. It must be a data frame with the following columns:

animal.id: An individual identification number. Rows with the same animal.id correspond to measurements of the saime individual manta ray.
photo.id: A photo identification number. Rows with the same photo.id correspond to measurements taken from the same image.
photo.id: An integer indicating the dimension the measurement is for.
measurement: The corresponding measurement.

References

Stevenson, B. C., Smit, E., and Setyawan, E. (2026) Measurement error models for morphometric data. Annals of Applied Statistics, 20: 945–962.

Examples

## Fitting model to manta ray data.
fit <- fit.morph(manta)
## Using maximum likelihood instead of REML.
fit <- fit.morph(manta, method = "ML")

## Fitting model to manta ray data.
fit <- fit.morph(manta)
## Using maximum likelihood instead of REML.
fit <- fit.morph(manta, method = "ML")

Manta Ray Morphometric Data

Description

Data collected on a drone photogrammetry survey of the reef manta ray Mobula alfredi in Raja Ampat, Indonesia.

Usage

manta
manta

Format

`manta`

A data frame with four columns:

animal.id: An individual identification number. Rows with the same animal.id correspond to measurements of the same individual manta ray.
photo.id: A photo identification number. Rows with the same photo.id correspond to measurements taken from the same image.
dim: An integer indicating the dimension the measurement is for. Here, 1 is for disc width, 2 is for disc length, and 3 is for cranial width.
measurement: The observed measurement value in centimetres.

Plot Morphometric Data and Estimated Relationships

Description

An S3 method that plots morphometric data, estimated relationships between dimensions, or both, from a fitted model object returned by fit.morph().

Usage

## S3 method for class 'lme.morph'
plot(
  x,
  dims = c(1, 2),
  type = "data",
  line.type = "lm",
  confints = !add,
  add = FALSE,
  reverse.axes = FALSE,
  plot.data = TRUE,
  xlim = NULL,
  ylim = NULL,
  xlab = NULL,
  ylab = NULL,
  ...
)
## S3 method for class 'lme.morph'
plot(
  x,
  dims = c(1, 2),
  type = "data",
  line.type = "lm",
  confints = !add,
  add = FALSE,
  reverse.axes = FALSE,
  plot.data = TRUE,
  xlim = NULL,
  ylim = NULL,
  xlab = NULL,
  ylab = NULL,
  ...
)

Arguments

x

An object of class lme.morph, returned by fit.morph().

dims

An integer vector of length two, indicating which dimensions will appear on the x- and y-axes, respectively.

type

A character string specifying the plot type. If "ratio", then the y-axis represents the ratio between measurements of the two dimensions. If "data", then the raw data are plotted.

line.type

A character string specifying the type of fitted line to overlay. If "lm", then a line with the same interpretation as linear regression is plotted. If "pca", then the reduced major axis (or principal component axis) summarising the relationship is plotted.

confints

Logical. If TRUE, then confidence intervals are plotted.

add

Logical. If TRUE, then fitted lines are added to an existing plot.

reverse.axes

Logical. If TRUE, then a line of type "lm" will provide the expected value of the x-axis variable conditional on the y-axis variable, rather than the other way around. Only use reverse.axes = TRUE to add to an existing plot. For a new plot, simply reverse the order of the elements in dims.

plot.data

Logical. If FALSE then the data are not plotted.

xlim, ylim

Limits for the axes.

xlab, ylab

Titles for the axes.

...

Additional arguments passed to graphics::abline() and graphics::lines() to modify the appearance of the fitted lines.

Value

No return value. Called to produce a plot.

Examples

## Fitting model to manta ray data.
fit <- fit.morph(manta)
## Plotting dimensions 1 and 2 with a fitted linear regression
## line.
plot(fit)
## Same again, but plotting the reduced major axis (or principal
## component axis) for dimensions 1 and 3.
plot(fit, dims = c(1, 3), line.type = "pca")
## A plot showing how the ratio between dimensions 2 and 3 changes
## with the size of dimension 3. Because the line is quite flat,
## it's plausible the relationship is isometric.
plot(fit, dims = c(3, 2), type = "ratio", line.type = "pca")
## On the other hand, the relationship between dimensions 1 and 2
## is clearly allometric.
plot(fit, dims = c(3, 1), type = "ratio", line.type = "pca")
## Fitting model to manta ray data.
fit <- fit.morph(manta)
## Plotting dimensions 1 and 2 with a fitted linear regression
## line.
plot(fit)
## Same again, but plotting the reduced major axis (or principal
## component axis) for dimensions 1 and 3.
plot(fit, dims = c(1, 3), line.type = "pca")
## A plot showing how the ratio between dimensions 2 and 3 changes
## with the size of dimension 3. Because the line is quite flat,
## it's plausible the relationship is isometric.
plot(fit, dims = c(3, 2), type = "ratio", line.type = "pca")
## On the other hand, the relationship between dimensions 1 and 2
## is clearly allometric.
plot(fit, dims = c(3, 1), type = "ratio", line.type = "pca")

Plot Morphometric Data

Description

Creates scatter plots of morphometric measurements, with options for different dimension combinations and plotting of ratios.

Usage

plotmorph(
  data,
  dims = c(1, 2),
  plot.data = TRUE,
  ratios = FALSE,
  xlim = NULL,
  ylim = NULL,
  xlab = NULL,
  ylab = NULL
)
plotmorph(
  data,
  dims = c(1, 2),
  plot.data = TRUE,
  ratios = FALSE,
  xlim = NULL,
  ylim = NULL,
  xlab = NULL,
  ylab = NULL
)

Arguments

data

A data frame containing the morphometric data. See the section below on the correct formatting of this argument.

dims

An integer vector of length two, indicating which dimensions will appear on the x- and y-axes, respectively.

plot.data

Logical. If FALSE, the plotting area is set up but points aren't plotted.

ratios

Logical. If TRUE, the y-axis represents the ratio between dimensions.

xlim, ylim

Limits for the axes.

xlab, ylab

Titles for the axes.

Value

No return value. Called to produce a plot.

The `data` argument

The manta object is an example of a correctly formatted data argument. It must be a data frame with the following columns:

animal.id: An individual identification number. Rows with the same animal.id correspond to measurements of the saime individual manta ray.
photo.id: A photo identification number. Rows with the same photo.id correspond to measurements taken from the same image.
photo.id: An integer indicating the dimension the measurement is for.
measurement: The corresponding measurement.

Examples

## Plotting dimensions 1 and 2.
plotmorph(manta)
## Plotting dimensions 1 and 3.
plotmorph(manta, dims = c(1, 3))
## Plotting the ratio of dimension 2 divided by dimension 1 on the
## y-axis.
plotmorph(manta, dims = c(1, 2), ratios = TRUE)

## Plotting dimensions 1 and 2.
plotmorph(manta)
## Plotting dimensions 1 and 3.
plotmorph(manta, dims = c(1, 3))
## Plotting the ratio of dimension 2 divided by dimension 1 on the
## y-axis.
plotmorph(manta, dims = c(1, 2), ratios = TRUE)

Predict Measurements from True Values

Description

Calculates model predictions for the true size of a dimension based on true values for any subset of the remaining dimensions. Predictions for multiple individuals are available from a single call to the function.

Usage

## S3 method for class 'lme.morph'
predict(object, y.dim, newdata = NULL, type = c("lm", "pca"), ...)
## S3 method for class 'lme.morph'
predict(object, y.dim, newdata = NULL, type = c("lm", "pca"), ...)

Arguments

object

An object of class lme.morph, returned by fit.morph().

y.dim

Integer specifying which dimension to predict

newdata

A data frame of other dimensions to use for prediction. Column names must be of the form "dimX" where X is the dimension number.

type

Either "lm" or "pca" for the type of prediction.

...

Additional arguments passed to methods

Details

This function computes estimated coefficients for the appropriate linear function (as per summary.lme.morph() with type = "betas-lm" or type = "betas-pca"), and then evaluates the function for the provided newdata. For type = "pca", only a single column can be provided in newdata.

Value

A matrix with estimated true sizes and standard errors. Note that these are standard errors, not prediction errors.

Prediction functions in `morphErr`

There are three key differences between predict.lme.morph() and predictblup().

predict.lme.morph() only generates estimates for one dimension based on true values for other dimensions, whereas predictblup() can generate estimates from true values, observed values (i.e., subject to measurement error), or a combination of both.
predict.lme.morph() can generate estimates for multiple individuals, whereas predictblup() only provides estimates for a single individual.
predict.lme.morph() provides standard errors, but predictblup() does not.

Examples

## Fitting model to manta ray data.
fit <- fit.morph(manta)
## Predicting dimension 2 for a single individual with a true value
## of 90 for dimension 3.
predict(fit, y.dim = 2, newdata = data.frame(dim3 = 90))
## Predicting dimension 1 from dimensions 2 and 3 for two
## individuals, one with true values of 130 and 60 for dimensions 2
## and 3, respectively, and one with true values of 140 and 70.
predict(fit, y.dim = 1, newdata = data.frame(dim2 = c(130, 140),
                                             dim3 = c(60, 70)))

## Fitting model to manta ray data.
fit <- fit.morph(manta)
## Predicting dimension 2 for a single individual with a true value
## of 90 for dimension 3.
predict(fit, y.dim = 2, newdata = data.frame(dim3 = 90))
## Predicting dimension 1 from dimensions 2 and 3 for two
## individuals, one with true values of 130 and 60 for dimensions 2
## and 3, respectively, and one with true values of 140 and 70.
predict(fit, y.dim = 1, newdata = data.frame(dim2 = c(130, 140),
                                             dim3 = c(60, 70)))

Predict from Observed Measurements

Description

Makes predictions for a single individual using the best linear unbiased predictor (BLUP).

Usage

predictblup(object, true = NULL, obs = NULL)
predictblup(object, true = NULL, obs = NULL)

Arguments

object

An object of class lme.morph, returned by fit.morph().

true

A vector of true dimension measurements, if available. Use NA for dimensions with unknown true measurements.

obs

A matrix of measurements observed with error, where each row represents measurements from one photograph. Use NA for dimensions with measurements that were not taken from a photo.

Details

This function uses a BLUP to compute estimated true values for a single individual. A BLUP is computed by finding the mode of the multivariate probability density function of the true values, conditional on any provided values for true dimension sizes, dimension measurements observed with error, or a combination of both.

Value

A numeric vector of predictions for all dimensions.

Prediction functions in `morphErr`

There are three key differences between predict.lme.morph() and predictblup().

predict.lme.morph() only generates estimates for one dimension based on true values for other dimensions, whereas predictblup() can generate estimates from true values, observed values (i.e., subject to measurement error), or a combination of both.
predict.lme.morph() can generate estimates for multiple individuals, whereas predictblup() only provides estimates for a single individual.
predict.lme.morph() provides standard errors, but predictblup() does not.

Examples

## Fitting model to manta ray data.
fit <- fit.morph(manta)
## Estimates for the true dimension sizes of an individual with a
## known true value for dimension 2 of 130, and observed 
## measurements subject to error from two photographs. The first 
## photograph has # observed measurements of 300 and 135 for 
## dimensions 1 and 2, respectively, while the second photograph 
## has observed # measurements of 290 and 140, respectively.
## Dimension 3 is not observed in any photograph.
predictblup(fit, true = c(NA, 130, NA), obs = rbind(c(300, 135, NA),
                                                    c(290, 140, NA)))

## Fitting model to manta ray data.
fit <- fit.morph(manta)
## Estimates for the true dimension sizes of an individual with a
## known true value for dimension 2 of 130, and observed 
## measurements subject to error from two photographs. The first 
## photograph has # observed measurements of 300 and 135 for 
## dimensions 1 and 2, respectively, while the second photograph 
## has observed # measurements of 290 and 140, respectively.
## Dimension 3 is not observed in any photograph.
predictblup(fit, true = c(NA, 130, NA), obs = rbind(c(300, 135, NA),
                                                    c(290, 140, NA)))

Simulate Morphometric Measurements

Description

Simulates morphometric data from a photogrammetry survey, with observations subject to measurement error, under the model described by Stevenson, Smit, and Setyawan (2026).

Usage

sim.measurements(
  n.animals = NULL,
  n.photos = NULL,
  data = NULL,
  mus,
  sigmas,
  rhos,
  psis,
  phis,
  log.transform = FALSE
)
sim.measurements(
  n.animals = NULL,
  n.photos = NULL,
  data = NULL,
  mus,
  sigmas,
  rhos,
  psis,
  phis,
  log.transform = FALSE
)

Arguments

n.animals

Integer. The number of animals in the sample.

n.photos

Integer vector. If there are n.animals elements, each one specifies the number of photos for an individual. If there is one element, then that number of photos is used for all animals.

data

A data frame with columns animal.id, photo.id, and dim, provided instead of n.animals and n.photos. This provides the user with full control over which dimensions are measured in which photos from which animals.

mus

A vector with an element for each dimension, providing the means of the true dimension sizes in the population.

sigmas

A vector with an element for each dimension, providing the standard deviations for true dimension sizes in the population.

rhos

A vector, with one element for each pair of dimensions, providing the pairwise correlations between true dimension sizes in the population. See 'Details' for the correct order for the correlations.

psis

A vector with an element for each dimension, providing the standard deviations of measurement errors for the dimensions.

phis

A vector, with one element for each pair of dimensions, providing the pairwise correlations between measurement errors for the dimensions. See 'Details' for the correct order for the correlations.

log.transform

Logical. If TRUE, the parameters are considered to correspond to a model where the response was log-transformed. The data frame returned by this function will contain the back-transformed measurments.

Details

For arguments rhos and phis, the elements must be ordered so that all $m - 1$ correlations involving dimension 1 appear first in ascending numerical order, followed by all remaining $m - 2$ correlations involving dimension 2, and so on, where ⁠eqn{m}⁠ is the number of dimensions.

For example, if $m = 4$ , then the first three elements are the correlations between dimension 1 and dimensions 2, 3, and 4, respectively. The following two elements are correlations between dimension 2 and dimensions 3 and 4, respectively. The final element is the correlation between dimension 3 and 4.

Value

A data frame with four columns:

animal.id: An individual identification number. Rows with the same animal.id correspond to measurements of the same individual.
photo.id: A photo identification number. Rows with the same photo.id correspond to measurements taken from the same image.
dim: An integer indicating the dimension the measurement is for.
measurement: The observed measurement value.

References

Stevenson, B. C., Smit, E., and Setyawan, E. (2026) Measurement error models for morphometric data. Annals of Applied Statistics, 20: 945–962.

Examples

## Simulating data for ten animals, with two photos each, measuring
## three dimensions.
sim.data <- sim.measurements(n.animals = 10, n.photos = 2,
                             mus = c(315, 150, 100),
                             sigmas = c(25, 15, 10),
                             rhos = c(0.85, 0.80, 0.75),
                             psis = c(10, 6, 4),
                             phis = c(0.5, 0.4, 0.3))
head(sim.data)

## Simulating data for two animals, with different numbers of
## photos for each, and different measurements available from
## different photos.
data <- data.frame(animal.id = c(1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2),
                   photo.id = c(1, 1, 2, 2, 2, 1, 2, 3, 3, 4, 4),
                   dim = c(1, 3, 1, 2, 3, 1, 1, 1, 3, 2, 3))
sim.data <- sim.measurements(data = data,
                             mus = c(315, 150, 100),
                             sigmas = c(25, 15, 10),
                             rhos = c(0.85, 0.80, 0.75),
                             psis = c(10, 6, 4),
                             phis = c(0.5, 0.4, 0.3))
sim.data

## Simulating data for ten animals, with two photos each, measuring
## three dimensions.
sim.data <- sim.measurements(n.animals = 10, n.photos = 2,
                             mus = c(315, 150, 100),
                             sigmas = c(25, 15, 10),
                             rhos = c(0.85, 0.80, 0.75),
                             psis = c(10, 6, 4),
                             phis = c(0.5, 0.4, 0.3))
head(sim.data)

## Simulating data for two animals, with different numbers of
## photos for each, and different measurements available from
## different photos.
data <- data.frame(animal.id = c(1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2),
                   photo.id = c(1, 1, 2, 2, 2, 1, 2, 3, 3, 4, 4),
                   dim = c(1, 3, 1, 2, 3, 1, 1, 1, 3, 2, 3))
sim.data <- sim.measurements(data = data,
                             mus = c(315, 150, 100),
                             sigmas = c(25, 15, 10),
                             rhos = c(0.85, 0.80, 0.75),
                             psis = c(10, 6, 4),
                             phis = c(0.5, 0.4, 0.3))
sim.data

Conduct a Simulation Study for Morphometric Models

Description

Simulates multiple datasets and fits a model to each one.

Usage

sim.morph(
  n.sims,
  n.animals = NULL,
  n.photos = NULL,
  data = NULL,
  mus,
  sigmas,
  rhos,
  psis,
  phis,
  log.transform = FALSE,
  method = "REML",
  control = list(maxIter = 1e+05, msMaxIter = 1e+05),
  progressbar = TRUE,
  n.cores = 1
)
sim.morph(
  n.sims,
  n.animals = NULL,
  n.photos = NULL,
  data = NULL,
  mus,
  sigmas,
  rhos,
  psis,
  phis,
  log.transform = FALSE,
  method = "REML",
  control = list(maxIter = 1e+05, msMaxIter = 1e+05),
  progressbar = TRUE,
  n.cores = 1
)

Arguments

n.sims

Integer. The number of data sets to simulate.

n.animals

Integer. The number of animals in the sample.

n.photos

Integer vector. If there are n.animals elements, each one specifies the number of photos for an individual. If there is one element, then that number of photos is used for all animals.

data

mus

A vector with an element for each dimension, providing the means of the true dimension sizes in the population.

sigmas

A vector with an element for each dimension, providing the standard deviations for true dimension sizes in the population.

rhos

A vector, with one element for each pair of dimensions, providing the pairwise correlations between true dimension sizes in the population. See 'Details' for the correct order for the correlations.

psis

A vector with an element for each dimension, providing the standard deviations of measurement errors for the dimensions.

phis

A vector, with one element for each pair of dimensions, providing the pairwise correlations between measurement errors for the dimensions. See 'Details' for the correct order for the correlations.

log.transform

method

A character string indicating the objective function used to fit the model. Either "ML" for maximum likelihood or "REML" for restricted maximum likelihood.

control

A list of control values for the estimation algorithm to replace the default values returned by the function nlme::lmeControl().

progressbar

Logical. If TRUE a progress bar will be displayed.

n.cores

Integer. The number of cores for parallel processing.

Value

An object of class lme.morph.sim. The best way to extract results from this object is to use extract.sim.morph(). See the example below.

Examples

## Running a small simulation study.
sim.fits <- sim.morph(n.sims = 5,
                      n.animals = 10,
                      n.photos = 3,
                      mus = c(315, 150, 100),
                      sigmas = c(25, 15, 10),
                      rhos = c(0.85, 0.80, 0.75),
                      psis = c(10, 6, 4),
                      phis = c(0.5, 0.4, 0.3),
                      method = "REML",
                      progressbar = FALSE,
                      n.cores = 1)
## Extracting p-values from tests for isometry from each model
## fit.
iso.p <- function(x) summary(x, type = "isometric-pca")[, 3]
extract.sim.morph(sim.fits, FUN = iso.p)

## Running a small simulation study.
sim.fits <- sim.morph(n.sims = 5,
                      n.animals = 10,
                      n.photos = 3,
                      mus = c(315, 150, 100),
                      sigmas = c(25, 15, 10),
                      rhos = c(0.85, 0.80, 0.75),
                      psis = c(10, 6, 4),
                      phis = c(0.5, 0.4, 0.3),
                      method = "REML",
                      progressbar = FALSE,
                      n.cores = 1)
## Extracting p-values from tests for isometry from each model
## fit.
iso.p <- function(x) summary(x, type = "isometric-pca")[, 3]
extract.sim.morph(sim.fits, FUN = iso.p)

Summarise Morphometric Model Fits

Description

An S3 method that creates summaries of fitted morphometric models. This function can provide different types of summaries including parameter estimates, beta coefficients, and tests for isometry.

Usage

## S3 method for class 'lme.morph'
summary(object, ..., type = "pars", y.dim, x.dim, level = 0.95)
## S3 method for class 'lme.morph'
summary(object, ..., type = "pars", y.dim, x.dim, level = 0.95)

Arguments

object

An object of class lme.morph, returned by fit.morph().

...

Other parameters (for S3 generic compatibility).

type

A character string specifying type of summary. Either "pars" (the default), "betas" "betas-lm", "betas-pca", or "isometric-pca". See 'Details' for further information.

y.dim

An integer specifying the response dimension for when type is "betas", "betas-lm", or "betas-pca".

x.dim

An integer vector specifying the explanatory dimensions for when type is "betas", "betas-lm", or "betas-pca".

level

The confidence level for any interval estimates.

Details

The following summaries are available with this method, controlled by the type argument:

type = "pars"

Estimates and standard errors for the model parameters, including the vectors $\mu$ for the means of the true dimension sizes, $\sigma$ for the standard deviations for true dimension sizes, $\rho$ for the correlations between true dimension sizes, $\psi$ for the standard deviations in measurement errors for the dimensions, and $\phi$ for the correlations between measurement errors for all pairs of dimensions.

type = "betas" or type = "betas-lm"

Estimates and standard errors for coefficients of a linear combination that provides the expected value of one dimension (specified by y.dim) using any subset of the remaining dimensions (specified in the vector x.dim).

type = "betas-pca"

An estimated intercept and slope for the reduced major axis (or principal component axis) summarising the relationship between the true values of dimensions specified by y.dim and x.dim.

type = "isometric-pca"

Results for tests of the null hypotheses of isometric relationships between all pairs of dimensions. The p-values are obtained using normal approximations for the test statistics.

For models with log.transform = FALSE, the test statistic to test for isometric growth between dimensions $p$ and $q$ is $\mu_p\sigma_q - \mu_q\sigma_p$ , which is equal to $0$ under the null hypothesis.

For models with log.transform = TRUE, the test statistic is the slope for the reduced major axis (or principal component axis) summarising the relationship between the two dimensions, which is equal to $1$ under the null hypothesis.

Value

A matrix or data frame containing the requested summary.

Examples

## Fitting model to manta ray data.
fit <- fit.morph(manta)
## Parameter estimates and standard errors.
summary(fit)
## Estimated coefficients for the linear combination that provides
## the expected value of the first dimension from only the second.
summary(fit, type = "betas-lm", y.dim = 1, x.dim = 2)
## Estimated coefficients for the linear combination that provides
## the expected value of the second dimension from both the first
## and third.
summary(fit, type = "betas-lm", y.dim = 2, x.dim = c(1, 3))
## Estimated intercept and slope for the reduced major axis (or
## pricipal component axis) summarising the relationship between
## the first and second dimensions.
summary(fit, type = "betas-pca", y.dim = 1, x.dim = 2)
## Tests for isometry between all pairs of dimensions.
summary(fit, type = "isometric-pca")
## Fitting model to manta ray data.
fit <- fit.morph(manta)
## Parameter estimates and standard errors.
summary(fit)
## Estimated coefficients for the linear combination that provides
## the expected value of the first dimension from only the second.
summary(fit, type = "betas-lm", y.dim = 1, x.dim = 2)
## Estimated coefficients for the linear combination that provides
## the expected value of the second dimension from both the first
## and third.
summary(fit, type = "betas-lm", y.dim = 2, x.dim = c(1, 3))
## Estimated intercept and slope for the reduced major axis (or
## pricipal component axis) summarising the relationship between
## the first and second dimensions.
summary(fit, type = "betas-pca", y.dim = 1, x.dim = 2)
## Tests for isometry between all pairs of dimensions.
summary(fit, type = "isometric-pca")

Extract Variance-Covariance Matrix from Morphometric Model

Description

An S3 method for extracting both parameter estimates and their variance-covariance matrix from a fitted morphometric model.

Usage

## S3 method for class 'lme.morph'
vcov(object, ...)
## S3 method for class 'lme.morph'
vcov(object, ...)

Arguments

object

A fitted model of class "lme.morph"

...

Other parameters (for S3 generic compatibility).

Value

A list containing:

est

Named vector of parameter estimates

varcov

Variance-covariance matrix

Examples

## Fitting model to manta ray data.
fit <- fit.morph(manta)
## Extracting variance-covariance matrix.
vcov(fit)

## Fitting model to manta ray data.
fit <- fit.morph(manta)
## Extracting variance-covariance matrix.
vcov(fit)

Package 'morphErr'

Help Index

Bootstrapping for a Morphometric Model

Description

Usage

Arguments

Value

Examples

Extract Results from a Morphometric Simulation Study

Description

Usage

Arguments

Value

Examples

Fit Morphometric Model

Description

Usage

Arguments

Details

Value

Log transformations

The data argument

References

Examples

Manta Ray Morphometric Data

Description

Usage

Format

manta

Plot Morphometric Data and Estimated Relationships

Description

Usage

Arguments

Value

Examples

Plot Morphometric Data

Description

Usage

Arguments

Value

The data argument

Examples

Predict Measurements from True Values

Description

Usage

Arguments

Details

Value

Prediction functions in morphErr

See Also

Examples

Predict from Observed Measurements

Description

Usage

Arguments

Details

Value

Prediction functions in morphErr

See Also

Examples

Simulate Morphometric Measurements

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Conduct a Simulation Study for Morphometric Models

Description

Usage

Arguments

Value

See Also

Examples

Summarise Morphometric Model Fits

Description

Usage

Arguments

The `data` argument

`manta`

The `data` argument

Prediction functions in `morphErr`

Prediction functions in `morphErr`