=======================================================================================
This is the help file for the level crossing function routine "invariantSCTweb.R" in R.
This routine estimates the level crossing function of a time series. This function is 
invariant under diffeomorphic transformations. In addition, a routine is provided that 
allows data to be simulated from several standard SDEs.
When using this program for scientific work, please cite 

Wagenmakers, E.-J., Molenaar, P. C. M., Grasman, R. P. P. P., Hartelman, P. A. I.,
& van der Maas, H. L. J. (2004). Tranformation Invariant Stochastic Catastrophe Theory.
Manuscript submitted for publication.

##### Getting it to Work #####

1. Copy this file ("helpinvariantSCTweb.txt") and the file "invariantSCTweb.R" to your 
   harddrive.
2. Install R, if you have not done so already. R is available at http://www.r-project.org/.
3. Start R.
4. Go the the menu bar, select "file" and then "Source R code". You will be prompted to select
   a file. Browse to the directory that contains "invariantSCTweb.R" and select this file.
5. You are now able to use the functions in "invariantSCTweb.R" by calling the functions 
   directly, as will be illustrated below. 

##### Input ##### 

The input to the two functions consists of a unidimensional time series (a vector), and 
several parameters.

We will now consider examples of each of the two functions (i.e., "gendat" and "levelcross").

##### Examples #####

# first, generate a time series of 1000 observations from a symmetrical cusp SDE.
# It has drift function (2x-x^3), and diffusion function s(x) = 1.

> gendat() 

# this works because the values for the default parameters. Now generate 1500 observations,
# without plotting the result, and assigning it to variable "myCusp" instead:

> myCusp = gendat(n=1500, plotit = FALSE)

# plot the result:

> plot(myCusp, type = "l")

# the pdf for this simulated series is most likely bimodal.
# N.B. "most likely", here and in the following, means "according to analytical results".
# See the Wagenmakers paper on how to calculate f(x) and f(x)s(x) and their transforms 
# from the SDE drift and diffusion function.
# To check the bimodality, plot the histogram and kernel density estimate:

> hist(myCusp, freq = F)
> lines(density(myCusp))

# now transform "myCusp":

> transmyCusp = 0.5*( exp(3*myCusp) - 0.5*exp(-3*myCusp) )

# plot transformed time series:

> plot(transmyCusp, type = "l")

# the pdf is now most likely unimodal
# check:

> hist(transmyCusp, freq = F)
> lines(density(transmyCusp))

# Now compare this to the level crossing function

# 
> levelcross(myCusp, plotit = T)
> levelcross(transmyCusp, plotit = T)

# Both will most likely be bimodal

#

# Let's do this again, but now for a different SDE.

# generate a time series of 800 observations from an OU SDE,
# with drift function -x, and diffusion function s(x) = 1.
# Plot and assign to variable "myOU". 

> myOU = gendat(ndat = 800, a = 0, b = -0.2, c = 0, plotit = T)

# the pdf for this simulated series is most likely unimodal.
# To check, plot the histogram and kernel density estimate:

> hist(myOU, freq = F)
> lines(density(myOU))

# now transform "myOU":

> transmyOU = log(myOU + sqrt(myOU^2 + 0.01))

# plot transformed time series:

> plot(transmyOU, type = "l")

# the pdf is now most likely bimodal
# check:

> hist(transmyOU, freq = F)
> lines(density(transmyOU))

# Now compare this to the level crossing function

# 
> levelcross(myOU, plotit = T)
> levelcross(transmyOU, plotit = T)

# Both will most likely be unimodal

=======================================================================================