Document Wiener overloads

[WardBrian]

Submission Checklist

• Builds locally
• New functions marked with <<{ since VERSION }>>
• Declare copyright holder and open-source license: see below

Summary

This closes #779 and adds documentation for the functions added in stan-dev/math#2822.

The signatures are fairly straightforward. The preamble which gives the definition of the distribution I adapted from the doxygen comment @Franzi2114 has in the Math documentation. I would appreciate if she could look it over, because I made a few changes (mostly for variable name consistency), and because the original uses $t_0$, $\tau_0$, and $t_o$ as variable names, which I think are all what the existing documentation called $\tau$?

Copyright and Licensing

Please list the copyright holder for the work you are submitting (this will be you or your assignee, such as a university or company):

By submitting this pull request, the copyright holder is agreeing to license the submitted work under the following licenses:

• Code: BSD 3-clause (https://opensource.org/licenses/BSD-3-Clause)
• Documentation: CC BY-ND 4.0 (https://creativecommons.org/licenses/by-nd/4.0/)

[mitzimorris]

LGTM. (and wow. quite a function!)

[WardBrian]

Here's the rendered latex, which I'd still appreciate if @Franzi2114 could review

[Franzi2114]

Thanks @WardBrian!

1. First of all: \tau and t_0 are not the same and cannot be named the same. You have to discriminate between the parameter \tau and an integration variable, e.g. \tau_0. Then you need a \tau_0 in the first line: y - \tau_0.
2. It should be \beta \in (0,1), beta is not allowed to be 0 or 1.
3. In the very first integral the integral boundaries should be \tau and \tau + s_\{tau}
4. The a you use here should be \alpha
   in p3(...\alpha)

There are some more spots that have to be changed.

This is what I published in the paper that describes the new function:
(Henrich et al., 2023)

[Franzi2114]

Here is my LaTeX code if this helps:

Mathematically, the function consists of the reaction times, $y$, and the seven parameters, boundary separation, $a$, (lower bound of the) non-decision time, $t_0$, relative starting point, $w$, drift rate, $v$, inter-trial variability of the drift rate, $s_v$, inter-trial variability of the relative starting point, $s_w$, and inter-trial variability of the non-decision time, $s_{t_0}$. It can be stated in the following terms:

\begin{equation}
\begin{split}
&\log\bigl[p(y\mid a,t_0,w,v,s_v,s_w,s_{t_0})\bigr] =
\
&\log\bigl[\frac{1}{s_{t_0}}\int_{t_0}^{t_0+s_{t_0}}\frac{1}{s_w}\int_{w-\frac{1}{2}s_w}^{w+\frac{1}{2}s_w}\int_{-\infty}^{\infty} p_3(y-\tau_0\mid a,\nu,\omega)
\
&\times \frac{1}{\sqrt{2\pi s_{v}^2}}\exp\Bigl(-\frac{(\nu-v)^2}{2s_{v}^2}\Bigr) ,d\nu ,d\omega ,d\tau_0\bigr]=
\
&\log\bigl[\frac{1}{s_{t_0}}\int_{t_0}^{t_0+s_{t_0}}\frac{1}{s_w}\int_{w-\frac{1}{2}s_w}^{w+\frac{1}{2}s_w} M\times p_3(y-\tau_0\mid a,\nu,\omega) ,d\omega ,d\tau_0\bigr],
\end{split}
\end{equation}

where $p()$ denotes the density function, and $M$ and $p_3()$ are defined, by using $t:=y-\tau_0$, as

\begin{equation}
M \coloneqq \frac{1}{\sqrt{1+s_v^2t}}\exp\Bigl(av\omega+\frac{v^2t}{2}+\frac{s_v^2a^2\omega^2-2av\omega-v^2t}{2(1+s_v^2t)}\Bigr)\text{ and}
\end{equation}

\begin{equation}
p_3(t\mid a,v,w) \coloneqq \frac{1}{a^2}\exp\Bigl(-avw-\frac{v^2t}{2}\Bigr)f(\frac{t}{a^2}\mid 0,1,w),
\end{equation}

where $f(t^*=\frac{t}{a^2}\mid0,1,w)$ can be specified in two ways:

\begin{equation}
f_l(t^\mid 0,1,w) = \sum_{k=1}^\infty k\pi \exp\Bigl(-\frac{k^2\pi^2t^}{2}\Bigr)\sin(k\pi w)\text{ and}
\end{equation}

\begin{equation}
f_s(t^\mid0,1,w) = \sum_{k=-\infty}^\infty \frac{1}{\sqrt{2\pi(t^)^3}}(w+2k) \exp\Bigl(-\frac{(w+2k)^2}{2t^*}\Bigr).
\end{equation}

Which of these is used in the computations depends on which expression requires the smaller number of components $k$ to guarantee a pre-specified precision \parencite{Blurton.2017, Gondan.2014, Hartmann.2021, Navarro.2009}.

[WardBrian]

Hi @Franzi2114 -

There are two difficulties here. One is, to be consistent with our existing documentation, I want to replace the variables in p(y| a, t0, w, v, ...) with p(y | \alpha, \tau, \beta, \delta, ...)

This would be relatively easy for me to find-and-replace, if not for my confusion about your original usages of t0 and \tau -- in particular, I don't know what tau is in your original latex - is it defined anywhere?

[Franzi2114]

In the latex above, I use \tau_0 as the integration variable. You find this at the end of the integrals: d\tau_0. And \tau_0 ranges from t0 to (t0+st0).
Does it make it clear?

[Franzi2114]

It's no problem to replace every a with \alpha, t0 with \tau, w with \beta and v with \delta.

Also the s_\nu you use above should be a s_\delta.

[WardBrian]

Thanks!

Does this look correct?

[Franzi2114]

Did you shorten the first expression?

Two changes are still left:

1. \beta is in (0,1) instead of [0,1]
2. in the definition of M there is another a that should be an \alpha

[Franzi2114]

In the first step we havee the 3 integrals to make clear that the 7-parameter density is integrated 3 times, over the three parameters \tau, \beta, \delta.
The integral over \delta can be calculated and leads to a factor, the M. This makes it clearer where the M-factor comes from.

[WardBrian]

Ok, I've put back the intermediate step

[Franzi2114]

Perfect! This looks good ;)

[Franzi2114]

Is there anything else to do for me?