# Naming help on function in CmdStanR and CmdStanPy to get variable from sample

**URL:** <https://discourse.mc-stan.org/t/naming-help-on-function-in-cmdstanr-and-cmdstanpy-to-get-variable-from-sample/15410>\
**Category:** Interfaces\
**Tags:** posterior-package\
**Created:** [May 27, 2020, 12:39am UTC](https://discourse.mc-stan.org/t/naming-help-on-function-in-cmdstanr-and-cmdstanpy-to-get-variable-from-sample/15410 "2020-05-27T00:39:38Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![mitzimorris](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/mitzimorris/32/29_2.png) [@mitzimorris](https://discourse.mc-stan.org/u/mitzimorris)\
**Post date:** [May 27, 2020, 12:39am UTC](https://discourse.mc-stan.org/t/naming-help-on-function-in-cmdstanr-and-cmdstanpy-to-get-variable-from-sample/15410/1 "2020-05-27T00:39:38Z")

</div>

Now that folks are using CmdStanR and CmdStanPy to run real models, it’s clear that we need an accessor function to retrieve the named variables in the sampler output structured according to the Stan program variable declaration.

There are issues filed for CmdStanR and CmdStanPy - [https://github.com/stan-dev/cmdstanr/issues/183](https://github.com/stan-dev/cmdstanr/issues/183), [https://github.com/stan-dev/cmdstanpy/issues/245](https://github.com/stan-dev/cmdstanpy/issues/245)

RStan provides the `extract` function, which has some confusing options and a bad name - (cf [https://github.com/stan-dev/rstan/issues/118](https://github.com/stan-dev/rstan/issues/118) - basically, extract has meaning in SQL and tidyverse and we should avoid it).

Possible names: `get_var`, `get_variable`, `get_param` - the latter is technically a misnomer - the sampler outputs draws for all variables declared in the parameters, transformed parameters, and generated quantities blocks, so `variable` is more correct than `param`.

---

<div class="post-metadata">

**Author:** ![andrewgelman](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/andrewgelman/32/1577_2.png) [@andrewgelman](https://discourse.mc-stan.org/u/andrewgelman)\
**Post date:** [May 27, 2020, 1:07am UTC](https://discourse.mc-stan.org/t/naming-help-on-function-in-cmdstanr-and-cmdstanpy-to-get-variable-from-sample/15410/2 "2020-05-27T01:07:30Z")

</div>

I used to use extract, but then following Ben and Jonah’s advice, I switched to as.matrix. We use as.matrix in Regression and Other Stories.

---

<div class="post-metadata">

**Author:** ![vincent-picaud](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/vincent-picaud/32/24_2.png) [@vincent-picaud](https://discourse.mc-stan.org/u/vincent-picaud)\
**Post date:** [May 27, 2020, 4:39am UTC](https://discourse.mc-stan.org/t/naming-help-on-function-in-cmdstanr-and-cmdstanpy-to-get-variable-from-sample/15410/3 "2020-05-27T04:39:08Z")

</div>

I do not pretend that’s a good choice, I m writing this for information purpose.

In MathematicaStan I have used `GetStanResult`.

I also introduced `GetStanResultMeta` to get Stan computed quantities like “lp\_\_”, “step\_size\_\_” as they depend more on the chosen solver than on the model.

Examples:

```
GetStanResultMeta[stanResult, "lp__"]  
GetStanResult[stanResult, "beta.2"] <- the beta[2] scalar
GetStanResult[stanResult, "beta"] <- the beta vector

```

> **[stan-dev/MathematicaStan](https://github.com/stan-dev/MathematicaStan#load-the-csv-result-file)**
>
> A Mathematica package to interact with CmdStan. Contribute to stan-dev/MathematicaStan development by creating an account on GitHub.

---

<div class="post-metadata">

**Author:** ![mitzimorris](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/mitzimorris/32/29_2.png) [@mitzimorris](https://discourse.mc-stan.org/u/mitzimorris)\
**Post date:** [May 31, 2020, 9:31pm UTC](https://discourse.mc-stan.org/t/naming-help-on-function-in-cmdstanr-and-cmdstanpy-to-get-variable-from-sample/15410/4 "2020-05-31T21:31:55Z")

</div>

I just added a `Concepts` section to the CmdStan3 design doc - [https://github.com/stan-dev/design-docs/blob/cmdstan3/designs/0005-cmdstan3.md#concepts](https://github.com/stan-dev/design-docs/blob/cmdstan3/designs/0005-cmdstan3.md#concepts)

From the interface perspective, the Stan program data comes in the following flavors:

- _input data_ - the set of all variables declared in the `data` block
- _output data_ - the set of all variables declared in the `parameters` , `transformed parameters` , `generated quantities` blocks
- _output meta-data_ - information on the solver (e.g. output columns of sampler state `lp __` , `accept_stat__ ` )
- _runtime data_ - variables declared in the `transformed data` block, and in local blocks. Only available as print statement to the console.

I still think that `get_variable` is the most general way to talk about the output data, but I like Vincent’s suggestion of differentiating between meta-data and model variables.

---

<div class="post-metadata">

**Author:** ![anon75146577](https://avatars.discourse-cdn.com/v4/letter/a/f07891/32.png) [@anon75146577](https://discourse.mc-stan.org/u/anon75146577)\
**Post date:** [May 31, 2020, 10:45pm UTC](https://discourse.mc-stan.org/t/naming-help-on-function-in-cmdstanr-and-cmdstanpy-to-get-variable-from-sample/15410/5 "2020-05-31T22:45:38Z")

</div>

`get_samples`? Preferably with an option to stack the chains so instead I’d getting a 3 dimensional array you can get a 2D one

---

<div class="post-metadata">

**Author:** ![mitzimorris](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/mitzimorris/32/29_2.png) [@mitzimorris](https://discourse.mc-stan.org/u/mitzimorris)\
**Post date:** [May 31, 2020, 10:57pm UTC](https://discourse.mc-stan.org/t/naming-help-on-function-in-cmdstanr-and-cmdstanpy-to-get-variable-from-sample/15410/6 "2020-05-31T22:57:03Z")

</div>

> `get_samples` ? Preferably with an option to stack the chains so instead I’d getting a 3 dimensional array you can get a 2D one

agreed - this functionality is available in CmdStanPy - names, however need to be changed.

the CmdStanMCMC object has property `sample`:  
[https://cmdstanpy.readthedocs.io/en/latest/api.html#cmdstanpy.CmdStanMCMC.sample](https://cmdstanpy.readthedocs.io/en/latest/api.html#cmdstanpy.CmdStanMCMC.sample)

> A 3-D numpy ndarray which contains all draws across all chains arranged as (draws, chains, columns) stored column major so that the values for each parameter are stored contiguously in memory, likewise all draws from a chain are contiguous.

and also method `get_drawset`:  
[https://cmdstanpy.readthedocs.io/en/latest/api.html#cmdstanpy.CmdStanMCMC.get\_drawset](https://cmdstanpy.readthedocs.io/en/latest/api.html#cmdstanpy.CmdStanMCMC.get_drawset)

> Returns the assembled sample as a pandas DataFrame consisting of one column per parameter and one row per draw.
> 
> Parameters: **params** – list of model parameter names.

But these names don’t match up with CmdStanR, and `get_drawset` doesn’t do enough for container variables.

Also, this should work for all estimation outputs, not just the sampler, although there it just a single estimate per variable, still, we need to provide the output variable in the right structure, not as a flattened list.

---

<div class="post-metadata">

**Author:** ![avehtari](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/avehtari/32/5935_2.png) [@avehtari](https://discourse.mc-stan.org/u/avehtari)\
**Post date:** [June 1, 2020, 1:54pm UTC](https://discourse.mc-stan.org/t/naming-help-on-function-in-cmdstanr-and-cmdstanpy-to-get-variable-from-sample/15410/7 "2020-06-01T13:54:58Z")

</div>

Have you looked at posterior package [https://github.com/jgabry/posterior](https://github.com/jgabry/posterior) which is already used by CmdStanR? See the readme for introduction and function names. The simplest accessor function is `as_draws`. posterior package is aware of meta variables and provides easy way to transform the posterior draws to different formats useful in R.

Pinging posterior developers @jonah and @paul.buerkner

---

<div class="post-metadata">

**Author:** ![jonah](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/jonah/32/200_2.png) [@jonah](https://discourse.mc-stan.org/u/jonah)\
**Post date:** [June 1, 2020, 5:02pm UTC](https://discourse.mc-stan.org/t/naming-help-on-function-in-cmdstanr-and-cmdstanpy-to-get-variable-from-sample/15410/8 "2020-06-01T17:02:25Z")

</div>

We have the `fit$draws()` method in CmdStanR currently, which returns a `draws_array` from the posterior package that can then be converted to other formats via posterior. However, the posterior package doesn’t have a format comparable to the list returned by `rstan::extract()` in which each variable has the structure that it does in the Stan program.

For example, if a Stan program has

```stan
parameters {
  real mu;
  real<lower=0> tau;
  vector[8] theta;
}

```

then the list returned by `rstan::extract()` has named elements `mu` (length 4000 vector), `tau` (length 4000 vector) and `theta` (4000 x 8 matrix). The posterior package doesn’t currently have any format like this. Even the `draws_list` format has separate entries for each element of `theta` (i.e. it treats `theta[j]` like it treats `mu` and `tau` and not as an element of a larger structure `theta`). There’s no way to treat `theta` as having the structure it does in the Stan program, at least not currently in the posterior package.

@paul.buerkner I know we talked at some point about this but I forget where we left things. On the one hand, we didn’t want the posterior package to have to know anything about Stan. On the other hand, vector/matrix/array parameters are not unique to Stan so the posterior package could in theory have a format for working with them (maybe this is related to the “random variable”-style format we previously discussed, although not sure if that encompassed multivariate RVs).

---

<div class="post-metadata">

**Author:** ![ahartikainen](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/ahartikainen/32/321_2.png) [@ahartikainen](https://discourse.mc-stan.org/u/ahartikainen)\
**Post date:** [June 1, 2020, 6:44pm UTC](https://discourse.mc-stan.org/t/naming-help-on-function-in-cmdstanr-and-cmdstanpy-to-get-variable-from-sample/15410/9 "2020-06-01T18:44:28Z")

</div>

I think the output should minimize the manual handling for post-sampling modelling.

if I have 100 parameters, how should I process my output from mcmc. Should I have a function and a way to unload values as function parameters, or should I create manually 100 variables?

Also, should we consider how “native” broadcasting rules work.

For example

```
dot(theta, beta)

```

How should we think the out when

One is mcmc, other one is static  
Both are mcmc

And dev work should have other interface (to select chains etc)

---

<div class="post-metadata">

**Author:** ![mitzimorris](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/mitzimorris/32/29_2.png) [@mitzimorris](https://discourse.mc-stan.org/u/mitzimorris)\
**Post date:** [June 1, 2020, 6:52pm UTC](https://discourse.mc-stan.org/t/naming-help-on-function-in-cmdstanr-and-cmdstanpy-to-get-variable-from-sample/15410/10 "2020-06-01T18:52:49Z")

</div>

> [@jonah](#):
>
> each variable has the structure that it does in the Stan program

to restate what Jonah said, because this is a Stan-specific, downstream analysis packages don’t have the functionality we need here - which is to take the flattened elements of a structured variable back to the corresponding structure. we want the functionality of extract, but a better name.

> [@vincent-picaud](#):
>
> In MathematicaStan I have used `GetStanResult` .

I think this is the right way to go - that said - `get` is implicit, `result` and `meta` too vague -  
how about `stan_var`, `stan_vars` and `mcmc_data`?

Given a program with parameters block:

```no-highlight
parameters {
  real alpha;
  real phi[3, 2];
  vector[2] nu;
}

```

and a resulting CmdStanMCMC object `my_fit`, then `my_draws = my_fit$draws()` is a draws\_array with column names: ` 'alpha', 'phi.1.1', 'phi.1.2', 'phi.1.3', 'phi.1.4', 'phi.1.5',' phi.2.1', 'phi.2.2', 'phi.2.3', 'phi.2.4', 'phi.2.5', 'nu.1', 'nu.2'`

- `my_fit$stan_var("phi")` returns a multi-dim array dimensions ( rows X chains X 3 X 2 )

- `my_fit$stan_vars()` returns a map of names to multi-dim arrays - for `alpha` this is ( rows X chains X 1),  
for `phi`, as above, and for `nu` (rows X chains X 2)

- `my_fit$mcmc_data` returns a map from names to single column arrays (rows X chains X 1)

---

<div class="post-metadata">

**Author:** ![mitzimorris](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/mitzimorris/32/29_2.png) [@mitzimorris](https://discourse.mc-stan.org/u/mitzimorris)\
**Post date:** [June 2, 2020, 2:20am UTC](https://discourse.mc-stan.org/t/naming-help-on-function-in-cmdstanr-and-cmdstanpy-to-get-variable-from-sample/15410/11 "2020-06-02T02:20:50Z")

</div>

suggestion from a very wise user: `stan_param`

this function returns the set of draws corresponding to the named parameter or generated quantities variable, with the corresponding structure.

---

<div class="post-metadata">

**Author:** ![anon75146577](https://avatars.discourse-cdn.com/v4/letter/a/f07891/32.png) [@anon75146577](https://discourse.mc-stan.org/u/anon75146577)\
**Post date:** [June 2, 2020, 6:00am UTC](https://discourse.mc-stan.org/t/naming-help-on-function-in-cmdstanr-and-cmdstanpy-to-get-variable-from-sample/15410/12 "2020-06-02T06:00:40Z")

</div>

Why the `Stan` prefix? That’s surely implied. Also generated quantities aren’t parameters.

---

<div class="post-metadata">

**Author:** ![mitzimorris](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/mitzimorris/32/29_2.png) [@mitzimorris](https://discourse.mc-stan.org/u/mitzimorris)\
**Post date:** [June 2, 2020, 2:32pm UTC](https://discourse.mc-stan.org/t/naming-help-on-function-in-cmdstanr-and-cmdstanpy-to-get-variable-from-sample/15410/13 "2020-06-02T14:32:14Z")

</div>

I agree with both points - I think that “var” (one var), “vars” (dict of vars), and “mcmc\_data” (dict of mcmc info - or “mcmc\_vars”) are relatively concise and correct.

here’s the reasoning behind the above proposal:

- “params” because that’s the term used in RStan since forever - this is to help users coming to CmdStanR and CmdStanPy from RStan and PyStan.

- “stan” because the variable has the same structure as in the Stan program.

maybe consensus on the right name is impossible, in which case, looking for consensus on names that are wrong.

---

<div class="post-metadata">

**Author:** ![bbbales2](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/bbbales2/32/77_2.png) [@bbbales2](https://discourse.mc-stan.org/u/bbbales2)\
**Post date:** [June 2, 2020, 2:48pm UTC](https://discourse.mc-stan.org/t/naming-help-on-function-in-cmdstanr-and-cmdstanpy-to-get-variable-from-sample/15410/14 "2020-06-02T14:48:11Z")

</div>

> [@jonah](#):
>
> The posterior package doesn’t currently have any format like this. Even the `draws_list` format has separate entries for each element of `theta` (i.e. it treats `theta[j]` like it treats `mu` and `tau` and not as an element of a larger structure `theta` )

For what it’s worth, I’m more interested in having a dataframe mechanism for handling things that are conceptually grouped, rather than deferring to the lists of whatever.

So I think what [tidybayes](https://mjskay.github.io/tidybayes/) (@mjskay) does is cool. Look at the `spread_draws` example on that page.

---

<div class="post-metadata">

**Author:** ![mjskay](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/mjskay/32/112_2.png) [@mjskay](https://discourse.mc-stan.org/u/mjskay)\
**Post date:** [June 4, 2020, 5:53am UTC](https://discourse.mc-stan.org/t/naming-help-on-function-in-cmdstanr-and-cmdstanpy-to-get-variable-from-sample/15410/15 "2020-06-04T05:53:33Z")

</div>

> [@jonah](#):
>
> @paul.buerkner I know we talked at some point about this but I forget where we left things. On the one hand, we didn’t want the posterior package to have to know anything about Stan. On the other hand, vector/matrix/array parameters are not unique to Stan so the posterior package could in theory have a format for working with them (maybe this is related to the “random variable”-style format we previously discussed, although not sure if that encompassed multivariate RVs).

When I find the time to finish the rvar stuff for posterior this summer (if such an interface is still desired) it such support something like this. In fact, the prototype already supports arbitrary-dimensional random variable arrays, I just need to revisit the most recent updates to vctrs to make it work inside dataframes. Then I was going to loop back around to you (@jonah) and @paul.buerkner to see what you’d be interested in for interfaces that use the rvar type (my plan for tidybayes was for dataframes of rvars, which will be _very_ nice I think :) ).

---

<div class="post-metadata">

**Author:** ![paul.buerkner](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/paul.buerkner/32/3303_2.png) [@paul.buerkner](https://discourse.mc-stan.org/u/paul.buerkner)\
**Post date:** [June 4, 2020, 7:27am UTC](https://discourse.mc-stan.org/t/naming-help-on-function-in-cmdstanr-and-cmdstanpy-to-get-variable-from-sample/15410/16 "2020-06-04T07:27:34Z")

</div>

I think the `rvar` feature in posterior is exactly what we need to represent the structure of Stan (or other parameters) with their corresponding dimension. With regard to the discussion of `vars`, `variables`, `parms` or `parametes`, in posterior we made the decision to go with `variables`, in short, because this does include quantities generated on the original model parameters (for more see: [https://github.com/jgabry/posterior/issues/1](https://github.com/jgabry/posterior/issues/1))

---

<div class="post-metadata">

**Author:** ![mitzimorris](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/mitzimorris/32/29_2.png) [@mitzimorris](https://discourse.mc-stan.org/u/mitzimorris)\
**Post date:** [June 4, 2020, 3:45pm UTC](https://discourse.mc-stan.org/t/naming-help-on-function-in-cmdstanr-and-cmdstanpy-to-get-variable-from-sample/15410/17 "2020-06-04T15:45:42Z")

</div>

glad there’s precedent for “variable” - here are some possibilities:

- `rvar` - as above, r for random
- `svar` - s for stan
- `mvar` - m for model

or just plain ol’ `var`

as for sampler diagnostic output columns ‘lp\_\_’, OK to go with `mcmc_vars` or `meta_vars` ?

---

<div class="post-metadata">

**Author:** ![paul.buerkner](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/paul.buerkner/32/3303_2.png) [@paul.buerkner](https://discourse.mc-stan.org/u/paul.buerkner)\
**Post date:** [June 4, 2020, 6:42pm UTC](https://discourse.mc-stan.org/t/naming-help-on-function-in-cmdstanr-and-cmdstanpy-to-get-variable-from-sample/15410/18 "2020-06-04T18:42:46Z")

</div>

To clarify, the term `rvar` is more an adjoc name that we have used to refer to a specific features temporarility ([https://github.com/jgabry/posterior/issues/8](https://github.com/jgabry/posterior/issues/8)). I am not sure with what name we will end up with in this regard.

In terms of the posterior naming conventions, we try to spell most of the things out. Hence, the full name “variable(s)”. This doesn’t mean, we need to use the same spelled out form for CmdStanX of course.

---

<div class="post-metadata">

**Author:** ![jonah](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/jonah/32/200_2.png) [@jonah](https://discourse.mc-stan.org/u/jonah)\
**Post date:** [June 5, 2020, 3:28pm UTC](https://discourse.mc-stan.org/t/naming-help-on-function-in-cmdstanr-and-cmdstanpy-to-get-variable-from-sample/15410/19 "2020-06-05T15:28:52Z")

</div>

@mjskay sounds good, thanks!

---

<div class="post-metadata">

**Author:** ![bbbales2](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/bbbales2/32/77_2.png) [@bbbales2](https://discourse.mc-stan.org/u/bbbales2)\
**Post date:** [June 9, 2020, 3:55pm UTC](https://discourse.mc-stan.org/t/naming-help-on-function-in-cmdstanr-and-cmdstanpy-to-get-variable-from-sample/15410/20 "2020-06-09T15:55:59Z")

</div>

Actually @mjskay does tidybayes work with any of the cmdstanr/posterior outputs yet? I tried a little but was getting errors. I don’t see it listed on the models [page](https://mjskay.github.io/tidybayes/reference/tidybayes-models.html), so I figured I’d ask before I tried too much.

[Next page](https://discourse.mc-stan.org/t/naming-help-on-function-in-cmdstanr-and-cmdstanpy-to-get-variable-from-sample/15410.md?page=2)