fitEPE: Data-Fitting Function for the Explicit Preston Equation

In biogeom: Biological Geometries

Data-Fitting Function for the Explicit Preston Equation

Description

fitEPE is used to estimate the parameters of the explicit Preston equation or one of its simplified versions.

Usage

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

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.
simpver	an optional argument to use the simplified version of the explicit Preston equation.
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 Preston curve.
xlim	the range of the x-axis over which to plot the Preston curve.
ylim	the range of the y-axis over which to plot the Preston curve.
unit	the unit of the x-axis and the y-axis when showing the Preston curve.
main	the main title of the figure.

Details

The simpver argument should correspond to EPE. 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.

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 Preston curve.
RSS	the residual sum of squares between the observed and predicted y values on the Preston 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 Preston curve at the standard state.
y.stand.obs	the observed y coordinates of the points on the Preston curve at the standard state.
y.stand.pred	the predicted y coordinates of the points on the Preston curve at the standard state.
x.obs	the observed x coordinates of the points on the Preston curve at the transferred polar angles as defined by the user.
y.obs	the observed y coordinates of the points on the Preston curve at the transferred polar angles as defined by the user.
y.pred	the predicted y coordinates of the points on the Preston curve at the transferred polar angles as defined by the user.

Note

In the outputs, there are no x.stand.pred and x.pred, because y.stand.obs and y.stand.pred share the same x values (i.e., x.stand.obs), and y.obs and y.pred share the same x values (i.e., x.obs).

Author(s)

Peijian Shi [e-mail], Johan Gielis [e-mail], Brady K. Quinn [e-mail].

References

Nelder, J.A., Mead, R. (1965) A simplex method for function minimization. Computer Journal 7, 308-313. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1093/comjnl/7.4.308")}

Preston, F.W. (1953) The shapes of birds' eggs. The Auk 70, 160-182.

Shi, P., Chen, L., Quinn, B.K., Yu, K., Miao, Q., Guo, X., Lian, M., Gielis, J., Niklas, K.J. (2023) A simple way to calculate the volume and surface area of avian eggs. Annals of the New York Academy of Sciences 1524, 118-131. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1111/nyas.15000")}

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. \Sexpr[results=rd]{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. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.3390/sym15010231")}

Todd, P.H., Smart, I.H.M. (1984) The shape of birds' eggs. Journal of Theoretical Biology 106, 239-243. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/0022-5193(84)90021-3")}

See Also

curveEPE, PE, lmPE, TSE

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")) )


  simpver   <- NULL
  res1      <- lmPE( x1, y1, simpver=simpver, dev.angle=seq(-0.05, 0.05, by=0.0001), 
                     unit="cm", fig.opt=FALSE )
  x0.ini    <- mean( x1 )
  y0.ini    <- mean( y1 )
  theta.ini <- res1$theta
  a.ini     <- res1$scan.length / 2
  b.ini     <- res1$scan.width / 2
  c1.ini    <- res1$par[2] / res1$par[1]
  c2.ini    <- res1$par[3] / res1$par[1]
  c3.ini    <- res1$par[4] / res1$par[1]

  ini.val <- list(x0.ini, y0.ini, theta.ini, a.ini, b.ini, c1.ini, c2.ini, c3.ini)

  res0 <- fitEPE( x=x1, y=y1, ini.val=ini.val, 
                 simpver=simpver, 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 <- fitEPE( x=x1, y=y1, ini.val=ini.val, 
                   simpver=simpver, 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
  VolumeEPE(P=res0$par[4:8])

  # To calculate the surface area of the egg
  SurfaceAreaEPE(P=res0$par[4:8])


graphics.off()

biogeom documentation built on May 29, 2024, 8:52 a.m.