floop {hysteresis} | R Documentation |
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 |
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 |
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 |
extended.classical |
logical. If true, uses
instead of
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 |
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 |
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 |
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 |
Estimates |
a named vector of parameter estimates. See |
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")