laplace_sample: expose CmdStan's diagnostic_file (the Hessian at the mode) #868

Summary

CmdStan's laplace method can write a diagnostic file (output diagnostic_file=...), but CmdStanModel.laplace_sample has no argument to request it. That file is where CmdStan reports the Hessian at the mode, so cmdstanpy users can't get the Hessian the Laplace approximation was built from.

Details

• laplace_sample's signature in 1.3.0 is (data, mode, draws, *, jacobian, seed, output_dir, sig_figs, save_profile, show_console, refresh, time_fmt, timeout, opt_args). There is no diagnostic_file or save_diagnostics, unlike sample(save_diagnostics=...).
• In CmdStan 2.40.0, running laplace mode=<mode.csv> ... output file=lap.csv diagnostic_file=lap_diag.json writes a JSON file whose "Hessian" key holds the Hessian of the log density at the mode, on the unconstrained scale. We confirmed this by running it directly.

Use case

We fit a model by optimize (MLE, jacobian=False) and want observed-information standard errors at the optimum. The Hessian at the mode is that object. Through cmdstanpy we can only get the Laplace draws, and from those we'd have to re-estimate a covariance that CmdStan has already computed exactly.

Suggested API

Add a save_diagnostics: bool = False argument, mirroring sample. It would pass diagnostic_file=<output_dir>/<name>-diagnostic.json to CmdStan, and expose the parsed file on CmdStanLaplace. For example, CmdStanLaplace.hessian would return an np.ndarray, or None if the diagnostic file wasn't requested.

We are happy to open a PR with a test, if this API is acceptable.

Versions

cmdstanpy 1.3.0, CmdStan 2.40.0, Python 3.12, Linux x86_64.