From 326a2767564925b86994312241512947f0728f24 Mon Sep 17 00:00:00 2001 From: Brian Ward Date: Tue, 16 Dec 2025 10:37:22 -0500 Subject: [PATCH 1/5] Documentation for the wiener cdf functions --- src/bibtex/all.bib | 27 ++++ src/functions-reference/functions_index.qmd | 12 ++ .../positive_lower-bounded_distributions.qmd | 116 +++++++++++++++++- 3 files changed, 154 insertions(+), 1 deletion(-) diff --git a/src/bibtex/all.bib b/src/bibtex/all.bib index 2891c2cf0..9223de516 100644 --- a/src/bibtex/all.bib +++ b/src/bibtex/all.bib @@ -1332,3 +1332,30 @@ @article{sklar1959 journal={The Original Document and an English Translation (March 3, 2023)}, year={1959} } + +@article{Henrich2024, + author={Henrich, Franziska + and Hartmann, Raphael + and Pratz, Valentin + and Voss, Andreas + and Klauer, Karl Christoph}, + title={The Seven-parameter Diffusion Model: an Implementation in Stan for Bayesian Analyses}, + journal={Behavior Research Methods}, + year={2024}, + month={Jun}, + day={01}, + volume={56}, + number={4}, + pages={3102-3116}, + abstract={Diffusion models have been widely used to obtain information about cognitive processes from the analysis of responses and response-time data in two-alternative forced-choice tasks. We present an implementation of the seven-parameter diffusion model, incorporating inter-trial variabilities in drift rate, non-decision time, and relative starting point, in the probabilistic programming language Stan. Stan is a free, open-source software that gives the user much flexibility in defining model properties such as the choice of priors and the model structure in a Bayesian framework. We explain the implementation of the new function and how it is used in Stan. We then evaluate its performance in a simulation study that addresses both parameter recovery and simulation-based calibration. The recovery study shows generally good recovery of the model parameters in line with previous findings. The simulation-based calibration study validates the Bayesian algorithm as implemented in Stan.}, + issn={1554-3528}, + doi={10.3758/s13428-023-02179-1}, + url={https://doi.org/10.3758/s13428-023-02179-1} +} + +@article{Henrich_inpress, + author = {Henrich, Franziska and Klauer, Karl Christoph}, + journal = {Behavior Research Methods}, + title = {Modeling Truncated and Censored Data With the Diffusion Model in {Stan}. }, + year = {in press} +} diff --git a/src/functions-reference/functions_index.qmd b/src/functions-reference/functions_index.qmd index 8f5947ae2..fb4ffbb23 100644 --- a/src/functions-reference/functions_index.qmd +++ b/src/functions-reference/functions_index.qmd @@ -4198,6 +4198,18 @@ pagetitle: Alphabetical Index -
[distribution statement](positive_lower-bounded_distributions.qmd#index-entry-a8609b3c51ac8487f51a5e8a445e626015dad49f) (positive_lower-bounded_distributions.html)
+**wiener_lccdf_defective**: + + -
[`(real y, real alpha, real tau, real beta, real delta) : real`](positive_lower-bounded_distributions.qmd#index-entry-5cf394b88c60ad50bb55e9f2f78eda21654bd116) (positive_lower-bounded_distributions.html)
+ -
[`(real y, real alpha, real tau, real beta, real delta, real var_delta, real var_beta, real var_tau) : real`](positive_lower-bounded_distributions.qmd#index-entry-314b58777550cb95437a70d36cad4aae94a6e3ad) (positive_lower-bounded_distributions.html)
+ + +**wiener_lcdf_defective**: + + -
[`(real y, real alpha, real tau, real beta, real delta) : real`](positive_lower-bounded_distributions.qmd#index-entry-9e49bdbd55d44a5fda74aedf4effd9cc2d014d6c) (positive_lower-bounded_distributions.html)
+ -
[`(real y, real alpha, real tau, real beta, real delta, real var_delta, real var_beta, real var_tau) : real`](positive_lower-bounded_distributions.qmd#index-entry-5e22ee1f434e976af89df85159a77fcc6a64c41e) (positive_lower-bounded_distributions.html)
+ + **wiener_lpdf**: -
[`(real y | real alpha, real tau, real beta, real delta, real var_delta) : real`](positive_lower-bounded_distributions.qmd#index-entry-dd5110522b6a5fb9baac9dab11ad3dca296d7a24) (positive_lower-bounded_distributions.html)
diff --git a/src/functions-reference/positive_lower-bounded_distributions.qmd b/src/functions-reference/positive_lower-bounded_distributions.qmd index 8e007ba7d..12998b3be 100644 --- a/src/functions-reference/positive_lower-bounded_distributions.qmd +++ b/src/functions-reference/positive_lower-bounded_distributions.qmd @@ -157,6 +157,9 @@ For a description of argument and return types, see section ## Wiener First Passage Time Distribution +For an explanation how to use the `wiener_lpdf` and `wiener_l[c]cdf_defective` functions, see +@Henrich2024 and @Henrich_inpress. + ### Probability density function If $\alpha \in \mathbb{R}^+$, $\tau \in \mathbb{R}^+$, $\beta \in (0, 1)$, @@ -204,7 +207,7 @@ In the case where $s_{\delta}$, $s_{\beta}$, and $s_{\tau}$ are all $0$, this si \frac{\alpha}{(y-\tau)^{3/2}} \exp \! \left(- \delta \alpha \beta - \frac{\delta^2(y-\tau)}{2}\right) \sum_{k = - \infty}^{\infty} (2k + \beta) \phi \! \left(\frac{(2k + \beta)\alpha }{\sqrt{y - \tau}}\right), -\end{equation*} where $\phi(x)$ denotes the standard normal density function; +\end{equation*} where $\phi(x)$ denotes the standard normal density function; and one representation that converges fast for large reaction-time values ("large time expansion"): \begin{equation*} @@ -215,6 +218,46 @@ and one representation that converges fast for large reaction-time values ("larg \end{equation*} see [@Feller1968], [@NavarroFuss2009]. +### Cumulative distribution function + +For the cumulative distribution function there also exist two expressions depending on the reaction time. + +Let $\alpha$, $\tau$, $\beta$, $\delta$, $s_{\delta}$, $s_{\beta}$, $s_{\tau}$ and $y$ be as above. + +The formula for the large-time CDF of decision times (excluding the additive reaction time components summarized in $\tau$ for the time being) at the upper boundary is stated as follows: + +\begin{equation} +F(y|\alpha, \beta, \delta) = P(\alpha, \beta, \delta) - \exp\left(\delta\alpha(1-\beta)-\frac{\delta^2 y}{2}\right)F_l(y|\alpha,\beta,\delta), +\end{equation} where $P(\alpha,\beta,\delta)$ is the probability to hit the upper boundary, defined as + +\begin{equation} +P(\alpha, \beta, \delta) = \begin{cases} + \frac{1-\exp(2\delta \alpha \beta)}{\exp(-2\delta \alpha(1-\beta)) - \exp(2\delta \alpha \beta)}, & \text{for } \delta\neq 0 \\ + \beta, & \text{for } \delta=0, + \end{cases} +\end{equation} + +and + +\begin{equation} +F_l(y|\alpha, \beta, \delta) = \frac{2\pi}{\alpha^2}\sum_{k=1}^{\infty}{\frac{k\sin{k\pi(1-\beta)}}{\delta^2+(k\pi)^2/\alpha^2}}\exp(-\frac{k^2\pi^2y}{2\alpha^2}). +\end{equation} + + +The formula for the small-time CDF at the upper boundary is stated as follows: + +\begin{equation} +F(y|\alpha,\beta,\delta) = \exp\left(\delta \alpha(1-\beta) -\frac{\delta^2y}{2}\right)F_s(y|\alpha, \beta,\delta), +\end{equation} where + +\begin{equation} +F_s(y|\alpha,\beta,\delta) = \sum_{k=0}^{\infty}(-1)^k\phi\left(\frac{\alpha(k+\beta^{*}_k)}{\sqrt{y}} \right) \times \left( R \left(\frac{\alpha(k+\beta^{*}_k)+\delta y}{\sqrt{y}} \right) + R \left(\frac{\alpha(k+\beta^*_k)-\delta y}{\sqrt{y}} \right)\right), +\end{equation} + +where $\beta^*_k=(1-\beta)$ for $k$ even, $\beta^*_k=\beta$ for $k$ odd, and $R$ Mill's Ratio. + +The CDF for the lower boundary is $F(y|\alpha,1-\beta,-\delta)$ + ### Distribution statement `y ~ ` **`wiener`**`(alpha, tau, beta, delta)` @@ -303,6 +346,61 @@ of the non-decision time `var_tau`, dropping constant additive terms. Setting `var_delta`, `var_beta`, and `var_tau` to `0` recovers the 4-parameter signature above. {{< since 2.35 >}} +--- + +**Note:** The `lcdf` and `lccdf` functions for the `wiener` distribution are +implemented defectively, meaning that the functions do **not** integrate to $1$, +but rather to the probability to hit [one or the other response boundary](#boundaries). + + + +\index{{\tt \bfseries wiener\_lcdf\_defective }!{\tt (real y, real alpha, real tau, real beta, real delta): real}|hyperpage} + +`real` **`wiener_lcdf_defective`**`(real y, real alpha, real tau, real beta, real delta)`
\newline + +The log of the cumulative distribution function (CDF) of the Wiener distribution +of `y` given boundary separation `alpha`, non-decision time `tau`, a-priori bias +`beta`, and drift rate `delta`. + +{{< since 2.38 >}} + + +\index{{\tt \bfseries wiener\_lccdf\_defective }!{\tt (real y, real alpha, real tau, real beta, real delta): real}|hyperpage} + +`real` **`wiener_lccdf_defective`**`(real y, real alpha, real tau, real beta, real delta)`
\newline + +The log of the complementary cumulative distribution function (CDF) of the +Wiener distribution of `y` given boundary separation `alpha`, non-decision time +`tau`, a-priori bias `beta`, and drift rate `delta`. + +{{< since 2.38 >}} + + +\index{{\tt \bfseries wiener\_lcdf\_defective }!{\tt (real y, real alpha, real tau, real beta, real delta, real var\_delta, real var\_beta, real var\_tau): real}|hyperpage} + +`real` **`wiener_lcdf_defective`**`(real y, real alpha, real tau, real beta, real delta, real var_delta, real var_beta, real var_tau)`
\newline + +The log of the cumulative distribution function (CDF) of the Wiener distribution +of `y` given boundary separation `alpha`, non-decision time `tau`, a-priori bias +`beta`, drift rate `delta`, inter-trial drift rate variability `var_delta`, +inter-trial variability of the starting point (bias) `var_beta`, and inter-trial +variability of the non-decision time `var_tau`. + +{{< since 2.38 >}} + + + +\index{{\tt \bfseries wiener\_lccdf\_defective }!{\tt (real y, real alpha, real tau, real beta, real delta, real var\_delta, real var\_beta, real var\_tau): real}|hyperpage} + +`real` **`wiener_lccdf_defective`**`(real y, real alpha, real tau, real beta, real delta, real var_delta, real var_beta, real var_tau)`
\newline + +The log of the complementary cumulative distribution function (CDF) of the +Wiener distribution of `y` given boundary separation `alpha`, non-decision time +`tau`, a-priori bias `beta`, drift rate `delta`, inter-trial drift rate +variability `var_delta`, inter-trial variability of the starting point (bias) +`var_beta`, and inter-trial variability of the non-decision time `var_tau`. + +{{< since 2.38 >}} ### Boundaries @@ -312,3 +410,19 @@ the upper boundary only. To get the result for the lower boundary, use \text{Wiener}(y | \alpha, \tau, 1 - \beta, - \delta) \end{equation*} For more details, see the appendix of @Vandekerckhove-Wabersich:2014. + +### Vectorization + +The 5- and 7-argument forms of the `wiener` distribution functions (listed above +as recieving only `real`) are implemented in such a way where they can be +fully [vectorized](conventions_for_probability_functions.qmd#prng-vectorization), +but currently only versions that accept all `real` and all `vector` arguments +are exposed by Stan. If there are additional signatures that would prove useful, +please request them on the Stan issue tracker. + +### Tolerance tuning + +The 5- and 7-argument forms of the `wiener` distribution functions can also +accept an additional `data real` argument controlling the required precision of +the gradient calculation of the function. If omitted, this defaults to `1e-4` +for the density and `1e-8` for the cdf functions. From 67a70eec16a9b3781c77d7f51c6c4592f45b0fe6 Mon Sep 17 00:00:00 2001 From: Brian Ward Date: Tue, 16 Dec 2025 16:20:37 -0500 Subject: [PATCH 2/5] changes per review --- src/bibtex/all.bib | 5 +- .../positive_lower-bounded_distributions.qmd | 68 +++++++++++-------- 2 files changed, 41 insertions(+), 32 deletions(-) diff --git a/src/bibtex/all.bib b/src/bibtex/all.bib index 9223de516..ea8765277 100644 --- a/src/bibtex/all.bib +++ b/src/bibtex/all.bib @@ -274,7 +274,7 @@ @article{turing:1936 volume={58}, number={345-363}, pages={5}, year={1936} } - + @article{kucukelbir:2015, title={Automatic variational inference in Stan}, author={Kucukelbir, Alp and Ranganath, Rajesh and Gelman, Andrew and Blei, David}, journal={Advances in @@ -1273,7 +1273,7 @@ @article{Timonen+etal:2023:ODE-PSIS title={An importance sampling approach for reliable and efficient inference in {Bayesian} ordinary differential equation models}, author={Timonen, Juho and Siccha, Nikolas and Bales, Ben and L{\"a}hdesm{\"a}ki, Harri and Vehtari, - Aki}, journal={Stat}, year={2023}, volume = 12, number = 1, pages = {e614} + Aki}, journal={Stat}, year={2023}, volume = 12, number = 1, pages = {e614} } @article{Vehtari+etal:2024:PSIS, @@ -1347,7 +1347,6 @@ @article{Henrich2024 volume={56}, number={4}, pages={3102-3116}, - abstract={Diffusion models have been widely used to obtain information about cognitive processes from the analysis of responses and response-time data in two-alternative forced-choice tasks. We present an implementation of the seven-parameter diffusion model, incorporating inter-trial variabilities in drift rate, non-decision time, and relative starting point, in the probabilistic programming language Stan. Stan is a free, open-source software that gives the user much flexibility in defining model properties such as the choice of priors and the model structure in a Bayesian framework. We explain the implementation of the new function and how it is used in Stan. We then evaluate its performance in a simulation study that addresses both parameter recovery and simulation-based calibration. The recovery study shows generally good recovery of the model parameters in line with previous findings. The simulation-based calibration study validates the Bayesian algorithm as implemented in Stan.}, issn={1554-3528}, doi={10.3758/s13428-023-02179-1}, url={https://doi.org/10.3758/s13428-023-02179-1} diff --git a/src/functions-reference/positive_lower-bounded_distributions.qmd b/src/functions-reference/positive_lower-bounded_distributions.qmd index 12998b3be..6309a1059 100644 --- a/src/functions-reference/positive_lower-bounded_distributions.qmd +++ b/src/functions-reference/positive_lower-bounded_distributions.qmd @@ -207,8 +207,8 @@ In the case where $s_{\delta}$, $s_{\beta}$, and $s_{\tau}$ are all $0$, this si \frac{\alpha}{(y-\tau)^{3/2}} \exp \! \left(- \delta \alpha \beta - \frac{\delta^2(y-\tau)}{2}\right) \sum_{k = - \infty}^{\infty} (2k + \beta) \phi \! \left(\frac{(2k + \beta)\alpha }{\sqrt{y - \tau}}\right), -\end{equation*} where $\phi(x)$ denotes the standard normal density function; - +\end{equation*} +where $\phi(x)$ denotes the standard normal density function, and one representation that converges fast for large reaction-time values ("large time expansion"): \begin{equation*} \text{Wiener}(y|\alpha, \tau, \beta, \delta) = @@ -220,43 +220,53 @@ see [@Feller1968], [@NavarroFuss2009]. ### Cumulative distribution function -For the cumulative distribution function there also exist two expressions depending on the reaction time. +For the cumulative distribution function (cdf) there also exist two expressions +depending on the reaction time. -Let $\alpha$, $\tau$, $\beta$, $\delta$, $s_{\delta}$, $s_{\beta}$, $s_{\tau}$ and $y$ be as above. +Let $\alpha$, $\tau$, $\beta$, $\delta$, $s_{\delta}$, $s_{\beta}$, $s_{\tau}$ +and $y$ be as above. -The formula for the large-time CDF of decision times (excluding the additive reaction time components summarized in $\tau$ for the time being) at the upper boundary is stated as follows: +The formula for the large-time cdf of decision times (excluding the additive +reaction time components summarized in $\tau$ for the time being) at the upper +boundary is stated as follows: \begin{equation} -F(y|\alpha, \beta, \delta) = P(\alpha, \beta, \delta) - \exp\left(\delta\alpha(1-\beta)-\frac{\delta^2 y}{2}\right)F_l(y|\alpha,\beta,\delta), -\end{equation} where $P(\alpha,\beta,\delta)$ is the probability to hit the upper boundary, defined as +F(y|\alpha, \beta, \delta) = P(\alpha, \beta, \delta) - + \exp\left(\delta\alpha(1-\beta)-\frac{\delta^2 y}{2}\right)F_l(y|\alpha,\beta,\delta), +\end{equation} +where $P(\alpha,\beta,\delta)$ is the probability to hit the upper boundary, defined as \begin{equation} -P(\alpha, \beta, \delta) = \begin{cases} +P(\alpha, \beta, \delta) = +\begin{cases} \frac{1-\exp(2\delta \alpha \beta)}{\exp(-2\delta \alpha(1-\beta)) - \exp(2\delta \alpha \beta)}, & \text{for } \delta\neq 0 \\ \beta, & \text{for } \delta=0, - \end{cases} +\end{cases} \end{equation} and \begin{equation} -F_l(y|\alpha, \beta, \delta) = \frac{2\pi}{\alpha^2}\sum_{k=1}^{\infty}{\frac{k\sin{k\pi(1-\beta)}}{\delta^2+(k\pi)^2/\alpha^2}}\exp(-\frac{k^2\pi^2y}{2\alpha^2}). +F_l(y|\alpha, \beta, \delta) = + \frac{2\pi}{\alpha^2}\sum_{k=1}^{\infty}{\frac{k\sin{k\pi(1-\beta)}}{\delta^2+(k\pi)^2/\alpha^2}}\exp(-\frac{k^2\pi^2y}{2\alpha^2}). \end{equation} -The formula for the small-time CDF at the upper boundary is stated as follows: +The formula for the small-time cdf at the upper boundary is stated as follows: \begin{equation} F(y|\alpha,\beta,\delta) = \exp\left(\delta \alpha(1-\beta) -\frac{\delta^2y}{2}\right)F_s(y|\alpha, \beta,\delta), \end{equation} where \begin{equation} -F_s(y|\alpha,\beta,\delta) = \sum_{k=0}^{\infty}(-1)^k\phi\left(\frac{\alpha(k+\beta^{*}_k)}{\sqrt{y}} \right) \times \left( R \left(\frac{\alpha(k+\beta^{*}_k)+\delta y}{\sqrt{y}} \right) + R \left(\frac{\alpha(k+\beta^*_k)-\delta y}{\sqrt{y}} \right)\right), +F_s(y|\alpha,\beta,\delta) = \sum_{k=0}^{\infty}(-1)^k\phi\left(\frac{\alpha(k+\beta^{*}_k)} + {\sqrt{y}} \right) \times \left( R \left(\frac{\alpha(k+\beta^{*}_k)+\delta y}{\sqrt{y}} \right) + + R \left(\frac{\alpha(k+\beta^*_k)-\delta y}{\sqrt{y}} \right)\right), \end{equation} -where $\beta^*_k=(1-\beta)$ for $k$ even, $\beta^*_k=\beta$ for $k$ odd, and $R$ Mill's Ratio. +where $\beta^*_k=(1-\beta)$ for $k$ even, $\beta^*_k=\beta$ for $k$ odd, and $R$ is Mill's ratio. -The CDF for the lower boundary is $F(y|\alpha,1-\beta,-\delta)$ +The cdf for the lower boundary is $F(y|\alpha,1-\beta,-\delta)$ ### Distribution statement @@ -283,7 +293,7 @@ Increment target log probability density with `wiener_lupdf(y | alpha, tau, beta `real` **`wiener_lpdf`**`(reals y | reals alpha, reals tau, reals beta, reals delta)`
\newline The log of the Wiener first passage time density of `y` given boundary -separation `alpha`, non-decision time `tau`, a-priori bias `beta`, and drift +separation `alpha`, non-decision time `tau`, starting point `beta`, and drift rate `delta`. {{< since 2.18 >}} @@ -292,7 +302,7 @@ rate `delta`. `real` **`wiener_lpdf`**`(real y | real alpha, real tau, real beta, real delta, real var_delta)`
\newline The log of the Wiener first passage time density of `y` given boundary -separation `alpha`, non-decision time `tau`, a-priori bias `beta`, drift +separation `alpha`, non-decision time `tau`, starting point `beta`, drift rate `delta`, and inter-trial drift rate variability `var_delta`. Setting `var_delta` to `0` recovers the 4-parameter signature above. @@ -303,7 +313,7 @@ Setting `var_delta` to `0` recovers the 4-parameter signature above. `real` **`wiener_lpdf`**`(real y | real alpha, real tau, real beta, real delta, real var_delta, real var_beta, real var_tau)`
\newline The log of the Wiener first passage time density of `y` given boundary -separation `alpha`, non-decision time `tau`, a-priori bias `beta`, drift +separation `alpha`, non-decision time `tau`, starting point `beta`, drift rate `delta`, inter-trial drift rate variability `var_delta`, inter-trial variability of the starting point (bias) `var_beta`, and inter-trial variability of the non-decision time `var_tau`. @@ -316,7 +326,7 @@ Setting `var_delta`, `var_beta`, and `var_tau` to `0` recovers the 4-parameter s `real` **`wiener_lupdf`**`(reals y | reals alpha, reals tau, reals beta, reals delta)`
\newline The log of the Wiener first passage time density of `y` given boundary -separation `alpha`, non-decision time `tau`, a-priori bias `beta`, and drift +separation `alpha`, non-decision time `tau`, starting point `beta`, and drift rate `delta`, dropping constant additive terms {{< since 2.25 >}} @@ -326,7 +336,7 @@ rate `delta`, dropping constant additive terms `real` **`wiener_lupdf`**`(real y | real alpha, real tau, real beta, real delta, real var_delta)`
\newline The log of the Wiener first passage time density of `y` given boundary -separation `alpha`, non-decision time `tau`, a-priori bias `beta`, drift +separation `alpha`, non-decision time `tau`, starting point `beta`, drift rate `delta`, and inter-trial drift rate variability `var_delta`, dropping constant additive terms. @@ -338,7 +348,7 @@ Setting `var_delta` to `0` recovers the 4-parameter signature above. `real` **`wiener_lupdf`**`(real y | real alpha, real tau, real beta, real delta, real var_delta, real var_beta, real var_tau)`
\newline The log of the Wiener first passage time density of `y` given boundary -separation `alpha`, non-decision time `tau`, a-priori bias `beta`, drift +separation `alpha`, non-decision time `tau`, starting point `beta`, drift rate `delta`, inter-trial drift rate variability `var_delta`, inter-trial variability of the starting point (bias) `var_beta`, and inter-trial variability of the non-decision time `var_tau`, dropping constant additive terms. @@ -358,8 +368,8 @@ but rather to the probability to hit [one or the other response boundary](#bound `real` **`wiener_lcdf_defective`**`(real y, real alpha, real tau, real beta, real delta)`
\newline -The log of the cumulative distribution function (CDF) of the Wiener distribution -of `y` given boundary separation `alpha`, non-decision time `tau`, a-priori bias +The log of the cumulative distribution function (cdf) of the Wiener distribution +of `y` given boundary separation `alpha`, non-decision time `tau`, starting point `beta`, and drift rate `delta`. {{< since 2.38 >}} @@ -369,9 +379,9 @@ of `y` given boundary separation `alpha`, non-decision time `tau`, a-priori bias `real` **`wiener_lccdf_defective`**`(real y, real alpha, real tau, real beta, real delta)`
\newline -The log of the complementary cumulative distribution function (CDF) of the +The log of the complementary cumulative distribution function (ccdf) of the Wiener distribution of `y` given boundary separation `alpha`, non-decision time -`tau`, a-priori bias `beta`, and drift rate `delta`. +`tau`, starting point `beta`, and drift rate `delta`. {{< since 2.38 >}} @@ -380,8 +390,8 @@ Wiener distribution of `y` given boundary separation `alpha`, non-decision time `real` **`wiener_lcdf_defective`**`(real y, real alpha, real tau, real beta, real delta, real var_delta, real var_beta, real var_tau)`
\newline -The log of the cumulative distribution function (CDF) of the Wiener distribution -of `y` given boundary separation `alpha`, non-decision time `tau`, a-priori bias +The log of the cumulative distribution function (cdf) of the Wiener distribution +of `y` given boundary separation `alpha`, non-decision time `tau`, starting point `beta`, drift rate `delta`, inter-trial drift rate variability `var_delta`, inter-trial variability of the starting point (bias) `var_beta`, and inter-trial variability of the non-decision time `var_tau`. @@ -394,9 +404,9 @@ variability of the non-decision time `var_tau`. `real` **`wiener_lccdf_defective`**`(real y, real alpha, real tau, real beta, real delta, real var_delta, real var_beta, real var_tau)`
\newline -The log of the complementary cumulative distribution function (CDF) of the +The log of the complementary cumulative distribution function (ccdf) of the Wiener distribution of `y` given boundary separation `alpha`, non-decision time -`tau`, a-priori bias `beta`, drift rate `delta`, inter-trial drift rate +`tau`, starting point `beta`, drift rate `delta`, inter-trial drift rate variability `var_delta`, inter-trial variability of the starting point (bias) `var_beta`, and inter-trial variability of the non-decision time `var_tau`. @@ -418,7 +428,7 @@ as recieving only `real`) are implemented in such a way where they can be fully [vectorized](conventions_for_probability_functions.qmd#prng-vectorization), but currently only versions that accept all `real` and all `vector` arguments are exposed by Stan. If there are additional signatures that would prove useful, -please request them on the Stan issue tracker. +please request them by [opening an issue](https://github.com/stan-dev/stanc3/issues/new). ### Tolerance tuning From 88432f4cbdd6a7d8b738a800ef95f875c161e7b2 Mon Sep 17 00:00:00 2001 From: Brian Ward Date: Tue, 16 Dec 2025 16:50:28 -0500 Subject: [PATCH 3/5] Fix comment on defective name --- .../positive_lower-bounded_distributions.qmd | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/functions-reference/positive_lower-bounded_distributions.qmd b/src/functions-reference/positive_lower-bounded_distributions.qmd index 6309a1059..aa906088b 100644 --- a/src/functions-reference/positive_lower-bounded_distributions.qmd +++ b/src/functions-reference/positive_lower-bounded_distributions.qmd @@ -359,8 +359,11 @@ Setting `var_delta`, `var_beta`, and `var_tau` to `0` recovers the 4-parameter s --- **Note:** The `lcdf` and `lccdf` functions for the `wiener` distribution are -implemented defectively, meaning that the functions do **not** integrate to $1$, -but rather to the probability to hit [one or the other response boundary](#boundaries). +implemented defectively, meaning that the cdf does not asymptote at 1, +but rather at the probability to hit the upper [boundary](#boundaries). + +Similarly, the ccdf is defined as the probability to hit the upper boundary less +the value of the cdf, as opposed to the more typical $1 - \textrm{cdf}$. From 7e8a89fb5c428be76a9f8c29fb007abc18f75f66 Mon Sep 17 00:00:00 2001 From: Brian Ward Date: Wed, 17 Dec 2025 11:12:37 -0500 Subject: [PATCH 4/5] Update to _unnorm --- src/functions-reference/functions_index.qmd | 12 ++++---- .../positive_lower-bounded_distributions.qmd | 28 +++++++++---------- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/src/functions-reference/functions_index.qmd b/src/functions-reference/functions_index.qmd index fb4ffbb23..4a50e6c70 100644 --- a/src/functions-reference/functions_index.qmd +++ b/src/functions-reference/functions_index.qmd @@ -4198,16 +4198,16 @@ pagetitle: Alphabetical Index -
[distribution statement](positive_lower-bounded_distributions.qmd#index-entry-a8609b3c51ac8487f51a5e8a445e626015dad49f) (positive_lower-bounded_distributions.html)
-**wiener_lccdf_defective**: +**wiener_lccdf_unnorm**: - -
[`(real y, real alpha, real tau, real beta, real delta) : real`](positive_lower-bounded_distributions.qmd#index-entry-5cf394b88c60ad50bb55e9f2f78eda21654bd116) (positive_lower-bounded_distributions.html)
- -
[`(real y, real alpha, real tau, real beta, real delta, real var_delta, real var_beta, real var_tau) : real`](positive_lower-bounded_distributions.qmd#index-entry-314b58777550cb95437a70d36cad4aae94a6e3ad) (positive_lower-bounded_distributions.html)
+ -
[`(real y, real alpha, real tau, real beta, real delta) : real`](positive_lower-bounded_distributions.qmd#index-entry-fd7dd400c38dd551f61ba9778cad3aefbb675a5e) (positive_lower-bounded_distributions.html)
+ -
[`(real y, real alpha, real tau, real beta, real delta, real var_delta, real var_beta, real var_tau) : real`](positive_lower-bounded_distributions.qmd#index-entry-d195ea5f4d8eba49c56313a0623fd5deb56d02fd) (positive_lower-bounded_distributions.html)
-**wiener_lcdf_defective**: +**wiener_lcdf_unnorm**: - -
[`(real y, real alpha, real tau, real beta, real delta) : real`](positive_lower-bounded_distributions.qmd#index-entry-9e49bdbd55d44a5fda74aedf4effd9cc2d014d6c) (positive_lower-bounded_distributions.html)
- -
[`(real y, real alpha, real tau, real beta, real delta, real var_delta, real var_beta, real var_tau) : real`](positive_lower-bounded_distributions.qmd#index-entry-5e22ee1f434e976af89df85159a77fcc6a64c41e) (positive_lower-bounded_distributions.html)
+ -
[`(real y, real alpha, real tau, real beta, real delta) : real`](positive_lower-bounded_distributions.qmd#index-entry-ffe70852994a9eadec88b671cd728e98feffb122) (positive_lower-bounded_distributions.html)
+ -
[`(real y, real alpha, real tau, real beta, real delta, real var_delta, real var_beta, real var_tau) : real`](positive_lower-bounded_distributions.qmd#index-entry-59df6a6c983bf3f79c62ff8031367686b0ffa70a) (positive_lower-bounded_distributions.html)
**wiener_lpdf**: diff --git a/src/functions-reference/positive_lower-bounded_distributions.qmd b/src/functions-reference/positive_lower-bounded_distributions.qmd index aa906088b..a00e33c71 100644 --- a/src/functions-reference/positive_lower-bounded_distributions.qmd +++ b/src/functions-reference/positive_lower-bounded_distributions.qmd @@ -157,7 +157,7 @@ For a description of argument and return types, see section ## Wiener First Passage Time Distribution -For an explanation how to use the `wiener_lpdf` and `wiener_l[c]cdf_defective` functions, see +For an explanation how to use the `wiener_lpdf` and `wiener_l[c]cdf_unnorm` functions, see @Henrich2024 and @Henrich_inpress. ### Probability density function @@ -359,17 +359,17 @@ Setting `var_delta`, `var_beta`, and `var_tau` to `0` recovers the 4-parameter s --- **Note:** The `lcdf` and `lccdf` functions for the `wiener` distribution are -implemented defectively, meaning that the cdf does not asymptote at 1, +conditional and unnormalized, meaning that the cdf does not asymptote at 1, but rather at the probability to hit the upper [boundary](#boundaries). Similarly, the ccdf is defined as the probability to hit the upper boundary less the value of the cdf, as opposed to the more typical $1 - \textrm{cdf}$. - -\index{{\tt \bfseries wiener\_lcdf\_defective }!{\tt (real y, real alpha, real tau, real beta, real delta): real}|hyperpage} + +\index{{\tt \bfseries wiener\_lcdf\_unnorm }!{\tt (real y, real alpha, real tau, real beta, real delta): real}|hyperpage} -`real` **`wiener_lcdf_defective`**`(real y, real alpha, real tau, real beta, real delta)`
\newline +`real` **`wiener_lcdf_unnorm`**`(real y, real alpha, real tau, real beta, real delta)`
\newline The log of the cumulative distribution function (cdf) of the Wiener distribution of `y` given boundary separation `alpha`, non-decision time `tau`, starting point @@ -377,10 +377,10 @@ of `y` given boundary separation `alpha`, non-decision time `tau`, starting poin {{< since 2.38 >}} - -\index{{\tt \bfseries wiener\_lccdf\_defective }!{\tt (real y, real alpha, real tau, real beta, real delta): real}|hyperpage} + +\index{{\tt \bfseries wiener\_lccdf\_unnorm }!{\tt (real y, real alpha, real tau, real beta, real delta): real}|hyperpage} -`real` **`wiener_lccdf_defective`**`(real y, real alpha, real tau, real beta, real delta)`
\newline +`real` **`wiener_lccdf_unnorm`**`(real y, real alpha, real tau, real beta, real delta)`
\newline The log of the complementary cumulative distribution function (ccdf) of the Wiener distribution of `y` given boundary separation `alpha`, non-decision time @@ -388,10 +388,10 @@ Wiener distribution of `y` given boundary separation `alpha`, non-decision time {{< since 2.38 >}} - -\index{{\tt \bfseries wiener\_lcdf\_defective }!{\tt (real y, real alpha, real tau, real beta, real delta, real var\_delta, real var\_beta, real var\_tau): real}|hyperpage} + +\index{{\tt \bfseries wiener\_lcdf\_unnorm }!{\tt (real y, real alpha, real tau, real beta, real delta, real var\_delta, real var\_beta, real var\_tau): real}|hyperpage} -`real` **`wiener_lcdf_defective`**`(real y, real alpha, real tau, real beta, real delta, real var_delta, real var_beta, real var_tau)`
\newline +`real` **`wiener_lcdf_unnorm`**`(real y, real alpha, real tau, real beta, real delta, real var_delta, real var_beta, real var_tau)`
\newline The log of the cumulative distribution function (cdf) of the Wiener distribution of `y` given boundary separation `alpha`, non-decision time `tau`, starting point @@ -402,10 +402,10 @@ variability of the non-decision time `var_tau`. {{< since 2.38 >}} - -\index{{\tt \bfseries wiener\_lccdf\_defective }!{\tt (real y, real alpha, real tau, real beta, real delta, real var\_delta, real var\_beta, real var\_tau): real}|hyperpage} + +\index{{\tt \bfseries wiener\_lccdf\_unnorm }!{\tt (real y, real alpha, real tau, real beta, real delta, real var\_delta, real var\_beta, real var\_tau): real}|hyperpage} -`real` **`wiener_lccdf_defective`**`(real y, real alpha, real tau, real beta, real delta, real var_delta, real var_beta, real var_tau)`
\newline +`real` **`wiener_lccdf_unnorm`**`(real y, real alpha, real tau, real beta, real delta, real var_delta, real var_beta, real var_tau)`
\newline The log of the complementary cumulative distribution function (ccdf) of the Wiener distribution of `y` given boundary separation `alpha`, non-decision time From cb1482b50d3d3bb7052a23f7532c58f59f1d3369 Mon Sep 17 00:00:00 2001 From: Brian Ward Date: Thu, 18 Dec 2025 09:57:32 -0500 Subject: [PATCH 5/5] Remove in-press citation --- src/bibtex/all.bib | 6 ------ .../positive_lower-bounded_distributions.qmd | 4 ++-- 2 files changed, 2 insertions(+), 8 deletions(-) diff --git a/src/bibtex/all.bib b/src/bibtex/all.bib index ea8765277..02b7c034b 100644 --- a/src/bibtex/all.bib +++ b/src/bibtex/all.bib @@ -1352,9 +1352,3 @@ @article{Henrich2024 url={https://doi.org/10.3758/s13428-023-02179-1} } -@article{Henrich_inpress, - author = {Henrich, Franziska and Klauer, Karl Christoph}, - journal = {Behavior Research Methods}, - title = {Modeling Truncated and Censored Data With the Diffusion Model in {Stan}. }, - year = {in press} -} diff --git a/src/functions-reference/positive_lower-bounded_distributions.qmd b/src/functions-reference/positive_lower-bounded_distributions.qmd index a00e33c71..9919e8245 100644 --- a/src/functions-reference/positive_lower-bounded_distributions.qmd +++ b/src/functions-reference/positive_lower-bounded_distributions.qmd @@ -157,8 +157,8 @@ For a description of argument and return types, see section ## Wiener First Passage Time Distribution -For an explanation how to use the `wiener_lpdf` and `wiener_l[c]cdf_unnorm` functions, see -@Henrich2024 and @Henrich_inpress. +For an extended explanation of how to use the `wiener_lpdf` and +`wiener_l[c]cdf_unnorm` functions, see @Henrich2024. ### Probability density function