fel {hysteresis}

Fitting Ellipses

Description

Fit a sinusoidal hysteretic (elliptical) process between an input and an output.

Usage

fel(x, y=NULL, method = "harmonic2", period = NULL, subjects = NULL,
  times="unknown",subset = NULL,na.action= getOption("na.action"),
  control=nls.control(), boot=FALSE,...)

Arguments

x

input

y

output

method

the method to be used for fitting; one of either the default method="harmonic2", method="nls", method="direct", method="lm" or method="geometric".

period

an optional number that defines the length of the period.

subjects

an optional factor or list of factors, each of the same length as x. Use to identify several different ellipses to fit at once, in which case fel returns an object of class ellipsefitlist instead of ellipsefit. If subjects is a list of factors each combination of the factors must be present in the data or an error will be produced.

times

either a numeric vector of length nrow(x) or one of the two options "equal" or the default "unknown". If the times at which ellipse observations are taken are known, a numeric vector can be used to give those times. If not, predicted values are found by minimizing geometric distances from the fitted ellipse to the observations. If "equal", time points are assumed to be equally spaced in a counterclockwise fashion. Do not use the "harmonic2" method unless times are either known or are known to be equal. Bootstrapping results are also more accurate if correct times are used.

subset

an optional vector specifying a subset of observations to be used in the fitting process.

control

optional and only used if method="nls" or "geometric". See nls.control for method="nls".

na.action

a function which indicates what should happen when the data contain NAs. The default is set by the na.action setting of options, the factory-fresh default is na.omit. Value na.exclude can be useful.

boot

logical, if TRUE results will be bootstrapped by summary.ellipsefit.

...

other othrt optional arguments passed to summary.ellipsefit if boot=TRUE.

Details

Where the response y is a sinusoidal process with an element of randomness that lags the controlling input x, which is also a stochastic sinusoidal process, an ellipse can be used to fit the relationship between x and y.

The values of parameters such as area, lag, retention, coercion, split angle and hysteresis.y are estimated from this ellipse. See loop.parameters.

The harmonic2 method is a two step harmonic least squares model using generalized transcendental equations presented by Lapshin (1995). Yang and Parkhurst provide the efficient estimates for parameters and as such "harmonic2" is used as the default. Direct specific least squares (method="direct") based on the work of Radim Halir and Jan Flusser is also available although work on delta method standard errors is still in progress. The geometric method is based on the work of Gander, Golub and Strebel and uses the results of an initial direct method to produce an ellipse that minimizes the sum of the squared geometric distances. Finally method="lm" and ellipse specific non-linear least squares (method="nls") are included as well.

If x and y contain more than 1 ellipse that needs to be fit, the argument subjects can be used to identify a period of data to fit separate ellipses.

Bootstrapped estimates for parameter values are provided with summary.ellipsefit. These bootstrapped estimates are generally less biased than those provided by fel in isolation.

Value

fel returns an object of class ellipsefit or ellipsefitlist.

call

the function call.

fit

information dependent on the fitting method used.

method

the method used.

x

the input x used.

y

the output y used.

pred.x

the fitted values for x.

pred.y

the fitted values for y.

period.time

a vector that contains times converted to radians for observations, either estimated after the ellipse has been fitted or given beforehand by times.

fit.statistics

rudimentary measures, based on the "harmonic2" method, include the Multivariate Final Prediction Error (MFPE) and the AIC for both the output alone and the two variables in combination. Although degree of freedom adjustments are made for other methods, measures of fit require further study.

values

a named vector of parameter estimates. See loop.parameters, same as Estimates here.

Estimates

a named vector of parameter estimates. See loop.parameters, same as values.

Std.Errors

Delta standard errors produced by the delta method.

residuals

algebraic residuals from the model. The function residuals.ellipsefit can produce other types of residuals from an ellipsefit object.

if boot==TRUE fel returns an object of class ellipsesummary by making a call to summary.ellipsefit. See summary.ellipsefit.

For bootstrapping

Boot.Estimates

bootstrapped estimates.

Boot.Std.Errors

bootstrap standard errors.

If multiple ellipses are fit simultaneously there will be three arguments to the response, models which will contain the separate model fits for each ellipse, Estimates which will have all of the parameter estimates in matrix form, and Std.Errors which will have all of the delta method standard errors in matrix form. See fel.repeated.

Author(s)

Spencer Maynes, Fan Yang, and Anne Parkhurst.

References

Yang, F and A. Parkhurst, "Efficient Estimation of Elliptical Hysteresis with Application to the Characterization of Heat Stress" DOI:10.1007/s13253-015-0213-6

See Also

plot.ellipsefit for plotting and summary.ellipsefit for summarizing and bootstrapping an ellipsefit object. Also residuals.ellipsefit.

Examples

### Simulate and fit a Single ellipse.
Sellipse <- mel(method=2,sd.x=0.2,sd.y=0.04)
Sellipse.fit <- fel(Sellipse$x,Sellipse$y)
Sellipse.fit  #Gives estimates, delta standard errors and 95% CI
Sellipse.fit$Estimates  

### Bootstrap estimates and standard errors (Seed is necessary if want to reproduce results)
booted.Sellipse <- fel(Sellipse$x,Sellipse$y,boot=TRUE, seed=123)
booted.Sellipse   #Gives boot estimates, boot bias, boot SE and boot quartiles
plot(booted.Sellipse,main="Simulated Bootstrap Ellipse Loop",xlab="X Input",
ylab="Y Output",values="ellipse.all")