Analysis API

[syclik]

Thanks for the summary, @Bob_Carpenter. And thanks for adding to the list, @avehtari. Some of my responses.

@Bob_Carpenter

Where I’m not sure there’s agreement is with

• whether this is an I/O based interface (protobuf, etc.) or whether it’s a C++ API or whether it’s the former layered on top of the latter,

For these methods, it should just be a C++ API. Earlier

in the thread, I believe we agreed that the input would be:

std::vector<double*> draws, std::vector<size_t> sizes

(the vector of sizes for generality; I think we could also have a convenience method that accepts std::vector<double*>, size_t.)

I think for the most part, the returns are straightforward, so we should use return values as the result and exceptions as exceptions to computing the function at hand.

For example, I think the R-hat function signature should look like (name can change, of course):

double split_r_hat(std::vector<double*> draws, std::vector<size_t> sizes);

There is an alternative return here, which could be something like std::pair<double, std::vector<double>> if we wanted to return the overall R-hat and then also one per chain, but I’m looking at the list and most of the things will either return a single value or one per chain, which is easy to return.

I believe we already have buy-in for these input types from CmdStan (me), RStan (@bgoodri), and PyStan (@ariddell).

@Bob_Carpenter

• how much of the functionality should go in the math lib

I’d suggest these live in the stan-dev/stan repo. They’re not basic math functions. They’re functions that operate on the output of the algorithms, which are in that repo.

Once place they could go is under src/stan/services/analysis/ or something else under src/stan/services/.

I think functions like autocorrelation() might make sense to live inside the math library.

@Bob_Carpenter

• who will manage it (related to where it goes, I suppose).

Hopefully by simplifying the function signatures, it won’t need to be managed much. A lot of it hasn’t needed to change over the years.

@Bob_Carpenter

Then there are some functions that can take consolidated output across chains:

• posterior quantiles
• posterior means
• posterior std. dev.

I think the arguments can be the same. For convenience, perhaps we offer an additional function signature (the second one):

std:vector<double> quantiles(std::vector<double*> draws, std::vector<size_t> size, std::vector<double> probs);
std:vector<double> quantiles(double* draws, size_t size, std::vector<double> probs);

Thoughts? I think the steps are to build one, integrate it all the way through, then build out the rest.