New user's experience with the Stan Math Library

I hope that that the following observations are useful. I spent a day on a train coding a Weibull regression model and a flexible parametric survival model using the Stan Math Library to calculate gradient and Hessians. Observations:

  • I started with the “Using the Stan Math C++ Library” vignette and the online documentation. This is strong documentation – thank you.
  • My first stumble was that, given containers of matching sizes, the stan::math::weibull_lccdf() and weibull_lpdf() functions return the log sum of probabilities and sum of log probability densities, respectively. For potentially censored data, this is not overly helpful – so I unrolled the vectorised calls into scalar calls using a for loop. (I should have read the documentation more carefully:().
  • My major stumble was trying to calculate the Hessian. After some debugging, I was able to use a functor to calculate the objective and gradient functions, but I was not able to get the Hessian to work, with abstruse and voluminous C++ template compiler errors. I eventually found a suggestion at to use #include <stan/math/mix/mat.hpp> – and suddenly everything worked:). Is there any way to add this include statement to the vignette?
  • For a new user, it was unclear when to use stan::math idioms (e.g. subtract()) and when to use Eigen idioms (e.g. -, possibly with .eval​()​). These were mixed in the vignette – and some guidance may be helpful.

Sincerely, Mark Clements.


Thanks for the feedback, @marcle. @SteveBronder is about to roll out a bunch of new doc that will hopefully make this a lot easier.

Basically, whenever there’s autodiff involved, use the Stan idioms, otherwise use Eigen’s. So if you’re just slicing without arithmetic, use Eigen. Or if you’re operating on double values, use Eigen. If you’re applying functions that do more than reshape and apply to autodiff variables, use Stan’s.

Yes, we definitely need that include. I think that vignette and online doc may be about to get completely revamped, but @SteveBronder will know what the status is and will be able to make sure the include is included.

1 Like