Document Wiener overloads

[WardBrian]

Submission Checklist

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

Summary

This closes #779 and adds documentation for the functions added in https://github.com/stan-dev/math/pull/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/)

[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, $sw$, 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,sw,s{t0})\bigr] = \ &\log\bigl[\frac{1}{s{t0}}\int{t_0}^{t0+s{t_0}}\frac{1}{sw}\int{w-\frac{1}{2}s_w}^{w+\frac{1}{2}sw}\int{-\infty}^{\infty} p_3(y-\tau0\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\tau0\bigr]= \ &\log\bigl[\frac{1}{s{t0}}\int{t_0}^{t0+s{t_0}}\frac{1}{sw}\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} fl(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} fs(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?