Example stan documentation with doxygen

General
, ,
1

Hi everyone, I just wanted to point you to this work we recently did in EpiNow2 to document our stan code (See EpiNow2 Stan Functions: EpiNow2 Stan Functions), using doxygen.

We’ve not seen any guides around on how to document stan code so a lot of this was by trial and error. We are now preparing a guide (WIP) and will link here when it’s ready. Do let us know if you have any feedback or would like some guidance on documenting your own code.

6 Likes
2

Cool! I know of a couple other projects that have spent some time documenting Stan code:

3 Likes
3

Very cool, thanks for sharing.

2 Likes
4

This is super cool. The function group organization is really nice for this scale. We have some examples of documenting Stan functions in our Functions Reference. But they’re not done with code markup.

I have some suggestions:

  • I think it would help to clearly indicate the consistency requirements (e.g., two inputs being required to have the same shape) and what happens when they fail (presumably rejection).
  • If this is the front-line landing spot for this code, I would suggest making the licensing terms clear and also indicate how to download. If not, it would help to have a pointer to such a page on the top.
  • Some functions seem to be documented for insiders. Just randomly, it’s not clear to me what accumulate_reports() does. It would help to say what functions actually do. Examples in these situations are really helpful if they can fit.
  • I see that these functions are defined collectively as parts of models. Is there a reason you didn’t just put each file in its own file and then just #include them in other models? External function definitions is the one place where our include macros are clean.
  • Somehow the array[]int is coming out all jammed together in the output.
  • Some of the conditions are a bit too loose. For example, in params_lp(), it indicates that the distribution ID must be less than 2, but it must also be greater than or equal to 0, which isn’t indicated—this is in the code, not the doc.

In the function params_lp, I see that you’re using truncation. This is necessary if the arguments for those distributions are Stan parameters, but otherwise it’s much much more efficient and much much more arithmetically stable to drop the truncation (our log cdfs and ccdfs are not the most stable). We also don’t usually recommend truncating unconstrained distributions for priors unless there’s a physical constraint on the parameter (e.g., a probability has to be between 0 and 1).

3 Likes
5

Thanks, we took some inspiration from the first one.

1 Like
6

Wow! Thanks, Bob, for taking the time to look through the code and documentation. I’ll raise an issue to make the suggested enhancements.

1 Like
7

We’ve now done more stan documentation work on primarycensored, another of our packages. See the rendered site here. We implemented some of the feedback here including adding a license. We use doxygen-awesome to theme it. Quite happy with the look and feel, especially the call and caller graphs that show how the functions interact. We welcome your feedback.

3 Likes
8

Thanks for sharing. That looks great, but I even more importantly, the organization is clear with an indication of what the package does and the structure of the doc clearly indicated. And the license (thanks!).

The only suggestion I would make now is that that you might want to indicate bounds for arguments and error conditions (e.g., presumably the scale parameter for log_weibull_g must be finite and positive).

3 Likes
9

Thanks, Bob. We’ll incorporate this feedback.

1 Like