=======================================================================================
This is the help file for the diffusion model routine "diffvar.R" in R.
This routine generates the mean and variance of a diffusion model using several methods.
When using this program for scientific work, please cite Wagenmakers, Grasman, & 
Molenaar (2004), referenced below.

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

1. Copy this file ("help.txt") and the file "diffvar.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 "diffvar.R" and select this file.
5. You are now able to use the functions in "diffvar.R", both by using the new R menu items
   on the R menu bar (i.e., the top right menu bar item now reads "Diffusion Model") and by
   calling the functions directly, as will be illustrated below. 

NOTE. The menu bar will only appear under Windows. For operating systems other than Windows,
the functions need to be called directly.

##### Input ##### 

The parameters that may be specified are drift rate v, boundary separation a, and
diffusion variance s2. s2 is a scaling parameter, and is set to a default value of 0.01.

Input is possible via the menu or by calling the functions directly from the console.

##### Parameter Values #####

In applications of the diffusion model to RT distributions in two-choice tasks
(e.g., Ratcliff, Gomez, & McKoon, 2004; Ratcliff, Thapar, & McKoon, 2003; Wagenmakers,
Ratcliff, Gomez, & McKoon, 2004) ranges of plausible parameter values can be identified.
These are:

1. Drift rate "v" usually lies in the range from |0.1| to |0.5|. Positive drift means that 
the process tends to go to the top boundary, negative drift means that the process tends 
to go to the bottom boundary. In this work, the sign of the drift rate is inconsequential, 
because we assume the starting point of the process is equidistant from the absorbing 
response boundaries, and there is no variability in drift rate or starting point across 
trials. In this simplyfied situation the RT distributions for top boundary absorptions 
and bottom boundary absorptions are identical.

2. Boundary separation "a" usually lies in the range from 0.07 to 0.17. Boundary separation 
is small under speed stress, and it is high under accuracy stress.  

3. Diffusion variance "s2" is a scaling parameter. For historical reasons, its default value 
is 0.01 rather than 1. To retain consistency with parameter values reported in earlier work,
it may be advisable to keep s2 at 0.01. 

##### Examples #####

Calculate mean and variance,

(1) using the exact method, with drift rate = 0.2, boundary separation = .14, s2 = 0.01,
directly addressing the function from the R prompt ">":

> exactmeanvar(c(0.2, 0.14, 0.01));

This function returns the mean, standard deviation, and the variance, which may of course 
also be stored in some vector:

> vm = exactmeanvar(c(0.2, 0.14, 0.01));
> vm

Which returns

$meanrtime
[1] 0.3098731

$sdrtime
[1] 0.2258088

$varrtime
[1] 0.05098959

(2) same as (1), but now by approximation using the pdf (e.g., Ratcliff & Smith, in press):

> smvm = pdfmeanvar(c(0.2, 0.14, 0.01));
> smvm

which returns 

$meanrtime
[1] 0.3098731

$sdrtime
[1] 0.2258088

$varrtime
[1] 0.05098959

This process contains 2 loops, one over time, and one over an infinite series that has to 
be truncated at some point (you may check the code to see how this is done). 
As you have noticed, executing this function can be a time-consuming process.

(3) finally, we can also check this result by simulating the diffusion process very
many trials. The approximating mean and variance, based on N = 1000 runs of the 
process, can be obtained by

> simvm = simmeanvar(c(0.2, 0.14, 0.01), 1000);
> simvm

which returns 

$meanrtime
[1] 0.3182722

$sdrtime
[1] 0.2394365

$varrtime
[1] 0.05732985

Directly addressing these functions allows the calculated values to be used in loops
or in some kind of batch program.

##### References #####

Ratcliff, R., Gomez, P., & McKoon, G. (2004). Diffusion model account of lexical 
decision. Psychological Review, 111, 159-182.

Ratcliff, R., & Smith, P. L. (in press). A comparison of sequential sampling models 
for two-choice reaction time. Psychological Review.

Ratcliff, R., Thapar, A., & McKoon, G. (2003). A diffusion model analysis of the
effects of aging on brightness discrimination. Perception & Psychophysics, 65, 
523-535.

Ratcliff, R., & Tuerlinckx, F. (2002). Estimating parameters of the diffusion model: 
Approaches to dealing with contaminant reaction times and parameter variability. 
Psychonomic Bulletin & Review, 9, 438-481.

Wagenmakers, E.-J., Grasman, R., & Molenaar, P. (2004). On the relation between mean and 
variance of a diffusion model response time distribution. Manuscript submitted
for publication.

Wagenmakers, E.-J., Ratcliff, R., Gomez, P., & McKoon, G. (2004). A diffusion model
account of criterion manipulations in lexical decision. Manuscript submitted for 
publication.

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