floop: 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",
...)

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.

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.

Author

Spencer Maynes, Fan Yang, and Anne Parkhurst.

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.

References

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

Examples

Run this code

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

Run the code above in your browser using DataLab