hysteresis-package {hysteresis}

Modeling Rate-Dependent Hysteretic Processes

Description

Fit, summarize and plot sinusoidal hysteretic processes using two step harmonic least squares. If the process is elliptical, other methods such as a geometric method, Halir and Flusser's direct specific least squares, ordinary least squares, and ellipse-specific non-linear least squares are also available.

Details

Package:	hysteresis
Type:	Package
Version:	2.7.2
Date:	2024-02-26
License:	gpl (>= 2)

Fits input and output variables x and y that form a hysteresis loop based on the generalized transcendental equation

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'

The functions mloop and floop can be used to simulate, fit, and obtain derived parameter estimates (see loop.parameters or ellipse.parameters ) along with delta method standard errors for hysteresis loops.. Additionally summary.fittedloop can be used to bootstrap results in order to produce less biased standard errors for derived parameters and obtain a model fit that is not dependent on the assumption of independent and normally distributed errors. If m=1 and n=1 then the hysteresis loop will form an ellipse which can be simulated with mel, fitted using 5 different available methods with fel, and bootstrapped using the function method summary.ellipsefit. If the upper and lower halves of the loop are structered differently, then the functions mloop2r, floop2r and summary.loop2r should be used. These functions fit a model with two values of retention for when the curve is above and below the split line. Studentized residuals are also available ((see residuals.ellipsesummary).

Author(s)

Spencer Maynes, Fan Yang, and Anne Parkhurst.

Maintainer: Spencer Maynes <[e-mail]>

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

Check out the vignette browseURL(system.file('doc/index.html',package='hysteresis'))
For simulating hysteresis loops, mloop and mel.
For fitting hysteresis loops, floop and fel.
For summarizing hysteresis loops, summary.fittedloop and summary.ellipsefit.
For bootstrapping ellipses, summary.ellipsefit. For fitting multiple hysteresis loops at once, can use fel and floop or fel.repeated and floop.repeated which can be easier to use for studies involving repeated measures.
Miscellaneous plot.ellipsefit, plot.ellipsefitlist, plot.ellipsesummary, residuals.ellipsesummary.

Examples

###Take a look at the vignette.
#browseURL(system.file('doc/index.html',package='hysteresis'))

### Simulate and fit a hysteresis loop with m=3 and n=5.
 loop1 <- mloop(sd.x=0.05,sd.y=0.05,n=5,m=3)
 model <- floop(loop1$x,loop1$y,n=5,m=3)
 model                #Gives estimate with delta standard errors
 model$Estimates      #Gives estimates  
 model$Std.Errors     #Lists delta standard errors  
 
### Plot hysteresis loop.
 plot(model,main="Simulated Hysteresis Loop n=5 m=3")

### Bootstrap estimates and standard errors (Seed is necessary if want to reproduce results)
 booted.loop <- floop(loop1$x,loop1$y,,n=5,m=3,boot=TRUE, seed=1523)
 booted.loop                   #Gives boot estimates, boot bias, boot SE and boot quartiles
 booted.loop$Boot.Estimates    #Gives boot estimates 
 booted.loop$Boot.Std.Errors   #Gives boot standard errors 
plot(booted.loop,main="Simulated Bootstrapped Loop n=5, m=3",putNumber=TRUE)


### Simulate and fit an ellipse.
ellipse1 <- mel(sd.x=0.2,sd.y=0.04)
ellipse1.fit <- fel(ellipse1$x,ellipse1$y)
ellipse1.fit             #Gives estimates with delta standard errors and 95%CI
ellipse1.fit$Estimates      #Gives all estimates 
ellipse1.fit$Std.Errors     #Lists delta standard errors  

### Plot ellipse
plot(ellipse1.fit,xlab="Input",ylab="Output",main="Simulated Ellipse")

### Bootstrap estimates and standard errors (Seed is necessary if want to reproduce results)
booted.ellipse <- fel(ellipse1$x,ellipse1$y,boot=TRUE, seed=123)
booted.ellipse                 #Gives boot estimates, boot bias, boot SE and boot quartiles
booted.ellipse$Boot.Estimates  #Gives boot estimates   
booted.ellipse$Boot.Std.Errors #Gives boot standard errors