floop {hysteresis}

Fit a Hysteresis Loop

Description

Fits a hysteresis loop given values of n and m chosen by the user. floop2r fits an asymetric loop with different values for retention above and below the split line.

Usage

floop(x,y=NULL,n=1,m=1,times="equal",period=NULL,
subjects=NULL, subset=NULL,na.action=getOption("na.action"),
extended.classical=FALSE,boot=FALSE,method="harmonic2",
...) 
floop2r(x,y=NULL,n=1,m=1,times="equal",period=NULL,
subjects=NULL, subset=NULL,na.action=getOption("na.action"),
extended.classical=FALSE,boot=FALSE,method="harmonic2",
...)

Arguments

x

numeric input vector.

y

numeric output vector.

n

a positive integer. Shape parameter regulating the central "plateau" of the hysteresis loop. Default is 1, which makes loop an ellipse when m is also equal to 1. See details.

m

an odd positive number. Bulging parameter of the hysteresis loop. Default is 1, which makes loop an ellipse when n is also equal to 1. In this case floop will automatically make a call to fel. See details.

period

length of time required to make a full loop. Reciprocal of frequency, and if times = "equal", the number of points needed to make a full loop.

subjects

an optional factor or list of factors, each of the same length as x. Use to identify a list of different loops to be fit from one set of data, in which case floop returns an object of class fittedlooplist instead of fittedloop.

times

either a numeric vector of length nrow(x) or the default "equal". If the times at which loop observations are taken are known, a numeric vector can be used to give those times. If the default "equal" is used instead, time points are assumed to be equally spaced in a counterclockwise fashion.

subset

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

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.

extended.classical

logical. If true, uses

y_t=sign(cos(2*pi*t/period))*b.y*abs(cos(2*pi*t/period))^n + retention*sin(2*pi*t/period)^m+cy+e_{y,t}

instead of

y_t=b.y*cos(2*pi*t/period)^n+retention*sin(2*pi*t/period)^m+cy+e_{y,t}

Allows the user to fit sinusoidal hysteresis loops with any positive real value of n > 1 instead of just odd numbered n. Default is false.

boot

logical, if TRUE results will be bootstrapped by the default arguments of summary.fittedloop.

method

if the default "harmonic2" is used, times along with m and n are either supplied by the user or given default values. Otherwise a non-linear "geometric" method that minimizes the sum of squared geometric residuals will be utilized.

...

other optional arguments such as seed, N=number of realizations, cbb for circular block bootstrapping, are passed to summary.fittedloop if boot=TRUE.

Details

Fits sinusoidal input and output variables x and y that form a hysteresis loop of the form

x_t=b.x*cos(2pi*t/period+phase.angle)+cx+e_{x,t}

y_t=b.y*cos(2pi*t/period+phase.angle)^n+ retention*sin(2pi*t/period+phase.angle)^m+cy+e_{y,t}

where

t=0,...,(n.points-1) if times='equal'

and the error terms, e, are independently and normally distributed. Also produces a vector of derived values. If floop2r is used, retention is assumed to be different above and below the split line that seperates the upper and lower loop trajectories, and addition terms are included in the model.

y_t=b.y*cos(2pi*t/period+phase.angle)^n+retention.above*sin(2pi*t/period+phase.angle)^m*I(0 < 2pi*t/period+phase.angle < pi)+retention.below*sin(2pi*t/period+phase.angle)^m*I(pi < 2pi*t/period+phase.angle < 2*pi)+cy+e_{y,t}

where retention.above and retention.below are retention above and below the split line.

Value

floop returns an object of class fittedloop while floop2r returns an object of class splitloop.

call

the function call.

fit

information dependent on the fitting method used.

x

the input.

y

the output.

pred.x

fitted x values.

pred.y

fitted y values.

period.time

time vector used to fit x and y.

residuals

residuals measured by Euclidean distance.The function residuals.fittedloop can produce other types of residuals

extended.classical

whether or not an extended loop is fit.

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

standard errors for parameters derived using the delta method.

method

fitting method used.

if boot==TRUE floop returns an object of class loopsummary by making a call to summary.fittedloop. See summary.fittedloop.

For bootstrapping

Boot.Estimates

bootstrapped estimates.

Boot.Std.Errors

bootstrap standard errors.

If multiple loops are fit simultaneously there will be three arguments to the response, models which will contain the separate model fits for each loop, 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 floop.repeated.

Author(s)

Spencer Maynes, Fan Yang, and Anne Parkhurst.

References

Lapshin, R. (1995) Analytical model for the approximation of hysteresis loop and its application to the scanning tunneling microscope.

See Also

Simulate a hysteresis loop with the function mloop. Alternatively see fel for fitting an ellipse (a hysteresis loop with parameters m=1, n=1) using a variety of methods. Also residuals.fittedloop. If a loop is an ellipse, use of fel is strongly recommended instead of floop.

Examples

### Simulate and fit a hysteresis loop with n=1 and m=3.
loopf <- mloop(sd.x=0.07,sd.y=0.05,n=3,m=3, retention=.5)
loopf.model <- floop(loopf$x,loopf$y,n=3,m=3)
loopf.model                #Gives estimate and delta standard errors
loopf.model$Estimates      #List estimates only  
loopf.model$Std.Errors     #List delta standard errors  

### Plot hysteresis loop.
plot(loopf.model,main="Simulated Hysteresis Loop n=3 m=3", values="hysteresis.all")
### Show characteristics of loop on plot
plot(loopf.model,main="Simulated Hysteresis Loop n=3 m=3",values="hysteresis.all",
show=c("retention","coercion"))
          
### Bootstrap estimates and standard errors (Seed is necessary if want to reproduce results)
booted.loopf <- floop(loopf$x,loopf$y,retention=.5,n=3,m=3,
boot=TRUE, seed=1523)
booted.loopf                   #Gives boot estimates, boot bias, boot SE and boot quartiles
booted.loopf$Boot.Estimates    #Gives boot estimates 
booted.loopf$Boot.Std.Errors   #Gives boot standard errors 
plot(booted.loopf,main="Simulated Bootstrapped Loop n=1, m=3",
putNumber=TRUE,values="hysteresis.all")