[JOSS REVIEW] Support CmdStanMCMC objects directly

[vankesteren]

version arviz[preview]==0.23.1

In combination with cmdstanpy, it would be nice to support the conversion to the ArviZ data structure using the CmdStanMCMC object directly, rather than having to use the draws_xr() method

Part of openjournals/joss-reviews#9889

[OriolAbril]

Thanks for the feedback, we do have the from_cmdstanpy function which takes a CmdStanMCMC object directly so the fact you didn't find it is a clear and grave issue with our docs.

Do you think a whole tutorial on using the converter like emcee and numpyro have would be enough?

Moreover, draws_xr doesn't allow naming the dimensions or adding coordinate values so I would strongly discourage using it (at least for now) because that means you get the extra verbosity of xarray while still having uninformative names like theta_dim_0 and also having only positional indexing operations available.

[vankesteren]

Ah yes, good point, I did not go through the whole API docs. I see the method now and it works perfectly.

My expectation for the api was the following:

mod = CmdStanModel(stan_file="mymodel.stan")
fit = model.sample(stan_data)
az.plot_trace_dist(fit)

So I expected that I would not have to do the conversion myself for the basic traceplots, but now that I'm going into it a bit further I see that for other methods you need more than just the posterior samples, so this is not really possible in general.

I think the docs of ArviZ would benefit from being more welcoming to new users by including a small example right at the start. I think one of the killer features of arviz is that it supports so many bayesian frameworks, so a tabset (one tab per supported framework) with a minimal example would be great to have in the "getting started" section. Currently the "getting started" does not provide a minimal example of how people will actually use the library.

So for cmdstanpy it could look like so (although you should then point users to the bernoulli.ppc code from cmdstanpy docs to make this run)

import arviz as az
from cmdstanpy import CmdStanModel

stan_model = CmdStanModel(stan_file="bernoulli.stan")
stan_data = {"N": 10, "y": [0, 1, 0, 0, 0, 0, 0, 0, 0, 1]}
fit = model.sample(stan_data)
idata = az.from_cmdstanpy(posterior=fit)
az.plot_trace_dist(fit)

Then you can point users to the more in-depth documentation at the end of the tabset. One problem I see: I could not find this worked example in the latest version of the documentation!

I think the docs of the arviz-base subpackage would improve with the following two things:

• on the main page, have a more descriptive first sentence (it now says "ArviZ base features and converters."). Something that explains that arviz-base supports creating and converting to and from the arviz data structure.
• immediately after, show minimal methods to convert to the data structure (from_*)

but your opinion may be different, there are more ways to improve this!

[patelshivani2283-lab]

Hi! I’d like to work on improving the documentation for CmdStanPy support.

I can:

• Add a minimal from_cmdstanpy example to the getting started section
• Make the converter more discoverable in arviz-base docs
• Add a short CmdStanPy example similar to emcee / numpyro

I’ll open a docs-only PR in arviz-base if that sounds good.