Skip to content

Commit 53f47d2

Browse files
WardBrianWardBrian
committed
More signature work
1 parent bffbede commit 53f47d2

File tree

2 files changed

+221
-93
lines changed

2 files changed

+221
-93
lines changed

‎src/functions-reference/embedded_laplace.qmd

Lines changed: 141 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -112,16 +112,31 @@ The size of $\theta_0$ must be consistent with the size of the $\theta$ argument
112112
passed to `ll_function`.
113113

114114
The signature of the function is:
115-
```
116-
real laplace_marginal(function ll_function, tuple(...), vector theta_0,
117-
function K_function, tuple(...));
118-
```
115+
116+
<!-- real; laplace_marginal; (function ll_function, tuple(...), vector theta0, function K_function, tuple(...)); -->
117+
\index{{\tt \bfseries laplace\_marginal }!{\tt (function ll\_function, tuple(...), vector theta0, function K\_function, tuple(...)): real}|hyperpage}
118+
119+
`real` **`laplace_marginal`**`(function ll_function, tuple(...), vector theta0, function K_function, tuple(...))`<br>\newline
120+
121+
TODO description.
122+
{{< since 2.37 >}}
123+
124+
119125
The `tuple(...)` after `ll_function` contains the arguments that get passed
120126
to `ll_function` *excluding $\theta$*. Likewise, the `tuple(...)` after
121-
`ll_function` contains the arguments that get passed to `K_function`.
127+
`K_function` contains the arguments that get passed to `K_function`.
122128

123129
It also possible to specify control parameters, which can help improve the
124-
optimization that underlies the Laplace approximation. Specifically:
130+
optimization that underlies the Laplace approximation, using `laplace_marginal_tol`
131+
with the following signature:
132+
133+
<!-- real; laplace_marginal_tol; (function ll_function, tuple(...), vector theta0, function K_function, tuple(...), real tol, int max_steps, int hessian_block_size, int solver, int max_steps_linesearch); -->
134+
\index{{\tt \bfseries laplace\_marginal\_tol }!{\tt (function ll\_function, tuple(...), vector theta0, function K\_function, tuple(...), real tol, int max\_steps, int hessian\_block\_size, int solver, int max\_steps\_linesearch): real}|hyperpage}
135+
136+
`real` **`laplace_marginal_tol`**`(function ll_function, tuple(...), vector theta0, function K_function, tuple(...), real tol, int max_steps, int hessian_block_size, int solver, int max_steps_linesearch)`<br>\newline
137+
138+
TODO description.
139+
125140

126141
* `tol`: the tolerance $\epsilon$ of the optimizer. Specifically, the optimizer
127142
stops when $||\nabla \log p(\theta \mid y, \phi)|| \le \epsilon$. By default,
@@ -156,34 +171,31 @@ the step is repeatedly halved until the objective function decreases or the
156171
maximum number of steps in the linesearch is reached. By default,
157172
`max_steps_linesearch=0`, meaning no linesearch is performed.
158173

159-
With these arguments at hand, we can call `laplace_marginal_tol` with the
160-
following signature:
161-
```
162-
target += laplace_margina_tol(function ll_function, tuple(...), vector theta_0,
163-
function K_function, tuple(...),
164-
real tol, int max_steps, int hessian_block_size,
165-
int solver, int max_steps_linesearch);
166-
```
174+
{{< since 2.37 >}}
167175

168176
## Sample from the approximate conditional $\hat{p}(\theta \mid y, \phi)$
169177

170178
In `generated quantities`, it is possible to sample from the Laplace
171179
approximation of $p(\theta \mid \phi, y)$ using `laplace_latent_rng`.
172180
The signature for `laplace_latent_rng` follows closely
173181
the signature for `laplace_marginal`:
174-
```
175-
vector theta =
176-
laplace_latent_rng(function ll_function, tuple(...), vector theta_0,
177-
function K_function, tuple(...));
178-
```
182+
183+
<!-- vector; laplace_latent_rng; (function ll_function, tuple(...), vector theta0, function K_function, tuple(...)); -->
184+
\index{{\tt \bfseries laplace\_latent\_rng }!{\tt (function ll\_function, tuple(...), vector theta0, function K\_function, tuple(...)): vector}|hyperpage}
185+
186+
`vector` **`laplace_latent_rng`**`(function ll_function, tuple(...), vector theta0, function K_function, tuple(...))`<br>\newline
187+
188+
TODO description.
189+
{{< since 2.37 >}}
190+
179191
Once again, it is possible to specify control parameters:
180-
```
181-
vector theta =
182-
laplace_latent_tol_rng(function ll_function, tuple(...), vector theta_0,
183-
function K_function, tuple(...),
184-
real tol, int max_steps, int hessian_block_size,
185-
int solver, int max_steps_linesearch);
186-
```
192+
<!-- vector; laplace_latent_tol_rng; (function ll_function, tuple(...), vector theta0, function K_function, tuple(...), real tol, int max_steps, int hessian_block_size, int solver, int max_steps_linesearch); -->
193+
\index{{\tt \bfseries laplace\_latent\_tol\_rng }!{\tt (function ll\_function, tuple(...), vector theta0, function K\_function, tuple(...), real tol, int max\_steps, int hessian\_block\_size, int solver, int max\_steps\_linesearch): vector}|hyperpage}
194+
195+
`vector` **`laplace_latent_tol_rng`**`(function ll_function, tuple(...), vector theta0, function K_function, tuple(...), real tol, int max_steps, int hessian_block_size, int solver, int max_steps_linesearch)`<br>\newline
196+
197+
TODO description.
198+
{{< since 2.37 >}}
187199

188200
## Built-in Laplace marginal likelihood functions
189201

@@ -210,32 +222,36 @@ group the $i^\text{th}$ observation belongs to.
210222
The signatures for the embedded Laplace approximation function with a Poisson
211223
likelihood are
212224

213-
<!-- real; laplace_marginal_poisson_log_lpmf; (array[] int y \textbar\ array[] int y_index, vector theta0, function K_function, tuple(...)); -->
225+
<!-- real; laplace_marginal_poisson_log_lpmf; (array[] int y | array[] int y_index, vector theta0, function K_function, tuple(...)); -->
214226
\index{{\tt \bfseries laplace\_marginal\_poisson\_log\_lpmf }!{\tt (array[] int y \textbar\ array[] int y\_index, vector theta0, function K\_function, tuple(...)): real}|hyperpage}
215227

216-
`real` **`laplace_marginal_poisson_log_lpmf`**`(array[] int y \textbar\ array[] int y_index, vector theta0, function K_function, tuple(...))`<br>\newline
228+
`real` **`laplace_marginal_poisson_log_lpmf`**`(array[] int y | array[] int y_index, vector theta0, function K_function, tuple(...))`<br>\newline
217229

230+
TODO description.
218231
{{< since 2.37 >}}
219232

220-
<!-- real; laplace_marginal_tol_poisson_log_lpmf; (array[] int y \textbar\ array[] int y_index, vector theta0, function K_function, tuple(...), real tol, int max_steps, int hessian_block_size, int solver, int max_steps_linesearch); -->
233+
<!-- real; laplace_marginal_tol_poisson_log_lpmf; (array[] int y | array[] int y_index, vector theta0, function K_function, tuple(...), real tol, int max_steps, int hessian_block_size, int solver, int max_steps_linesearch); -->
221234
\index{{\tt \bfseries laplace\_marginal\_tol\_poisson\_log\_lpmf }!{\tt (array[] int y \textbar\ array[] int y\_index, vector theta0, function K\_function, tuple(...), real tol, int max\_steps, int hessian\_block\_size, int solver, int max\_steps\_linesearch): real}|hyperpage}
222235

223-
`real` **`laplace_marginal_tol_poisson_log_lpmf`**`(array[] int y \textbar\ array[] int y_index, vector theta0, function K_function, tuple(...), real tol, int max_steps, int hessian_block_size, int solver, int max_steps_linesearch)`<br>\newline
236+
`real` **`laplace_marginal_tol_poisson_log_lpmf`**`(array[] int y | array[] int y_index, vector theta0, function K_function, tuple(...), real tol, int max_steps, int hessian_block_size, int solver, int max_steps_linesearch)`<br>\newline
224237

238+
TODO description.
225239
{{< since 2.37 >}}
226240

227241
<!-- vector; laplace_latent_poisson_log_rng; (array[] int y, array[] int y_index, vector theta0, function K_function, tuple(...)); -->
228242
\index{{\tt \bfseries laplace\_latent\_poisson\_log\_rng }!{\tt (array[] int y, array[] int y\_index, vector theta0, function K\_function, tuple(...)): vector}|hyperpage}
229243

230244
`vector` **`laplace_latent_poisson_log_rng`**`(array[] int y, array[] int y_index, vector theta0, function K_function, tuple(...))`<br>\newline
231245

246+
TODO description.
232247
{{< since 2.37 >}}
233248

234249
<!-- vector; laplace_latent_tol_poisson_log_rng; (array[] int y, array[] int y_index, vector theta0, function K_function, tuple(...), real tol, int max_steps, int hessian_block_size, int solver, int max_steps_linesearch); -->
235250
\index{{\tt \bfseries laplace\_latent\_tol\_poisson\_log\_rng }!{\tt (array[] int y, array[] int y\_index, vector theta0, function K\_function, tuple(...), real tol, int max\_steps, int hessian\_block\_size, int solver, int max\_steps\_linesearch): vector}|hyperpage}
236251

237252
`vector` **`laplace_latent_tol_poisson_log_rng`**`(array[] int y, array[] int y_index, vector theta0, function K_function, tuple(...), real tol, int max_steps, int hessian_block_size, int solver, int max_steps_linesearch)`<br>\newline
238253

254+
TODO description.
239255
{{< since 2.37 >}}
240256

241257
A similar built-in likelihood lets users specify an offset $x_i \in \mathbb R^+$
@@ -244,27 +260,38 @@ $$
244260
p(y \mid \theta, \phi) = \prod_i\text{Poisson} (y_i \mid \exp(\theta_{g(i)}) x_i).
245261
$$
246262
The signatures for this function are:
247-
```
248-
real laplace_marginal_poisson2_log_lpmf(array[] int y | array[] int y_index,
249-
vector x, vector theta0,
250-
function K_function, tuple(...));
251-
252-
real laplace_marginal_tol_poisson2_log_lpmf(array[] int y | array[] int y_index,
253-
vector x, vector theta0,
254-
function K_function, tuple(...),
255-
real tol, int max_steps, int hessian_block_size,
256-
int solver, int max_steps_linesearch);
257-
258-
vector laplace_latent_poisson2_log_rng(array[] int y, array[] int y_index,
259-
vector x, vector theta0,
260-
function K_function, tuple(...));
261-
262-
vector laplace_latent_tol_poisson2_log_rng(array[] int y, array[] int y_index,
263-
vector x, vector theta0,
264-
function K_function, tuple(...),
265-
real tol, int max_steps, int hessian_block_size,
266-
int solver, int max_steps_linesearch);
267-
```
263+
264+
<!-- real; laplace_marginal_poisson_2_log_lpmf; (array[] int y | array[] int y_index, vector x, vector theta0, function K_function, tuple(...)); -->
265+
\index{{\tt \bfseries laplace\_marginal\_poisson\_2\_log\_lpmf }!{\tt (array[] int y \textbar\ array[] int y\_index, vector theta0, function K\_function, tuple(...)): real}|hyperpage}
266+
267+
`real` **`laplace_marginal_poisson_2_log_lpmf`**`(array[] int y | array[] int y_index, vector x, vector theta0, function K_function, tuple(...))`<br>\newline
268+
269+
TODO description.
270+
{{< since 2.37 >}}
271+
272+
<!-- real; laplace_marginal_tol_poisson_2_log_lpmf; (array[] int y | array[] int y_index, vector x, vector theta0, function K_function, tuple(...), real tol, int max_steps, int hessian_block_size, int solver, int max_steps_linesearch); -->
273+
\index{{\tt \bfseries laplace\_marginal\_tol\_poisson\_2\_log\_lpmf }!{\tt (array[] int y \textbar\ array[] int y\_index, vector theta0, function K\_function, tuple(...), real tol, int max\_steps, int hessian\_block\_size, int solver, int max\_steps\_linesearch): real}|hyperpage}
274+
275+
`real` **`laplace_marginal_tol_poisson_2_log_lpmf`**`(array[] int y | array[] int y_index, vector x, vector theta0, function K_function, tuple(...), real tol, int max_steps, int hessian_block_size, int solver, int max_steps_linesearch)`<br>\newline
276+
277+
TODO description.
278+
{{< since 2.37 >}}
279+
280+
<!-- vector; laplace_latent_poisson_2_log_rng; (array[] int y, array[] int y_index, vector x, vector theta0, function K_function, tuple(...)); -->
281+
\index{{\tt \bfseries laplace\_latent\_poisson\_2\_log\_rng }!{\tt (array[] int y, array[] int y\_index, vector theta0, function K\_function, tuple(...)): vector}|hyperpage}
282+
283+
`vector` **`laplace_latent_poisson_2_log_rng`**`(array[] int y, array[] int y_index, vector x, vector theta0, function K_function, tuple(...))`<br>\newline
284+
285+
TODO description.
286+
{{< since 2.37 >}}
287+
288+
<!-- vector; laplace_latent_tol_poisson_2_log_rng; (array[] int y, array[] int y_index, vector x, vector theta0, function K_function, tuple(...), real tol, int max_steps, int hessian_block_size, int solver, int max_steps_linesearch); -->
289+
\index{{\tt \bfseries laplace\_latent\_tol\_poisson\_2\_log\_rng }!{\tt (array[] int y, array[] int y\_index, vector theta0, function K\_function, tuple(...), real tol, int max\_steps, int hessian\_block\_size, int solver, int max\_steps\_linesearch): vector}|hyperpage}
290+
291+
`vector` **`laplace_latent_tol_poisson_2_log_rng`**`(array[] int y, array[] int y_index, vector x, vector theta0, function K_function, tuple(...), real tol, int max_steps, int hessian_block_size, int solver, int max_steps_linesearch)`<br>\newline
292+
293+
TODO description.
294+
{{< since 2.37 >}}
268295

269296

270297
### Negative Binomial with log link
@@ -288,27 +315,37 @@ group the $i^\text{th}$ observation belongs to.
288315

289316
The function signatures for the embedded Laplace approximation with a negative
290317
Binomial likelihood are
291-
```
292-
real laplace_marginal_neg_binomial_2_log_lpmf(array[] int y |
293-
array[] int y_index, real eta, vector theta0,
294-
function K_function, tuple(...));
295-
296-
real laplace_marginal_tol_neg_binomial_2_log_lpmf(array[] int y |
297-
array[] int y_index, real eta, vector theta0,
298-
function K_function, tuple(...),
299-
real tol, int max_steps, int hessian_block_size,
300-
int solver, int max_steps_linesearch);
301-
302-
vector laplace_latent_neg_binomial_2_log_rng(array[] int y,
303-
array[] int y_index, real eta, vector theta0,
304-
function K_function, tuple(...));
305-
306-
vector laplace_latent_tol_neg_binomial_2_log_rng(array[] int y,
307-
array[] int y_index, real eta, vector theta0,
308-
function K_function, tuple(...),
309-
real tol, int max_steps, int hessian_block_size,
310-
int solver, int max_steps_linesearch);
311-
```
318+
<!-- real; laplace_marginal_neg_binomial_2_log_lpmf; (array[] int y | array[] int y_index, real eta, vector theta0, function K_function, tuple(...)); -->
319+
\index{{\tt \bfseries laplace\_marginal\_neg\_binomial\_2\_log\_lpmf }!{\tt (array[] int y \textbar\ array[] int y\_index, vector theta0, function K\_function, tuple(...)): real}|hyperpage}
320+
321+
`real` **`laplace_marginal_neg_binomial_2_log_lpmf`**`(array[] int y | array[] int y_index, real eta, vector theta0, function K_function, tuple(...))`<br>\newline
322+
323+
TODO description.
324+
{{< since 2.37 >}}
325+
326+
<!-- real; laplace_marginal_tol_neg_binomial_2_log_lpmf; (array[] int y | array[] int y_index, real eta, vector theta0, function K_function, tuple(...), real tol, int max_steps, int hessian_block_size, int solver, int max_steps_linesearch); -->
327+
\index{{\tt \bfseries laplace\_marginal\_tol\_neg\_binomial\_2\_log\_lpmf }!{\tt (array[] int y \textbar\ array[] int y\_index, vector theta0, function K\_function, tuple(...), real tol, int max\_steps, int hessian\_block\_size, int solver, int max\_steps\_linesearch): real}|hyperpage}
328+
329+
`real` **`laplace_marginal_tol_neg_binomial_2_log_lpmf`**`(array[] int y | array[] int y_index, real eta, vector theta0, function K_function, tuple(...), real tol, int max_steps, int hessian_block_size, int solver, int max_steps_linesearch)`<br>\newline
330+
331+
TODO description.
332+
{{< since 2.37 >}}
333+
334+
<!-- vector; laplace_latent_neg_binomial_2_log_rng; (array[] int y, array[] int y_index, real eta, vector theta0, function K_function, tuple(...)); -->
335+
\index{{\tt \bfseries laplace\_latent\_neg\_binomial\_2\_log\_rng }!{\tt (array[] int y, array[] int y\_index, vector theta0, function K\_function, tuple(...)): vector}|hyperpage}
336+
337+
`vector` **`laplace_latent_neg_binomial_2_log_rng`**`(array[] int y, array[] int y_index, real eta, vector theta0, function K_function, tuple(...))`<br>\newline
338+
339+
TODO description.
340+
{{< since 2.37 >}}
341+
342+
<!-- vector; laplace_latent_tol_neg_binomial_2_log_rng; (array[] int y, array[] int y_index, real eta, vector theta0, function K_function, tuple(...), real tol, int max_steps, int hessian_block_size, int solver, int max_steps_linesearch); -->
343+
\index{{\tt \bfseries laplace\_latent\_tol\_neg\_binomial\_2\_log\_rng }!{\tt (array[] int y, array[] int y\_index, vector theta0, function K\_function, tuple(...), real tol, int max\_steps, int hessian\_block\_size, int solver, int max\_steps\_linesearch): vector}|hyperpage}
344+
345+
`vector` **`laplace_latent_tol_neg_binomial_2_log_rng`**`(array[] int y, array[] int y_index, real eta, vector theta0, function K_function, tuple(...), real tol, int max_steps, int hessian_block_size, int solver, int max_steps_linesearch)`<br>\newline
346+
347+
TODO description.
348+
{{< since 2.37 >}}
312349

313350
### Bernoulli with logit link
314351

@@ -323,27 +360,38 @@ The arguments of the likelihood function are:
323360
group the $i^\text{th}$ observation belongs to.
324361

325362
The function signatures for the embedded Laplace approximation with a Bernoulli likelihood are
326-
```
327-
real laplace_marginal_bernoulli_logit_lpmf(array[] int y |
328-
array[] int y_index, real eta, vector theta0,
329-
function K_function, tuple(...));
330-
331-
real laplace_marginal_tol_bernoulli_logit_lpmf(array[] int y |
332-
array[] int y_index, real eta, vector theta0,
333-
function K_function, tuple(...),
334-
real tol, int max_steps, int hessian_block_size,
335-
int solver, int max_steps_linesearch);
336-
337-
vector laplace_latent_bernoulli_logit_rng(array[] int y,
338-
array[] int y_index, real eta, vector theta0,
339-
function K_function, tuple(...));
340-
341-
vector laplace_latent_tol_bernoulli_logit_rng(array[] int y,
342-
array[] int y_index, real eta, vector theta0,
343-
function K_function, tuple(...),
344-
real tol, int max_steps, int hessian_block_size,
345-
int solver, int max_steps_linesearch);
346-
```
363+
364+
<!-- real; laplace_marginal_bernoulli_logit_lpmf; (array[] int y | array[] int y_index, vector theta0, function K_function, tuple(...)); -->
365+
\index{{\tt \bfseries laplace\_marginal\_bernoulli\_logit\_lpmf }!{\tt (array[] int y \textbar\ array[] int y\_index, vector theta0, function K\_function, tuple(...)): real}|hyperpage}
366+
367+
`real` **`laplace_marginal_bernoulli_logit_lpmf`**`(array[] int y | array[] int y_index, vector theta0, function K_function, tuple(...))`<br>\newline
368+
369+
TODO description.
370+
{{< since 2.37 >}}
371+
372+
<!-- real; laplace_marginal_tol_bernoulli_logit_lpmf; (array[] int y | array[] int y_index, vector theta0, function K_function, tuple(...), real tol, int max_steps, int hessian_block_size, int solver, int max_steps_linesearch); -->
373+
\index{{\tt \bfseries laplace\_marginal\_tol\_bernoulli\_logit\_lpmf }!{\tt (array[] int y \textbar\ array[] int y\_index, vector theta0, function K\_function, tuple(...), real tol, int max\_steps, int hessian\_block\_size, int solver, int max\_steps\_linesearch): real}|hyperpage}
374+
375+
`real` **`laplace_marginal_tol_bernoulli_logit_lpmf`**`(array[] int y | array[] int y_index, vector theta0, function K_function, tuple(...), real tol, int max_steps, int hessian_block_size, int solver, int max_steps_linesearch)`<br>\newline
376+
377+
TODO description.
378+
{{< since 2.37 >}}
379+
380+
<!-- vector; laplace_latent_bernoulli_logit_rng; (array[] int y, array[] int y_index, vector theta0, function K_function, tuple(...)); -->
381+
\index{{\tt \bfseries laplace\_latent\_bernoulli\_logit\_rng }!{\tt (array[] int y, array[] int y\_index, vector theta0, function K\_function, tuple(...)): vector}|hyperpage}
382+
383+
`vector` **`laplace_latent_bernoulli_logit_rng`**`(array[] int y, array[] int y_index, vector theta0, function K_function, tuple(...))`<br>\newline
384+
385+
TODO description.
386+
{{< since 2.37 >}}
387+
388+
<!-- vector; laplace_latent_tol_bernoulli_logit_rng; (array[] int y, array[] int y_index, vector theta0, function K_function, tuple(...), real tol, int max_steps, int hessian_block_size, int solver, int max_steps_linesearch); -->
389+
\index{{\tt \bfseries laplace\_latent\_tol\_bernoulli\_logit\_rng }!{\tt (array[] int y, array[] int y\_index, vector theta0, function K\_function, tuple(...), real tol, int max\_steps, int hessian\_block\_size, int solver, int max\_steps\_linesearch): vector}|hyperpage}
390+
391+
`vector` **`laplace_latent_tol_bernoulli_logit_rng`**`(array[] int y, array[] int y_index, vector theta0, function K_function, tuple(...), real tol, int max_steps, int hessian_block_size, int solver, int max_steps_linesearch)`<br>\newline
392+
393+
TODO description.
394+
{{< since 2.37 >}}
347395

348396
<!-- ## Draw approximate samples for out-of-sample latent variables. -->
349397

0 commit comments

Comments
 (0)