biogeom (version 1.4.3)

fitETE: Data-Fitting Function for the Explicit Troscianko Equation

Description

fitETE is used to estimate the parameters of the explicit Troscianko equation.

Usage

fitETE(x, y, ini.val, control = list(), par.list = FALSE, 
      stand.fig = TRUE, angle = NULL, fig.opt = FALSE, np = 2000,
      xlim = NULL, ylim = NULL, unit = NULL, main = NULL)

Value

par

the estimates of the model parameters.

scan.length

the observed length of the egg's profile.

scan.width

the observed width of the egg's profile.

scan.area

the observed area of the egg's profile.

scan.perimeter

the observed perimeter of the egg's profile.

r.sq

the coefficient of determination between the observed and predicted \(y\) values on the Troscianko curve.

RSS

the residual sum of squares between the observed and predicted \(y\) values on the Troscianko curve.

sample.size

the number of data points used in the data fitting.

x.stand.obs

the observed \(x\) coordinates of the points on the Troscianko curve at the standard state.

y.stand.obs

the observed \(y\) coordinates of the points on the Troscianko curve at the standard state.

y.stand.pred

the predicted \(y\) coordinates of the points on the Troscianko curve at the standard state.

x.obs

the observed \(x\) coordinates of the points on the Troscianko curve at the transferred polar angles as defined by the user.

y.obs

the observed \(y\) coordinates of the points on the Troscianko curve at the transferred polar angles as defined by the user.

y.pred

the predicted \(y\) coordinates of the points on the Troscianko curve at the transferred polar angles as defined by the user.

Arguments

x

the \(x\) coordinates of an egg's profile.

y

the \(y\) coordinates of an egg's profile.

ini.val

the list of initial values for the model parameters.

control

the list of control parameters for using the optim function in package stats.

par.list

the option of showing the list of parameters on the screen.

stand.fig

the option of drawing the observed and predicted profiles of an egg at the standard state (i.e., the egg's centre is located at (0, 0), and the mid-line is aligned to the \(x\)-axis).

angle

the angle between the mid-line and the \(x\)-axis, which can be defined by the user.

fig.opt

an optional argument of drawing the observed and predicted profiles of an egg at arbitrary angle between the major axis and the \(x\)-axis.

np

the number of data points on the predicted explicit Troscianko curve.

xlim

the range of the \(x\)-axis over which to plot the Troscianko curve.

ylim

the range of the \(y\)-axis over which to plot the Troscianko curve.

unit

the unit of the \(x\)-axis and the \(y\)-axis when showing the Troscianko curve.

main

the main title of the figure.

Author

Peijian Shi , Johan Gielis , Brady K. Quinn .

Details

Here, the major axis (i.e., the mid-line of an egg's profile) is the straight line trhough the two ends of the egg's length. The Nelder-Mead algorithm (Nelder and Mead, 1965) is used to carry out the optimization of minimizing the residual sum of squares (RSS) between the observed and predicted \(y\) values. The optim function in package stats was used to carry out the Nelder-Mead algorithm. When angle = NULL, the observed egg's profile will be shown at its initial angle in the scanned image; when angle is a numerical value (e.g., \(\pi/4\)) defined by the user, it indicates that the major axis is rotated by the amount (\(\pi/4\)) counterclockwise from the \(x\)-axis.

References

Biggins, J.D., Montgomeries, R.M., Thompson, J.E., Birkhead, T.R. (2022) Preston’s universal formula for avian egg shape. Ornithology 139, ukac028. tools:::Rd_expr_doi("10.1093/ornithology/ukac028")

Biggins, J.D., Thompson, J.E., Birkhead, T.R. (2018) Accurately quantifying the shape of birds' eggs. Ecology and Evolution 8, 9728\(-\)9738. tools:::Rd_expr_doi("10.1002/ece3.4412")

Nelder, J.A., Mead, R. (1965) A simplex method for function minimization. Computer Journal 7, 308\(-\)313. tools:::Rd_expr_doi("10.1093/comjnl/7.4.308")

Shi, P., Gielis, J., Quinn, B.K., Niklas, K.J., Ratkowsky, D.A., Schrader, J., Ruan, H., Wang, L., Niinemets, Ü. (2022) 'biogeom': An R package for simulating and fitting natural shapes. Annals of the New York Academy of Sciences 1516, 123\(-\)134. tools:::Rd_expr_doi("10.1111/nyas.14862")

Shi, P., Wang, L., Quinn, B.K., Gielis, J. (2023) A new program to estimate the parameters of Preston's equation, a general formula for describing the egg shape of birds. Symmetry 15, 231. tools:::Rd_expr_doi("10.3390/sym15010231")

Troscianko, J. (2014). A simple tool for calculating egg shape, volume and surface area from digital images. Ibis, 156, 874\(-\)878. tools:::Rd_expr_doi("10.1111/ibi.12177")

See Also

curveETE, TE, lmTE

Examples

data(eggs)

uni.C <- sort( unique(eggs$Code) )
ind   <- 8
Data  <- eggs[eggs$Code==uni.C[ind], ]
x0    <- Data$x
y0    <- Data$y

Res1 <- adjdata(x0, y0, ub.np=2000, times=1.2, len.pro=1/20)
x1   <- Res1$x
y1   <- Res1$y

dev.new()
plot( x1, y1, asp=1, cex.lab=1.5, cex.axis=1.5,  type="l", col=4,  
      xlab=expression(italic("x")), ylab=expression(italic("y")) )

# \donttest{
  res1      <- lmTE( x1, y1, unit="cm", fig.opt=FALSE )
  
  if(FALSE){
    P0  <- c(res1$scan.length/2, res1$par)
    xx  <- seq(-res1$scan.length/2, res1$scan.length/2, len=2000)
    yy1 <- ETE(P0, xx)
    yy2 <- -ETE(P0, xx)
    dev.new()
    plot( xx, yy1, cex.lab=1.5, cex.axis=1.5, asp=1, col=2, 
          ylim=c(-res1$scan.length/2, res1$scan.length/2),
          type="l", xlab=expression(x), ylab=expression(y) )
    lines( xx, yy2, col=4 )
  }

  x0.ini    <- mean( x1 )
  y0.ini    <- mean( y1 )
  theta.ini <- res1$theta
  a.ini     <- res1$scan.length / 2
  alpha0.ini <- res1$par[1] 
  alpha1.ini <- res1$par[2]
  alpha2.ini <- res1$par[3]

  ini.val <- list(x0.ini, y0.ini, theta.ini, a.ini, alpha0.ini, alpha1.ini, alpha2.ini)

  res0 <- fitETE( x=x1, y=y1, ini.val=ini.val, 
                 unit="cm", par.list=FALSE, 
                 stand.fig=FALSE, angle=NULL, fig.opt=FALSE, 
                 control=list(reltol=1e-30, maxit=50000), 
                 np=2000 ) 

  n.loop <- 12
  Show   <- FALSE
  for(i in 1:n.loop){
    ini.val <- res0$par
    if(i==n.loop) Show <- TRUE
    print(paste(i, "/", n.loop, sep=""))
    res0 <- fitETE( x=x1, y=y1, ini.val=ini.val, 
                   unit="cm", par.list=FALSE, 
                   stand.fig=Show, angle=pi/4, fig.opt=Show,  
                   control=list(reltol=1e-30, maxit=50000), 
                   np=2000 )    
  }

  # The numerical values of the location and model parameters
  res0$par

  # The root-mean-square error (RMSE) between 
  #   the observed and predicted y values
  sqrt(res0$RSS/res0$sample.size)

  sqrt(sum((res0$y.stand.obs-res0$y.stand.pred)^2)/length(res0$y.stand.obs))

  # To calculate the volume of the egg
  VolumeETE(P=res0$par[4:7])

  # To calculate the surface area of the egg
  SurfaceAreaETE(P=res0$par[4:7])
# }

graphics.off()